@holistics/cli-core 2.4.3 → 2.5.0-internal.0

package/README.md

@@ -13,6 +13,7 @@ The CLI core is using our private packages (such as aml, aml-std, etc...), so to
 The CLI core can also be installed as a package from NPM registry with the name `@holistics/cli-core`.
 This is possible because we already compiled the code into a single `commands.js` file, and removed all the private dependencies (check `bun_build.sh`)
 
+For the code-sync commands (`holistics sync …`) and how a sync session asks for user input, see [docs/sync-cli.md](docs/sync-cli.md).
 
 ## Local build
 - Install `bun` at the version specified in `.bun-version` file.
@@ -20,6 +21,17 @@ This is possible because we already compiled the code into a single `commands.js
 
 If `bun` is not installed at the local, the build will be skipped.
 
+## Native binaries
+
+`@holistics/hwip` is the engine behind `holistics sync`: a Rust addon with one `.node` binary per platform. Its version is cli-core's `@holistics/hwip` pin in `package.json`, installed from GitHub Packages. The registry package ships only the JS loader, and npm installs just the current platform's binary from an optional `@holistics/hwip-<platform>` package. The CLI app only extracts the tarball and never runs `npm install`, so the published package must carry the binaries for every platform the CLI app ships for (`napi.targets` in the installed `@holistics/hwip/package.json`):
+
+- `vendor_hwip.mjs` puts `hwip.<platform>.node` for each target into the installed package's `dist/`, next to the loader, which tries that file first. It downloads them from the `@holistics/hwip-<platform>` packages on GitHub Packages, at the pinned version, using `npm pack`. So it needs the `@holistics` registry and token in `~/.npmrc`, which CI sets up. End users never need that access: the binaries end up inside the public `cli-core` tarball. The package lives in pnpm's virtual store (`node_modules/.pnpm/@holistics+hwip@<version>/`), so a reinstall drops the binaries and the next build downloads them again. Each tarball must match the integrity `pnpm-lock.yaml` records for it: a mismatch fails the download, and a missing entry is a warning locally and a failure on CI. Locally it only downloads the binaries that are missing. If a download fails, it prints a warning. On CI it downloads all of them and fails if one is missing.
+- `bun build` copies each binary the hwip loader `require`s into `dist/` as `hwip.<platform>-<hash>.node` and points the `require` at the copy. A binary that is missing at build time becomes a `throw` in the bundle. That is why `bun_build.sh` then checks that `dist/` has a binary for every target platform.
+
+To update hwip: release it first (`.github/workflows/hwip_tag_and_release.yml`), then bump cli-core's `@holistics/hwip` pin and the lockfile.
+
+This adds about 10 MB per platform to the tarball. `@holistics/aml` needs none of this: `cli-core` uses its default TypeScript parser, and its native parser loads only on request (`AML_PARSER_BACKEND=rust-napi`).
+
 ## Quick run
 For quickly testing the build file, can use the below command to run