@guiho/runx 0.2.6 → 0.4.0

package/library/cli.js

@@ -1,15 +1,21 @@
 /**
  * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
-import { resolve } from 'node:path';
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
 import { defineCommand, renderUsage, runCommand as runCittyCommand } from 'citty';
-import { installAgentInstructions, installAgentSkill } from './agents.js';
+import { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, } from './agents.js';
 import { RunXError } from './errors.js';
 import { runCommand } from './executor.js';
-import { readVersion, showHelpDocs, showHelpTree, showHome } from './help.js';
+import { readVersion, renderHelpDocs, renderHelpTree } from './help.js';
+import { initializeRunXManifest } from './init.js';
 import { readManifest, resolveCommand } from './manifest.js';
+import { resolvePath } from './path-utils.js';
 import { renderDescription, renderExecutionPlan, renderJson, renderList } from './render.js';
-import { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf } from './self-management.js';
+import { fetchReleaseCatalog, resolveUpgradePlatform } from './release-catalog.js';
+import { checkForLatestVersion, uninstallSelf, upgradeSelf } from './self-management.js';
+import { readCachedUpdateNotice, runUpdateWorker, spawnUpdateWorker } from './update-cache.js';
+import { renderReleaseCatalog, renderUpgradeEvent, renderUpgradeHeading, renderUpgradePlan, renderUpgradeResult } from './upgrade-reporting.js';
 export { runCli, runCliWithErrorHandling, runxCommand, };
 class CliHandled extends Error {
 }
@@ -21,199 +27,202 @@ class CliUsageError extends Error {
         this.usage = usage;
     }
 }
-const commonArgs = {
-    cwd: { type: 'string', description: 'Resolve the manifest from this directory.', valueHint: 'path' },
-    file: { type: 'string', description: 'Use this runx.yaml file.', valueHint: 'path' },
-    format: { type: 'string', description: 'Select text or JSON output.', valueHint: 'text|json', default: 'text' },
-    verbose: { type: 'boolean', description: 'Enable additional diagnostics.' },
-    'help-tree': { type: 'boolean', description: 'Show the complete command hierarchy.' },
-    'help-docs': { type: 'boolean', description: 'Show manifest and agent guidance.' },
+const formatSchema = Type.Union([Type.Literal('text'), Type.Literal('json')]);
+const archSchema = Type.Union([Type.Literal('x64'), Type.Literal('arm64')]);
+const variantSchema = Type.Union([Type.Literal('baseline'), Type.Literal('default'), Type.Literal('modern')]);
+const positiveIntegerSchema = Type.Integer({ minimum: 1 });
+const helpArgs = {
     help: { type: 'boolean', alias: 'h', description: 'Show command help.' },
-    version: { type: 'boolean', alias: 'v', description: 'Show the RunX version.' },
+    'help-tree': { type: 'boolean', description: 'Show this command hierarchy.' },
+    'help-tree-depth': { type: 'string', valueHint: 'positive-integer', description: 'Limit help-tree recursion depth.' },
+    'help-docs': { type: 'boolean', description: 'Emit Markdown documentation for this command.' },
 };
-const runArgs = {
-    ...commonArgs,
-    'dry-run': { type: 'boolean', description: 'Show the action without executing it.' },
-    yes: { type: 'boolean', description: 'Approve a confirmation-gated command.' },
+const catalogArgs = {
+    cwd: { type: 'string', valueHint: 'path', description: 'Use this effective working directory.' },
+    config: { type: 'string', valueHint: 'path', description: 'Use this runx.yaml configuration file.' },
+    format: { type: 'string', valueHint: 'text|json', default: 'text', description: 'Select output format.' },
+    verbose: { type: 'boolean', description: 'Enable diagnostics.' },
+    ...helpArgs,
 };
-const agentInstallArgs = {
-    ...commonArgs,
-    tool: { type: 'string', description: 'Select agents, claude, or all.', valueHint: 'agents|claude|all' },
-};
-const selfManagementArgs = {
-    ...commonArgs,
-    'dry-run': { type: 'boolean', description: 'Show the action without changing the executable.' },
-};
-const rootArgs = {
-    ...runArgs,
-    tool: agentInstallArgs.tool,
-};
-const knownArgumentKeys = new Set([
-    '_',
-    'cwd',
-    'file',
-    'format',
-    'verbose',
-    'dryRun',
-    'dry-run',
-    'yes',
-    'tool',
-    'helpTree',
-    'help-tree',
-    'helpDocs',
-    'help-docs',
-    'help',
-    'h',
-    'version',
-    'v',
-]);
-const createCommandTree = () => {
-    const state = { globalArgs: { _: [] }, usageCommand: {} };
-    const listCommand = defineCommand({
-        meta: { name: 'runx list', description: 'List commands in a RunX manifest.' },
-        args: commonArgs,
-        setup: withCommandHelp(state),
-        run: async () => listCommands(resolveOptions(state.globalArgs)),
-    });
-    const describeCommandDefinition = defineCommand({
-        meta: { name: 'runx describe', description: 'Describe one manifest command.' },
-        args: {
-            selector: { type: 'positional', description: 'Command UID, group/id, index, or unambiguous ID.' },
-            ...commonArgs,
-        },
-        setup: withCommandHelp(state),
-        run: async ({ args }) => {
-            if (!args.selector)
-                throw await missingSelector(state);
-            await describeCommand(args.selector, resolveOptions(state.globalArgs));
-        },
-    });
-    const runCommandDefinition = createRunCommand(state);
-    const checkCommand = defineCommand({
-        meta: { name: 'runx check', description: 'Validate a RunX manifest without executing it.' },
-        args: commonArgs,
-        setup: withCommandHelp(state),
-        run: async () => checkManifest(resolveOptions(state.globalArgs)),
-    });
-    const agentsInstallCommand = defineCommand({
-        meta: { name: 'runx agents install', description: 'Install the bundled RunX skill.' },
-        args: {
-            scope: { type: 'positional', description: 'Install locally or globally.', default: 'local', valueHint: 'local|global' },
-            ...agentInstallArgs,
-        },
-        setup: withCommandHelp(state),
-        run: async ({ args }) => runAgentsInstall(args.scope, resolveOptions(state.globalArgs), state.globalArgs),
-    });
-    const agentsInstructionsCommand = defineCommand({
-        meta: { name: 'runx agents instructions', description: 'Install or refresh managed RunX agent instructions.' },
-        args: commonArgs,
-        setup: withCommandHelp(state),
-        run: async () => runAgentsInstructions(resolveOptions(state.globalArgs)),
-    });
-    const agentsCommand = defineCommand({
-        meta: { name: 'runx agents', description: 'Manage the bundled RunX agent integration.' },
-        args: agentInstallArgs,
-        subCommands: {
-            install: agentsInstallCommand,
-            instructions: agentsInstructionsCommand,
-        },
-        setup: withCommandHelp(state),
+function createCommandTree() {
+    const state = { args: { _: [] }, command: {}, commands: new Map() };
+    const leaf = (name, description, args, run) => {
+        const command = defineCommand({ meta: { name, description }, args: { ...args, ...helpArgs }, setup: helpSetup(state), run });
+        state.commands.set(name.replace(/^runx(?:\s+|$)/, ''), command);
+        return command;
+    };
+    const list = leaf('runx list', 'List commands in a RunX configuration.', catalogArgs, async () => listCommands(options(state.args)));
+    const describe = leaf('runx describe', 'Describe one catalog command without execution.', {
+        selector: { type: 'positional', description: 'UID, group/id, index, or unambiguous ID.' },
+        ...catalogArgs,
+    }, async ({ args }) => {
+        if (!args.selector)
+            throw await usageError(state, 'Missing required positional argument: SELECTOR');
+        await describeCommand(String(args.selector), options(state.args));
     });
-    const upgradeApplyCommand = defineCommand({
-        meta: { name: 'runx upgrade', description: 'Upgrade a native RunX executable.', hidden: true },
-        args: selfManagementArgs,
-        setup: withCommandHelp(state),
-        run: async () => runUpgrade(resolveOptions(state.globalArgs), state.globalArgs),
+    const run = leaf('runx run', 'Execute one selected catalog command.', {
+        selector: { type: 'positional', description: 'UID, group/id, index, or unambiguous ID.' },
+        ...catalogArgs,
+        'dry-run': { type: 'boolean', description: 'Print the execution plan without spawning.' },
+        yes: { type: 'boolean', description: 'Approve a confirmation-gated command.' },
+    }, async ({ args }) => {
+        if (!args.selector)
+            throw await usageError(state, 'Missing required positional argument: SELECTOR');
+        await runSelected(String(args.selector), options(state.args), state.args);
     });
-    const upgradeCheckCommand = defineCommand({
-        meta: { name: 'runx upgrade check', description: 'Check whether a newer RunX release is available.' },
-        args: commonArgs,
-        setup: withCommandHelp(state),
-        run: async () => runUpgradeCheck(resolveOptions(state.globalArgs)),
+    const check = leaf('runx check', 'Validate a RunX configuration without execution.', catalogArgs, async () => checkManifest(options(state.args)));
+    const init = leaf('runx init', 'Create a new YAML RunX configuration.', catalogArgs, async () => {
+        const result = await initializeRunXManifest({ cwd: options(state.args).cwd, config: options(state.args).config });
+        write(state.args.format === 'json' ? renderJson(result) : `created: ${result.path}\n`);
     });
-    const upgradeListCommand = defineCommand({
-        meta: { name: 'runx upgrade list', description: 'List recent RunX release versions.' },
-        args: commonArgs,
-        setup: withCommandHelp(state),
-        run: async () => runUpgradeList(resolveOptions(state.globalArgs)),
+    const skillInstall = leaf('runx agent skill install', 'Install the bundled skill into both global tool locations.', {
+        cwd: catalogArgs.cwd, local: { type: 'boolean', description: 'Use project-local tool directories.' }, format: catalogArgs.format,
+    }, async () => agentMutation('installed', installAgentSkill, state.args));
+    const skillUninstall = leaf('runx agent skill uninstall', 'Remove the bundled skill from both tool locations.', {
+        cwd: catalogArgs.cwd, local: { type: 'boolean', description: 'Use project-local tool directories.' }, format: catalogArgs.format,
+    }, async () => agentMutation('removed', uninstallAgentSkill, state.args));
+    const skillUpdate = leaf('runx agent skill update', 'Refresh the bundled skill in both tool locations.', {
+        cwd: catalogArgs.cwd, local: { type: 'boolean', description: 'Use project-local tool directories.' }, format: catalogArgs.format,
+    }, async () => agentMutation('updated', updateAgentSkill, state.args));
+    const skillList = leaf('runx agent skill list', 'List bundled RunX skills.', {
+        filter: { type: 'string', valueHint: 'keyword', description: 'Filter skill metadata.' }, format: catalogArgs.format,
+    }, () => writeFormatted(listAgentSkills(state.args.filter), state.args));
+    const skillShow = leaf('runx agent skill show', 'Show metadata for one bundled skill.', {
+        id: { type: 'positional', description: 'Bundled skill ID.' }, format: catalogArgs.format,
+    }, async ({ args }) => {
+        if (!args.id)
+            throw await usageError(state, 'Missing required positional argument: ID');
+        writeFormatted(await showAgentSkill(String(args.id)), state.args);
     });
-    const upgradeCommand = defineCommand({
-        meta: { name: 'runx upgrade', description: 'Inspect or upgrade a native RunX executable.' },
-        args: selfManagementArgs,
-        default: '_apply',
-        subCommands: {
-            _apply: upgradeApplyCommand,
-            check: upgradeCheckCommand,
-            list: upgradeListCommand,
-        },
-        setup: withCommandHelp(state),
+    const skill = group('runx agent skill', 'Manage the bundled RunX skill.', { install: skillInstall, uninstall: skillUninstall, update: skillUpdate, list: skillList, show: skillShow }, state);
+    const instructionApply = leaf('runx agent instruction apply', 'Apply the managed instruction block.', { cwd: catalogArgs.cwd, format: catalogArgs.format }, async () => instructionMutation('updated', applyAgentInstructions, state.args));
+    const instructionRemove = leaf('runx agent instruction remove', 'Remove the managed instruction block.', { cwd: catalogArgs.cwd, format: catalogArgs.format }, async () => instructionMutation('removed', removeAgentInstructions, state.args));
+    const instructionUpdate = leaf('runx agent instruction update', 'Replace stale managed instruction content.', { cwd: catalogArgs.cwd, format: catalogArgs.format }, async () => instructionMutation('updated', updateAgentInstructions, state.args));
+    const instructionShow = leaf('runx agent instruction show', 'Print the raw instruction template.', {}, async () => write(await showAgentInstructions()));
+    const instruction = group('runx agent instruction', 'Manage RunX instruction blocks.', { apply: instructionApply, remove: instructionRemove, update: instructionUpdate, show: instructionShow }, state);
+    const promptList = leaf('runx agent prompt list', 'List bundled RunX prompts.', {
+        names: { type: 'boolean', description: 'Print prompt names only.' }, format: catalogArgs.format,
+    }, () => writeFormatted(listAgentPrompts(Boolean(state.args.names)), state.args));
+    const promptShow = leaf('runx agent prompt show', 'Print one raw bundled prompt.', {
+        id: { type: 'positional', description: 'Bundled prompt ID.' },
+    }, async ({ args }) => {
+        if (!args.id)
+            throw await usageError(state, 'Missing required positional argument: ID');
+        write(await showAgentPrompt(String(args.id)));
     });
-    const uninstallCommand = defineCommand({
-        meta: { name: 'runx uninstall', description: 'Uninstall a native RunX executable.' },
-        args: selfManagementArgs,
-        setup: withCommandHelp(state),
-        run: async () => runUninstall(resolveOptions(state.globalArgs), state.globalArgs),
+    const prompt = group('runx agent prompt', 'Inspect bundled agent prompts.', { list: promptList, show: promptShow }, state);
+    const agent = group('runx agent', 'Manage RunX agent integration.', { skill, instruction, prompt }, state);
+    const upgradeApply = leaf('runx upgrade', 'Upgrade the canonical native RunX executable.', {
+        version: { type: 'string', valueHint: 'version', description: 'Select an exact release version.' },
+        arch: { type: 'string', valueHint: 'x64|arm64', description: 'Select target architecture.' },
+        variant: { type: 'string', valueHint: 'baseline|default|modern', description: 'Select x64 binary variant.' },
+        'dry-run': { type: 'boolean', description: 'Plan without mutation.' },
+        format: catalogArgs.format,
+    }, async () => runUpgrade(options(state.args), state.args));
+    upgradeApply.meta = { ...upgradeApply.meta, hidden: true };
+    const upgradeCheck = leaf('runx upgrade check', 'Check whether a newer stable release exists.', {
+        format: catalogArgs.format,
+    }, async () => {
+        const result = await checkForLatestVersion();
+        writeFormatted(result, state.args);
     });
-    const homeCommand = defineCommand({
-        meta: { name: 'runx', description: 'Show the RunX home page.', hidden: true },
-        args: rootArgs,
-        setup: withCommandHelp(state),
-        run: () => write(showHome()),
+    const upgradeList = leaf('runx upgrade list', 'List RunX releases newest first.', {
+        page: { type: 'string', valueHint: 'positive-integer', description: 'Select result page.' },
+        'per-page': { type: 'string', valueHint: 'positive-integer', description: 'Select page size.' },
+        'pre-releases': { type: 'boolean', description: 'Include prerelease versions.' },
+        arch: { type: 'string', valueHint: 'x64|arm64', description: 'Select target architecture.' },
+        variant: { type: 'string', valueHint: 'baseline|default|modern', description: 'Select x64 variant.' },
+        format: catalogArgs.format,
+    }, async () => runUpgradeList(state.args));
+    const upgrade = group('runx upgrade', 'Inspect or upgrade a native RunX executable.', { _apply: upgradeApply, check: upgradeCheck, list: upgradeList }, state, '_apply');
+    const uninstall = leaf('runx uninstall', 'Uninstall the native RunX executable.', {
+        'dry-run': { type: 'boolean', description: 'Print the target without deleting it.' }, format: catalogArgs.format,
+    }, async () => {
+        const result = await uninstallSelf(Boolean(state.args.dryRun));
+        writeFormatted(result, state.args);
     });
-    const staticSubCommands = Object.assign(Object.create(null), {
-        _home: homeCommand,
-        list: listCommand,
-        describe: describeCommandDefinition,
-        run: runCommandDefinition,
-        check: checkCommand,
-        agents: agentsCommand,
-        upgrade: upgradeCommand,
-        uninstall: uninstallCommand,
-    });
-    const usageCommands = new Map([
-        ['list', listCommand],
-        ['describe', describeCommandDefinition],
-        ['run', runCommandDefinition],
-        ['r', runCommandDefinition],
-        ['check', checkCommand],
-        ['agents', agentsCommand],
-        ['agents install', agentsInstallCommand],
-        ['agents instructions', agentsInstructionsCommand],
-        ['upgrade', upgradeCommand],
-        ['upgrade check', upgradeCheckCommand],
-        ['upgrade list', upgradeListCommand],
-        ['uninstall', uninstallCommand],
-    ]);
-    const subCommands = createSelectorCompatibleCommands(staticSubCommands, state);
-    const command = defineCommand({
-        meta: {
-            name: 'runx',
-            version: readVersion(),
-            description: 'A documented, local command catalog for runx.yaml manifests.',
-        },
-        args: rootArgs,
-        default: '_home',
-        subCommands,
+    const root = defineCommand({
+        meta: { name: 'runx', version: readVersion(), description: 'A documented local command catalog for runx.yaml.' },
+        args: { version: { type: 'boolean', alias: 'v', description: 'Show the RunX version.' }, ...helpArgs },
+        subCommands: { list, describe, run, check, init, agent, upgrade, uninstall },
         setup: async (context) => {
-            state.globalArgs = context.args;
-            state.usageCommand = resolveUsageCommand(context.args._, usageCommands, state);
-            await validateArguments(context, state);
-            if (state.globalArgs.version || state.globalArgs.v)
-                return handleOutput(`${readVersion()}\n`);
-            if (state.globalArgs.helpTree)
-                return handleOutput(`${showHelpTree()}\n`);
-            if (state.globalArgs.helpDocs)
-                return handleOutput(showHelpDocs());
-            if (state.globalArgs.help || state.globalArgs.h)
-                return handleUsage(state.usageCommand);
+            state.args = context.args;
+            state.command = resolveHelpCommand(state);
+            await validateInvocation(state);
+            if (state.args.v || state.args.version === true)
+                return handled(`${readVersion()}\n`);
+            await handleHelp(state);
+        },
+        run: ({ args }) => {
+            if (args._.length === 0)
+                write(`Hello Windows - runx v${readVersion()}\n`);
         },
     });
-    state.usageCommand = command;
-    return { command, state };
-};
+    state.commands.set('', root);
+    state.command = root;
+    return { command: root, state };
+}
+async function validateInvocation(state) {
+    const first = state.args._[0];
+    const topLevel = new Set(['list', 'describe', 'run', 'check', 'init', 'agent', 'upgrade', 'uninstall']);
+    if (first && !topLevel.has(first))
+        throw await usageError(state, `Unknown command: ${first}`);
+    const allowed = new Set(['_', 'h', 'v']);
+    for (const command of state.commands.values()) {
+        for (const key of Object.keys(command.args ?? {})) {
+            allowed.add(key);
+            allowed.add(key.replace(/-([a-z])/g, (_, character) => character.toUpperCase()));
+        }
+    }
+    const unknown = Object.keys(state.args).find((key) => !allowed.has(key));
+    if (unknown)
+        throw await usageError(state, `Unknown option: --${unknown.replace(/[A-Z]/g, (character) => `-${character.toLowerCase()}`)}`);
+}
+function group(name, description, subCommands, state, defaultCommand) {
+    const command = defineCommand({ meta: { name, description }, args: helpArgs, subCommands, ...(defaultCommand ? { default: defaultCommand } : {}), setup: helpSetup(state) });
+    state.commands.set(name.replace(/^runx(?:\s+|$)/, ''), command);
+    return command;
+}
+function helpSetup(state) {
+    return async (context) => {
+        state.args = context.args;
+        state.command = context.cmd;
+        await handleHelp(state);
+    };
+}
+async function handleHelp(state) {
+    if (state.args.helpDocs)
+        return handled(renderHelpDocs(state.command));
+    if (state.args.helpTree || state.args.helpTreeDepth) {
+        const depth = state.args.helpTreeDepth ? positiveInteger(state.args.helpTreeDepth, '--help-tree-depth') : Number.POSITIVE_INFINITY;
+        return handled(renderHelpTree(state.command, depth));
+    }
+    if (state.args.help || state.args.h)
+        return handled(`${await renderUsage(state.command)}\n`);
+}
+function resolveHelpCommand(state) {
+    const tokens = state.args._.filter((token) => !token.startsWith('-'));
+    for (let length = tokens.length; length > 0; length -= 1) {
+        const command = state.commands.get(tokens.slice(0, length).join(' '));
+        if (command)
+            return command;
+    }
+    return state.commands.get('') ?? state.command;
+}
 const { command: runxCommand } = createCommandTree();
 async function runCli(rawArgs = process.argv.slice(2)) {
+    if (rawArgs.length === 1 && rawArgs[0] === '--check-updates-worker') {
+        await runUpdateWorker();
+        return;
+    }
     const { command, state } = createCommandTree();
+    const cleanOutput = rawArgs.some((arg) => ['-h', '--help', '-v', '--version', '--help-tree', '--help-docs'].includes(arg) || arg.startsWith('--help-tree-depth'));
+    if (!cleanOutput && rawArgs.length > 0) {
+        const notice = await readCachedUpdateNotice(rawArgs.includes('--verbose'));
+        if (notice)
+            process.stderr.write(`${notice}\n`);
+    }
+    spawnUpdateWorker();
     try {
         await runCittyCommand(command, { rawArgs });
     }
@@ -222,9 +231,8 @@ async function runCli(rawArgs = process.argv.slice(2)) {
             return;
         if (error instanceof CliUsageError)
             throw error;
-        if (isCittyUsageError(error)) {
-            throw new CliUsageError(error.message, await renderUsage(state.usageCommand));
-        }
+        if (error instanceof Error && error.name === 'CLIError')
+            throw new CliUsageError(error.message, await renderUsage(state.command));
         throw error;
     }
 }
@@ -235,165 +243,137 @@ async function runCliWithErrorHandling(rawArgs) {
     catch (error) {
         if (error instanceof CliUsageError) {
             process.stderr.write(`${error.usage}\n\nerror: ${error.message}\n`);
-            process.exitCode = 1;
-            return;
+            process.exitCode = 2;
         }
-        if (error instanceof RunXError) {
+        else if (error instanceof RunXError) {
             process.stderr.write(`error: ${error.message}\n`);
             process.exitCode = error.exitCode;
-            return;
         }
-        process.stderr.write(`error: ${error instanceof Error ? error.message : 'Unexpected failure.'}\n`);
-        process.exitCode = 1;
-    }
-}
-function createRunCommand(state, selectorDefault) {
-    return defineCommand({
-        meta: {
-            name: selectorDefault ? 'runx <selector>' : 'runx run',
-            alias: selectorDefault ? undefined : 'r',
-            description: selectorDefault ? 'Run a selector using the root shorthand.' : 'Run one manifest command.',
-        },
-        args: selectorDefault
-            ? runArgs
-            : {
-                selector: { type: 'positional', description: 'Command UID, group/id, index, or unambiguous ID.' },
-                ...runArgs,
-            },
-        setup: withCommandHelp(state),
-        run: async ({ args }) => {
-            const selector = selectorDefault ?? (typeof args.selector === 'string' ? args.selector : undefined);
-            if (!selector)
-                throw await missingSelector(state);
-            await runSelectedCommand(selector, resolveOptions(state.globalArgs), state.globalArgs);
-        },
-    });
-}
-function createSelectorCompatibleCommands(commands, state) {
-    const aliases = new Set(['r']);
-    return new Proxy(commands, {
-        has: (target, property) => {
-            if (typeof property !== 'string')
-                return Reflect.has(target, property);
-            if (aliases.has(property))
-                return false;
-            return true;
-        },
-        get: (target, property, receiver) => {
-            if (typeof property !== 'string' || Reflect.has(target, property))
-                return Reflect.get(target, property, receiver);
-            return createRunCommand(state, property);
-        },
-    });
-}
-function resolveUsageCommand(positionals, commands, state) {
-    const name = positionals[0];
-    if (!name)
-        return state.usageCommand;
-    if (!commands.has(name))
-        return createRunCommand(state, name);
-    for (let length = positionals.length; length > 0; length -= 1) {
-        const command = commands.get(positionals.slice(0, length).join(' '));
-        if (command)
-            return command;
+        else {
+            process.stderr.write(`error: ${error instanceof Error ? error.message : 'Unexpected failure.'}\n`);
+            process.exitCode = 1;
+        }
     }
-    return commands.get(name);
-}
-function withCommandHelp(state) {
-    return (context) => {
-        state.usageCommand = context.cmd;
-    };
-}
-async function missingSelector(state) {
-    return new CliUsageError('Missing required positional argument: SELECTOR', await renderUsage(state.usageCommand));
-}
-async function validateArguments(context, state) {
-    const unknown = Object.keys(context.args).find((key) => !knownArgumentKeys.has(key));
-    if (!unknown)
-        return;
-    throw new CliUsageError(`Unknown option --${unknown}`, await renderUsage(state.usageCommand));
-}
-async function handleUsage(command) {
-    return handleOutput(`${await renderUsage(command)}\n`);
 }
-function handleOutput(value) {
-    write(value);
-    throw new CliHandled();
+async function load(optionsValue) {
+    const loaded = await readManifest(optionsValue.cwd, optionsValue.config);
+    const message = `configuration file loaded: ${loaded.path}\n`;
+    if (optionsValue.format === 'json')
+        process.stderr.write(message);
+    else
+        write(message);
+    return loaded;
 }
-async function listCommands(options) {
-    const { manifest, path } = await readManifest(options.cwd, options.file);
-    write(options.format === 'json' ? renderJson({ manifestPath: path, manifest }) : renderList(manifest, path));
+async function listCommands(optionsValue) {
+    const { manifest, path } = await load(optionsValue);
+    write(optionsValue.format === 'json' ? renderJson({ manifestPath: path, manifest }) : renderList(manifest, path));
 }
-async function describeCommand(selector, options) {
-    const { manifest, path } = await readManifest(options.cwd, options.file);
+async function describeCommand(selector, optionsValue) {
+    const { manifest, path } = await load(optionsValue);
     const command = resolveCommand(manifest, path, selector);
-    write(options.format === 'json' ? renderJson(command) : renderDescription(command));
+    write(optionsValue.format === 'json' ? renderJson(command) : renderDescription(command));
 }
-async function checkManifest(options) {
-    const { manifest, path } = await readManifest(options.cwd, options.file);
+async function checkManifest(optionsValue) {
+    const { manifest, path } = await load(optionsValue);
     const result = { valid: true, manifestPath: path, commandCount: manifest.commands.length, groups: Object.keys(manifest.groups) };
-    write(options.format === 'json' ? renderJson(result) : `valid: true\nmanifest: ${path}\ncommands: ${result.commandCount}\n`);
+    write(optionsValue.format === 'json' ? renderJson(result) : `valid: true\nmanifest: ${path}\ncommands: ${result.commandCount}\n`);
 }
-async function runSelectedCommand(selector, options, args) {
-    const { manifest, path } = await readManifest(options.cwd, options.file);
+async function runSelected(selector, optionsValue, args) {
+    const { manifest, path } = await load(optionsValue);
     const command = resolveCommand(manifest, path, selector);
     if (args.dryRun) {
-        write(options.format === 'json' ? renderJson({ dryRun: true, command }) : renderExecutionPlan(command));
+        write(optionsValue.format === 'json' ? renderJson({ dryRun: true, command }) : renderExecutionPlan(command));
         return;
     }
-    if (command.confirm === 'always' && !args.yes) {
-        throw new RunXError(`Command ${command.uid} requires confirmation. Review it with \`runx describe ${command.uid}\` and rerun with --yes when authorized.`);
-    }
-    if (options.format === 'text')
+    if (command.confirm === 'always' && !args.yes)
+        throw new RunXError(`Command ${command.uid} requires confirmation. Rerun with --yes only after authorization.`, 2);
+    if (optionsValue.format === 'text')
         write(`Running ${command.uid} (${command.selector})\n`);
     process.exitCode = await runCommand(command);
 }
-async function runAgentsInstall(scopeValue, options, args) {
-    const scope = scopeValue;
-    if (scope !== 'local' && scope !== 'global')
-        throw new RunXError('Agent scope must be local or global.');
-    const tool = (args.tool ?? 'agents');
-    if (!['agents', 'claude', 'all'].includes(tool))
-        throw new RunXError('Agent tool must be agents, claude, or all.');
-    const installed = await installAgentSkill(scope, tool, options.cwd);
-    write(options.format === 'json' ? renderJson({ installed }) : `${installed.map((path) => `installed: ${path}`).join('\n')}\n`);
+async function agentMutation(label, action, args) {
+    try {
+        const paths = await action(args.local ? 'local' : 'global', resolvePath(args.cwd ?? process.cwd()));
+        writeFormatted({ [label]: paths }, args);
+    }
+    catch (error) {
+        if (error instanceof RunXError)
+            throw error;
+        throw new RunXError(`Agent skill mutation failed: ${error instanceof Error ? error.message : String(error)}`, 5);
+    }
+}
+async function instructionMutation(label, action, args) {
+    try {
+        const paths = await action(resolvePath(args.cwd ?? process.cwd()));
+        writeFormatted({ [label]: paths }, args);
+    }
+    catch (error) {
+        if (error instanceof RunXError)
+            throw error;
+        throw new RunXError(`Agent instruction mutation failed: ${error instanceof Error ? error.message : String(error)}`, 5);
+    }
+}
+async function runUpgradeList(args) {
+    const requestedArch = args.arch ? decode(archSchema, args.arch, '--arch') : process.arch;
+    const platform = resolveUpgradePlatform(process.platform, requestedArch);
+    const variant = decode(variantSchema, args.variant ?? 'baseline', '--variant');
+    const page = positiveInteger(args.page ?? '1', '--page');
+    const perPage = positiveInteger(args.perPage ?? '20', '--per-page');
+    const catalog = await fetchReleaseCatalog({ ...platform, variant, currentVersion: readVersion() });
+    const filtered = args.preReleases ? catalog.releases : catalog.releases.filter((release) => !release.prerelease);
+    const paged = { ...catalog, releases: filtered.slice((page - 1) * perPage, page * perPage) };
+    write(options(args).format === 'json' ? renderJson(paged) : renderReleaseCatalog(paged));
 }
-async function runAgentsInstructions(options) {
-    const path = await installAgentInstructions(options.cwd);
-    write(options.format === 'json' ? renderJson({ instructions: path }) : `updated: ${path}\n`);
+async function runUpgrade(optionsValue, args) {
+    if (args.arch)
+        decode(archSchema, args.arch, '--arch');
+    if (args.variant)
+        decode(variantSchema, args.variant, '--variant');
+    const text = optionsValue.format === 'text';
+    if (text)
+        write(renderUpgradeHeading());
+    const result = await upgradeSelf({
+        dryRun: Boolean(args.dryRun),
+        requestedVersion: typeof args.version === 'string' ? args.version : undefined,
+        arch: args.arch,
+        variant: args.variant,
+        onPlan: text ? (plan) => write(renderUpgradePlan(plan)) : undefined,
+        onEvent: text ? (event) => write(renderUpgradeEvent(event)) : undefined,
+    });
+    write(text ? renderUpgradeResult(result) : renderJson(result));
+    if (result.outcome === 'failed' || result.outcome === 'rolled-back')
+        process.exitCode = result.error?.code.includes('download') ? 4 : 5;
 }
-async function runUpgradeCheck(options) {
-    const result = await checkForLatestVersion();
-    write(options.format === 'json' ? renderJson(result) : `current: ${result.currentVersion}\nlatest: ${result.latestVersion}\nupdate_available: ${result.updateAvailable}\n`);
+function options(args) {
+    const format = decode(formatSchema, args.format ?? 'text', '--format');
+    return { cwd: resolvePath(args.cwd ?? process.cwd()), config: args.config, format: format, verbose: Boolean(args.verbose) };
 }
-async function runUpgradeList(options) {
-    const versions = await listAvailableVersions();
-    write(options.format === 'json' ? renderJson({ versions }) : `${versions.join('\n')}\n`);
+function decode(schema, value, flag) {
+    try {
+        return Value.Decode(schema, value);
+    }
+    catch {
+        throw new RunXError(`Invalid ${flag} value: ${String(value)}`, 2);
+    }
 }
-async function runUpgrade(options, args) {
-    const result = await upgradeSelf(Boolean(args.dryRun));
-    if (options.format === 'json')
-        return write(renderJson(result));
-    const summary = `current: ${result.currentVersion}\ntarget: ${result.latestVersion}\n`;
-    write(result.upToDate ? `${summary}Already up to date.\n` : `${summary}path: ${result.executablePath}\n${result.scheduled ? 'scheduled: true\n' : ''}`);
+function positiveInteger(value, flag) {
+    const number = Number(value);
+    try {
+        return Value.Decode(positiveIntegerSchema, number);
+    }
+    catch {
+        throw new RunXError(`${flag} must be a positive integer.`, 2);
+    }
 }
-async function runUninstall(options, args) {
-    const result = await uninstallSelf(Boolean(args.dryRun));
-    write(options.format === 'json' ? renderJson(result) : `path: ${result.executablePath}\n${result.dryRun ? 'dry_run: true\n' : result.scheduled ? 'scheduled: true\n' : 'uninstalled: true\n'}`);
+async function usageError(state, message) {
+    return new CliUsageError(message, await renderUsage(state.command));
 }
-function resolveOptions(args) {
-    const format = args.format ?? 'text';
-    if (format !== 'text' && format !== 'json')
-        throw new RunXError('Invalid --format value. Expected text or json.');
-    return {
-        cwd: resolve(args.cwd ?? process.cwd()),
-        file: args.file,
-        format: format,
-        verbose: Boolean(args.verbose),
-    };
+function writeFormatted(value, args) {
+    write(options(args).format === 'json' ? renderJson(value) : `${typeof value === 'string' ? value : JSON.stringify(value, null, 2)}\n`);
 }
-function isCittyUsageError(error) {
-    return error instanceof Error && error.name === 'CLIError';
+function handled(value) {
+    write(value.endsWith('\n') ? value : `${value}\n`);
+    throw new CliHandled();
 }
 function write(value) {
     process.stdout.write(value);