Skip to content

Publish @hyperpolymath/affine-vscode to npm (eliminate vendoring) #104

Closed
Closed
Publish @hyperpolymath/affine-vscode to npm (eliminate vendoring)#104

Description

@hyperpolymath
hyperpolymath
opened on May 11, 2026

Problem

packages/affine-vscode/mod.js is the JS-side adapter for stdlib/Vscode.affine + stdlib/VscodeLanguageClient.affine. It maps each extern fn to a real vscode / vscode-languageclient/node call and maintains the handle table.

Today the package has no package.json — only mod.js, README.adoc, and deno.json. Consumers outside this repo (currently hyperpolymath/my-lang and hyperpolymath/standards rsr-certifier; soon every other AffineScript-authored VS Code extension) vendor the adapter by copying mod.js into src/affine-vscode-adapter.cjs in their own repo.

Vendoring works but has clear drawbacks:

  • Drift risk. Every change to mod.js here requires manual re-sync in every consumer. The bindings PR (feat(vscode-bindings): expand surface for rsr-certifier port (#64) #102) added ~20 new functions; each consumer downstream had to remember to copy them across.
  • Update protocol is implicit. There's no machine-readable version to pin, no changelog the consumer can diff against, no tooling to surface "your vendored copy is N commits behind".
  • Discoverability. New extension authors find the adapter only by reading existing extensions' source.

Proposed plan

Publish @hyperpolymath/affine-vscode to npm so consumers can npm install @hyperpolymath/affine-vscode and require() the adapter directly. The vendoring step in each extension's src/index.cjs collapses to:

const shim = require("../out/extension.cjs");
const makeVscodeBindings = require("@hyperpolymath/affine-vscode");

shim.extraImports = () => makeVscodeBindings(
    require("vscode"),
    require("vscode-languageclient/node"),
    shim,
);

exports.activate = shim.activate;
exports.deactivate = shim.deactivate;

Steps

  1. Add packages/affine-vscode/package.json with name: "@hyperpolymath/affine-vscode", main: "./mod.js", an MIT or PMPL license entry matching the repo, peerDependencies: { vscode: "*", "vscode-languageclient": "^9.0.0" }, and a repository.directory field pointing at this subdirectory.
  2. Pick a version (0.1.0 is fine for the first published cut).
  3. Confirm the publishing account / token. The hyperpolymath org doesn't currently have an npm presence — decide whether to publish under that scope (needs the npm org creating) or under a personal scope.
  4. npm publish --access public from packages/affine-vscode/. Add the publish step to a GitHub Actions workflow guarded on a tag pattern so subsequent releases are tag-driven.
  5. Update hyperpolymath/my-lang's vscode-extension and hyperpolymath/standards's rsr-certifier to depend on @hyperpolymath/affine-vscode instead of vendoring; remove their local src/affine-vscode-adapter.cjs files.
  6. Document the consumer pattern in packages/affine-vscode/README.adoc (the existing Usage section already gets close — just needs the vendoring escape hatch removed and the npm-install path made primary).

Acceptance criteria

  • @hyperpolymath/affine-vscode is resolvable via npm view.
  • CI publishes new versions automatically on tag push (no manual npm publish after the first one).
  • my-lang vscode-extension and standards rsr-certifier depend on the published package; their local affine-vscode-adapter.cjs files are removed.
  • packages/affine-vscode/README.adoc documents the npm-install consumer pattern as primary.

Out of scope

  • Cutting a major version. 0.x is fine while the binding surface is still growing organically.
  • Replacing the current module.exports = function (...) factory shape with ESM exports. CJS is what the vscode extension host loads.

Related

Activity

  1. hyperpolymath
    added 5 commits that reference this issue on May 15, 2026

    feat(affine-vscode): npm package manifest + tag-driven publish (issue #…

    f15371c

    affine-vscode: align docs with --vscode-extension + npm publish manif…

    d2875a5

    chore(affine-vscode): finish PMPL→MPL sweep + truth-up Status paragra…

    17ed8d5

    test(vscode): in-editor smoke harness via @vscode/test-electron (Closes

    7eeb3d8

    chore(vscode-extension): un-vendor affine-vscode adapter (Refs hyperp…

    a4ba3b8

  2. hyperpolymath commented on May 21, 2026

    @hyperpolymath
    hyperpolymath
    on May 21, 2026
    OwnerAuthor

    Status sweep 2026-05-21

    Most of the work in this issue already shipped via earlier PRs. The remaining gap is the first npm publish + downstream un-vendoring. Current state vs the four acceptance bullets:

    AC Status Where
    @hyperpolymath/affine-vscode resolvable via npm view ❌ owner action needs npm org create + NPM_TOKEN secret + tag push
    CI publishes on tag push ✅ on main .github/workflows/affine-vscode-publish.yml (trigger: affine-vscode-v*)
    my-lang + standards depend on the published package; vendored .cjs removed 🟡 staged as DRAFTs hyperpolymath/my-lang#66, hyperpolymath/standards#160
    README.adoc documents npm-install as primary ✅ on main (tightened) tightened in #316 (PMPL→MPL sweep + Status truth-up)

    Owner action checklist to land the first publish

    1. Merge chore(affine-vscode): finish PMPL→MPL sweep + truth-up Status paragraph (Refs #104) #316 (manifest+doc-only PMPL→MPL finishing sweep; the two stale license fields missed by 3170a6b).
    2. Create npm org hyperpolymath at https://www.npmjs.com/org/create (free tier is fine for public packages — issue body §3 noted this org doesn't yet exist on npm).
    3. Generate an npm automation token with publish rights to the @hyperpolymath scope and add it as repo secret NPM_TOKEN at https://github.com/hyperpolymath/affinescript/settings/secrets/actions.
    4. Push tag affine-vscode-v0.1.0 to fire affine-vscode-publish.yml: 
      cd /home/hyperpolymath/dev/repos/affinescript
git fetch origin main
git tag -a affine-vscode-v0.1.0 origin/main -m "affine-vscode 0.1.0 — first npm publish (Refs #104)"
git push origin affine-vscode-v0.1.0
    5. Verify with npm view @hyperpolymath/affine-vscode.
    6. Mark chore(vscode-extension): un-vendor affine-vscode (Refs hyperpolymath/affinescript#104) my-lang#66 + chore(rsr-certifier/vscode): un-vendor affine-vscode (Refs hyperpolymath/affinescript#104) standards#160 ready-for-review, run their test plans, merge.
    7. Close this issue with a Closes #104 reference on whichever PR (likely standards#160) lands last, per the ISSUE-CLOSURE rule in CLAUDE.md.

    What the DRAFT consumer PRs contain

    hyperpolymath/my-lang#66 (uses the --vscode-extension codegen pattern):

    • vscode-extension/package.json: drop --vscode-extension-adapter=../src/affine-vscode-adapter.cjs override from compile + vscode:prepublish scripts; add @hyperpolymath/affine-vscode@^0.1.0 to dependencies.
    • vscode-extension/src/affine-vscode-adapter.cjs: deleted (-141 lines).
    • vscode-extension/out/extension.cjs line 101: require("../src/affine-vscode-adapter.cjs") → require("@hyperpolymath/affine-vscode"). This is auto-generated --vscode-extension glue; matches what npm run vscode:prepublish will regenerate on first compile after publish.

    hyperpolymath/standards#160 (uses the manual-wiring pattern):

    • rhodium-standard-repositories/satellites/rsr-certifier/extensions/vscode/package.json: add the dep.
    • extensions/vscode/src/index.cjs line 18: require("./affine-vscode-adapter.cjs") → require("@hyperpolymath/affine-vscode").
    • extensions/vscode/src/affine-vscode-adapter.cjs: deleted (-463 lines).
    • out/extension.cjs unchanged — this extension's compiled wasm shim doesn't reference the adapter directly.

    Per the ISSUE-CLOSURE rule, this comment does not self-close the issue.

  3. hyperpolymath
    added 2 commits that reference this issue on May 21, 2026

    chore(rsr-certifier/vscode): un-vendor affine-vscode (Refs hyperpolym…

    4f97da4

    Qa 139 vscode smoke (#320)

    de19c49

  4. hyperpolymath commented on May 21, 2026

    @hyperpolymath
    hyperpolymath
    on May 21, 2026
    OwnerAuthor

    Final session status 2026-05-21 (handover)

    All three PRs landed earlier today merged successfully:

    ⚠️ Issue stays OPEN — first publish not yet landed

    Verified at session-close: npm view @hyperpolymath/affine-vscode → 404; no affine-vscode-v* tag on the repo; zero runs of affine-vscode-publish.yml.

    Consequence: both consumer extensions now declare @hyperpolymath/affine-vscode@^0.1.0 in dependencies and have deleted their vendored adapters, so npm install in hyperpolymath/my-lang/vscode-extension/ and hyperpolymath/standards/.../rsr-certifier/extensions/vscode/ will 404 until the publish lands.

    Blocked on owner action (2FA lockout)

    Owner reports phone/2FA issues blocking the npm-side sequence, same pattern as the deferred VS Code Marketplace PAT lockout. When 2FA is restored:

    1. Create npm org hyperpolymath at https://www.npmjs.com/org/create
    2. Generate an npm automation token with publish rights to the scope; add as repo secret NPM_TOKEN at https://github.com/hyperpolymath/affinescript/settings/secrets/actions
    3. Push the tag: 
      git tag -a affine-vscode-v0.1.0 origin/main -m "affine-vscode 0.1.0 — first npm publish (Closes #104)"
git push origin affine-vscode-v0.1.0
    4. After npm view @hyperpolymath/affine-vscode resolves, this issue may be closed with a comment referencing the workflow run that published.

    Fallback option (if 2FA stays blocked indefinitely)

    If the publish can't land soon and the broken-install state needs resolving first, a pair of hotfix PRs against my-lang + standards can restore the vendored adapter as a temporary fallback. Not opened — owner discretion.

    Per ISSUE-CLOSURE in CLAUDE.md, this comment does not self-close.

  5. hyperpolymath
    added 7 commits that reference this issue on May 25, 2026

    fix(ci): mark vscode-smoke continue-on-error until adapter publishes (#…

    3d378ae

    fix(ci): three foundational unblocks for the main-branch baseline (PR…

    2ca7893

    fix(ci): mark vscode-smoke continue-on-error until adapter publishes (#…

    f79f401

    fix(ci): unblock the PR queue — bench/dune + adapter-load + .res-fixt…

    f1d47e6

    fix(vscode-smoke): SKIP cleanly when @hyperpolymath/affine-vscode is …

    44b5341

    feat(codegen): embed affine-vscode adapter at compile time (root-caus…

    b1190a3

    feat(codegen): embed affine-vscode adapter at compile time (root-caus…

    6749fd2

  6. hyperpolymath commented on May 30, 2026

    @hyperpolymath
    hyperpolymath
    on May 30, 2026
    OwnerAuthor

    Closing — Signal C (policy-superseded). npm publishing is contra-policy per the estate npm-avoidant direction (#67 lockfile elimination + #253 npm→Deno migration). The intent — eliminating vendoring of packages/affine-vscode/mod.js — remains valid, but the canonical replacement is JSR via the publish-jsr.yml workflow that landed today.

    If JSR publishing for affine-vscode needs its own narrow tracker, please refile under JSR scope rather than reopening this ticket (older tickets accumulate stale context).

  7. hyperpolymath
    closed this as completedon May 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions