@hagicode/hagiscript 0.1.6 → 0.1.8

package/README.md

@@ -1,288 +1,231 @@
-# Hagiscript
+# Hagiscript Runtime Guide
 
 [![npm version](https://img.shields.io/npm/v/%40hagicode%2Fhagiscript?logo=npm&color=cb3837)](https://www.npmjs.com/package/@hagicode/hagiscript)
 [![npm downloads](https://img.shields.io/npm/dm/%40hagicode%2Fhagiscript?logo=npm&color=2d8cf0)](https://www.npmjs.com/package/@hagicode/hagiscript)
 [![license](https://img.shields.io/badge/license-MIT-ffd43b)](./LICENSE)
 
-`@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.
+`@hagicode/hagiscript` is the runtime management CLI behind the `hagicode-runtime` contract. Use it to install, inspect, update, remove, and operate a managed HagiCode runtime without depending on system Node.js, system PM2, or host-global npm packages.
 
-## Installation Assumptions
+## Install
 
-- 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.
+```bash
+npm install -g @hagicode/hagiscript
+```
 
-## Usage
+Primary entrypoints:
 
-Install the package from npm:
+- `hagiscript`
+- `hagicode-runtime` (`hagiscript runtime ...` wrapper)
 
-```bash
-npm install @hagicode/hagiscript
-```
+Node.js 20 or newer is required to run the package itself.
 
-The installed CLI command remains `hagiscript`.
+## Runtime Model
 
-Run the CLI locally during development:
+By default, Hagiscript loads `runtime/manifest.yaml` and manages the runtime under `~/.hagicode/runtime`.
 
-```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
+```text
+<runtime-root>/
+  program/
+    bin/
+    npm/
+    components/
+  runtime-data/
+    config/
+    logs/
+    data/
+    components/
+    state.json
 ```
 
-After building, run the compiled CLI:
+The split is intentional:
 
-```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
-```
+- `program/` holds managed executables, vendored payloads, wrappers, and the managed npm prefix.
+- `runtime-data/` holds mutable config, logs, state, PM2 data, and component-specific writable files.
+
+The packaged manifest currently manages:
 
-### Managed Node.js Runtime Commands
+- `node` - managed Node.js runtime
+- `dotnet` - managed .NET runtime
+- `npm-packages` - managed npm prefix, including `pm2`
+- `omniroute` - vendored bundled runtime
+- `code-server` - vendored bundled runtime
 
-`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.
+## Core Runtime Commands
+
+Install the full runtime:
 
 ```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
+hagiscript runtime install
 ```
 
-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`.
+Install selected components only:
 
-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.
+```bash
+hagiscript runtime install --components node,npm-packages
+```
 
-Example success output:
+Preview planned changes without mutating files:
 
-```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
+```bash
+hagiscript runtime install --dry-run
+hagiscript runtime update --check-only
 ```
 
-`check-node` validates an existing runtime directory and exits with code `0` only when both `node --version` and `npm --version` succeed.
+Inspect the canonical runtime state:
 
 ```bash
-hagiscript check-node --target /opt/hagiscript/node
+hagiscript runtime state
+hagiscript runtime state --json
 ```
 
-Example valid output:
+Update or remove managed components:
 
-```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
+```bash
+hagiscript runtime update
+hagiscript runtime remove --components code-server --purge
 ```
 
-Example invalid output exits non-zero and includes the failure reason:
+Override the runtime root or manifest when needed:
 
-```text
-Node.js runtime is invalid.
-Target: /opt/hagiscript/node
-Reason: missing executable
+```bash
+hagiscript runtime install --runtime-root /srv/hagicode/runtime
+hagiscript runtime state --from-manifest /path/to/runtime-manifest.yaml --json
 ```
 
-### 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.
+If you prefer the runtime-oriented wrapper:
 
 ```bash
-hagiscript npm-sync --manifest ./manifest.json
-hagiscript npm-sync --runtime /opt/hagiscript/node --manifest ./manifest.json
-hagiscript npm-sync --manifest ./manifest.json --force
-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
+hagicode-runtime install --runtime-root /srv/hagicode/runtime
 ```
 
-Compatibility manifest schema:
-
-```json
-{
-  "registryMirror": "https://registry.npmmirror.com/",
-  "packages": {
-    "<npm-package-name>": {
-      "version": "<semver range>",
-      "target": "<optional npm install selector>"
-    }
-  }
-}
-```
+## Runtime State and Maintenance
 
-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>`.
+`hagiscript runtime state --json` is the canonical inspection surface for automation. It reports:
 
-By default, `npm-sync` plans installed packages that already satisfy the requested range as `noop` and skips `npm install -g` for them. Use `--force` to skip that installed-package satisfaction check and re-run sync for matching packages. `--force` does not upgrade packages to the latest version and does not change semver selection; it only turns an otherwise skipped `noop` action into an executable `sync` action.
+- resolved runtime root
+- `program/` and `runtime-data/` locations
+- per-component install status
+- per-component runtime data homes
+- derived PM2 homes for managed services
+- program/data path separation
 
-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/`.
+Use it before and after maintenance work to confirm the expected component set and writable paths.
 
-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.
+Typical maintenance flow:
 
-```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"
-      }
-    ]
-  }
-}
-```
+1. Check current state: `hagiscript runtime state --json`
+2. Apply changes: `hagiscript runtime install`, `update`, or `remove`
+3. Re-check state to confirm the final layout
+4. Operate services through `hagiscript pm2 ...`
+
+Lifecycle commands print the resolved manifest, managed root, changed component count, skipped entries, and log file path when a log is generated.
+
+## Managed PM2 Services
+
+Hagiscript manages runtime-scoped PM2 services for:
 
-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.
+- `omniroute`
+- `code-server`
 
-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.
+Supported actions:
 
-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.
+- `start`
+- `stop`
+- `status`
 
-For simple product-managed requests, optional CLI selections can be provided directly without writing a manifest:
+Examples:
 
 ```bash
-hagiscript npm-sync --selected-agent-cli codex
-hagiscript npm-sync --selected-agent-cli codex --custom-agent-cli @scope/agent-cli@^1.0.0
+hagiscript pm2 omniroute status
+hagiscript pm2 omniroute start
+hagiscript pm2 code-server stop
 ```
 
-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"
-    }
-  }
-}
-```
+The PM2 flow is runtime-scoped:
 
-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. With `--force`, packages that already satisfy the requested range are replanned from `noop` to `sync`, so the same selector is installed again to re-sync the existing target.
+- PM2 is installed into the managed npm prefix, not the host environment.
+- Hagiscript resolves the runtime manifest before every PM2 action.
+- PM2 runs with the managed Node runtime and managed PATH ordering.
+- `PM2_HOME` is derived from the managed runtime layout, so service state stays inside the runtime data boundary.
 
-Example output:
+This means maintenance scripts should call `hagiscript pm2 ...` instead of a system `pm2` binary.
 
-```text
-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)
-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
-Registry mirror: https://registry.npmmirror.com/
-Fallback policy: auto
-Fallback used: no
-Packages: 2
-No-op: 1
-Changed: 1
-```
+## Runtime Environment Contract
 
-Forced re-sync example:
+Runtime lifecycle scripts and managed services receive a stable environment contract:
 
-```text
-$ hagiscript npm-sync --manifest ./manifest.json --force
-Plan: @openspec/cli sync installed=1.0.2 required=^1.0.0 selector=@openspec/cli@^1.0.0
-Install: @openspec/cli using @openspec/cli@^1.0.0
-Synced: @openspec/cli (sync)
-```
+- `HAGICODE_RUNTIME_HOME` - runtime program home
+- `HAGICODE_RUNTIME_DATA_HOME` - writable runtime data home for the current component
+- `PM2_HOME` - PM2 state directory for the current managed service
+- `PATH` - rebuilt so managed Node, managed npm, and managed wrappers come first
 
-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.
+This contract is what keeps installs, updates, wrappers, and PM2-managed services aligned to the same runtime root.
 
-Use the library API from ESM consumers:
+## Manifest Customization
 
-```ts
-import { createRuntimeInfo, getPackageMetadata } from "@hagicode/hagiscript";
+`runtime/manifest.yaml` controls the runtime shape. Common override points:
 
-console.log(getPackageMetadata());
-console.log(createRuntimeInfo());
-```
+- `paths.runtimeRoot`
+- `paths.runtimeHome`
+- `paths.runtimeDataRoot`
+- `paths.componentDataRoot`
+- `paths.defaultPm2Home`
+- component `runtimeDataDir`
+- service `pm2.appName`
+- service `pm2.cwd`
+- service `pm2.script`
+- service `pm2.args`
+- service `pm2.env`
+- service `pm2.pm2Home`
 
-## Development Commands
+For deployment-specific behavior, keep the packaged manifest as the baseline and pass `--from-manifest` with an override manifest rather than mutating the installed package in place.
 
-Run all commands from `repos/hagiscript/`:
+## Related Runtime Tooling
 
-```bash
-npm install
-npm run lint
-npm run format:check
-npm test
-npm run build
-npm run pack:check
-```
+### Managed Node Runtime
 
-Additional commands:
+Install a standalone managed Node.js runtime:
 
 ```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
+hagiscript install-node --target /opt/hagiscript/node
+hagiscript install-node --target /opt/hagiscript/node22 --version 22
 ```
 
-## Build Outputs
-
-`npm run build` compiles TypeScript with strict NodeNext settings into `dist/`. Expected entry points include:
+Validate an existing managed Node.js runtime:
 
-- `dist/index.js`
-- `dist/index.d.ts`
-- `dist/index.js.map`
-- `dist/cli.js`
-- `dist/cli.d.ts`
-- `dist/cli.js.map`
+```bash
+hagiscript check-node --target /opt/hagiscript/node
+```
 
-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`.
+### Managed npm Package Sync
 
-## Package Verification
+Sync npm global packages into a managed runtime instead of the host environment:
 
-`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.
+```bash
+hagiscript npm-sync --manifest ./manifest.json
+hagiscript npm-sync --runtime /opt/hagiscript/node --manifest ./manifest.json
+```
 
-## Release Automation
+This is mainly useful when runtime maintenance also needs a controlled agent CLI or package inventory inside the managed runtime.
 
-GitHub Actions provide three automation paths:
+## Development
 
-- `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`.
+Run from `repos/hagiscript/`:
 
-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.
+```bash
+npm install
+npm test
+npm run build
+npm run pack:check
+```
 
-Run the publish prerequisite check before retrying a failed release:
+Useful runtime-focused checks:
 
 ```bash
-npm run publish:check-prereqs
+npm run integration:runtime-management
+npm run integration:installed-runtime
 ```
 
-For local manual releases, run plain `npm publish` after logging in with an npm account that can publish under `@hagicode`.
-
 ## License
 
 MIT. See [LICENSE](./LICENSE).

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;