@hagicode/hagiscript 0.1.0

package/README.md

@@ -0,0 +1,215 @@
+# Hagiscript
+
+`@hagicode/hagiscript` is the scoped npm package foundation for future Hagiscript language tooling. This initial package intentionally keeps runtime behavior small: it exposes version metadata, a baseline runtime-info API, and an executable CLI placeholder that can be built, tested, packed, and published safely.
+
+## Installation Assumptions
+
+- Node.js 20 or newer is required.
+- npm is the package manager for this standalone repository.
+- The npm package name is `@hagicode/hagiscript`.
+- GitHub Actions publishing uses `npm publish --provenance`. Local manual publishing should use plain `npm publish` unless you are inside a supported trusted publishing environment.
+
+## Usage
+
+Install the package from npm:
+
+```bash
+npm install @hagicode/hagiscript
+```
+
+The installed CLI command remains `hagiscript`.
+
+Run the CLI locally during development:
+
+```bash
+npm run dev -- --help
+npm run dev -- info
+npm run dev -- install-node --target .tmp/node-runtime
+npm run dev -- check-node --target .tmp/node-runtime
+npm run dev -- npm-sync --runtime .tmp/node-runtime --manifest manifest.json
+```
+
+After building, run the compiled CLI:
+
+```bash
+npm run build
+node dist/cli.js --version
+node dist/cli.js info
+node dist/cli.js install-node --target .tmp/node-runtime
+node dist/cli.js check-node --target .tmp/node-runtime
+node dist/cli.js npm-sync --runtime .tmp/node-runtime --manifest manifest.json
+```
+
+### Managed Node.js Runtime Commands
+
+`install-node` downloads an official Node.js archive from `https://nodejs.org/dist`, extracts it into the target directory, and verifies both `node` and `npm` before reporting success.
+
+```bash
+hagiscript install-node --target /opt/hagiscript/node
+hagiscript install-node --target /opt/hagiscript/node20 --version 20
+hagiscript install-node --target /opt/hagiscript/lts --version lts
+```
+
+When `--version` is omitted, Hagiscript installs the latest available Node.js 22 release. Supported selectors are `lts`, `latest`, `current`, a major version such as `22`, an exact version such as `22.12.0`, or an exact version with a `v` prefix such as `v22.12.0`.
+
+The target path must be missing or empty. Hagiscript refuses to install into a non-empty target directory and does not delete existing user files. During installation, temporary staging files are created beside the target directory and cleaned up after success or failure.
+
+Example success output:
+
+```text
+Installing Node.js 22 into /opt/hagiscript/node
+Download progress: 100%
+Node.js runtime installed successfully.
+Target: /opt/hagiscript/node
+Node.js: v22.12.0
+npm: 10.9.0
+node: /opt/hagiscript/node/bin/node
+npm: /opt/hagiscript/node/bin/npm
+```
+
+`check-node` validates an existing runtime directory and exits with code `0` only when both `node --version` and `npm --version` succeed.
+
+```bash
+hagiscript check-node --target /opt/hagiscript/node
+```
+
+Example valid output:
+
+```text
+Node.js runtime is valid.
+Target: /opt/hagiscript/node
+Node.js: v22.12.0
+npm: 10.9.0
+node: /opt/hagiscript/node/bin/node
+npm: /opt/hagiscript/node/bin/npm
+```
+
+Example invalid output exits non-zero and includes the failure reason:
+
+```text
+Node.js runtime is invalid.
+Target: /opt/hagiscript/node
+Reason: missing executable
+```
+
+### npm Global Package Synchronization
+
+`npm-sync` aligns npm global packages inside an explicit Node.js runtime with a JSON manifest. It always uses the `npm` executable resolved from `--runtime`; it does not use or mutate npm from the ambient shell `PATH`.
+
+```bash
+hagiscript npm-sync --runtime /opt/hagiscript/node --manifest ./manifest.json
+```
+
+Manifest schema:
+
+```json
+{
+  "packages": {
+    "<npm-package-name>": {
+      "version": "<semver range>",
+      "target": "<optional npm install selector>"
+    }
+  }
+}
+```
+
+The required `version` field accepts package.json-style semver ranges such as `^1.2.0`, `>=1.0.0 <2.0.0`, or `1.0.0 || 2.0.0`. The optional `target` field controls the selector used for `npm install -g`; when omitted, Hagiscript installs `<package>@<version>`.
+
+Example manifest for openspec and skills tooling:
+
+```json
+{
+  "packages": {
+    "@openspec/cli": {
+      "version": "^1.0.0"
+    },
+    "@hagicode/skills": {
+      "version": ">=0.5.0 <1.0.0",
+      "target": "0.5.4"
+    }
+  }
+}
+```
+
+During execution, Hagiscript validates the manifest and runtime before any npm install command runs, lists global packages with `/opt/hagiscript/node/bin/npm list -g --depth=0 --json`, plans no-op, install, upgrade, downgrade, or sync actions, and then runs `npm install -g <package>@<selector>` only for packages that need changes.
+
+Example output:
+
+```text
+Manifest validated: ./manifest.json (2 packages)
+Runtime validated: /opt/hagiscript/node
+node: /opt/hagiscript/node/bin/node (v22.12.0)
+npm: /opt/hagiscript/node/bin/npm (10.9.0)
+Detected global packages: 4
+Plan: @openspec/cli noop installed=1.0.2 required=^1.0.0 selector=@openspec/cli@^1.0.0
+Skip: @openspec/cli already satisfies range
+Plan: @hagicode/skills upgrade installed=0.4.0 required=>=0.5.0 <1.0.0 selector=@hagicode/skills@0.5.4
+Install: @hagicode/skills using @hagicode/skills@0.5.4
+Synced: @hagicode/skills (upgrade)
+npm-sync complete.
+Runtime: /opt/hagiscript/node
+Manifest: ./manifest.json
+Packages: 2
+No-op: 1
+Changed: 1
+```
+
+Use the library API from ESM consumers:
+
+```ts
+import { createRuntimeInfo, getPackageMetadata } from "@hagicode/hagiscript";
+
+console.log(getPackageMetadata());
+console.log(createRuntimeInfo());
+```
+
+## Development Commands
+
+Run all commands from `repos/hagiscript/`:
+
+```bash
+npm install
+npm run lint
+npm run format:check
+npm test
+npm run build
+npm run pack:check
+```
+
+Additional commands:
+
+```bash
+npm run clean
+npm run format
+npm run test:watch
+npm run publish:prepare-dev-version
+npm run publish:verify-release -- v0.1.0
+```
+
+## Build Outputs
+
+`npm run build` compiles TypeScript with strict NodeNext settings into `dist/`. Expected entry points include:
+
+- `dist/index.js`
+- `dist/index.d.ts`
+- `dist/index.js.map`
+- `dist/cli.js`
+- `dist/cli.d.ts`
+- `dist/cli.js.map`
+
+The package `exports` field points consumers to `dist/index.js` and `dist/index.d.ts`. The published package name is `@hagicode/hagiscript`, and the `bin.hagiscript` entry points to `dist/cli.js`.
+
+## Package Verification
+
+`npm run pack:check` runs a dry-run package inspection and fails if required runtime files are missing or source-only files are accidentally included. The published package should contain generated `dist` files and documentation, not raw tests, scripts, coverage, or temporary files.
+
+## Release Automation
+
+GitHub Actions provide three automation paths:
+
+- `ci.yml` installs dependencies with `npm ci`, then runs lint, format check, tests, build, and package verification.
+- `npm-publish.yml` publishes a unique prerelease version to the `dev` dist-tag from `main`.
+- `npm-publish.yml` also publishes stable GitHub releases tagged as `vX.Y.Z` to the `latest` dist-tag after validating the tag against `package.json`.
+- `release-drafter.yml` keeps a categorized release draft using `.github/release-drafter.yml`.
+
+Before the first publish, make sure the npm organization `hagicode` exists and grant publish access for `@hagicode/hagiscript`. For GitHub Actions releases, configure npm trusted publishing. For local manual releases, run plain `npm publish`.

package/README_cn.md

@@ -0,0 +1,215 @@
+# Hagiscript
+
+`@hagicode/hagiscript` 是 Hagiscript 语言工具链的作用域 npm 包基础工程。本次初始化只提供最小运行能力：版本元数据、基础运行时信息 API，以及一个可构建、可测试、可打包、可发布的 CLI 占位入口。
+
+## 安装假设
+
+- 需要 Node.js 20 或更高版本。
+- 该独立仓库使用 npm 作为包管理器。
+- npm 包名为 `@hagicode/hagiscript`。
+- GitHub Actions 发布使用 `npm publish --provenance`。本地手动发布时，应直接使用普通 `npm publish`，除非当前环境本身就是受支持的 trusted publishing 环境。
+
+## 使用方式
+
+先从 npm 安装该包：
+
+```bash
+npm install @hagicode/hagiscript
+```
+
+安装后的 CLI 命令仍然是 `hagiscript`。
+
+开发时运行 CLI：
+
+```bash
+npm run dev -- --help
+npm run dev -- info
+npm run dev -- install-node --target .tmp/node-runtime
+npm run dev -- check-node --target .tmp/node-runtime
+npm run dev -- npm-sync --runtime .tmp/node-runtime --manifest manifest.json
+```
+
+构建后运行编译产物：
+
+```bash
+npm run build
+node dist/cli.js --version
+node dist/cli.js info
+node dist/cli.js install-node --target .tmp/node-runtime
+node dist/cli.js check-node --target .tmp/node-runtime
+node dist/cli.js npm-sync --runtime .tmp/node-runtime --manifest manifest.json
+```
+
+### 托管 Node.js 运行时命令
+
+`install-node` 会从 `https://nodejs.org/dist` 下载官方 Node.js 归档包，解压到目标目录，并在成功前验证 `node` 与 `npm` 都可执行。
+
+```bash
+hagiscript install-node --target /opt/hagiscript/node
+hagiscript install-node --target /opt/hagiscript/node20 --version 20
+hagiscript install-node --target /opt/hagiscript/lts --version lts
+```
+
+省略 `--version` 时，Hagiscript 默认安装最新可用的 Node.js 22 版本。支持的选择器包括 `lts`、`latest`、`current`、类似 `22` 的主版本号、类似 `22.12.0` 的精确版本，以及类似 `v22.12.0` 的带 `v` 精确版本。
+
+目标路径必须不存在或为空目录。Hagiscript 会拒绝安装到非空目标目录，也不会删除已有用户文件。安装期间，临时 staging 文件会创建在目标目录旁边，并在成功或失败后清理。
+
+成功输出示例：
+
+```text
+Installing Node.js 22 into /opt/hagiscript/node
+Download progress: 100%
+Node.js runtime installed successfully.
+Target: /opt/hagiscript/node
+Node.js: v22.12.0
+npm: 10.9.0
+node: /opt/hagiscript/node/bin/node
+npm: /opt/hagiscript/node/bin/npm
+```
+
+`check-node` 会验证已有运行时目录；只有 `node --version` 和 `npm --version` 都成功时才以退出码 `0` 结束。
+
+```bash
+hagiscript check-node --target /opt/hagiscript/node
+```
+
+有效运行时输出示例：
+
+```text
+Node.js runtime is valid.
+Target: /opt/hagiscript/node
+Node.js: v22.12.0
+npm: 10.9.0
+node: /opt/hagiscript/node/bin/node
+npm: /opt/hagiscript/node/bin/npm
+```
+
+无效运行时会以非零退出码结束，并输出失败原因：
+
+```text
+Node.js runtime is invalid.
+Target: /opt/hagiscript/node
+Reason: missing executable
+```
+
+### npm 全局包同步
+
+`npm-sync` 会根据 JSON manifest，把指定 Node.js 运行时中的 npm 全局包版本同步到约束范围内。它始终使用 `--runtime` 解析出的 `npm` 可执行文件，不会使用或修改当前 shell `PATH` 中的 npm。
+
+```bash
+hagiscript npm-sync --runtime /opt/hagiscript/node --manifest ./manifest.json
+```
+
+Manifest 结构：
+
+```json
+{
+  "packages": {
+    "<npm-package-name>": {
+      "version": "<semver range>",
+      "target": "<optional npm install selector>"
+    }
+  }
+}
+```
+
+必填的 `version` 字段使用 package.json 风格的 semver 范围，例如 `^1.2.0`、`>=1.0.0 <2.0.0` 或 `1.0.0 || 2.0.0`。可选的 `target` 字段用于指定实际执行 `npm install -g` 时使用的选择器；如果省略，Hagiscript 会安装 `<package>@<version>`。
+
+openspec 和 skills 工具同步示例：
+
+```json
+{
+  "packages": {
+    "@openspec/cli": {
+      "version": "^1.0.0"
+    },
+    "@hagicode/skills": {
+      "version": ">=0.5.0 <1.0.0",
+      "target": "0.5.4"
+    }
+  }
+}
+```
+
+执行时，Hagiscript 会先验证 manifest 和运行时，再执行任何 npm install 操作；它会用 `/opt/hagiscript/node/bin/npm list -g --depth=0 --json` 检测全局包，生成 no-op、install、upgrade、downgrade 或 sync 计划，然后只对需要变更的包执行 `npm install -g <package>@<selector>`。
+
+输出示例：
+
+```text
+Manifest validated: ./manifest.json (2 packages)
+Runtime validated: /opt/hagiscript/node
+node: /opt/hagiscript/node/bin/node (v22.12.0)
+npm: /opt/hagiscript/node/bin/npm (10.9.0)
+Detected global packages: 4
+Plan: @openspec/cli noop installed=1.0.2 required=^1.0.0 selector=@openspec/cli@^1.0.0
+Skip: @openspec/cli already satisfies range
+Plan: @hagicode/skills upgrade installed=0.4.0 required=>=0.5.0 <1.0.0 selector=@hagicode/skills@0.5.4
+Install: @hagicode/skills using @hagicode/skills@0.5.4
+Synced: @hagicode/skills (upgrade)
+npm-sync complete.
+Runtime: /opt/hagiscript/node
+Manifest: ./manifest.json
+Packages: 2
+No-op: 1
+Changed: 1
+```
+
+在 ESM 项目中使用库 API：
+
+```ts
+import { createRuntimeInfo, getPackageMetadata } from "@hagicode/hagiscript";
+
+console.log(getPackageMetadata());
+console.log(createRuntimeInfo());
+```
+
+## 开发命令
+
+所有命令都应在 `repos/hagiscript/` 下执行：
+
+```bash
+npm install
+npm run lint
+npm run format:check
+npm test
+npm run build
+npm run pack:check
+```
+
+其他常用命令：
+
+```bash
+npm run clean
+npm run format
+npm run test:watch
+npm run publish:prepare-dev-version
+npm run publish:verify-release -- v0.1.0
+```
+
+## 构建输出
+
+`npm run build` 会使用严格的 NodeNext TypeScript 配置编译到 `dist/`。预期入口文件包括：
+
+- `dist/index.js`
+- `dist/index.d.ts`
+- `dist/index.js.map`
+- `dist/cli.js`
+- `dist/cli.d.ts`
+- `dist/cli.js.map`
+
+`package.json` 的 `exports` 字段指向 `dist/index.js` 和 `dist/index.d.ts`。发布到 npm 后的包名是 `@hagicode/hagiscript`，`bin.hagiscript` 指向 `dist/cli.js`。
+
+## 包内容校验
+
+`npm run pack:check` 会执行 dry-run 打包检查。如果缺少必要运行文件，或错误包含源码测试、脚本、覆盖率、临时目录等只应存在于开发环境的文件，脚本会失败。
+
+## 发布自动化
+
+GitHub Actions 提供三类自动化流程：
+
+- `ci.yml` 使用 `npm ci` 安装依赖，并执行 lint、格式检查、测试、构建和包内容校验。
+- `npm-publish.yml` 在 `main` 分支发布唯一预发布版本到 `dev` dist-tag。
+- `npm-publish.yml` 也会在非草稿、非 prerelease 的 GitHub Release 发布时，校验 `vX.Y.Z` 标签并发布到 `latest` dist-tag。
+- `release-drafter.yml` 通过 `.github/release-drafter.yml` 维护分类清晰的发布草稿。
+
+首次发布前，需要先确保 npm 组织 `hagicode` 已存在，并且 `@hagicode/hagiscript` 已授权当前发布主体。GitHub Actions 发布时再配置 trusted publishing；本地手动发布时直接执行普通 `npm publish` 即可。

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+export declare function createCli(): Command;
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { createRuntimeInfo, packageVersion } from "./index.js";
+import { registerNpmSyncCommand } from "./commands/npm-sync-commands.js";
+import { registerNodeRuntimeCommands } from "./commands/node-runtime-commands.js";
+export function createCli() {
+    const program = new Command();
+    program
+        .name("hagiscript")
+        .description("Hagiscript language tooling CLI foundation.")
+        .version(packageVersion, "-v, --version", "print the hagiscript version");
+    program
+        .command("info")
+        .description("print package foundation metadata")
+        .action(() => {
+        const info = createRuntimeInfo();
+        process.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
+    });
+    registerNodeRuntimeCommands(program);
+    registerNpmSyncCommand(program);
+    program.action(() => {
+        program.outputHelp();
+    });
+    return program;
+}
+export async function runCli(argv = process.argv) {
+    const program = createCli();
+    await program.parseAsync(argv);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runCli().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAElF,MAAM,UAAU,SAAS;IACvB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,YAAY,CAAC;SAClB,WAAW,CAAC,6CAA6C,CAAC;SAC1D,OAAO,CAAC,cAAc,EAAE,eAAe,EAAE,8BAA8B,CAAC,CAAC;IAE5E,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,mCAAmC,CAAC;SAChD,MAAM,CAAC,GAAG,EAAE;QACX,MAAM,IAAI,GAAG,iBAAiB,EAAE,CAAC;QACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEL,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACrC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAEhC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE;QAClB,OAAO,CAAC,UAAU,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI;IAC9C,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC;IAC5B,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACpD,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAChC,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;QACrC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/node-runtime-commands.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerNodeRuntimeCommands(program: Command): void;

package/dist/commands/node-runtime-commands.js

@@ -0,0 +1,88 @@
+import { InvalidArgumentError } from "commander";
+import { installNodeRuntime } from "../runtime/node-installer.js";
+import { validateVersionSelector } from "../runtime/node-release.js";
+import { verifyNodeRuntime } from "../runtime/node-verify.js";
+export function registerNodeRuntimeCommands(program) {
+    program
+        .command("install-node")
+        .description("install an official Node.js runtime into a target directory")
+        .requiredOption("--target <path>", "empty target directory for the managed runtime")
+        .option("--version <selector>", "Node.js selector: lts, latest, current, 22, 22.11.0, or v22.11.0", validateVersionOption)
+        .action(async (options, command) => {
+        const target = validateTargetOption(options.target);
+        const versionSelector = options.version;
+        try {
+            process.stdout.write(`Installing Node.js ${versionSelector ?? "22"} into ${target}\n`);
+            const result = await installNodeRuntime({
+                targetDirectory: target,
+                versionSelector,
+                onProgress: (progress) => {
+                    if (progress.totalBytes && progress.totalBytes > 0) {
+                        const percent = Math.floor((progress.receivedBytes / progress.totalBytes) * 100);
+                        process.stdout.write(`Download progress: ${percent}%\r`);
+                    }
+                    else {
+                        process.stdout.write(`Downloaded ${progress.receivedBytes} bytes\r`);
+                    }
+                }
+            });
+            process.stdout.write("\n");
+            process.stdout.write(`Node.js runtime installed successfully.\n`);
+            process.stdout.write(`Target: ${result.targetDirectory}\n`);
+            process.stdout.write(`Node.js: ${result.version}\n`);
+            process.stdout.write(`npm: ${result.npmVersion}\n`);
+            process.stdout.write(`node: ${result.nodePath}\n`);
+            process.stdout.write(`npm: ${result.npmPath}\n`);
+        }
+        catch (error) {
+            command.error(formatCommandError("install-node failed", error), {
+                exitCode: 1
+            });
+        }
+    });
+    program
+        .command("check-node")
+        .description("validate an existing HagicScript-managed Node.js runtime")
+        .requiredOption("--target <path>", "target runtime directory to validate")
+        .action(async (options, command) => {
+        const target = validateTargetOption(options.target);
+        const result = await verifyNodeRuntime(target);
+        if (!result.valid) {
+            process.stderr.write(`Node.js runtime is invalid.\n`);
+            process.stderr.write(`Target: ${result.targetDirectory}\n`);
+            process.stderr.write(`Reason: ${result.failureReason ?? "unknown failure"}\n`);
+            command.error("check-node failed", { exitCode: 1 });
+            return;
+        }
+        process.stdout.write(`Node.js runtime is valid.\n`);
+        process.stdout.write(`Target: ${result.targetDirectory}\n`);
+        process.stdout.write(`Node.js: ${result.nodeVersion}\n`);
+        process.stdout.write(`npm: ${result.npmVersion}\n`);
+        process.stdout.write(`node: ${result.nodePath}\n`);
+        process.stdout.write(`npm: ${result.npmPath}\n`);
+    });
+}
+function validateVersionOption(value) {
+    try {
+        validateVersionSelector(value);
+        return value;
+    }
+    catch (error) {
+        throw new InvalidArgumentError(error instanceof Error ? error.message : String(error));
+    }
+}
+function validateTargetOption(value) {
+    const target = value?.trim();
+    if (!target) {
+        throw new InvalidArgumentError("--target must be a non-empty path.");
+    }
+    if (target.includes("\0")) {
+        throw new InvalidArgumentError("--target contains an invalid null byte.");
+    }
+    return target;
+}
+function formatCommandError(prefix, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `${prefix}: ${message}`;
+}
+//# sourceMappingURL=node-runtime-commands.js.map

package/dist/commands/node-runtime-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-runtime-commands.js","sourceRoot":"","sources":["../../src/commands/node-runtime-commands.ts"],"names":[],"mappings":"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"}

package/dist/commands/npm-sync-commands.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerNpmSyncCommand(program: Command): void;

package/dist/commands/npm-sync-commands.js

@@ -0,0 +1,92 @@
+import { InvalidArgumentError } from "commander";
+import { NpmManifestValidationError, NpmSyncCommandError, syncNpmGlobals } from "../runtime/npm-sync.js";
+export function registerNpmSyncCommand(program) {
+    program
+        .command("npm-sync")
+        .description("sync npm global packages in an explicit Node.js runtime")
+        .requiredOption("--runtime <path>", "target Node.js runtime directory")
+        .requiredOption("--manifest <path>", "npm-sync manifest JSON file")
+        .action(async (options, command) => {
+        const runtimePath = validatePathOption(options.runtime, "--runtime");
+        const manifestPath = validatePathOption(options.manifest, "--manifest");
+        try {
+            await syncNpmGlobals({
+                runtimePath,
+                manifestPath,
+                onLog: printNpmSyncLog
+            });
+        }
+        catch (error) {
+            command.error(formatNpmSyncError(error), { exitCode: 1 });
+        }
+    });
+}
+function validatePathOption(value, optionName) {
+    const normalized = value?.trim();
+    if (!normalized) {
+        throw new InvalidArgumentError(`${optionName} must be a non-empty path.`);
+    }
+    if (normalized.includes("\0")) {
+        throw new InvalidArgumentError(`${optionName} contains an invalid null byte.`);
+    }
+    return normalized;
+}
+function printNpmSyncLog(event) {
+    switch (event.type) {
+        case "manifest-loaded":
+            process.stdout.write(`Manifest validated: ${event.manifestPath} (${event.packageCount} packages)\n`);
+            break;
+        case "runtime-valid":
+            process.stdout.write(`Runtime validated: ${event.runtime.targetDirectory}\n`);
+            process.stdout.write(`node: ${event.runtime.nodePath} (${event.runtime.nodeVersion})\n`);
+            process.stdout.write(`npm: ${event.runtime.npmPath} (${event.runtime.npmVersion})\n`);
+            break;
+        case "inventory":
+            process.stdout.write(`Detected global packages: ${Object.keys(event.packages).sort().length}\n`);
+            break;
+        case "planned-action":
+            process.stdout.write(`Plan: ${event.action.packageName} ${event.action.action} installed=${event.action.installedVersion ?? "missing"} required=${event.action.requiredRange} selector=${event.action.selectedInstallSelector}\n`);
+            break;
+        case "skip":
+            process.stdout.write(`Skip: ${event.action.packageName} already satisfies range\n`);
+            break;
+        case "install-start":
+            process.stdout.write(`Install: ${event.action.packageName} using ${event.action.selectedInstallSelector}\n`);
+            break;
+        case "install-complete":
+            process.stdout.write(`Synced: ${event.action.packageName} (${event.action.action})\n`);
+            break;
+        case "summary":
+            printSummary(event.summary);
+            break;
+    }
+}
+function printSummary(summary) {
+    process.stdout.write(`npm-sync complete.\n`);
+    process.stdout.write(`Runtime: ${summary.runtime.targetDirectory}\n`);
+    process.stdout.write(`Manifest: ${summary.manifestPath}\n`);
+    process.stdout.write(`Packages: ${summary.packageCount}\n`);
+    process.stdout.write(`No-op: ${summary.noopCount}\n`);
+    process.stdout.write(`Changed: ${summary.changedCount}\n`);
+}
+function formatNpmSyncError(error) {
+    if (error instanceof NpmManifestValidationError) {
+        return error.message;
+    }
+    if (error instanceof NpmSyncCommandError) {
+        const lines = [error.message];
+        if (error.packageName) {
+            lines.push(`Package: ${error.packageName}`);
+        }
+        lines.push(`Command: ${error.command} ${error.args.join(" ")}`);
+        if (error.stderr.trim().length > 0) {
+            lines.push(`stderr: ${error.stderr.trim()}`);
+        }
+        if (error.stdout.trim().length > 0) {
+            lines.push(`stdout: ${error.stdout.trim()}`);
+        }
+        return lines.join("\n");
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=npm-sync-commands.js.map