Code reference detail
prepare-native-packages.mjs
scripts/prepare-native-packages.mjs
| Idea | Status | Tags | Summary | Katz |
|---|---|---|---|---|
| deployment_flow | On push to main, the release workflow first completes ["./distribution.rq".ci_gate]. If pending changesets remain, it then applies them with `pnpm changeset version`. This bumps package. json for each affected package and writes changelogs. ["../../scripts/prepare-native-packages.mjs"] then copies the `@reqlan/analytical` version onto each platform package ( [version_management] ). The workflow commits the result, creates annotated tags for every bumped publishable package, and pushes the commit and tags back to main. Release tags use `site/v{version}`, `ext/v{version}`, `language/v{version}`, `analytical/v{version}`, `cli/v{version}`, and `mcp/v{version}` where `{version}` is the semver from that package's package. json. Deployment is tag-driven for every channel per ["./distribution.rq".release_tagging]; after ["./distribution.rq".ci_gate], the release workflow only versions and tags. GitHub Actions pushes with the default `GITHUB_TOKEN` do not trigger other workflows, so site and npm deploy are also invoked directly from the release workflow. Optional `RELEASE_PAT` allows tag pushes to trigger downstream workflows for manual reruns and external CI. Recursive runs are prevented by skipping the release workflow for release commits. Tag patterns and downstream deploy workflows follow ["./distribution.rq".release_tagging]. The implementation lives in ["../../.github/workflows/release.yml"]. | 0.224 | ||
| npm_distribution | in-progress | npm publishing runs only when a `language/v*`, `analytical/v*`, `cli/v*`, or `mcp/v*` tag is pushed. Tags are created by ["./distribution.rq".deployment_flow]; the npm workflow does not publish on ordinary commits. The workflow builds platform binaries when `@reqlan/analytical` was bumped ( `analytical/v*` tag, or `analytical_tag` from the release workflow ). It does not use `github.event_name == 'workflow_call'` for that gate: in a reusable workflow that name is the caller event ( `push` ), and `npm_ref` is the first language / analytical / cli / mcp tag, so a language bump would skip natives. It then publishes each package in sequence with `pnpm --filter <pkg> publish --access public --no-git-checks`. The sequence is language, then all platform packages for [native_targets], then `@reqlan/analytical`, then cli, then mcp. The workflow does not publish `@reqlan/analytical` until every platform package of that `@reqlan/analytical` version is on the npm registry or was published in the same job ( [rust_binary_distribution] ). ["../../scripts/require-natives-published.mjs"] enforces that gate from the analytical package. json version ( not Changesets ). Before each package publishes, ["../../scripts/skip-already-published.mjs"] with `--filter <pkg>` checks the public npm registry and skips that step when the version is already published ( sets `should_publish=false` ). That avoids re-attempting already-published versions under OIDC. Auth uses npm trusted publishing ( OIDC ) from GitHub Actions — no long-lived `NPM_TOKEN`. Workflow requirements: `permissions.id-token: write`, Node ≥ 22. 14 with npm ≥ 11. 5. 1, registry `https://registry.npmjs.org`. Each of `@reqlan/language`, `@reqlan/analytical`, `@reqlan/cli`, `@reqlan/mcp`, and every `@reqlan/analytical-<platform>-<arch>` platform package must have a Trusted Publisher on npmjs. com for GitHub Actions with org / user `littletuna4`, repository `reqlan`, workflow filename `deploy-npm.yml`, allowed action `npm publish`. Package `repository.url` must match `https://github.com/littletuna4/reqlan.git`. Provenance attestations are generated automatically for public packages from this public repo. Bootstrap: first publish of each scoped package can be done locally ( you must be logged in to npm as an `@reqlan` org member ) with `pnpm --filter @reqlan/language publish --access public --no-git-checks`, then platform packages, then analytical, then cli, then mcp — or wait for the trusted-publisher CI path after packages exist and Trusted Publisher is configured. Note: Packages must be `private: true` to skip local `changeset publish` ( `pnpm run release:npm` ), as with `reqlan-extension`. Platform packages are in the Changesets `ignore` list ( `@reqlan/analytical-*` ). Git `@reqlan/analytical` does not list them as `optionalDependencies`. ["../../scripts/prepare-native-packages.mjs"] `--publish-versions` writes pinned optionalDependencies for the npm checkout only. CI publishes platform packages per-package after binaries are built and does not use `changeset publish` for those tarballs. Published packages declare `publishConfig.access: public`. Trusted Publisher is configured on npmjs. com for each `@reqlan/analytical-<platform>-<arch>` package | 0.266 | |
| rust_binary_distribution | in-progress | One platform-specific npm package per [native_targets] tuple: `@reqlan/analytical-<platform>-<arch>` ( napi suffixes: `linux-x64-gnu`, `linux-arm64-gnu`, `darwin-x64`, `darwin-arm64`, `win32-x64-msvc`, `win32-arm64-msvc` ). Each package declares `os` and `cpu`, contains the matching core engine `.node`, and uses the `@reqlan/analytical` package. json version as the single source of truth. ["../../scripts/prepare-native-packages.mjs"] writes that version. Changesets ignores `@reqlan/analytical-*` in ["../../.changeset/config.json"]. Git `@reqlan/analytical` does not list platform packages as `optionalDependencies`; this workspace links them through `packageExtensions` in ["../../pnpm-workspace.yaml"]. The published tarball lists pinned optionalDependencies ( `--publish-versions` ) ( [version_management] ). CLI and MCP install the host-matching binary from those published optionalDependencies. The published tarball runs ["./native_host_binary.rq".published_host_native_install] so a host miss prints a warning. Published on the existing `analytical/v*` channel ( [npm_distribution] / [release_tagging] ); not a separate tag channel. The napi build runs when this channel moved: a direct `analytical/v*` tag, or `analytical_tag` from [deployment_flow]. The first npm tag ( `npm_ref` ) can be `language/v*` in the same release, so that ref is not the native-build gate. Website download listing and GitHub-release postinstall are later follow-ups ( out of scope here ). Engine port: ["../core_analysis/rust_port.rq".analytical_rust_port] / ["../core_analysis/rust_port.rq".native_bridge]. Per-target VSIX packaging uses the same package layout under ["../../packages/analytical-native/"], filled by Azure from this git commit ( [vsix_export], [vsix_native_not_from_npm] ). npm tarballs of those packages are for CLI / MCP only. `collect-napi-binary.mjs` copies `reqlan-lsp` only with `--with-lsp`. The npm workflow does not pass that flag. Azure does, because the VSIX ships `bin/reqlan-lsp` ( [vsix_export] ). Implementation: ["../../packages/analytical-native/"], ["../../scripts/prepare-native-packages.mjs"], ["../../scripts/require-natives-published.mjs"], ["../../packages/analytical/scripts/check-host-native.mjs"], ["../../.changeset/config.json"], ["../../.github/workflows/deploy-npm.yml"] build-native job, ["../../azure-pipelines.yml"] build_native job. | 0.380 | |
| stopgap | Stopgap distribution is at https://marketplace.visualstudio.com/manage/publishers/reqlan | 0.040 | ||
| version_management | done | Package versions are managed with Changesets via ["../../.changeset/config.json"]. Publishable channels ( each tag-driven ): - Marketplace / Open VSX: ["./distribution.rq".extension_package] ( private npm package; tagged `ext/v*` ) - GitHub Pages: ["./distribution.rq".site_package] ( tagged `site/v*` ) - npm: `@reqlan/language`, `@reqlan/analytical`, `@reqlan/cli`, and `@reqlan/mcp` ( tagged `language/v*`, `analytical/v*`, `cli/v*`, `mcp/v*` ) `reqlan-extension` has its own semver. It is not version-locked to `@reqlan/analytical`. The extension can update independently of the analytical surfaces it uses ( [extension_package] ). The version of `@reqlan/analytical` is the single source of truth for every `@reqlan/analytical-<platform>-<arch>` package ( [rust_binary_distribution] ). Platform packages are in the Changesets `ignore` list ( `@reqlan/analytical-*` ). Git `@reqlan/analytical` does not list them as `optionalDependencies`, so `changeset version` can run. This workspace still links the checkout packages during `pnpm install` via `packageExtensions` in ["../../pnpm-workspace.yaml"] ( `workspace:*`, not npm ). After `changeset version`, ["../../scripts/prepare-native-packages.mjs"] copies the analytical version onto each platform package. The published tarball lists pinned `optionalDependencies` ( `--publish-versions` ) so CLI and MCP customers get the host binary. Platform native packages are not a separate tag channel; they ride `analytical/v*` ( [rust_binary_distribution] ). VSIX packaging uses the package. json versions in that git commit ( [vsix_native_not_from_npm] ). `@reqlan/language`, `@reqlan/cli`, `@reqlan/mcp`, and the site keep their own versions. Contributors record release intent by adding a changeset file when a publishable package changes. | 0.233 | |
| vsix_export | in-progress | One VSIX is built per [native_targets] tuple via `vsce package --target <tuple> --no-dependencies`. Each VSIX keeps today's esbuild-bundled JS ( TS dependency graph stays bundled ); only the matching platform native package is staged into the VSIX so other targets' binaries are excluded. The same VSIX packs `bin/reqlan-lsp` for that target ( ["../extension/language/support/language-server-rust.rq".language_server_rust] ). Azure `collect-napi-binary.mjs --with-lsp` copies that binary into the native artifact. The pack script checks that zip entry by `file_size`. It does not read the binary through a pipe. The napi addon stays for the index host. npm platform packages do not contain it ( [rust_binary_distribution] ). Stamp `targetPlatform` so Marketplace / Open VSX route by extension host ( [extension_host_target], ["./native_host_binary.rq".native_host_binary_distributed] ). Artifact name shape: `reqlan-extension-<version>-<target>.vsix`. The VSIX includes logo assets from the extension media build: PNG for marketplace icon, language file icon, activity bar, and README; WebP as a raster fallback. Implementation: ["../../scripts/package-extension-targets.mjs"], ["../../scripts/prepare-native-packages.mjs"], ["../../scripts/collect-napi-binary.mjs"], ["../../packages/extension/.vscodeignore"] ( `native/`, `bin/` ), ["../../azure-pipelines.yml"]. | 0.446 | |
| native_host_binary | done | Select the native core-engine binary from the extension host. The host is the Node process that runs the extension. Read `process.platform` and `process.arch` from that process. Do not use the platform of the VS Code UI client. Examples: - UI on Windows and host on Linux SSH: use a linux tuple. - UI on Windows and host on WSL: use a linux tuple. - UI and host on macOS: use a darwin tuple. Map the platform and the arch to one tuple in ["./distribution.rq".native_targets]. Load only the binary that matches that tuple. Do not load a binary for a different tuple. If the platform and the arch are not in ["./distribution.rq".native_targets], fail. If the binary is missing, fail. Do not use sql. js. Keep the loader map the same as ["../../scripts/native-targets.mjs"]. Local development: [native_host_binary_development]. Production distribution: [native_host_binary_distributed]. Implementation: ["../../packages/analytical/src/native/load-native.ts"]. | 0.144 | |
| native_host_binary_distributed | in-progress | Use this procedure for a published VSIX and for published npm packages. VS Code extension: The registry installs the VSIX that has `targetPlatform` equal to the extension host. Each VSIX contains one `.node` file for one ["./distribution.rq".native_targets] tuple. The file name is `native/reqlan_napi.node`. The VSIX also contains `native/target.json`. At run time, read `process.platform` and `process.arch` on the extension host. If `target.json` records a different tuple, do not load `native/reqlan_napi.node`. Do not put binaries for other platforms in that VSIX. The Azure pipeline compiles each platform binary from this git commit ( `build_native` + `collect-napi-binary.mjs` + `prepare-native-packages.mjs --binary-dir` ). Package versions in git are canonical. The pipeline does not wait for npm. Related: ["./distribution.rq".vsix_export], ["./distribution.rq".extension_distribution], ["./distribution.rq".vsix_native_not_from_npm]. CLI and MCP: npm installs the host package from `optionalDependencies` on the published `@reqlan/analytical` tarball. Git does not list those entries. ["../../scripts/prepare-native-packages.mjs"] `--publish-versions` writes them at npm publish. The loader resolves that package from `@reqlan/analytical/package.json` ( `createRequire` ), which is where the optional dependency is attached after `npm install`. Published installs also run [published_host_native_install]. Related: ["./distribution.rq".rust_binary_distribution], [rust_port.native_bridge]. Implementation: ["../../scripts/package-extension-targets.mjs"], ["../../scripts/prepare-native-packages.mjs"], ["../../packages/analytical/src/native/load-native.ts"], ["../../packages/analytical/scripts/check-host-native.mjs"], ["../../azure-pipelines.yml"]. | 0.129 |
Reference labels
"../../scripts/prepare-native-packages.mjs", ../../scripts/prepare-native-packages.mjs