@hagicode/hagiscript 0.1.0 → 0.1.3

package/README.md

@@ -94,16 +94,20 @@ 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`.
+`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
+hagiscript npm-sync --manifest ./manifest.json --registry-mirror https://registry.npmmirror.com/
+hagiscript npm-sync --manifest ./manifest.json --registry-mirror https://registry.npmmirror.com/ --mirror-only
 ```
 
-Manifest schema:
+Compatibility manifest schema:
 
 ```json
 {
+  "registryMirror": "https://registry.npmmirror.com/",
   "packages": {
     "<npm-package-name>": {
       "version": "<semver range>",
@@ -115,6 +119,39 @@ Manifest schema:
 
 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>`.
 
+The optional top-level `registryMirror` field configures the npm registry used for both inventory and install commands. It must be a non-empty absolute `http:` or `https:` URL. When present, HagiScript first appends `--registry <registryMirror>` to `npm list -g --depth=0 --json` and `npm install -g <package>@<selector>` without changing package selection. If that mirror-backed npm command fails, HagiScript automatically retries the same inventory or install command once against the official npm registry `https://registry.npmjs.org/`. This mirror-first retry scope is intentionally limited to npm inventory and package mutation commands; runtime validation, manifest validation, and package planning do not retry. This is useful for public mirrors such as `https://registry.npmmirror.com/` or enterprise registries such as `https://npm.company.example/repository/npm/`.
+
+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
+{
+  "registryMirror": "https://npm.company.example/repository/npm/",
+  "tools": {
+    "optionalAgentCliSyncEnabled": true,
+    "selectedOptionalAgentCliIds": ["codex", "claude-code", "fission-openspec", "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`), `claude-code` (`@anthropic-ai/claude-code@2.1.119`), `fission-openspec` (`@fission-ai/openspec@1.3.1`), `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.
+
+Use `--registry-mirror <url>` when automation needs to override the manifest registry for a single run. Precedence is CLI override first, manifest `registryMirror` second, and npm's default registry behavior third. If neither the CLI nor manifest provides a mirror, HagiScript does not add `--registry` and existing npm defaults, `.npmrc`, or environment configuration continue to apply.
+
+Use `--mirror-only` when a run must stay on the configured mirror and must not retry against `https://registry.npmjs.org/`. When omitted, automatic official-registry fallback remains enabled by default for mirror-backed npm inventory and install commands.
+
+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
@@ -136,7 +173,9 @@ During execution, Hagiscript validates the manifest and runtime before any npm i
 Example output:
 
 ```text
-Manifest validated: ./manifest.json (2 packages)
+Manifest validated: ./manifest.json (2 packages, mode=packages)
+Registry mirror: https://registry.npmmirror.com/
+Fallback policy: auto
 Runtime validated: /opt/hagiscript/node
 node: /opt/hagiscript/node/bin/node (v22.12.0)
 npm: /opt/hagiscript/node/bin/npm (10.9.0)
@@ -149,11 +188,17 @@ Synced: @hagicode/skills (upgrade)
 npm-sync complete.
 Runtime: /opt/hagiscript/node
 Manifest: ./manifest.json
+Mode: packages
+Registry mirror: https://registry.npmmirror.com/
+Fallback policy: auto
+Fallback used: no
 Packages: 2
 No-op: 1
 Changed: 1
 ```
 
+When fallback is triggered, HagiScript logs `Fallback used: ...` during execution and records `Fallback detail: ...` in the final summary so CI or desktop automation can see which mirror failed, which official registry retry was used, and whether that retry succeeded.
+
 Use the library API from ESM consumers:
 
 ```ts
@@ -207,9 +252,17 @@ The package `exports` field points consumers to `dist/index.js` and `dist/index.
 
 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`.
+- `ci.yml` installs dependencies with `npm ci`, then runs 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 the tag format, rejecting tags older than the repository base version, 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 `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`.
+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

@@ -94,13 +94,16 @@ Reason: missing executable
 
 ### npm 全局包同步
 
-`npm-sync` 会根据 JSON manifest，把指定 Node.js 运行时中的 npm 全局包版本同步到约束范围内。它始终使用 `--runtime` 解析出的 `npm` 可执行文件，不会使用或修改当前 shell `PATH` 中的 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
+hagiscript npm-sync --manifest ./manifest.json --registry-mirror https://registry.npmmirror.com/
+hagiscript npm-sync --manifest ./manifest.json --registry-mirror https://registry.npmmirror.com/ --mirror-only
 ```
 
-Manifest 结构：
+兼容模式 manifest 结构：
 
 ```json
 {
@@ -115,6 +118,38 @@ Manifest 结构：
 
 必填的 `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>`。
 
+可选的顶层 `registryMirror` 字段用于指定 npm 检测与安装命令所使用的镜像地址，必须是非空的绝对 `http:` 或 `https:` URL。配置后，Hagiscript 会先对 `npm list -g --depth=0 --json` 和 `npm install -g <package>@<selector>` 追加 `--registry <registryMirror>` 并优先走镜像；如果镜像对应的 npm 命令失败，则会把同一条 inventory 或 install 命令自动重试一次到官方源 `https://registry.npmjs.org/`。这个自动降级只作用于 npm inventory 与包变更命令，不会重试运行时校验、manifest 校验或同步计划计算。
+
+产品托管的工具同步可使用扩展后的 `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", "claude-code", "fission-openspec", "opencode"],
+    "customAgentClis": [
+      {
+        "packageName": "@scope/agent-cli",
+        "version": "^1.0.0"
+      }
+    ]
+  }
+}
+```
+
+首批内置可选 agent CLI ID 为 `codex`（`@openai/codex@0.125.0`）、`claude-code`（`@anthropic-ai/claude-code@2.1.119`）、`fission-openspec`（`@fission-ai/openspec@1.3.1`）、`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 包名和版本选择器。
+
+使用 `--registry-mirror <url>` 可以在单次运行中覆盖 manifest 中的镜像地址，优先级依次为 CLI 覆盖、manifest 的 `registryMirror`、以及 npm 默认注册表行为。如果 CLI 与 manifest 都没有提供镜像，Hagiscript 就不会附加 `--registry`，现有的 npm 默认设置、`.npmrc` 或环境变量行为会保持不变。
+
+如果某次同步必须严格停留在镜像源且不能自动切回官方源，请添加 `--mirror-only`。省略该选项时，只要配置了镜像，Hagiscript 默认就会在镜像失败后自动回退到 `https://registry.npmjs.org/` 一次。
+
+简单的产品托管请求也可以直接通过 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
@@ -136,7 +171,9 @@ openspec 和 skills 工具同步示例：
 输出示例：
 
 ```text
-Manifest validated: ./manifest.json (2 packages)
+Manifest validated: ./manifest.json (2 packages, mode=packages)
+Registry mirror: https://registry.npmmirror.com/
+Fallback policy: auto
 Runtime validated: /opt/hagiscript/node
 node: /opt/hagiscript/node/bin/node (v22.12.0)
 npm: /opt/hagiscript/node/bin/npm (10.9.0)
@@ -149,11 +186,17 @@ Synced: @hagicode/skills (upgrade)
 npm-sync complete.
 Runtime: /opt/hagiscript/node
 Manifest: ./manifest.json
+Mode: packages
+Registry mirror: https://registry.npmmirror.com/
+Fallback policy: auto
+Fallback used: no
 Packages: 2
 No-op: 1
 Changed: 1
 ```
 
+如果触发了回退，Hagiscript 会在执行期间输出 `Fallback used: ...`，并在最终摘要中记录 `Fallback detail: ...`，这样 CI 或桌面端自动化就能明确知道哪个镜像失败了、是否切到了官方源，以及官方源重试是否成功。
+
 在 ESM 项目中使用库 API：
 
 ```ts
@@ -207,9 +250,17 @@ npm run publish:verify-release -- v0.1.0
 
 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。
+- `ci.yml` 使用 `npm ci` 安装依赖，并执行测试、构建和包内容校验。
+- `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 组织 `hagicode` 已存在，并且 `@hagicode/hagiscript` 已授权当前发布主体。GitHub Actions 发布时再配置 trusted publishing；本地手动发布时直接执行普通 `npm publish` 即可。
+首次发布前，需要先确保 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

@@ -2,3 +2,4 @@
 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

@@ -1,4 +1,6 @@
 #!/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";
@@ -27,7 +29,18 @@ export async function runCli(argv = process.argv) {
     const program = createCli();
     await program.parseAsync(argv);
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
+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`);

package/dist/cli.js.map

@@ -1 +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"}
+{"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/npm-sync-commands.js

@@ -1,18 +1,49 @@
 import { InvalidArgumentError } from "commander";
-import { NpmManifestValidationError, NpmSyncCommandError, syncNpmGlobals } from "../runtime/npm-sync.js";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getDefaultManagedNodeRuntimeDirectory, resolveManagedNodeRuntime } from "../runtime/node-installer.js";
+import { NpmManifestValidationError, NpmSyncCommandError, syncNpmGlobals, validateRegistryMirror } 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")
+        .description("sync managed npm tools using HagiScript's Node.js runtime, or an explicit runtime for compatibility")
+        .option("--runtime <path>", "explicit Node.js runtime directory")
+        .option("--managed-runtime <path>", "HagiScript-managed runtime directory to verify or install before sync")
+        .option("--manifest <path>", "npm-sync manifest JSON file")
+        .option("--registry-mirror <url>", "npm registry mirror URL to use for this sync run")
+        .option("--mirror-only", "disable automatic retry against https://registry.npmjs.org/ when a registry mirror is configured")
+        .option("--selected-agent-cli <id>", "selected optional agent CLI ID for product-managed tool sync", collectValues, [])
+        .option("--custom-agent-cli <package[@version]>", "custom npm-installable agent CLI for product-managed tool sync", collectValues, [])
         .action(async (options, command) => {
-        const runtimePath = validatePathOption(options.runtime, "--runtime");
-        const manifestPath = validatePathOption(options.manifest, "--manifest");
+        const explicitRuntime = options.runtime
+            ? validatePathOption(options.runtime, "--runtime")
+            : undefined;
+        const registryMirror = validateRegistryMirror(options.registryMirror, "--registry-mirror");
+        const selectedAgentCliIds = options.selectedAgentCli ?? [];
+        const customAgentCliSelectors = options.customAgentCli ?? [];
+        const hasInlineToolSelection = selectedAgentCliIds.length > 0 || customAgentCliSelectors.length > 0;
+        const manifestPath = options.manifest
+            ? validatePathOption(options.manifest, "--manifest")
+            : hasInlineToolSelection
+                ? await writeInlineToolManifest(selectedAgentCliIds, customAgentCliSelectors)
+                : undefined;
+        if (!manifestPath) {
+            throw new InvalidArgumentError("--manifest is required unless --selected-agent-cli or --custom-agent-cli is provided.");
+        }
+        const managedRuntimePath = options.managedRuntime
+            ? validatePathOption(options.managedRuntime, "--managed-runtime")
+            : getDefaultManagedNodeRuntimeDirectory();
         try {
+            const runtimePath = explicitRuntime ?? (await resolveManagedNodeRuntime({
+                targetDirectory: managedRuntimePath
+            })).targetDirectory;
+            const fallbackPolicy = options.mirrorOnly ? "mirror-only" : "auto";
             await syncNpmGlobals({
                 runtimePath,
                 manifestPath,
+                registryMirror,
+                fallbackPolicy,
                 onLog: printNpmSyncLog
             });
         }
@@ -21,6 +52,37 @@ export function registerNpmSyncCommand(program) {
         }
     });
 }
+function collectValues(value, previous) {
+    return [...previous, value];
+}
+async function writeInlineToolManifest(selectedAgentCliIds, customAgentCliSelectors) {
+    const directory = await mkdtemp(join(tmpdir(), "hagiscript-tool-sync-"));
+    const manifestPath = join(directory, "manifest.json");
+    await writeFile(manifestPath, JSON.stringify({
+        tools: {
+            optionalAgentCliSyncEnabled: true,
+            selectedOptionalAgentCliIds: selectedAgentCliIds,
+            customAgentClis: customAgentCliSelectors.map(parseCustomAgentCli)
+        }
+    }, null, 2));
+    return manifestPath;
+}
+function parseCustomAgentCli(selector) {
+    const trimmed = selector.trim();
+    const versionSeparator = trimmed.startsWith("@")
+        ? trimmed.indexOf("@", 1)
+        : trimmed.indexOf("@");
+    if (versionSeparator <= 0) {
+        return { packageName: trimmed };
+    }
+    const packageName = trimmed.slice(0, versionSeparator);
+    const version = trimmed.slice(versionSeparator + 1);
+    return {
+        packageName,
+        version,
+        target: version
+    };
+}
 function validatePathOption(value, optionName) {
     const normalized = value?.trim();
     if (!normalized) {
@@ -34,7 +96,19 @@ function validatePathOption(value, optionName) {
 function printNpmSyncLog(event) {
     switch (event.type) {
         case "manifest-loaded":
-            process.stdout.write(`Manifest validated: ${event.manifestPath} (${event.packageCount} packages)\n`);
+            process.stdout.write(`Manifest validated: ${event.manifestPath} (${event.packageCount} packages, mode=${event.syncMode})\n`);
+            if (event.registryMirror) {
+                process.stdout.write(`Registry mirror: ${event.registryMirror}\n`);
+            }
+            break;
+        case "fallback-policy":
+            process.stdout.write(`Fallback policy: ${event.fallbackPolicy}\n`);
+            break;
+        case "fallback-used":
+            process.stdout.write(`Fallback used: ${formatFallbackEvent(event.fallback)}\n`);
+            break;
+        case "mirror-only":
+            process.stdout.write(`Mirror-only: official registry fallback disabled for ${event.registryMirror}\n`);
             break;
         case "runtime-valid":
             process.stdout.write(`Runtime validated: ${event.runtime.targetDirectory}\n`);
@@ -45,7 +119,7 @@ function printNpmSyncLog(event) {
             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`);
+            process.stdout.write(`Plan: ${event.action.packageName} ${event.action.action} installed=${event.action.installedVersion ?? "missing"} required=${event.action.requiredRange} selector=${event.action.selectedInstallSelector}${formatToolMetadata(event.action)}\n`);
             break;
         case "skip":
             process.stdout.write(`Skip: ${event.action.packageName} already satisfies range\n`);
@@ -65,10 +139,31 @@ 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(`Mode: ${summary.syncMode}\n`);
+    if (summary.registryMirror) {
+        process.stdout.write(`Registry mirror: ${summary.registryMirror}\n`);
+        process.stdout.write(`Fallback policy: ${summary.fallbackPolicy}\n`);
+        process.stdout.write(`Fallback used: ${summary.fallbackUsed ? "yes" : "no"}\n`);
+        for (const fallback of summary.fallbackEvents) {
+            process.stdout.write(`Fallback detail: ${formatFallbackEvent(fallback)}\n`);
+        }
+    }
     process.stdout.write(`Packages: ${summary.packageCount}\n`);
     process.stdout.write(`No-op: ${summary.noopCount}\n`);
     process.stdout.write(`Changed: ${summary.changedCount}\n`);
 }
+function formatFallbackEvent(fallback) {
+    const packageSegment = fallback.packageName
+        ? ` package=${fallback.packageName}`
+        : "";
+    return `${fallback.commandKind}${packageSegment} mirror=${fallback.mirrorRegistry} fallback=${fallback.fallbackRegistry} success=${fallback.retrySucceeded}`;
+}
+function formatToolMetadata(action) {
+    if (!action.toolId) {
+        return "";
+    }
+    return ` tool=${action.toolId} group=${action.toolGroup ?? "unknown"}`;
+}
 function formatNpmSyncError(error) {
     if (error instanceof NpmManifestValidationError) {
         return error.message;
@@ -78,12 +173,42 @@ function formatNpmSyncError(error) {
         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.registryMirror) {
+            lines.push(`Registry mirror: ${error.registryMirror}`);
+            lines.push(`Fallback policy: ${error.fallbackPolicy}`);
+            if (error.fallbackPolicy === "mirror-only") {
+                lines.push("Mirror-only: official registry fallback disabled.");
+            }
+        }
+        if (error.fallbackAttempted && error.fallbackRegistry) {
+            lines.push(`Fallback registry: ${error.fallbackRegistry}`);
+        }
+        if (error.mirrorContext) {
+            lines.push(`Mirror command: ${error.mirrorContext.command} ${error.mirrorContext.args.join(" ")}`);
+            if (error.mirrorContext.stderr.trim().length > 0) {
+                lines.push(`mirror stderr: ${error.mirrorContext.stderr.trim()}`);
+            }
+            if (error.mirrorContext.stdout.trim().length > 0) {
+                lines.push(`mirror stdout: ${error.mirrorContext.stdout.trim()}`);
+            }
+        }
+        if (error.officialContext) {
+            lines.push(`Official retry command: ${error.officialContext.command} ${error.officialContext.args.join(" ")}`);
+            if (error.officialContext.stderr.trim().length > 0) {
+                lines.push(`official stderr: ${error.officialContext.stderr.trim()}`);
+            }
+            if (error.officialContext.stdout.trim().length > 0) {
+                lines.push(`official stdout: ${error.officialContext.stdout.trim()}`);
+            }
         }
-        if (error.stdout.trim().length > 0) {
-            lines.push(`stdout: ${error.stdout.trim()}`);
+        if (!error.mirrorContext && !error.officialContext) {
+            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");
     }

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

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

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export interface HagiscriptRuntimeInfo {
     status: "foundation";
 }
 export declare function createRuntimeInfo(): HagiscriptRuntimeInfo;
-export { installNodeRuntime, type InstallNodeRuntimeResult } from "./runtime/node-installer.js";
+export { getDefaultManagedNodeRuntimeDirectory, installNodeRuntime, resolveManagedNodeRuntime, type InstallNodeRuntimeResult, type ResolveManagedNodeRuntimeResult } from "./runtime/node-installer.js";
 export { verifyNodeRuntime, type NodeRuntimeVerificationResult } from "./runtime/node-verify.js";
-export { createNpmSyncPlan, loadNpmSyncManifest, normalizeGlobalInventory, syncNpmGlobals, validateNpmSyncManifest, type InstalledGlobalPackages, type NpmSyncActionKind, type NpmSyncActionResult, type NpmSyncManifest, type NpmSyncManifestEntry, type NpmSyncPlannedAction, type NpmSyncRuntimeMetadata, type NpmSyncSummary } from "./runtime/npm-sync.js";
+export { createNpmSyncPlan, loadNpmSyncManifest, normalizeGlobalInventory, syncNpmGlobals, validateNpmSyncManifest, type InstalledGlobalPackages, type NpmSyncActionKind, type NpmSyncActionResult, type NpmSyncCommandKind, type NpmSyncFallbackEvent, type NpmSyncFallbackPolicy, type NpmSyncManifest, type NpmSyncManifestEntry, type NpmSyncPlannedAction, type NpmSyncRuntimeMetadata, type NpmSyncSummary } from "./runtime/npm-sync.js";
+export { buildToolSyncPackageSet, builtInToolSyncCatalog, normalizeToolSyncEntry, validateToolSyncCatalog, type CustomAgentCliToolInput, type ToolSyncCatalogEntry, type ToolSyncGroupId, type ToolSyncPackageConstraint, type ToolSyncRequirement, type ToolSyncSelection } from "./runtime/tool-sync-catalog.js";

package/dist/index.js

@@ -7,7 +7,8 @@ export function createRuntimeInfo() {
         status: "foundation"
     };
 }
-export { installNodeRuntime } from "./runtime/node-installer.js";
+export { getDefaultManagedNodeRuntimeDirectory, installNodeRuntime, resolveManagedNodeRuntime } from "./runtime/node-installer.js";
 export { verifyNodeRuntime } from "./runtime/node-verify.js";
 export { createNpmSyncPlan, loadNpmSyncManifest, normalizeGlobalInventory, syncNpmGlobals, validateNpmSyncManifest } from "./runtime/npm-sync.js";
+export { buildToolSyncPackageSet, builtInToolSyncCatalog, normalizeToolSyncEntry, validateToolSyncCatalog } from "./runtime/tool-sync-catalog.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,cAAc,EAEf,MAAM,cAAc,CAAC;AAQtB,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,WAAW;QACX,OAAO,EAAE,cAAc;QACvB,MAAM,EAAE,YAAY;KACrB,CAAC;AACJ,CAAC;AAED,OAAO,EACL,kBAAkB,EAEnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,iBAAiB,EAElB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EASxB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,cAAc,EAEf,MAAM,cAAc,CAAC;AAQtB,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,WAAW;QACX,OAAO,EAAE,cAAc;QACvB,MAAM,EAAE,YAAY;KACrB,CAAC;AACJ,CAAC;AAED,OAAO,EACL,qCAAqC,EACrC,kBAAkB,EAClB,yBAAyB,EAG1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,iBAAiB,EAElB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EAYxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EAOxB,MAAM,gCAAgC,CAAC"}

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

@@ -1,4 +1,5 @@
 import { type DownloadProgress } from "./node-download.js";
+import { verifyNodeRuntime } from "./node-verify.js";
 export interface InstallNodeRuntimeOptions {
     targetDirectory: string;
     versionSelector?: string;
@@ -7,6 +8,16 @@ export interface InstallNodeRuntimeOptions {
     verifyTimeoutMs?: number;
     onProgress?: (progress: DownloadProgress) => void;
 }
+export interface ResolveManagedNodeRuntimeOptions {
+    targetDirectory?: string;
+    versionSelector?: string;
+    fetchImpl?: typeof fetch;
+    downloadTimeoutMs?: number;
+    verifyTimeoutMs?: number;
+    verifyRuntime?: typeof verifyNodeRuntime;
+    installRuntime?: typeof installNodeRuntime;
+    onProgress?: (progress: DownloadProgress) => void;
+}
 export interface InstallNodeRuntimeResult {
     version: string;
     npmVersion: string;
@@ -15,4 +26,14 @@ export interface InstallNodeRuntimeResult {
     npmPath: string;
     archiveUrl: string;
 }
+export interface ResolveManagedNodeRuntimeResult {
+    targetDirectory: string;
+    nodePath: string;
+    npmPath: string;
+    nodeVersion: string;
+    npmVersion: string;
+    installed: boolean;
+}
+export declare function getDefaultManagedNodeRuntimeDirectory(): string;
+export declare function resolveManagedNodeRuntime(options?: ResolveManagedNodeRuntimeOptions): Promise<ResolveManagedNodeRuntimeResult>;
 export declare function installNodeRuntime(options: InstallNodeRuntimeOptions): Promise<InstallNodeRuntimeResult>;

package/dist/runtime/node-installer.js

@@ -1,10 +1,38 @@
 import { mkdtemp, rm } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
 import { assertTargetIsEmptyOrMissing, extractNodeArchive, moveExtractedRootToTarget } from "./node-extract.js";
 import { downloadNodeArchive } from "./node-download.js";
 import { fetchNodeReleaseMetadata, selectNodeArchive } from "./node-release.js";
 import { mapNodePlatform } from "./node-platform.js";
 import { getRuntimeExecutablePaths, verifyNodeRuntime } from "./node-verify.js";
+export function getDefaultManagedNodeRuntimeDirectory() {
+    return join(homedir(), ".hagiscript", "node-runtime");
+}
+export async function resolveManagedNodeRuntime(options = {}) {
+    const targetDirectory = resolve(options.targetDirectory ?? getDefaultManagedNodeRuntimeDirectory());
+    const verifyRuntime = options.verifyRuntime ?? verifyNodeRuntime;
+    const initialVerification = await verifyRuntime(targetDirectory, {
+        timeoutMs: options.verifyTimeoutMs
+    });
+    if (initialVerification.valid) {
+        return toResolvedRuntime(initialVerification, false);
+    }
+    const installRuntime = options.installRuntime ?? installNodeRuntime;
+    await installRuntime({
+        targetDirectory,
+        versionSelector: options.versionSelector,
+        fetchImpl: options.fetchImpl,
+        downloadTimeoutMs: options.downloadTimeoutMs,
+        verifyTimeoutMs: options.verifyTimeoutMs,
+        onProgress: options.onProgress
+    });
+    const finalVerification = await verifyRuntime(targetDirectory, {
+        timeoutMs: options.verifyTimeoutMs
+    });
+    assertValidVerification(finalVerification);
+    return toResolvedRuntime(finalVerification, true);
+}
 export async function installNodeRuntime(options) {
     const targetDirectory = resolve(options.targetDirectory);
     await assertTargetIsEmptyOrMissing(targetDirectory);
@@ -43,4 +71,15 @@ function assertValidVerification(verification) {
         throw new Error(`Installed Node.js runtime failed verification: ${verification.failureReason ?? "unknown failure"}`);
     }
 }
+function toResolvedRuntime(verification, installed) {
+    assertValidVerification(verification);
+    return {
+        targetDirectory: verification.targetDirectory,
+        nodePath: verification.nodePath,
+        npmPath: verification.npmPath,
+        nodeVersion: verification.nodeVersion,
+        npmVersion: verification.npmVersion,
+        installed
+    };
+}
 //# sourceMappingURL=node-installer.js.map