@guiho/runx 0.2.6 → 0.4.0

package/library/upgrade-reporting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-reporting.d.ts","sourceRoot":"","sources":["../source/upgrade-reporting.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAwB,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAE1H,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,GACpB,CAAA;AAED,QAAA,MAAM,oBAAoB,QAAO,MAId,CAAA;AAEnB,QAAA,MAAM,iBAAiB,SAAU,WAAW,KAAG,MAS5B,CAAA;AAEnB,QAAA,MAAM,kBAAkB,UAAW,YAAY,KAAG,MAWjD,CAAA;AAED,QAAA,MAAM,mBAAmB,WAAY,eAAe,KAAG,MAWtD,CAAA;AAYD,QAAA,MAAM,oBAAoB,YAAa,cAAc,KAAG,MAavD,CAAA"}

package/library/upgrade-reporting.js

@@ -0,0 +1,67 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export { renderReleaseCatalog, renderUpgradeEvent, renderUpgradeHeading, renderUpgradePlan, renderUpgradeResult, };
+const renderUpgradeHeading = () => [
+    '------------------------------------------------------------',
+    '  Upgrading the CLI',
+    '------------------------------------------------------------',
+].join('\n') + '\n';
+const renderUpgradePlan = (plan) => [
+    `  current : ${plan.currentVersion}`,
+    `  target  : ${plan.targetVersion}`,
+    `  os      : ${plan.os}`,
+    `  arch    : ${plan.arch}`,
+    `  binary  : ${plan.assetName}`,
+    `  path    : ${plan.executablePath.replaceAll('\\', '/')}`,
+    `  url     : ${plan.assetUrl}`,
+    '------------------------------------------------------------',
+].join('\n') + '\n';
+const renderUpgradeEvent = (event) => {
+    if (event.status !== 'started' || event.phase === 'plan')
+        return '';
+    const labels = {
+        download: 'Downloading...',
+        validate: 'Validating...',
+        replace: 'Replacing...',
+        verify: 'Verifying...',
+        cleanup: 'Cleaning up...',
+    };
+    const label = labels[event.phase];
+    return label ? `${label}\n` : '';
+};
+const renderUpgradeResult = (result) => {
+    const summary = result.outcome === 'upgraded'
+        ? `Upgrade complete: ${result.plan?.currentVersion} -> ${result.plan?.targetVersion}`
+        : result.outcome === 'up-to-date'
+            ? `Already up to date: ${result.result?.installedVersion ?? result.recovery.targetVersion}`
+            : result.outcome === 'dry-run'
+                ? `Dry run complete: ${result.plan?.currentVersion} -> ${result.plan?.targetVersion}`
+                : result.outcome === 'rolled-back'
+                    ? `Upgrade failed during ${result.error?.phase ?? 'replace'}; restored RunX ${result.result?.installedVersion ?? result.recovery.targetVersion}.`
+                    : `Upgrade failed during ${result.error?.phase ?? 'plan'}.`;
+    return `${summary}\n\n${renderRecovery(result.recovery, result.outcome === 'failed' || result.outcome === 'rolled-back')}\n`;
+};
+const renderRecovery = (recovery, repair) => [
+    recovery.targetSource === 'fallback-current'
+        ? `Repair reinstall (target lookup failed; pinned to installed RunX ${recovery.targetVersion}):`
+        : `${repair ? 'To repair RunX' : 'If the new version is not active'}, install RunX ${recovery.targetVersion} directly:`,
+    `  ${recovery.installCommand}`,
+    '',
+    'If RunX is still running and blocks installation, stop it first:',
+    `  ${recovery.stopProcessCommand}`,
+].join('\n');
+const renderReleaseCatalog = (catalog) => {
+    const headers = ['VERSION', 'CHANNEL', 'PUBLISHED', 'CURRENT', 'LATEST', 'ASSET'];
+    const rows = catalog.releases.map((release) => [
+        release.version,
+        release.channel,
+        release.publishedAt?.slice(0, 10) ?? '-',
+        release.current ? 'yes' : '',
+        release.latestStable ? 'yes' : '',
+        release.compatibleAsset ? 'yes' : 'no',
+    ]);
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)));
+    const line = (values) => values.map((value, index) => value.padEnd(widths[index] ?? value.length)).join('  ').trimEnd();
+    return ['AVAILABLE RUNX VERSIONS', '', line(headers), ...rows.map(line)].join('\n') + '\n';
+};

package/library/upgrade-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export type UpgradeOs = 'windows' | 'darwin' | 'linux';
+export type UpgradeArch = 'x64' | 'arm64';
+export type UpgradeVariant = 'baseline' | 'default' | 'modern';
+export type ReleaseAsset = {
+    name: string;
+    url: string;
+};
+export type ReleaseCatalogEntry = {
+    tag: string;
+    version: string;
+    channel: string;
+    prerelease: boolean;
+    publishedAt: string | null;
+    current: boolean;
+    latestStable: boolean;
+    compatibleAsset: ReleaseAsset | null;
+};
+export type ReleaseCatalog = {
+    schemaVersion: 1;
+    command: 'runx upgrade list';
+    currentVersion: string;
+    latestStableVersion: string | null;
+    releases: ReleaseCatalogEntry[];
+};
+export type RecoveryInstructions = {
+    targetVersion: string;
+    targetSource: 'resolved' | 'fallback-current';
+    installCommand: string;
+    stopProcessCommand: string;
+};
+export type UpgradePlan = {
+    currentVersion: string;
+    targetVersion: string;
+    os: UpgradeOs;
+    arch: UpgradeArch;
+    assetName: string;
+    assetUrl: string;
+    executablePath: string;
+};
+export type UpgradePhase = 'plan' | 'download' | 'validate' | 'replace' | 'verify' | 'cache' | 'cleanup';
+export type UpgradePhaseStatus = 'started' | 'succeeded' | 'skipped' | 'failed';
+export type UpgradeEvent = {
+    sequence: number;
+    phase: UpgradePhase;
+    status: UpgradePhaseStatus;
+    message?: string;
+};
+export type UpgradeOutcome = 'upgraded' | 'up-to-date' | 'dry-run' | 'rolled-back' | 'failed';
+export type UpgradeResult = {
+    installedVersion: string;
+    cleanupDeferred: boolean;
+};
+export type UpgradeErrorCode = 'release_lookup_failed' | 'release_payload_invalid' | 'no_compatible_asset' | 'download_failed' | 'download_invalid' | 'backup_failed' | 'replace_failed' | 'verification_failed' | 'rollback_failed' | 'installer_verification_failed';
+export type UpgradeError = {
+    code: UpgradeErrorCode;
+    phase: UpgradePhase;
+    message: string;
+};
+export type UpgradeEnvelope = {
+    schemaVersion: 1;
+    command: 'runx upgrade';
+    outcome: UpgradeOutcome;
+    plan: UpgradePlan | null;
+    events: UpgradeEvent[];
+    result: UpgradeResult | null;
+    recovery: RecoveryInstructions;
+    error: UpgradeError | null;
+};
+//# sourceMappingURL=upgrade-types.d.ts.map

package/library/upgrade-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-types.d.ts","sourceRoot":"","sources":["../source/upgrade-types.ts"],"names":[],"mappings":"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"}

package/library/upgrade-types.js

@@ -0,0 +1,3 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.2.6",
+  "version": "0.4.0",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "bin": {
-    "runx": "scripts/runx-bin.ts"
+    "runx": "scripts/runx-bin.mjs"
   },
   "files": [
     "library/",
@@ -57,6 +57,7 @@
     "build": "rm -rf library && tsc -p .",
     "binary": "bun build source/guiho-runx-native-bin.ts --compile --outfile bin/runx",
     "binaries": "bun run devops/build-binaries.ts",
+    "verify-assets": "bun run devops/verify-release-assets.ts",
     "test": "bun test",
     "typecheck": "tsc -p . --noEmit",
     "check": "bun run typecheck && bun test",
@@ -69,10 +70,12 @@
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.52",
-    "citty": "^0.2.2"
+    "citty": "^0.2.2",
+    "semver": "^7.8.5"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",
+    "@types/semver": "^7.7.1",
     "typescript": "^7.0.2"
   }
 }

package/scripts/runx-bin.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { spawn } from 'node:child_process'
+import { chmod, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { arch, homedir, platform } from 'node:os'
+import { join } from 'node:path'
+
+import packageJson from '../package.json' with { type: 'json' }
+
+const os = platform() === 'win32' ? 'windows' : platform() === 'darwin' ? 'darwin' : platform() === 'linux' ? 'linux' : null
+const cpu = arch() === 'x64' ? 'x64' : arch() === 'arm64' ? 'arm64' : null
+if (!os || !cpu) fail(`Unsupported platform: ${platform()} ${arch()}`)
+
+const suffix = os === 'windows' ? '.exe' : ''
+const asset = cpu === 'arm64' ? `runx-${os}-arm64${suffix}` : `runx-${os}-x64-baseline${suffix}`
+const cache = process.env.RUNX_NATIVE_CACHE || join(homedir(), '.guiho', 'runx', 'npm', packageJson.version)
+const executable = join(cache, `runx${suffix}`)
+const tag = encodeURIComponent(`@guiho/runx@${packageJson.version}`)
+const downloadBase = (process.env.RUNX_DOWNLOAD_BASE_URL || 'https://github.com/CGuiho/runx/releases/download').replace(/\/$/, '')
+const url = `${downloadBase}/${tag}/${asset}`
+
+try {
+  await stat(executable)
+} catch {
+  await mkdir(cache, { recursive: true })
+  const response = await fetch(url, { redirect: 'follow' })
+  if (!response.ok) fail(`Could not download ${asset}: HTTP ${response.status}`)
+  const temporary = `${executable}.${process.pid}.tmp`
+  await writeFile(temporary, new Uint8Array(await response.arrayBuffer()), { flag: 'wx' })
+  if (os !== 'windows') await chmod(temporary, 0o755)
+  await rename(temporary, executable)
+}
+
+const child = spawn(executable, process.argv.slice(2), { env: process.env, stdio: 'inherit' })
+child.once('error', (error) => fail(error.message))
+child.once('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  else process.exit(code ?? 1)
+})
+
+function fail(message) {
+  process.stderr.write(`error: ${message}\n`)
+  void rm(executable, { force: true }).catch(() => undefined)
+  process.exit(1)
+}

package/scripts/runx-bin.spec.ts

@@ -0,0 +1,62 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+let directory = ''
+
+afterEach(async () => {
+  if (directory) await rm(directory, { recursive: true, force: true })
+  directory = ''
+})
+
+test('packed npm bootstrap downloads and delegates with Node while Bun is absent from PATH', async () => {
+  const node = Bun.which('node')
+  if (!node) throw new Error('Node is required for the npm bootstrap test.')
+  directory = await mkdtemp(join(tmpdir(), 'runx-npm-'))
+  const root = Bun.fileURLToPath(new URL('..', import.meta.url))
+  const packed = Bun.spawn([process.execPath, 'pm', 'pack', '--destination', directory, '--ignore-scripts'], {
+    cwd: root,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [packCode, packOutput, packError] = await Promise.all([
+    packed.exited,
+    new Response(packed.stdout).text(),
+    new Response(packed.stderr).text(),
+  ])
+  expect(packCode, packError).toBe(0)
+  const archiveName = [...new Bun.Glob('*.tgz').scanSync({ cwd: directory, onlyFiles: true })][0]
+  expect(archiveName, packOutput).toBeDefined()
+  const extraction = Bun.spawn(['tar', '-xzf', join(directory, archiveName), '-C', directory])
+  expect(await extraction.exited).toBe(0)
+
+  const server = Bun.serve({ port: 0, fetch: () => new Response(Bun.file(process.execPath)) })
+  try {
+    const wrapper = join(directory, 'package', 'scripts', 'runx-bin.mjs')
+    const child = Bun.spawn([node, wrapper, '--version'], {
+      cwd: join(directory, 'package'),
+      env: {
+        ...process.env,
+        PATH: join(node, '..'),
+        RUNX_NATIVE_CACHE: join(directory, 'native-cache'),
+        RUNX_DOWNLOAD_BASE_URL: `http://127.0.0.1:${server.port}`,
+      },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [exitCode, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ])
+    expect(exitCode, stderr).toBe(0)
+    expect(stdout.trim()).toBe(process.versions.bun)
+  } finally {
+    server.stop(true)
+  }
+})

package/scripts/scripts.xdocs.md

@@ -4,7 +4,8 @@ description: Package-manager launcher scripts for RunX.
 parent: runx
 children: []
 files:
-  runx-bin.ts: Executes a packaged native binary, the published compiled library launcher, or the source CLI fallback in a checkout.
+  runx-bin.mjs: Node-compatible npm bootstrap that downloads, caches, and delegates to the exact native release binary.
+  runx-bin.spec.ts: Packs the npm package and proves Node-only bootstrap download/delegation with Bun absent from PATH.
 documents: {}
 tags:
   - scripts
@@ -16,5 +17,4 @@ flags: []
 status: stable
 ---
 
-The package launcher preserves the `runx` bin command in installed npm packages
-and development checkouts without requiring unpublished source files.
+The npm launcher contains no RunX domain logic and requires no Bun installation.

package/skills/guiho-s-runx/SKILL.md

@@ -1,73 +1,78 @@
 ---
 name: guiho-s-runx
-purpose: Guide agents through safe inspection and execution of RunX command catalogs.
-description: Use when inspecting, creating, validating, organizing, documenting, or running a RunX `runx.yaml` command catalog. This includes listing available project commands, choosing a command by UID or selector, reviewing command descriptions, dry runs, confirmation-gated execution, and agent-safe project automation.
-created: 2026-07-12
-owner: guiho-s-runx
-flags: []
+description: Use when inspecting, validating, documenting, or safely executing a RunX runx.yaml command catalog.
+purpose: Teach agents the supported RunX catalog inspection and execution workflow.
+created: 2026-07-18
+flags:
+  - bundled
 tags:
-  - agents
   - runx
+  - cli
 keywords:
-  - runx
-  - citty
+  - runx.yaml
   - command catalog
   - dry run
+owner: guiho-s-runx
+metadata:
+  version: "0.2.0"
 ---
 
 # GUIHO RunX
 
-Use RunX as the command catalog for a project. It documents executable local
-commands but does not make them inherently safe: a manifest is trusted code.
-
-## Inspect Before Executing
-
-1. From the intended project directory, run `runx check --format json`.
-2. Run `runx list --format json` to inspect groups, UIDs, summaries, tags, and
-   confirmation requirements.
-3. Choose a stable `uid` for automation. An index is only for the current list
-   and an unqualified ID can be ambiguous.
-4. Run `runx describe <uid>` before an unfamiliar or high-impact command.
-5. Run `runx run <uid> --dry-run` before a real execution when the command has
-   filesystem, database, release, deployment, or production effects.
-
-## Execute Safely
-
-- Use `runx run <uid>` or the short alias `runx r <uid>`.
-- `runx <selector>` is allowed as a human shorthand only when it cannot be
-  confused with a built-in command; agents should prefer explicit `runx run`.
-- If `confirm: always` is set, RunX requires `--yes`.
-- Add `--yes` only after the user explicitly authorizes the specific command.
-- Do not treat a group name such as `development` or `operations` as a safety
-  guarantee. Read the command description and command text.
-- Do not add secrets to `runx.yaml`. Use the project's existing environment or
-  secret-management workflow.
-- Use `runx <command> --help` for command-specific Citty usage. `runx -h` and
-  `runx -v` are global operations and do not require a manifest.
-
-## Maintain Manifests
-
-- Keep `uid`, `id`, `group`, `summary`, `description`, and `command` present.
-- Keep UIDs stable; never reuse a UID for a materially different command.
-- Use a group for organization, a concise summary for listings, and a complete
-  description for prerequisites, effects, and risk.
-- Set `confirm: always` for destructive, release, deployment, migration, and
-  production-impacting commands when confirmation is useful.
-- Run `runx check` after every manifest change. It rejects unknown fields,
-  duplicate UIDs/selectors, missing descriptions, invalid working directories,
-  and unsupported shell choices.
-
-## Useful Commands
+## Inspect Before Execution
+
+1. Run `runx check --format json`.
+2. Run `runx list --format json`.
+3. Prefer a stable UID for automation.
+4. Run `runx describe <uid>` before unfamiliar work.
+5. Run `runx run <uid> --dry-run` before any mutation or high-impact command.
+
+RunX manifests are trusted executable code. A group name is not a safety
+boundary. Never add `--yes` unless the developer explicitly authorizes the
+specific confirmation-gated command.
+
+## Configuration
+
+RunX resolves YAML only:
+
+1. `--config <path>`;
+2. effective-cwd `runx.yaml`;
+3. `~/.guiho/runx/runx.yaml`.
+
+It does not search parent directories.
+
+## Execute
+
+Use only:
 
 ```text
-runx                         Show the RunX home page and usage.
-runx -h                      Show generated command help.
-runx -v                      Show the installed version.
-runx list                    List the nearest manifest.
-runx describe <uid>          Explain one command without execution.
-runx run <uid> --dry-run     Inspect the execution plan.
-runx r <uid>                 Run through the short alias.
-runx agents install local    Install this skill into .agents/skills.
-runx --help-tree             Show the command hierarchy.
-runx --help-docs             Show manifest documentation guidance.
+runx run <uid>
 ```
+
+Listing, describing, checking, help, agent operations, and dry runs must never
+execute a manifest command. Preserve the child command's exact exit code.
+
+## Maintain Catalogs
+
+- Keep `uid`, `id`, `group`, `summary`, `description`, and `command`.
+- Keep UIDs stable and never reuse one for materially different behavior.
+- Use `confirm: always` for destructive, release, deployment, migration, and
+  production-impacting operations.
+- Do not place secrets in `runx.yaml`.
+- Run `runx check` after every change.
+
+## Agent And Upgrade Commands
+
+```text
+runx agent skill list
+runx agent skill show guiho-s-runx
+runx agent instruction show
+runx agent prompt list --names
+runx agent prompt show guiho-i-runx
+runx upgrade check
+runx upgrade list
+runx upgrade --dry-run
+```
+
+Use `--help`, `--help-tree`, or `--help-docs` at any command scope for the
+current executable contract.

package/skills/guiho-s-runx/guiho-s-runx.xdocs.md

@@ -1,12 +1,12 @@
 ---
 subject: guiho-s-runx
-description: Agent workflow for inspecting, validating, getting Citty usage for, and safely executing RunX manifest commands.
+description: Agent workflow for safe RunX catalog execution and verified native upgrade/list/recovery operations.
 parent: runx-skills
 children: []
 files:
-  SKILL.md: RunX-specific agent instructions, help aliases, and safe execution workflow.
+  SKILL.md: RFC-aligned RunX catalog inspection, execution safety, YAML precedence, agent, and upgrade guidance.
 documents:
-  SKILL.md: RunX-specific agent instructions, Citty help/version guidance, and safe execution workflow.
+  SKILL.md: RunX-specific command execution and verified native self-upgrade workflow.
 tags:
   - agents
   - runx
@@ -15,9 +15,12 @@ keywords:
   - citty
   - command catalog
   - dry run
+  - runx upgrade
+  - recovery install
 flags: []
 status: stable
 ---
 
 The skill makes manifest inspection, UID selection, dry runs, and explicit
-confirmation the default agent workflow for RunX commands.
+confirmation the default agent workflow for RunX commands and teaches agents
+how to interpret transactional native upgrades and their recovery contract.

package/skills/skills.xdocs.md

@@ -16,4 +16,4 @@ flags: []
 status: stable
 ---
 
-Bundled skills ship with RunX and can be installed through `runx agents install`.
+Bundled skills ship with RunX and can be managed through `runx agent skill`.

package/docs/todo/implement-runx-alpha.md

@@ -1,36 +0,0 @@
----
-name: Implement RunX Alpha Command Catalog
-purpose: Define the expected outcome, constraints, and completion signals for task 1 in TODO.md.
-description: Describes the first RunX CLI release and the safety, documentation, and validation constraints that govern it.
-created: 2026-07-12
-flags:
-  - implementation
-tags:
-  - todo
-  - cli
-keywords:
-  - runx
-  - alpha
-owner: runx-todo
----
-
-# Implement RunX Alpha Command Catalog
-
-## Todo Index
-
-- Task: `1. Implement RunX Alpha Command Catalog`
-- Status: completed
-- Index: [TODO.md](../../TODO.md)
-
-## Outcome
-
-Deliver a documented, locally executable RunX alpha that meets the approved
-command-catalog acceptance criteria without publishing a package.
-
-## Watch-outs
-
-- Preserve read-only behavior for list, describe, check, and dry run paths.
-- Never place secrets in a manifest or run confirmation-gated commands without
-  `--yes`.
-- Keep every new module and document represented by XDocs metadata.
-- Use Mirror for the version transition and keep commits one file at a time.

package/scripts/runx-bin.ts

@@ -1,24 +0,0 @@
-#!/usr/bin/env bun
-
-const args = process.argv.slice(2)
-const binaryPath = new URL(`../vendor/runx${process.platform === 'win32' ? '.exe' : ''}`, import.meta.url)
-const libraryPath = new URL('../library/guiho-runx-bin.js', import.meta.url)
-const sourcePath = new URL('../source/guiho-runx-bin.ts', import.meta.url)
-
-if (await Bun.file(binaryPath).exists()) {
-  const child = Bun.spawn([Bun.fileURLToPath(binaryPath), ...args], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
-  process.exit(await child.exited)
-}
-
-if (await Bun.file(libraryPath).exists()) {
-  const child = Bun.spawn([process.execPath, Bun.fileURLToPath(libraryPath), ...args], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
-  process.exit(await child.exited)
-}
-
-if (await Bun.file(sourcePath).exists()) {
-  const child = Bun.spawn([process.execPath, Bun.fileURLToPath(sourcePath), ...args], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
-  process.exit(await child.exited)
-}
-
-console.error('error: RunX executable is unavailable. Install an official native release or reinstall @guiho/runx.')
-process.exit(1)