@hagicode/hagiscript 0.1.0-dev.9.1.ba06982

package/README.md

@@ -0,0 +1,251 @@
+# 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 a HagiScript-managed Node.js runtime with a JSON manifest. By default, it verifies or installs the managed runtime at `~/.hagiscript/node-runtime` and uses that runtime's `npm`; it does not use or mutate npm from the ambient shell `PATH`. Existing automation can keep passing `--runtime` to use an explicit runtime directory.
+
+```bash
+hagiscript npm-sync --manifest ./manifest.json
+hagiscript npm-sync --runtime /opt/hagiscript/node --manifest ./manifest.json
+```
+
+Compatibility 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>`.
+
+Product-managed tool sync can use the expanded `tools` manifest shape. Mandatory tools are always included using internally pinned versions from `src/runtime/tool-sync-catalog.config.json`: OpenSpec skills (`skills@1.5.1`), OmniRoute (`omniroute@3.6.9`), and code-server (`code-server@4.117.0`). Optional agent CLI sync is enabled explicitly; selected built-in CLIs or custom npm packages are added when provided.
+
+```json
+{
+  "tools": {
+    "optionalAgentCliSyncEnabled": true,
+    "selectedOptionalAgentCliIds": ["codex", "opencode"],
+    "customAgentClis": [
+      {
+        "packageName": "@scope/agent-cli",
+        "version": "^1.0.0"
+      }
+    ]
+  }
+}
+```
+
+The first built-in optional agent CLI IDs are `codex` (`@openai/codex@0.125.0`), `qoder` (`@qoder-ai/qodercli@0.1.48`), and `opencode` (`opencode-ai@1.14.24`). These built-in package versions are pinned in `src/runtime/tool-sync-catalog.config.json`. HagiScript validates unknown tool IDs, npm package names, and version selectors before `npm list` or `npm install` runs.
+
+For simple product-managed requests, optional CLI selections can be provided directly without writing a manifest:
+
+```bash
+hagiscript npm-sync --selected-agent-cli codex
+hagiscript npm-sync --selected-agent-cli codex --custom-agent-cli @scope/agent-cli@^1.0.0
+```
+
+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, mode=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
+Mode: packages
+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` resolves a unique prerelease version from `main`, stamps both `package.json` and `package-lock.json` with `npm version --no-git-tag-version`, then publishes to the `dev` dist-tag.
+- `npm-publish.yml` also publishes stable GitHub releases tagged as `vX.Y.Z` to the `latest` dist-tag after validating and stamping the stable version the same way.
+- `release-drafter.yml` keeps a categorized release draft using `.github/release-drafter.yml`.
+
+Before the first publish, make sure the npm organization or user scope `hagicode` exists on npm and grant publish access for `@hagicode/hagiscript`. For GitHub Actions releases, configure npm trusted publishing with package `@hagicode/hagiscript`, owner `HagiCode-org`, repository `hagiscript`, and workflow filename `npm-publish.yml`. Do not enter the full workflow path as the filename; leave the npm environment field empty unless the workflow job explicitly declares an environment. If the scope is missing or the workflow identity cannot create packages under it, npm returns `E404 Not Found` during the final `PUT https://registry.npmjs.org/@hagicode%2fhagiscript` publish request.
+
+Run the publish prerequisite check before retrying a failed release:
+
+```bash
+npm run publish:check-prereqs
+```
+
+For local manual releases, run plain `npm publish` after logging in with an npm account that can publish under `@hagicode`.

package/README_cn.md

@@ -0,0 +1,251 @@
+# 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，把 HagiScript 托管 Node.js 运行时中的 npm 全局包版本同步到约束范围内。默认情况下，它会验证或安装 `~/.hagiscript/node-runtime`，并使用该运行时内的 `npm`；它不会使用或修改当前 shell `PATH` 中的 npm。已有自动化仍可继续传入 `--runtime` 使用显式运行时目录。
+
+```bash
+hagiscript npm-sync --manifest ./manifest.json
+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>`。
+
+产品托管的工具同步可使用扩展后的 `tools` manifest。必选工具始终会按 `src/runtime/tool-sync-catalog.config.json` 中的内部固定版本纳入同步：OpenSpec skills（`skills@1.5.1`）、OmniRoute（`omniroute@3.6.9`）和 code-server（`code-server@4.117.0`）。可选 agent CLI 同步需要显式启用；如果传入内置 CLI 或自定义 npm 包选择，它们会被加入同步。
+
+```json
+{
+  "tools": {
+    "optionalAgentCliSyncEnabled": true,
+    "selectedOptionalAgentCliIds": ["codex", "opencode"],
+    "customAgentClis": [
+      {
+        "packageName": "@scope/agent-cli",
+        "version": "^1.0.0"
+      }
+    ]
+  }
+}
+```
+
+首批内置可选 agent CLI ID 为 `codex`（`@openai/codex@0.125.0`）、`qoder`（`@qoder-ai/qodercli@0.1.48`）和 `opencode`（`opencode-ai@1.14.24`）。这些内置包版本固定在 `src/runtime/tool-sync-catalog.config.json` 中。HagiScript 会在执行 `npm list` 或 `npm install` 前校验未知工具 ID、npm 包名和版本选择器。
+
+简单的产品托管请求也可以直接通过 CLI 选项传入可选 CLI，而不必先写 manifest：
+
+```bash
+hagiscript npm-sync --selected-agent-cli codex
+hagiscript npm-sync --selected-agent-cli codex --custom-agent-cli @scope/agent-cli@^1.0.0
+```
+
+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, mode=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
+Mode: packages
+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` 分支解析唯一预发布版本，用 `npm version --no-git-tag-version` 同步 `package.json` 和 `package-lock.json`，再发布到 `dev` dist-tag。
+- `npm-publish.yml` 也会在非草稿、非 prerelease 的 GitHub Release 发布时，校验 `vX.Y.Z` 标签，用同样方式写入稳定版本并发布到 `latest` dist-tag。
+- `release-drafter.yml` 通过 `.github/release-drafter.yml` 维护分类清晰的发布草稿。
+
+首次发布前，需要先确保 npm 上已经存在组织或用户 scope `hagicode`，并且 `@hagicode/hagiscript` 已授权当前发布主体。GitHub Actions 发布时，需要在 npm trusted publishing 中配置：package `@hagicode/hagiscript`、owner `HagiCode-org`、repository `hagiscript`、workflow filename `npm-publish.yml`。不要把 workflow filename 填成完整路径；如果 npm 表单有 environment 字段，除非 workflow job 显式声明了 environment，否则保持为空。如果 scope 不存在，或 workflow 身份无权在该 scope 下创建包，npm 会在最后的 `PUT https://registry.npmjs.org/@hagicode%2fhagiscript` 发布请求中返回 `E404 Not Found`。
+
+重试失败的发布前，先运行发布前置检查：
+
+```bash
+npm run publish:check-prereqs
+```
+
+本地手动发布时，先登录一个有权发布到 `@hagicode` scope 的 npm 账号，再直接执行普通 `npm publish`。

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+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);
+}
+export function isCliEntrypoint(moduleUrl = import.meta.url, argvPath = process.argv[1]) {
+    if (!argvPath) {
+        return false;
+    }
+    try {
+        return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argvPath);
+    }
+    catch {
+        return false;
+    }
+}
+if (isCliEntrypoint()) {
+    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,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,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,MAAM,UAAU,eAAe,CAC7B,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAC3B,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAE1B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,KAAK,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,eAAe,EAAE,EAAE,CAAC;IACtB,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;