@hagicode/hagiscript 0.1.6 → 0.1.7

package/README.md

@@ -215,6 +215,74 @@ Synced: @openspec/cli (sync)
 
 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.
 
+### Runtime Package Management
+
+`hagiscript runtime` adds a manifest-driven package manager for the broader `hagicode-runtime` contract. By default it loads `runtime/manifest.yaml` from the installed package, resolves the managed runtime root to `~/.hagicode/runtime`, then splits that managed runtime into a program home and a mutable runtime-data home unless `--runtime-root <path>` overrides the base location for a specific install, deployment mode, or automation run.
+
+```bash
+hagiscript runtime install
+hagiscript runtime install --components node,npm-packages --dry-run
+hagiscript runtime update --runtime-root /opt/hagicode/runtime --check-only
+hagiscript runtime remove --components code-server --purge
+hagiscript runtime state --json
+```
+
+The packaged runtime manifest aligns its default component boundaries with HagiCode Desktop:
+
+- Node is governed as a Desktop-aligned Node 22 toolchain component.
+- `.NET` is modeled as a Desktop-aligned 10.0 runtime component.
+- Mutable npm packages, including the managed `pm2` binary, are installed into a managed prefix under the runtime program home instead of the immutable Node payload or host-global npm locations.
+- `code-server` and `omniroute` stay grouped as vendored bundled-runtime components rather than npm-managed packages.
+
+The runtime layout is explicit and stable for downstream consumers:
+
+```text
+<runtime-root>/
+  program/
+    bin/
+    npm/
+    components/
+  runtime-data/
+    config/
+    logs/
+    data/
+    components/
+    state.json
+```
+
+`hagiscript runtime state --json` is the canonical contract for install, update, remove, and downstream inspection. It reports the resolved runtime home, runtime data root, per-component runtime data homes, and derived PM2 homes so Desktop, local bootstrap flows, or automation does not need to probe files directly.
+
+Runtime lifecycle scripts and managed PM2 services receive the same public runtime environment contract:
+
+- `HAGICODE_RUNTIME_HOME` points to the runtime program home.
+- `HAGICODE_RUNTIME_DATA_HOME` points to the current component's writable runtime data home.
+- `PM2_HOME` defaults to a child directory beneath `HAGICODE_RUNTIME_DATA_HOME`.
+- `PATH` is rebuilt so the managed Node runtime, managed npm prefix, and managed wrappers take precedence over the ambient shell environment.
+
+### Managed PM2 Service Commands
+
+`hagiscript pm2` manages the runtime-scoped `omniroute` and `code-server` services through the PM2 binary installed by `hagiscript runtime install`.
+
+```bash
+hagiscript pm2 omniroute start
+hagiscript pm2 omniroute status
+hagiscript pm2 code-server stop
+```
+
+Each PM2 command resolves the runtime manifest first, loads the canonical runtime homes, derives a component-scoped `PM2_HOME`, and executes the managed PM2 binary from `<runtime-home>/npm`. It does not rely on a system PM2 or a system Node on the ambient shell `PATH`.
+
+The packaged `runtime/manifest.yaml` can override:
+
+- runtime-level `paths.runtimeHome`, `paths.runtimeDataRoot`, `paths.componentDataRoot`, and `paths.defaultPm2Home`
+- component-level `runtimeDataDir`
+- service-level `pm2.appName`, `pm2.cwd`, `pm2.script`, `pm2.args`, `pm2.env`, and `pm2.pm2Home`
+
+The package also ships a thin `hagicode-runtime` wrapper binary that delegates to `hagiscript runtime ...` for automation that prefers a runtime-oriented entrypoint:
+
+```bash
+hagicode-runtime install --runtime-root /srv/hagicode/runtime
+```
+
 Use the library API from ESM consumers:
 
 ```ts

package/README_cn.md

@@ -197,6 +197,61 @@ Changed: 1
 
 如果触发了回退，Hagiscript 会在执行期间输出 `Fallback used: ...`，并在最终摘要中记录 `Fallback detail: ...`，这样 CI 或桌面端自动化就能明确知道哪个镜像失败了、是否切到了官方源，以及官方源重试是否成功。
 
+### Runtime 包管理
+
+`hagiscript runtime` 提供了面向 `hagicode-runtime` 的 manifest 驱动包管理能力。默认情况下，它会加载安装包内置的 `runtime/manifest.yaml`，把托管运行时根目录解析为 `~/.hagicode/runtime`，然后在该根目录下拆分出只读程序目录和可写运行时数据目录；如果某次部署或自动化需要独立路径，可通过 `--runtime-root <path>` 覆盖基础位置。
+
+```bash
+hagiscript runtime install
+hagiscript runtime install --components node,npm-packages --dry-run
+hagiscript runtime update --runtime-root /opt/hagicode/runtime --check-only
+hagiscript runtime remove --components code-server --purge
+hagiscript runtime state --json
+```
+
+默认运行时布局如下：
+
+```text
+<runtime-root>/
+  program/
+    bin/
+    npm/
+    components/
+  runtime-data/
+    config/
+    logs/
+    data/
+    components/
+    state.json
+```
+
+`hagiscript runtime state --json` 是安装、更新、删除与下游诊断的标准状态接口。它会输出解析后的运行时程序目录、运行时数据根目录、组件级 `HAGICODE_RUNTIME_DATA_HOME`，以及派生出的 `PM2_HOME`，下游工具不需要再自己探测文件系统。
+
+运行时脚本和 PM2 托管服务会共享同一套公开环境变量约定：
+
+- `HAGICODE_RUNTIME_HOME`：运行时程序目录
+- `HAGICODE_RUNTIME_DATA_HOME`：当前组件的可写运行时数据目录
+- `PM2_HOME`：默认位于 `HAGICODE_RUNTIME_DATA_HOME` 下的独立子目录
+- `PATH`：优先注入托管 Node 运行时、托管 npm 前缀和托管 wrapper，再继承当前 shell 的 PATH
+
+### PM2 托管服务命令
+
+`hagiscript pm2` 用于管理运行时作用域内的 `omniroute` 和 `code-server` 服务，底层始终调用 `hagiscript runtime install` 安装到托管 npm 前缀中的 PM2。
+
+```bash
+hagiscript pm2 omniroute start
+hagiscript pm2 omniroute status
+hagiscript pm2 code-server stop
+```
+
+每次 PM2 命令都会先解析运行时 manifest，计算规范化的运行时目录和组件数据目录，再以组件级 `PM2_HOME` 和托管 Node-first PATH 调用 `<runtime-home>/npm` 下的 PM2；它不会依赖系统预装的 PM2 或系统 Node。
+
+`runtime/manifest.yaml` 现在支持以下覆盖项：
+
+- 运行时级别：`paths.runtimeHome`、`paths.runtimeDataRoot`、`paths.componentDataRoot`、`paths.defaultPm2Home`
+- 组件级别：`runtimeDataDir`
+- 服务级别：`pm2.appName`、`pm2.cwd`、`pm2.script`、`pm2.args`、`pm2.env`、`pm2.pm2Home`
+
 在 ESM 项目中使用库 API：
 
 ```ts

package/bin/runtime

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { runCli } from "../dist/cli.js"
+
+const argv = [
+  process.argv[0] ?? process.execPath,
+  "hagicode-runtime",
+  "runtime",
+  ...process.argv.slice(2)
+]
+
+runCli(argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+})

package/dist/cli.js

@@ -5,6 +5,8 @@ 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";
+import { registerPm2Commands } from "./commands/pm2-commands.js";
+import { registerRuntimeCommands } from "./commands/runtime-commands.js";
 export function createCli() {
     const program = new Command();
     program
@@ -20,6 +22,8 @@ export function createCli() {
     });
     registerNodeRuntimeCommands(program);
     registerNpmSyncCommand(program);
+    registerPm2Commands(program);
+    registerRuntimeCommands(program);
     program.action(() => {
         program.outputHelp();
     });

package/dist/cli.js.map

@@ -1 +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"}
+{"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;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAEzE,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;IAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,uBAAuB,CAAC,OAAO,CAAC,CAAC;IAEjC,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/pm2-commands.d.ts

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

package/dist/commands/pm2-commands.js

@@ -0,0 +1,54 @@
+import { InvalidArgumentError } from "commander";
+import { renderManagedPm2StatusText, runManagedPm2Command, supportedPm2Services } from "../runtime/pm2-manager.js";
+export function registerPm2Commands(program) {
+    program
+        .command("pm2")
+        .description("manage PM2-backed hagicode-runtime services")
+        .argument("<service>", "managed service name", parseManagedPm2Service)
+        .argument("<action>", "pm2 action", parseManagedPm2Action)
+        .option("--from-manifest <path>", "override the default runtime manifest")
+        .option("--runtime-root <path>", "managed runtime root override")
+        .action(async (service, action, options, command) => {
+        try {
+            const result = await runManagedPm2Command({
+                manifestPath: validatePathOption(options.fromManifest, "--from-manifest"),
+                runtimeRoot: validatePathOption(options.runtimeRoot, "--runtime-root"),
+                service,
+                action
+            });
+            process.stdout.write(`${renderManagedPm2StatusText(result)}\n`);
+        }
+        catch (error) {
+            command.error(formatPm2Error(error), { exitCode: 1 });
+        }
+    });
+}
+function parseManagedPm2Service(value) {
+    if (supportedPm2Services.includes(value)) {
+        return value;
+    }
+    throw new InvalidArgumentError(`Unsupported managed PM2 service "${value}". Supported services: ${supportedPm2Services.join(", ")}.`);
+}
+function parseManagedPm2Action(value) {
+    if (value === "start" || value === "stop" || value === "status") {
+        return value;
+    }
+    throw new InvalidArgumentError(`Unsupported PM2 action "${value}". Supported actions: start, stop, status.`);
+}
+function validatePathOption(value, optionName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    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 formatPm2Error(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=pm2-commands.js.map

package/dist/commands/pm2-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pm2-commands.js","sourceRoot":"","sources":["../../src/commands/pm2-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACzD,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB,EAGrB,MAAM,2BAA2B,CAAA;AAOlC,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,OAAO,CAAC,KAAK,CAAC;SACd,WAAW,CAAC,6CAA6C,CAAC;SAC1D,QAAQ,CAAC,WAAW,EAAE,sBAAsB,EAAE,sBAAsB,CAAC;SACrE,QAAQ,CAAC,UAAU,EAAE,YAAY,EAAE,qBAAqB,CAAC;SACzD,MAAM,CAAC,wBAAwB,EAAE,uCAAuC,CAAC;SACzE,MAAM,CAAC,uBAAuB,EAAE,+BAA+B,CAAC;SAChE,MAAM,CACL,KAAK,EACH,OAA8B,EAC9B,MAAwB,EACxB,OAA0B,EAC1B,OAAgB,EAChB,EAAE;QACF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC;gBACxC,YAAY,EAAE,kBAAkB,CAAC,OAAO,CAAC,YAAY,EAAE,iBAAiB,CAAC;gBACzE,WAAW,EAAE,kBAAkB,CAAC,OAAO,CAAC,WAAW,EAAE,gBAAgB,CAAC;gBACtE,OAAO;gBACP,MAAM;aACP,CAAC,CAAA;YAEF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,0BAA0B,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACjE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;QACvD,CAAC;IACH,CAAC,CACF,CAAA;AACL,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAa;IAC3C,IAAK,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,OAAO,KAA8B,CAAA;IACvC,CAAC;IAED,MAAM,IAAI,oBAAoB,CAC5B,oCAAoC,KAAK,0BAA0B,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACtG,CAAA;AACH,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAa;IAC1C,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChE,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,IAAI,oBAAoB,CAC5B,2BAA2B,KAAK,4CAA4C,CAC7E,CAAA;AACH,CAAC;AAED,SAAS,kBAAkB,CACzB,KAAyB,EACzB,UAAkB;IAElB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC/B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,oBAAoB,CAAC,GAAG,UAAU,4BAA4B,CAAC,CAAA;IAC3E,CAAC;IAED,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,oBAAoB,CAAC,GAAG,UAAU,iCAAiC,CAAC,CAAA;IAChF,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC/D,CAAC"}

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

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

package/dist/commands/runtime-commands.js

@@ -0,0 +1,136 @@
+import { InvalidArgumentError } from "commander";
+import { installRuntime, queryRuntimeState, removeRuntime, renderRuntimeStateText, updateRuntime } from "../runtime/runtime-manager.js";
+export function registerRuntimeCommands(program) {
+    const runtime = program
+        .command("runtime")
+        .description("manage manifest-driven hagicode-runtime components");
+    runtime
+        .command("install")
+        .description("install runtime components into a managed runtime root")
+        .option("--from-manifest <path>", "override the default runtime manifest")
+        .option("--runtime-root <path>", "managed runtime root override")
+        .option("--components <list>", "comma-separated runtime component names to install", parseComponentList)
+        .option("--dry-run", "print the install plan without mutating managed files")
+        .option("--force", "force reinstall of mutable managed components")
+        .option("--verbose", "print detailed lifecycle output")
+        .action(async (options, command) => {
+        await runLifecycleCommand("install", options, command);
+    });
+    runtime
+        .command("remove")
+        .description("remove runtime components from the managed runtime root")
+        .option("--from-manifest <path>", "override the default runtime manifest")
+        .option("--runtime-root <path>", "managed runtime root override")
+        .option("--components <list>", "comma-separated runtime component names to remove", parseComponentList)
+        .option("--dry-run", "print the removal plan without mutating managed files")
+        .option("--force", "reserved compatibility flag for scripted removals")
+        .option("--purge", "remove retained managed config and data where supported")
+        .option("--verbose", "print detailed lifecycle output")
+        .action(async (options, command) => {
+        await runLifecycleCommand("remove", options, command);
+    });
+    runtime
+        .command("update")
+        .description("update installed runtime components")
+        .option("--from-manifest <path>", "override the default runtime manifest")
+        .option("--runtime-root <path>", "managed runtime root override")
+        .option("--components <list>", "comma-separated runtime component names to update", parseComponentList)
+        .option("--dry-run", "print the update plan without mutating managed files")
+        .option("--check-only", "report components that would be updated")
+        .option("--force", "force update execution for mutable managed components")
+        .option("--verbose", "print detailed lifecycle output")
+        .action(async (options, command) => {
+        await runLifecycleCommand("update", options, command);
+    });
+    runtime
+        .command("state")
+        .description("query the canonical managed runtime state")
+        .option("--from-manifest <path>", "override the default runtime manifest")
+        .option("--runtime-root <path>", "managed runtime root override")
+        .option("--json", "emit machine-readable JSON output")
+        .action(async (options, command) => {
+        try {
+            const report = await queryRuntimeState({
+                manifestPath: validatePathOption(options.fromManifest, "--from-manifest"),
+                runtimeRoot: validatePathOption(options.runtimeRoot, "--runtime-root")
+            });
+            process.stdout.write(options.json
+                ? `${JSON.stringify(report, null, 2)}\n`
+                : `${renderRuntimeStateText(report)}\n`);
+        }
+        catch (error) {
+            command.error(formatRuntimeError(error), { exitCode: 1 });
+        }
+    });
+}
+async function runLifecycleCommand(phase, options, command) {
+    const runtimeOptions = {
+        manifestPath: validatePathOption(options.fromManifest, "--from-manifest"),
+        runtimeRoot: validatePathOption(options.runtimeRoot, "--runtime-root"),
+        components: options.components ?? [],
+        dryRun: options.dryRun ?? false,
+        force: options.force ?? false,
+        purge: "purge" in options ? options.purge ?? false : false,
+        checkOnly: "checkOnly" in options ? options.checkOnly ?? false : false,
+        verbose: options.verbose ?? false,
+        logger: (message) => process.stdout.write(`${message}\n`)
+    };
+    try {
+        const result = phase === "install"
+            ? await installRuntime(runtimeOptions)
+            : phase === "remove"
+                ? await removeRuntime(runtimeOptions)
+                : await updateRuntime(runtimeOptions);
+        printLifecycleSummary(phase, runtimeOptions, result);
+    }
+    catch (error) {
+        command.error(formatRuntimeError(error), { exitCode: 1 });
+    }
+}
+function parseComponentList(value) {
+    const components = value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    if (components.length === 0) {
+        throw new InvalidArgumentError("--components must include at least one component name.");
+    }
+    return Array.from(new Set(components));
+}
+function validatePathOption(value, optionName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    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 printLifecycleSummary(phase, options, result) {
+    const modeSuffix = options.dryRun || (phase === "update" && options.checkOnly)
+        ? options.checkOnly
+            ? " (check-only)"
+            : " (dry-run)"
+        : "";
+    process.stdout.write(`Runtime ${phase} complete${modeSuffix}.\n`);
+    process.stdout.write(`Manifest: ${result.manifest.manifestPath}\n`);
+    process.stdout.write(`Managed root: ${result.paths.root}\n`);
+    process.stdout.write(`Planned components: ${result.plan.length}\n`);
+    process.stdout.write(`Changed components: ${result.changedComponents.length}\n`);
+    if (result.skipped.length > 0) {
+        for (const skipped of result.skipped) {
+            process.stdout.write(`Skipped: ${skipped.componentName} (${skipped.reason})\n`);
+        }
+    }
+    if (result.logFilePath) {
+        process.stdout.write(`Log: ${result.logFilePath}\n`);
+    }
+}
+function formatRuntimeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=runtime-commands.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-commands.js","sourceRoot":"","sources":["../../src/commands/runtime-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACzD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,sBAAsB,EACtB,aAAa,EAGd,MAAM,+BAA+B,CAAA;AA8BtC,MAAM,UAAU,uBAAuB,CAAC,OAAgB;IACtD,MAAM,OAAO,GAAG,OAAO;SACpB,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,oDAAoD,CAAC,CAAA;IAEpE,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,wDAAwD,CAAC;SACrE,MAAM,CAAC,wBAAwB,EAAE,uCAAuC,CAAC;SACzE,MAAM,CAAC,uBAAuB,EAAE,+BAA+B,CAAC;SAChE,MAAM,CACL,qBAAqB,EACrB,oDAAoD,EACpD,kBAAkB,CACnB;SACA,MAAM,CAAC,WAAW,EAAE,uDAAuD,CAAC;SAC5E,MAAM,CAAC,SAAS,EAAE,+CAA+C,CAAC;SAClE,MAAM,CAAC,WAAW,EAAE,iCAAiC,CAAC;SACtD,MAAM,CAAC,KAAK,EAAE,OAA8B,EAAE,OAAgB,EAAE,EAAE;QACjE,MAAM,mBAAmB,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACxD,CAAC,CAAC,CAAA;IAEJ,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,yDAAyD,CAAC;SACtE,MAAM,CAAC,wBAAwB,EAAE,uCAAuC,CAAC;SACzE,MAAM,CAAC,uBAAuB,EAAE,+BAA+B,CAAC;SAChE,MAAM,CACL,qBAAqB,EACrB,mDAAmD,EACnD,kBAAkB,CACnB;SACA,MAAM,CAAC,WAAW,EAAE,uDAAuD,CAAC;SAC5E,MAAM,CAAC,SAAS,EAAE,mDAAmD,CAAC;SACtE,MAAM,CAAC,SAAS,EAAE,yDAAyD,CAAC;SAC5E,MAAM,CAAC,WAAW,EAAE,iCAAiC,CAAC;SACtD,MAAM,CAAC,KAAK,EAAE,OAA6B,EAAE,OAAgB,EAAE,EAAE;QAChE,MAAM,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACvD,CAAC,CAAC,CAAA;IAEJ,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,qCAAqC,CAAC;SAClD,MAAM,CAAC,wBAAwB,EAAE,uCAAuC,CAAC;SACzE,MAAM,CAAC,uBAAuB,EAAE,+BAA+B,CAAC;SAChE,MAAM,CACL,qBAAqB,EACrB,mDAAmD,EACnD,kBAAkB,CACnB;SACA,MAAM,CAAC,WAAW,EAAE,sDAAsD,CAAC;SAC3E,MAAM,CAAC,cAAc,EAAE,yCAAyC,CAAC;SACjE,MAAM,CAAC,SAAS,EAAE,uDAAuD,CAAC;SAC1E,MAAM,CAAC,WAAW,EAAE,iCAAiC,CAAC;SACtD,MAAM,CAAC,KAAK,EAAE,OAA6B,EAAE,OAAgB,EAAE,EAAE;QAChE,MAAM,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACvD,CAAC,CAAC,CAAA;IAEJ,OAAO;SACJ,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,2CAA2C,CAAC;SACxD,MAAM,CAAC,wBAAwB,EAAE,uCAAuC,CAAC;SACzE,MAAM,CAAC,uBAAuB,EAAE,+BAA+B,CAAC;SAChE,MAAM,CAAC,QAAQ,EAAE,mCAAmC,CAAC;SACrD,MAAM,CAAC,KAAK,EAAE,OAA4B,EAAE,OAAgB,EAAE,EAAE;QAC/D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC;gBACrC,YAAY,EAAE,kBAAkB,CAAC,OAAO,CAAC,YAAY,EAAE,iBAAiB,CAAC;gBACzE,WAAW,EAAE,kBAAkB,CAAC,OAAO,CAAC,WAAW,EAAE,gBAAgB,CAAC;aACvE,CAAC,CAAA;YAEF,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,OAAO,CAAC,IAAI;gBACV,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI;gBACxC,CAAC,CAAC,GAAG,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAC1C,CAAA;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;QAC3D,CAAC;IACH,CAAC,CAAC,CAAA;AACN,CAAC;AAED,KAAK,UAAU,mBAAmB,CAChC,KAAsC,EACtC,OAA4E,EAC5E,OAAgB;IAEhB,MAAM,cAAc,GAA4B;QAC9C,YAAY,EAAE,kBAAkB,CAAC,OAAO,CAAC,YAAY,EAAE,iBAAiB,CAAC;QACzE,WAAW,EAAE,kBAAkB,CAAC,OAAO,CAAC,WAAW,EAAE,gBAAgB,CAAC;QACtE,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;QAC/B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;QAC7B,KAAK,EAAE,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK;QAC1D,SAAS,EAAE,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK;QACtE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;QACjC,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC;KAC1D,CAAA;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GACV,KAAK,KAAK,SAAS;YACjB,CAAC,CAAC,MAAM,cAAc,CAAC,cAAc,CAAC;YACtC,CAAC,CAAC,KAAK,KAAK,QAAQ;gBAClB,CAAC,CAAC,MAAM,aAAa,CAAC,cAAc,CAAC;gBACrC,CAAC,CAAC,MAAM,aAAa,CAAC,cAAc,CAAC,CAAA;QAE3C,qBAAqB,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,CAAA;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;IAC3D,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa;IACvC,MAAM,UAAU,GAAG,KAAK;SACrB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,OAAO,CAAC,CAAA;IAElB,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,oBAAoB,CAAC,wDAAwD,CAAC,CAAA;IAC1F,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAA;AACxC,CAAC;AAED,SAAS,kBAAkB,CACzB,KAAyB,EACzB,UAAkB;IAElB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC/B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,oBAAoB,CAAC,GAAG,UAAU,4BAA4B,CAAC,CAAA;IAC3E,CAAC;IAED,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,oBAAoB,CAAC,GAAG,UAAU,iCAAiC,CAAC,CAAA;IAChF,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,SAAS,qBAAqB,CAC5B,KAAsC,EACtC,OAAgC,EAChC,MAA8B;IAE9B,MAAM,UAAU,GACd,OAAO,CAAC,MAAM,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC;QACzD,CAAC,CAAC,OAAO,CAAC,SAAS;YACjB,CAAC,CAAC,eAAe;YACjB,CAAC,CAAC,YAAY;QAChB,CAAC,CAAC,EAAE,CAAA;IAER,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,KAAK,YAAY,UAAU,KAAK,CAAC,CAAA;IACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,QAAQ,CAAC,YAAY,IAAI,CAAC,CAAA;IACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAA;IAC5D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAA;IACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,MAAM,CAAC,iBAAiB,CAAC,MAAM,IAAI,CAAC,CAAA;IAEhF,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,OAAO,CAAC,aAAa,KAAK,OAAO,CAAC,MAAM,KAAK,CAAC,CAAA;QACjF,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,MAAM,CAAC,WAAW,IAAI,CAAC,CAAA;IACtD,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -9,3 +9,9 @@ export { getDefaultManagedNodeRuntimeDirectory, installNodeRuntime, resolveManag
 export { verifyNodeRuntime, type NodeRuntimeVerificationResult } from "./runtime/node-verify.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";
+export { getDefaultRuntimeManifestPath, loadRuntimeManifest, type LoadedRuntimeManifest, type RuntimeComponentDefinition, type RuntimeLifecyclePhase, type RuntimeManifestPaths } from "./runtime/runtime-manifest.js";
+export { defaultRuntimeRoot, getComponentConfigDirectory, getComponentLogsDirectory, getComponentManagedRoot, getComponentPm2Home, getComponentRuntimeDataHome, resolveRuntimePaths, type ResolvedRuntimePaths } from "./runtime/runtime-paths.js";
+export { createInitialRuntimeState, mergeRuntimeState, readRuntimeState, writeRuntimeState, type RuntimeComponentState, type RuntimeOperationState, type RuntimeState } from "./runtime/runtime-state.js";
+export { renderManagedPm2StatusText, resolveManagedPm2ServiceDefinition, runManagedPm2Command, supportedPm2Services, type ManagedPm2Action, type ManagedPm2CommandResult, type ManagedPm2CommandOptions, type ManagedPm2ServiceName, type ManagedPm2Status, type ResolvedManagedPm2ServiceDefinition } from "./runtime/pm2-manager.js";
+export { buildManagedRuntimeEnvironment, getManagedNpmBinDirectory, getManagedRuntimePathEntries, prependPathEntries } from "./runtime/runtime-executor.js";
+export { installRuntime, planRuntimeLifecycle, queryRuntimeState, removeRuntime, renderRuntimeStateText, runRuntimeLifecycle, updateRuntime, type RuntimeLifecycleOptions, type RuntimeLifecycleResult, type RuntimePlannedAction, type RuntimeStateReport } from "./runtime/runtime-manager.js";

package/dist/index.js

@@ -11,4 +11,10 @@ export { getDefaultManagedNodeRuntimeDirectory, installNodeRuntime, resolveManag
 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";
+export { getDefaultRuntimeManifestPath, loadRuntimeManifest } from "./runtime/runtime-manifest.js";
+export { defaultRuntimeRoot, getComponentConfigDirectory, getComponentLogsDirectory, getComponentManagedRoot, getComponentPm2Home, getComponentRuntimeDataHome, resolveRuntimePaths } from "./runtime/runtime-paths.js";
+export { createInitialRuntimeState, mergeRuntimeState, readRuntimeState, writeRuntimeState } from "./runtime/runtime-state.js";
+export { renderManagedPm2StatusText, resolveManagedPm2ServiceDefinition, runManagedPm2Command, supportedPm2Services } from "./runtime/pm2-manager.js";
+export { buildManagedRuntimeEnvironment, getManagedNpmBinDirectory, getManagedRuntimePathEntries, prependPathEntries } from "./runtime/runtime-executor.js";
+export { installRuntime, planRuntimeLifecycle, queryRuntimeState, removeRuntime, renderRuntimeStateText, runRuntimeLifecycle, updateRuntime } from "./runtime/runtime-manager.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,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"}
+{"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;AACxC,OAAO,EACL,6BAA6B,EAC7B,mBAAmB,EAKpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,2BAA2B,EAC3B,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EAIlB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,0BAA0B,EAC1B,kCAAkC,EAClC,oBAAoB,EACpB,oBAAoB,EAOrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,4BAA4B,EAC5B,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EAKd,MAAM,8BAA8B,CAAC"}

package/dist/runtime/command-launch.js

@@ -19,6 +19,7 @@ export function normalizeCommandPath(commandPath) {
     return trimmed;
 }
 export function requiresShellLaunch(_commandPath, _platform = process.platform) {
+    void _platform;
     // Execa already handles Windows command shims without a shell wrapper.
     // Keeping direct execution preserves argv boundaries for paths with spaces.
     return false;

package/dist/runtime/command-launch.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-launch.js","sourceRoot":"","sources":["../../src/runtime/command-launch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AA4C9B,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,OAAO,CAAwB;IAExC,YAAY,OAAe,EAAE,OAA8B,EAAE,OAAsB;QACjF,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;IAEnC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAEzC,IAAI,CAAC,KAAK,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACvE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,YAAoB,EACpB,YAA6B,OAAO,CAAC,QAAQ;IAE7C,uEAAuE;IACvE,4EAA4E;IAC5E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,WAAmB,EACnB,UAAgC,EAAE;IAElC,OAAO,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC;QACvD,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE;QACjB,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAkB,KAAK,EAC5C,OAAO,EACP,IAAI,EACJ,OAAO,GAAG,EAAE,EACZ,EAAE;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YACxC,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,OAAO,EAAE,OAAO,CAAC,SAAS;YAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,WAAW,EAAE,IAAI;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;QAEH,OAAO;YACL,OAAO;YACP,IAAI;YACJ,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC;YACtC,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC;YACtC,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,qBAAqB,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC,CAAC;AAEF,SAAS,qBAAqB,CAC5B,OAAe,EACf,IAAc,EACd,KAAc,EACd,OAA6B;IAE7B,MAAM,UAAU,GAAG,KAKlB,CAAC;IACF,MAAM,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,UAAU,CAAC,YAAY,IAAI,UAAU,CAAC,OAAO,CAAC;IACnE,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,KAAK,IAAI,CAAC;IAC9C,MAAM,QAAQ,GAAG,OAAO,UAAU,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3F,MAAM,MAAM,GAAG,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACrF,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,KAAK,KAAK,CAAC;IAE3C,OAAO,IAAI,qBAAqB,CAC9B,YAAY,IAAI,mBAAmB,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAC9D;QACE,OAAO;QACP,IAAI;QACJ,MAAM;QACN,MAAM;QACN,GAAG,EAAE,OAAO,UAAU,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG;QACtE,QAAQ;QACR,MAAM;QACN,QAAQ;QACR,MAAM;QACN,YAAY;KACb,EACD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CACtD,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,MAAe;IACtC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC"}
+{"version":3,"file":"command-launch.js","sourceRoot":"","sources":["../../src/runtime/command-launch.ts"],"names":[],"mappings":"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"}

package/dist/runtime/pm2-manager.d.ts

@@ -0,0 +1,54 @@
+import type { CommandRunner } from "./command-launch.js";
+import { type LoadedRuntimeManifest, type RuntimeComponentDefinition } from "./runtime-manifest.js";
+import { type ResolvedRuntimePaths } from "./runtime-paths.js";
+export declare const supportedPm2Services: readonly ["omniroute", "code-server"];
+export type ManagedPm2ServiceName = (typeof supportedPm2Services)[number];
+export type ManagedPm2Action = "start" | "stop" | "status";
+export type ManagedPm2Status = "online" | "stopped" | "errored" | "missing" | "unknown";
+export interface ManagedPm2CommandOptions {
+    manifestPath?: string;
+    runtimeRoot?: string;
+    service: ManagedPm2ServiceName;
+    action: ManagedPm2Action;
+    runner?: CommandRunner;
+}
+export interface ResolvedManagedPm2ServiceDefinition {
+    service: ManagedPm2ServiceName;
+    component: RuntimeComponentDefinition;
+    manifestDir: string;
+    paths: ResolvedRuntimePaths;
+    appName: string;
+    cwd: string;
+    script: string;
+    args: string[];
+    env: Record<string, string>;
+    runtimeHome: string;
+    runtimeDataHome: string;
+    componentRoot: string;
+    componentConfigDir: string;
+    pm2Home: string;
+    pm2Binary: string;
+    nodePath: string;
+}
+export interface ManagedPm2CommandResult {
+    service: ManagedPm2ServiceName;
+    action: ManagedPm2Action;
+    appName: string;
+    cwd: string;
+    script: string;
+    runtimeHome: string;
+    runtimeDataHome: string;
+    pm2Home: string;
+    pm2Binary: string;
+    exists: boolean;
+    status: ManagedPm2Status;
+    pid: number | null;
+    stdout: string;
+    stderr: string;
+}
+export declare class ManagedPm2Error extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function runManagedPm2Command(options: ManagedPm2CommandOptions): Promise<ManagedPm2CommandResult>;
+export declare function resolveManagedPm2ServiceDefinition(manifest: LoadedRuntimeManifest, paths: ResolvedRuntimePaths, service: ManagedPm2ServiceName): Promise<ResolvedManagedPm2ServiceDefinition>;
+export declare function renderManagedPm2StatusText(result: ManagedPm2CommandResult): string;