@guiho/runx 0.2.0

package/docs/todo/todo.xdocs.md

@@ -0,0 +1,21 @@
+---
+subject: runx-todo
+description: Linked task specifications for the RunX TODO index.
+parent: runx-docs
+children: []
+files:
+  implement-runx-alpha.md: Defines the completion signals and constraints for the alpha task.
+  protect-branches-and-tag-creation.md: Records the verified active GitHub branch and release-tag rulesets for RunX.
+documents:
+  implement-runx-alpha.md: Task specification for implementing RunX alpha.
+  protect-branches-and-tag-creation.md: Completed task specification with active RunX ruleset IDs, protected patterns, and verification evidence.
+tags:
+  - todo
+keywords:
+  - runx
+  - tasks
+flags: []
+status: stable
+---
+
+Task specifications linked from the package-local RunX TODO index.

package/docs/validation/alpha-implementation-summary.md

@@ -0,0 +1,52 @@
+---
+name: RunX Alpha Implementation Summary
+purpose: Summarize the first implemented RunX alpha and preserve its validation evidence.
+description: Records delivered CLI behavior, agent and distribution support, checks run, and release boundaries.
+created: 2026-07-12
+flags:
+  - validated
+tags:
+  - validation
+  - implementation
+keywords:
+  - runx
+  - alpha
+  - summary
+owner: runx-validation
+---
+
+# RunX Alpha Implementation Summary
+
+## Implementation Summary
+
+RunX is implemented as the open-source `@guiho/runx` Bun/TypeScript CLI. The
+alpha discovers one nearest `runx.yaml`, validates it strictly with TypeBox,
+lists documented commands through `runx list`, and runs an explicitly selected
+command through `runx run` or `runx r`. A bare selector remains available as a
+human shorthand; no-argument `runx` now shows the requested home page and usage.
+
+The implementation includes UID/group-ID/index selector handling, JSON output,
+describe, check, dry run, confirmation gates, help/help-tree/help-docs, bundled
+`guiho-s-runx` skill installation, native upgrade and uninstall paths, Windows
+and macOS/Linux direct installers, MIT licensing, and GitHub Actions CI. CI
+validates only; npm and release publishing are intentionally absent.
+
+## Validation Evidence
+
+- `bun run typecheck` passed.
+- `bun test` passed with four tests covering manifest discovery, selector
+  behavior, flags, the `r` alias, dry runs, and real local command execution.
+- `bun run build` passed and emitted the ignored TypeScript library output.
+- `bun run binary` passed and emitted the ignored Windows native executable.
+- The Bun source CLI displayed `--help`, `--help-tree`, and `--help-docs`.
+- `xdocs tree`, `xdocs scan`, and `xdocs doctor --format json` passed. The
+  doctor reported only metadata warnings for the special-purpose skill file;
+  there were no descriptor, document, or tree errors.
+- `mirror config check` passed. Mirror applied the local `0.1.0` minor release
+  and created `@guiho/runx@0.1.0`; the configuration did not push or publish.
+
+## Release Boundary
+
+The initial external capability warranted and received a Mirror minor transition
+from `0.0.0` to `0.1.0`. It created the configured local version commit and Git
+tag without pushing either because `mirror.config.toml` sets `push = false`.

package/docs/validation/validation.xdocs.md

@@ -0,0 +1,21 @@
+---
+subject: runx-validation
+description: Validation evidence and implementation summaries for RunX releases.
+parent: runx-docs
+children: []
+files:
+  alpha-implementation-summary.md: Records the completed alpha implementation, checks, and release boundaries.
+documents:
+  alpha-implementation-summary.md: Validation summary for the first RunX implementation.
+tags:
+  - validation
+keywords:
+  - runx
+  - tests
+  - summary
+flags: []
+status: stable
+---
+
+Validation records document exact checks, results, exclusions, and manual
+release boundaries for RunX.

package/library/agents.d.ts

@@ -0,0 +1,11 @@
+import type { AgentScope, AgentTool } from './types.js';
+type EmbeddedResources = {
+    skill: string;
+} | undefined;
+declare global {
+    var __RUNX_EMBEDDED_RESOURCES__: EmbeddedResources;
+}
+export declare const installAgentSkill: (scope: AgentScope, tool: AgentTool, cwd: string) => Promise<string[]>;
+export declare const installAgentInstructions: (cwd: string) => Promise<string>;
+export {};
+//# sourceMappingURL=agents.d.ts.map

package/library/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAGvD,KAAK,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAA;AAEtD,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,2BAA2B,EAAE,iBAAiB,CAAA;CACnD;AAKD,eAAO,MAAM,iBAAiB,UAAiB,UAAU,QAAQ,SAAS,OAAO,MAAM,KAAG,OAAO,CAAC,MAAM,EAAE,CAiBzG,CAAA;AAED,eAAO,MAAM,wBAAwB,QAAe,MAAM,KAAG,OAAO,CAAC,MAAM,CAgB1E,CAAA"}

package/library/agents.js

@@ -0,0 +1,51 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { RunXError } from './errors.js';
+const managedStart = '<!-- BEGIN RUNX AGENT INSTRUCTIONS -->';
+const managedEnd = '<!-- END RUNX AGENT INSTRUCTIONS -->';
+export const installAgentSkill = async (scope, tool, cwd) => {
+    const root = scope === 'global' ? homedir() : cwd;
+    const skill = await readBundledSkill();
+    const targets = tool === 'all' ? ['agents', 'claude'] : [tool];
+    const installed = [];
+    for (const target of targets) {
+        const directory = target === 'agents'
+            ? join(root, '.agents', 'skills', 'guiho-s-runx')
+            : join(root, '.claude', 'skills', 'guiho-s-runx');
+        const path = join(directory, 'SKILL.md');
+        await mkdir(directory, { recursive: true });
+        await writeFile(path, skill, 'utf8');
+        installed.push(path);
+    }
+    return installed;
+};
+export const installAgentInstructions = async (cwd) => {
+    const path = join(cwd, 'AGENTS.md');
+    let existing = '';
+    try {
+        existing = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    const section = `${managedStart}\n## RunX Command Catalog\n\nUse the bundled \`guiho-s-runx\` skill whenever working with \`runx.yaml\` manifests. Inspect with \`runx check --format json\` and \`runx list --format json\` before selecting a command. Use a UID for automation and require explicit developer approval before \`--yes\` on confirmation-gated commands.\n${managedEnd}`;
+    const pattern = new RegExp(`${escapeRegExp(managedStart)}[\\s\\S]*?${escapeRegExp(managedEnd)}`, 'g');
+    const next = pattern.test(existing) ? existing.replace(pattern, section) : `${existing.trimEnd()}${existing.trim() ? '\n\n' : ''}${section}\n`;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, next, 'utf8');
+    return path;
+};
+const readBundledSkill = async () => {
+    if (globalThis.__RUNX_EMBEDDED_RESOURCES__?.skill)
+        return globalThis.__RUNX_EMBEDDED_RESOURCES__.skill;
+    const path = new URL('../skills/guiho-s-runx/SKILL.md', import.meta.url);
+    try {
+        return await Bun.file(path).text();
+    }
+    catch {
+        throw new RunXError('Bundled guiho-s-runx skill is unavailable. Reinstall RunX from an official release.');
+    }
+};
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/library/cli.d.ts

@@ -0,0 +1,3 @@
+export declare const runCli: (rawArgs?: string[]) => Promise<void>;
+export declare const runCliWithErrorHandling: (rawArgs?: string[]) => Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/library/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,MAAM,aAAmB,MAAM,EAAE,KAA2B,OAAO,CAAC,IAAI,CAyBpF,CAAA;AAED,eAAO,MAAM,uBAAuB,aAAoB,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAY9E,CAAA"}

package/library/cli.js

@@ -0,0 +1,146 @@
+import { resolve } from 'node:path';
+import { installAgentInstructions, installAgentSkill } from './agents.js';
+import { RunXError } from './errors.js';
+import { runCommand } from './executor.js';
+import { booleanFlag, parseArgs, stringFlag } from './flags.js';
+import { readVersion, showCommandHelp, showHelpDocs, showHelpTree, showHome } from './help.js';
+import { readManifest, resolveCommand } from './manifest.js';
+import { renderDescription, renderExecutionPlan, renderJson, renderList } from './render.js';
+import { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf } from './self-management.js';
+const builtins = new Set(['list', 'describe', 'run', 'r', 'check', 'agents', 'upgrade', 'uninstall']);
+export const runCli = async (rawArgs = process.argv.slice(2)) => {
+    const parsed = parseArgs(rawArgs);
+    const options = resolveOptions(parsed.flags);
+    if (booleanFlag(parsed.flags, 'version'))
+        return write(`${readVersion()}\n`);
+    if (booleanFlag(parsed.flags, 'helpTree'))
+        return write(`${showHelpTree()}\n`);
+    if (booleanFlag(parsed.flags, 'helpDocs'))
+        return write(showHelpDocs());
+    if (booleanFlag(parsed.flags, 'help'))
+        return write(parsed.command && builtins.has(parsed.command) ? showCommandHelp(parsed.command) : showHome());
+    if (!parsed.command)
+        return write(showHome());
+    if (!builtins.has(parsed.command)) {
+        await runSelectedCommand(parsed.command, parsed.positionals, options, parsed.flags);
+        return;
+    }
+    switch (parsed.command) {
+        case 'list':
+            await listCommands(options);
+            return;
+        case 'describe':
+            await describeCommand(parsed.positionals[0], options);
+            return;
+        case 'run':
+        case 'r':
+            await runSelectedCommand(parsed.positionals[0], parsed.positionals.slice(1), options, parsed.flags);
+            return;
+        case 'check':
+            await checkManifest(options);
+            return;
+        case 'agents':
+            await runAgents(parsed.positionals, options, parsed.flags);
+            return;
+        case 'upgrade':
+            await runUpgrade(parsed.positionals, options, parsed.flags);
+            return;
+        case 'uninstall':
+            await runUninstall(options, parsed.flags);
+            return;
+    }
+};
+export const runCliWithErrorHandling = async (rawArgs) => {
+    try {
+        await runCli(rawArgs);
+    }
+    catch (error) {
+        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;
+    }
+};
+const listCommands = async (options) => {
+    const { manifest, path } = await readManifest(options.cwd, options.file);
+    write(options.format === 'json' ? renderJson({ manifestPath: path, manifest }) : renderList(manifest, path));
+};
+const describeCommand = async (selector, options) => {
+    if (!selector)
+        throw new RunXError('Missing selector. Usage: runx describe <selector>');
+    const { manifest, path } = await readManifest(options.cwd, options.file);
+    const command = resolveCommand(manifest, path, selector);
+    write(options.format === 'json' ? renderJson(command) : renderDescription(command));
+};
+const checkManifest = async (options) => {
+    const { manifest, path } = await readManifest(options.cwd, options.file);
+    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`);
+};
+const runSelectedCommand = async (selector, _, options, flags) => {
+    if (!selector)
+        throw new RunXError('Missing selector. Usage: runx run <selector>');
+    const { manifest, path } = await readManifest(options.cwd, options.file);
+    const command = resolveCommand(manifest, path, selector);
+    if (booleanFlag(flags, 'dryRun')) {
+        write(options.format === 'json' ? renderJson({ dryRun: true, command }) : renderExecutionPlan(command));
+        return;
+    }
+    if (command.confirm === 'always' && !booleanFlag(flags, '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')
+        write(`Running ${command.uid} (${command.selector})\n`);
+    const exitCode = await runCommand(command);
+    process.exitCode = exitCode;
+};
+const runAgents = async (positionals, options, flags) => {
+    const action = positionals[0];
+    if (action === 'install') {
+        const scope = (positionals[1] ?? 'local');
+        if (scope !== 'local' && scope !== 'global')
+            throw new RunXError('Agent scope must be local or global.');
+        const tool = (stringFlag(flags, '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`);
+        return;
+    }
+    if (action === 'instructions') {
+        const path = await installAgentInstructions(options.cwd);
+        write(options.format === 'json' ? renderJson({ instructions: path }) : `updated: ${path}\n`);
+        return;
+    }
+    throw new RunXError('Usage: runx agents install <local|global> [--tool agents|claude|all] | runx agents instructions');
+};
+const runUpgrade = async (positionals, options, flags) => {
+    if (positionals[0] === 'check') {
+        const result = await checkForLatestVersion();
+        write(options.format === 'json' ? renderJson(result) : `current: ${result.currentVersion}\nlatest: ${result.latestVersion}\nupdate_available: ${result.updateAvailable}\n`);
+        return;
+    }
+    if (positionals[0] === 'list') {
+        const versions = await listAvailableVersions();
+        write(options.format === 'json' ? renderJson({ versions }) : `${versions.join('\n')}\n`);
+        return;
+    }
+    const result = await upgradeSelf(booleanFlag(flags, 'dryRun'));
+    write(options.format === 'json' ? renderJson(result) : `current: ${result.currentVersion}\ntarget: ${result.latestVersion}\npath: ${result.executablePath}\n${result.scheduled ? 'scheduled: true\n' : ''}`);
+};
+const runUninstall = async (options, flags) => {
+    const result = await uninstallSelf(booleanFlag(flags, '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'}`);
+};
+const resolveOptions = (flags) => {
+    const format = stringFlag(flags, 'format') ?? 'text';
+    if (format !== 'text' && format !== 'json')
+        throw new RunXError('Invalid --format value. Expected text or json.');
+    return { cwd: resolve(stringFlag(flags, 'cwd') ?? process.cwd()), file: stringFlag(flags, 'file'), format: format, verbose: booleanFlag(flags, 'verbose') };
+};
+const write = (value) => {
+    process.stdout.write(value);
+};

package/library/embedded-resources.d.ts

@@ -0,0 +1,7 @@
+declare global {
+    var __RUNX_EMBEDDED_RESOURCES__: {
+        skill: string;
+    } | undefined;
+}
+export declare const registerEmbeddedResources: () => void;
+//# sourceMappingURL=embedded-resources.d.ts.map

package/library/embedded-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded-resources.d.ts","sourceRoot":"","sources":["../source/embedded-resources.ts"],"names":[],"mappings":"AAGA,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,2BAA2B,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CAC/D;AAED,eAAO,MAAM,yBAAyB,QAAO,IAE5C,CAAA"}

package/library/embedded-resources.js

@@ -0,0 +1,5 @@
+// @ts-expect-error Bun text imports embed the bundled agent skill in native binaries.
+import skill from '../skills/guiho-s-runx/SKILL.md' with { type: 'text' };
+export const registerEmbeddedResources = () => {
+    globalThis.__RUNX_EMBEDDED_RESOURCES__ = { skill };
+};

package/library/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class RunXError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare const invariant: (condition: unknown, message: string) => asserts condition;
+//# sourceMappingURL=errors.d.ts.map

package/library/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../source/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IAEzB,YAAY,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,EAIxC;CACF;AAED,eAAO,MAAM,SAAS,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,SAExE,CAAA"}

package/library/errors.js

@@ -0,0 +1,12 @@
+export class RunXError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'RunXError';
+        this.exitCode = exitCode;
+    }
+}
+export const invariant = (condition, message) => {
+    if (!condition)
+        throw new RunXError(message);
+};

package/library/executor.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedCommand } from './types.js';
+export declare const runCommand: (command: ResolvedCommand) => Promise<number>;
+//# sourceMappingURL=executor.d.ts.map

package/library/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../source/executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD,eAAO,MAAM,UAAU,YAAmB,eAAe,KAAG,OAAO,CAAC,MAAM,CAWzE,CAAA"}

package/library/executor.js

@@ -0,0 +1,24 @@
+import { existsSync } from 'node:fs';
+import { RunXError } from './errors.js';
+export const runCommand = async (command) => {
+    if (!existsSync(command.cwd))
+        throw new RunXError(`Command working directory does not exist: ${command.cwd}`);
+    const process = Bun.spawn(shellArguments(command), {
+        cwd: command.cwd,
+        stdin: 'inherit',
+        stdout: 'inherit',
+        stderr: 'inherit',
+    });
+    return process.exited;
+};
+const shellArguments = (command) => {
+    switch (command.shell ?? 'auto') {
+        case 'bash': return ['bash', '-lc', command.command];
+        case 'sh': return ['sh', '-lc', command.command];
+        case 'powershell': return [process.platform === 'win32' ? 'powershell.exe' : 'pwsh', '-NoProfile', '-NonInteractive', '-Command', command.command];
+        case 'cmd': return ['cmd.exe', '/d', '/s', '/c', command.command];
+        case 'auto': return process.platform === 'win32'
+            ? ['cmd.exe', '/d', '/s', '/c', command.command]
+            : ['sh', '-lc', command.command];
+    }
+};

package/library/flags.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedArgs } from './types.js';
+export declare const parseArgs: (args: string[]) => ParsedArgs;
+export declare const booleanFlag: (flags: ParsedArgs['flags'], name: string) => boolean;
+export declare const stringFlag: (flags: ParsedArgs['flags'], name: string) => string | undefined;
+//# sourceMappingURL=flags.d.ts.map

package/library/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../source/flags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAI5C,eAAO,MAAM,SAAS,SAAU,MAAM,EAAE,KAAG,UA8B1C,CAAA;AAED,eAAO,MAAM,WAAW,UAAW,UAAU,CAAC,OAAO,CAAC,QAAQ,MAAM,KAAG,OAA+B,CAAA;AAEtG,eAAO,MAAM,UAAU,UAAW,UAAU,CAAC,OAAO,CAAC,QAAQ,MAAM,KAAG,MAAM,GAAG,SAG9E,CAAA"}

package/library/flags.js

@@ -0,0 +1,32 @@
+const booleanFlags = new Set(['help', 'helpTree', 'helpDocs', 'version', 'verbose', 'dryRun', 'yes']);
+export const parseArgs = (args) => {
+    const positionals = [];
+    const flags = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (!value.startsWith('--')) {
+            positionals.push(value);
+            continue;
+        }
+        const [rawName, inlineValue] = value.slice(2).split('=', 2);
+        const name = toCamelCase(rawName);
+        if (inlineValue !== undefined) {
+            flags[name] = inlineValue;
+            continue;
+        }
+        const next = args[index + 1];
+        if (!booleanFlags.has(name) && next && !next.startsWith('--')) {
+            flags[name] = next;
+            index += 1;
+            continue;
+        }
+        flags[name] = true;
+    }
+    return { command: positionals.shift(), positionals, flags };
+};
+export const booleanFlag = (flags, name) => flags[name] === true;
+export const stringFlag = (flags, name) => {
+    const value = flags[name];
+    return typeof value === 'string' ? value : undefined;
+};
+const toCamelCase = (value) => value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());

package/library/guiho-runx-bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=guiho-runx-bin.d.ts.map

package/library/guiho-runx-bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guiho-runx-bin.d.ts","sourceRoot":"","sources":["../source/guiho-runx-bin.ts"],"names":[],"mappings":""}

package/library/guiho-runx-bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+import { runCliWithErrorHandling } from './cli.js';
+await runCliWithErrorHandling();

package/library/guiho-runx-native-bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=guiho-runx-native-bin.d.ts.map

package/library/guiho-runx-native-bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guiho-runx-native-bin.d.ts","sourceRoot":"","sources":["../source/guiho-runx-native-bin.ts"],"names":[],"mappings":""}

package/library/guiho-runx-native-bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { registerEmbeddedResources } from './embedded-resources.js';
+registerEmbeddedResources();
+const { runCliWithErrorHandling } = await import('./cli.js');
+await runCliWithErrorHandling();

package/library/guiho-runx.d.ts

@@ -0,0 +1,4 @@
+export { runCli, runCliWithErrorHandling } from './cli.js';
+export { findManifest, readManifest, resolveCommand } from './manifest.js';
+export type { CliOptions, ResolvedCommand, RunXCommand, RunXManifest } from './types.js';
+//# sourceMappingURL=guiho-runx.d.ts.map

package/library/guiho-runx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guiho-runx.d.ts","sourceRoot":"","sources":["../source/guiho-runx.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC1E,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}

package/library/guiho-runx.js

@@ -0,0 +1,2 @@
+export { runCli, runCliWithErrorHandling } from './cli.js';
+export { findManifest, readManifest, resolveCommand } from './manifest.js';

package/library/help.d.ts

@@ -0,0 +1,6 @@
+export declare const readVersion: () => string;
+export declare const showHome: () => string;
+export declare const showHelpTree: () => string;
+export declare const showHelpDocs: () => string;
+export declare const showCommandHelp: (command: string) => string;
+//# sourceMappingURL=help.d.ts.map

package/library/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,QAAO,MAAiF,CAAA;AAEhH,eAAO,MAAM,QAAQ,QAAO,MAe3B,CAAA;AAED,eAAO,MAAM,YAAY,QAAO,MAapB,CAAA;AAEZ,eAAO,MAAM,YAAY,QAAO,MAU/B,CAAA;AAED,eAAO,MAAM,eAAe,YAAa,MAAM,KAAG,MAGjD,CAAA"}

package/library/help.js

@@ -0,0 +1,47 @@
+import packageJson from '../package.json' with { type: 'json' };
+export const readVersion = () => typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+export const showHome = () => `RunX ${readVersion()}
+
+A documented, local command catalog for runx.yaml manifests.
+
+Usage:
+  runx list [--file <path>] [--format <text|json>]
+  runx describe <selector>
+  runx run <selector> [--dry-run] [--yes]
+  runx r <selector> [--dry-run] [--yes]
+  runx <selector>
+
+Start here:
+  runx list                 List every command in the nearest manifest.
+  runx --help-tree          Show the complete command tree.
+  runx --help-docs          Show manifest and agent documentation guidance.
+`;
+export const showHelpTree = () => [
+    'runx',
+    '|- list',
+    '|- describe <selector>',
+    '|- run <selector>',
+    '|  `- alias: r',
+    '|- check',
+    '|- agents',
+    '|  |- install <local|global>',
+    '|  `- instructions',
+    '|- upgrade [check|list]',
+    '`- uninstall',
+    '',
+].join('\n');
+export const showHelpDocs = () => `RunX documentation
+
+Manifest: runx.yaml, discovered from the current directory upward or selected with --file.
+Required command fields: uid, id, group, summary, description, command.
+Optional command fields: cwd, shell, tags, confirm.
+
+Selectors resolve in this order: UID, group/id, one-based index, then an unambiguous ID.
+Use UID values for automation. Use runx describe <selector> and runx run <selector> --dry-run before unfamiliar execution.
+
+Agent skill: runx agents install local installs guiho-s-runx under .agents/skills.
+`;
+export const showCommandHelp = (command) => `RunX ${command}
+
+Run \`runx --help-tree\` for command structure and \`runx --help-docs\` for manifest guidance.
+`;

package/library/manifest.d.ts

@@ -0,0 +1,41 @@
+import type { ResolvedCommand, RunXManifest } from './types.js';
+export declare const CommandSchema: import("@sinclair/typebox").TObject<{
+    uid: import("@sinclair/typebox").TString;
+    id: import("@sinclair/typebox").TString;
+    group: import("@sinclair/typebox").TString;
+    summary: import("@sinclair/typebox").TString;
+    description: import("@sinclair/typebox").TString;
+    command: import("@sinclair/typebox").TString;
+    cwd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    shell: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"auto">, import("@sinclair/typebox").TLiteral<"bash">, import("@sinclair/typebox").TLiteral<"sh">, import("@sinclair/typebox").TLiteral<"powershell">, import("@sinclair/typebox").TLiteral<"cmd">]>>;
+    tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    confirm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"never">, import("@sinclair/typebox").TLiteral<"always">]>>;
+}>;
+export declare const ManifestSchema: import("@sinclair/typebox").TObject<{
+    version: import("@sinclair/typebox").TLiteral<1>;
+    project: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        name: import("@sinclair/typebox").TString;
+    }>>;
+    groups: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+        summary: import("@sinclair/typebox").TString;
+    }>>;
+    commands: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        uid: import("@sinclair/typebox").TString;
+        id: import("@sinclair/typebox").TString;
+        group: import("@sinclair/typebox").TString;
+        summary: import("@sinclair/typebox").TString;
+        description: import("@sinclair/typebox").TString;
+        command: import("@sinclair/typebox").TString;
+        cwd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        shell: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"auto">, import("@sinclair/typebox").TLiteral<"bash">, import("@sinclair/typebox").TLiteral<"sh">, import("@sinclair/typebox").TLiteral<"powershell">, import("@sinclair/typebox").TLiteral<"cmd">]>>;
+        tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+        confirm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"never">, import("@sinclair/typebox").TLiteral<"always">]>>;
+    }>>;
+}>;
+export declare const findManifest: (cwd: string, explicitFile?: string) => Promise<string>;
+export declare const readManifest: (cwd: string, explicitFile?: string) => Promise<{
+    manifest: RunXManifest;
+    path: string;
+}>;
+export declare const resolveCommand: (manifest: RunXManifest, manifestPath: string, selector: string) => ResolvedCommand;
+//# sourceMappingURL=manifest.d.ts.map

package/library/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../source/manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAe,YAAY,EAAE,MAAM,YAAY,CAAA;AAI5E,eAAO,MAAM,aAAa;;;;;;;;;;;EAiBS,CAAA;AAEnC,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;EAKQ,CAAA;AAInC,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC,MAAM,CAiBrF,CAAA;AAED,eAAO,MAAM,YAAY,QAAe,MAAM,iBAAiB,MAAM,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmBvH,CAAA;AAED,eAAO,MAAM,cAAc,aAAc,YAAY,gBAAgB,MAAM,YAAY,MAAM,KAAG,eAkC/F,CAAA"}