@guiho/runx 0.2.6 → 0.4.0

package/library/configuration.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { Static } from '@sinclair/typebox';
+export { commandSchema, findConfiguration, manifestSchema, readManifest, resolveCommand, };
+export type { RunXCommand, RunXManifest, };
+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">]>>;
+}>;
+declare const manifestSchema: import("@sinclair/typebox").TObject<{
+    version: import("@sinclair/typebox").TString;
+    project: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        name: import("@sinclair/typebox").TString;
+    }>>;
+    scripts: import("@sinclair/typebox").TObject<{
+        directory: 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">]>>;
+    }>>;
+}>;
+type RunXCommand = Static<typeof commandSchema>;
+type RunXManifest = Static<typeof manifestSchema>;
+type ResolvedCommand = RunXCommand & {
+    index: number;
+    selector: string;
+    manifestPath: string;
+    cwd: string;
+};
+declare function findConfiguration(cwd: string, explicitConfig?: string): Promise<string>;
+declare function readManifest(cwd: string, explicitConfig?: string): Promise<{
+    manifest: RunXManifest;
+    path: string;
+}>;
+declare function resolveCommand(manifest: RunXManifest, manifestPath: string, selector: string): ResolvedCommand;
+//# sourceMappingURL=configuration.d.ts.map

package/library/configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../source/configuration.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,cAAc,GACf,CAAA;AACD,YAAY,EACV,WAAW,EACX,YAAY,GACb,CAAA;AAKD,QAAA,MAAM,aAAa;;;;;;;;;;;EAiBgB,CAAA;AAEnC,QAAA,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;EAMe,CAAA;AAEnC,KAAK,WAAW,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAA;AAC/C,KAAK,YAAY,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAA;AAEjD,KAAK,eAAe,GAAG,WAAW,GAAG;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,iBAAe,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWtF;AAED,iBAAe,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBnH;AAED,iBAAS,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAevG"}

package/library/configuration.js

@@ -0,0 +1,111 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { RunXError } from './errors.js';
+import { directoryName, homeDirectory, isAbsolutePath, joinPath, relativePath, resolvePath } from './path-utils.js';
+export { commandSchema, findConfiguration, manifestSchema, readManifest, resolveCommand, };
+const identifier = '^[a-z][a-z0-9-]*$';
+const semver = '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$';
+const commandSchema = Type.Object({
+    uid: Type.String({ pattern: identifier }),
+    id: Type.String({ pattern: identifier }),
+    group: Type.String({ pattern: identifier }),
+    summary: Type.String({ minLength: 1 }),
+    description: Type.String({ minLength: 1 }),
+    command: Type.String({ minLength: 1 }),
+    cwd: Type.Optional(Type.String({ minLength: 1 })),
+    shell: Type.Optional(Type.Union([
+        Type.Literal('auto'),
+        Type.Literal('bash'),
+        Type.Literal('sh'),
+        Type.Literal('powershell'),
+        Type.Literal('cmd'),
+    ])),
+    tags: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    confirm: Type.Optional(Type.Union([Type.Literal('never'), Type.Literal('always')])),
+}, { additionalProperties: false });
+const manifestSchema = Type.Object({
+    version: Type.String({ pattern: semver }),
+    project: Type.Optional(Type.Object({ name: Type.String({ minLength: 1 }) }, { additionalProperties: false })),
+    scripts: Type.Object({ directory: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+    groups: Type.Record(Type.String({ pattern: identifier }), Type.Object({ summary: Type.String({ minLength: 1 }) }, { additionalProperties: false })),
+    commands: Type.Array(commandSchema),
+}, { additionalProperties: false });
+async function findConfiguration(cwd, explicitConfig) {
+    const candidates = explicitConfig
+        ? [resolvePath(cwd, explicitConfig)]
+        : [joinPath(resolvePath(cwd), 'runx.yaml'), joinPath(homeDirectory(), '.guiho', 'runx', 'runx.yaml')];
+    for (const candidate of candidates)
+        if (await Bun.file(candidate).exists())
+            return candidate;
+    throw new RunXError(explicitConfig
+        ? `Configuration file not found: ${candidates[0]}`
+        : `No runx.yaml found in ${resolvePath(cwd)} or ${joinPath(homeDirectory(), '.guiho', 'runx', 'runx.yaml')}.`, 3);
+}
+async function readManifest(cwd, explicitConfig) {
+    const path = await findConfiguration(cwd, explicitConfig);
+    let input;
+    try {
+        input = Bun.YAML.parse(await Bun.file(path).text());
+    }
+    catch (error) {
+        throw new RunXError(`Invalid YAML in ${path}: ${error instanceof Error ? error.message : 'Unknown YAML parsing error.'}`, 3);
+    }
+    let parsed;
+    try {
+        parsed = Value.Decode(manifestSchema, input);
+    }
+    catch (error) {
+        throw new RunXError(`Invalid RunX configuration ${path}: ${error instanceof Error ? error.message : 'schema validation failed'}`, 3);
+    }
+    validateManifestSemantics(parsed, path);
+    return { manifest: parsed, path };
+}
+function resolveCommand(manifest, manifestPath, selector) {
+    let command = manifest.commands.find((entry) => entry.uid === selector);
+    if (!command && selector.includes('/'))
+        command = manifest.commands.find((entry) => `${entry.group}/${entry.id}` === selector);
+    if (!command && /^\d+$/.test(selector))
+        command = manifest.commands[Number.parseInt(selector, 10) - 1];
+    if (!command) {
+        const matches = manifest.commands.filter((entry) => entry.id === selector);
+        if (matches.length > 1)
+            throw new RunXError(`Ambiguous command ID "${selector}". Use a UID or group/id selector.`, 2);
+        command = matches[0];
+    }
+    if (!command)
+        throw new RunXError(`Unknown command selector: ${selector}`, 2);
+    const root = directoryName(manifestPath);
+    const commandCwd = resolvePath(root, command.cwd ?? '.');
+    const relative = relativePath(root, commandCwd);
+    if (isAbsolutePath(relative) || relative.startsWith('..'))
+        throw new RunXError(`Command ${command.uid} has a cwd outside the configuration directory.`, 3);
+    return { ...command, index: manifest.commands.indexOf(command) + 1, selector: `${command.group}/${command.id}`, manifestPath, cwd: commandCwd };
+}
+function validateManifestSemantics(manifest, path) {
+    if (manifest.version.split('.', 1)[0] !== '1')
+        throw new RunXError(`Unsupported RunX manifest version "${manifest.version}" in ${path}.`, 3);
+    if (!manifest.groups.public)
+        throw new RunXError(`RunX configuration ${path} must define the "public" group.`, 3);
+    const root = directoryName(path);
+    const scripts = resolvePath(root, manifest.scripts.directory);
+    const relative = relativePath(root, scripts);
+    if (relative === '.' || isAbsolutePath(relative) || relative.startsWith('..')) {
+        throw new RunXError(`Scripts directory must be a relative subdirectory in ${path}.`, 3);
+    }
+    const uids = new Set();
+    const selectors = new Set();
+    for (const command of manifest.commands) {
+        if (!manifest.groups[command.group])
+            throw new RunXError(`Command ${command.uid} references unknown group "${command.group}".`, 3);
+        if (uids.has(command.uid))
+            throw new RunXError(`Duplicate command UID "${command.uid}".`, 3);
+        const selector = `${command.group}/${command.id}`;
+        if (selectors.has(selector))
+            throw new RunXError(`Duplicate command selector "${selector}".`, 3);
+        uids.add(command.uid);
+        selectors.add(selector);
+    }
+}

package/library/embedded-resources.d.ts

@@ -1,7 +1,12 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export { registerEmbeddedResources, };
 declare global {
     var __RUNX_EMBEDDED_RESOURCES__: {
         skill: string;
+        prompt: string;
     } | undefined;
 }
-export declare const registerEmbeddedResources: () => void;
+declare function registerEmbeddedResources(): void;
 //# sourceMappingURL=embedded-resources.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"embedded-resources.d.ts","sourceRoot":"","sources":["../source/embedded-resources.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,EACL,yBAAyB,GAC1B,CAAA;AAED,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,2BAA2B,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CAC/E;AAED,iBAAS,yBAAyB,IAAI,IAAI,CAEzC"}

package/library/embedded-resources.js

@@ -1,5 +1,11 @@
-// @ts-expect-error Bun text imports embed the bundled agent skill in native binaries.
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+// @ts-expect-error Bun text imports embed the bundled skill in native binaries.
 import skill from '../skills/guiho-s-runx/SKILL.md' with { type: 'text' };
-export const registerEmbeddedResources = () => {
-    globalThis.__RUNX_EMBEDDED_RESOURCES__ = { skill };
-};
+// @ts-expect-error Bun text imports embed the bundled instruction prompt in native binaries.
+import prompt from '../prompts/guiho-i-runx.md' with { type: 'text' };
+export { registerEmbeddedResources, };
+function registerEmbeddedResources() {
+    globalThis.__RUNX_EMBEDDED_RESOURCES__ = { skill, prompt };
+}

package/library/executor.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
 import type { ResolvedCommand } from './types.js';
-export declare const runCommand: (command: ResolvedCommand) => Promise<number>;
+export { runCommand, };
+declare function runCommand(command: ResolvedCommand): Promise<number>;
 //# sourceMappingURL=executor.d.ts.map

package/library/executor.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../source/executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,EACL,UAAU,GACX,CAAA;AAED,iBAAe,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAQnE"}

package/library/executor.js

@@ -1,17 +1,17 @@
-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), {
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export { runCommand, };
+async function runCommand(command) {
+    const child = Bun.spawn(shellArguments(command), {
         cwd: command.cwd,
         stdin: 'inherit',
         stdout: 'inherit',
         stderr: 'inherit',
     });
-    return process.exited;
-};
-const shellArguments = (command) => {
+    return child.exited;
+}
+function shellArguments(command) {
     switch (command.shell ?? 'auto') {
         case 'bash': return ['bash', '-lc', command.command];
         case 'sh': return ['sh', '-lc', command.command];
@@ -21,4 +21,4 @@ const shellArguments = (command) => {
             ? ['cmd.exe', '/d', '/s', '/c', command.command]
             : ['sh', '-lc', command.command];
     }
-};
+}

package/library/help.d.ts

@@ -1,5 +1,9 @@
-export declare const readVersion: () => string;
-export declare const showHome: () => string;
-export declare const showHelpTree: () => string;
-export declare const showHelpDocs: () => string;
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { CommandDef } from 'citty';
+export { readVersion, renderHelpDocs, renderHelpTree, };
+declare function readVersion(): string;
+declare function renderHelpTree(command: CommandDef<any>, depth?: number): string;
+declare function renderHelpDocs(command: CommandDef<any>): string;
 //# sourceMappingURL=help.d.ts.map

package/library/help.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../source/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAEvC,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,GACf,CAAA;AAED,iBAAS,WAAW,IAAI,MAAM,CAE7B;AAED,iBAAS,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,KAAK,SAA2B,GAAG,MAAM,CAI1F;AAuBD,iBAAS,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CA6BxD"}

package/library/help.js

@@ -1,43 +1,71 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
 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 { readVersion, renderHelpDocs, renderHelpTree, };
+function readVersion() {
+    return typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+}
+function renderHelpTree(command, depth = Number.POSITIVE_INFINITY) {
+    const lines = ['COMMAND TREE', '', commandMeta(command).name ?? 'runx'];
+    appendChildren(lines, command, '', depth);
+    return `${lines.join('\n')}\n`;
+}
+function appendChildren(lines, command, prefix, depth) {
+    if (depth <= 0)
+        return;
+    const subCommands = Object.entries(command.subCommands ?? {}).filter(([name, child]) => !name.startsWith('_') && !commandMeta(child).hidden);
+    const flags = Object.entries(command.args ?? {});
+    const visibleFlags = flags.filter(([, value]) => value.type !== 'positional');
+    const nodes = [
+        ...subCommands.map(([name, child]) => ({ label: name, description: commandMeta(child).description ?? '', child })),
+        ...visibleFlags.map(([name, value]) => ({
+            label: `--${name}${value.type === 'string' ? ` <${value.valueHint ?? 'value'}>` : ''}`,
+            description: value.description ?? '',
+            child: null,
+        })),
+    ];
+    const width = Math.max(0, ...nodes.map((node) => node.label.length));
+    nodes.forEach((node, index) => {
+        const last = index === nodes.length - 1;
+        lines.push(`${prefix}${last ? '└── ' : '├── '}${node.label.padEnd(width)}${node.description ? `  ${node.description}` : ''}`);
+        if (node.child)
+            appendChildren(lines, node.child, `${prefix}${last ? '    ' : '│   '}`, depth - 1);
+    });
+}
+function renderHelpDocs(command) {
+    const meta = commandMeta(command);
+    const name = meta.name ?? 'runx';
+    const description = meta.description ?? '';
+    const args = Object.entries(command.args ?? {});
+    const positionals = args.filter(([, value]) => value.type === 'positional');
+    const flags = args.filter(([, value]) => value.type !== 'positional');
+    const children = Object.entries(command.subCommands ?? {}).filter(([key, value]) => !key.startsWith('_') && !commandMeta(value).hidden);
+    const syntax = [
+        name,
+        ...positionals.map(([key]) => `<${key}>`),
+        children.length ? '<command>' : '',
+        flags.length ? '[options]' : '',
+    ].filter(Boolean).join(' ');
+    const lines = [`# ${name}`, '', description, '', '## Syntax', '', '```text', syntax, '```'];
+    if (positionals.length) {
+        lines.push('', '## Positionals', '');
+        for (const [key, value] of positionals)
+            lines.push(`- \`${key}\` — ${value.description ?? ''}`);
+    }
+    if (flags.length) {
+        lines.push('', '## Flags', '');
+        for (const [key, value] of flags)
+            lines.push(`- \`--${key}${value.type === 'string' ? ` <${value.valueHint ?? 'value'}>` : ''}\` — ${value.description ?? ''}`);
+    }
+    if (children.length) {
+        lines.push('', '## Subcommands', '');
+        for (const [key, value] of children)
+            lines.push(`- \`${key}\` — ${commandMeta(value).description ?? ''}`);
+    }
+    lines.push('', '## Examples', '', '```text', `${name} --help`, `${name} --help-tree`, `${name} --help-docs`, '```', '');
+    return lines.join('\n');
+}
+function commandMeta(command) {
+    return (command.meta ?? {});
+}

package/library/init.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { RunXManifest } from './types.js';
+export { createInitialManifest, initializeRunXManifest, renderInitialManifest, };
+export type { RunXInitResult, };
+type RunXInitResult = {
+    status: 'created';
+    path: string;
+    manifest: RunXManifest;
+};
+declare function initializeRunXManifest(options: {
+    cwd: string;
+    config?: string;
+}): Promise<RunXInitResult>;
+declare function createInitialManifest(projectName: string, scriptsDirectory: string): RunXManifest;
+declare function renderInitialManifest(manifest: RunXManifest): string;
+//# sourceMappingURL=init.d.ts.map

package/library/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../source/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,GACtB,CAAA;AACD,YAAY,EACV,cAAc,GACf,CAAA;AAED,KAAK,cAAc,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,CAAA;AAEjF,iBAAe,sBAAsB,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAOxG;AAED,iBAAS,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,YAAY,CAQ1F;AAED,iBAAS,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAiB7D"}

package/library/init.js

@@ -0,0 +1,43 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { RunXError } from './errors.js';
+import { baseName, resolvePath } from './path-utils.js';
+import { writeTextFile } from './storage.js';
+export { createInitialManifest, initializeRunXManifest, renderInitialManifest, };
+async function initializeRunXManifest(options) {
+    const cwd = resolvePath(options.cwd);
+    const path = resolvePath(cwd, options.config ?? 'runx.yaml');
+    if (await Bun.file(path).exists())
+        throw new RunXError(`Configuration already exists: ${path}`, 5);
+    const manifest = createInitialManifest(baseName(cwd) || 'my-project', 'scripts');
+    await writeTextFile(path, renderInitialManifest(manifest));
+    return { status: 'created', path, manifest };
+}
+function createInitialManifest(projectName, scriptsDirectory) {
+    return {
+        version: '1.0.0',
+        project: { name: projectName },
+        scripts: { directory: scriptsDirectory },
+        groups: { public: { summary: 'Default public project commands.' } },
+        commands: [],
+    };
+}
+function renderInitialManifest(manifest) {
+    return [
+        `version: ${JSON.stringify(manifest.version)}`,
+        '',
+        'project:',
+        `  name: ${JSON.stringify(manifest.project?.name ?? '')}`,
+        '',
+        'scripts:',
+        `  directory: ${JSON.stringify(manifest.scripts.directory)}`,
+        '',
+        'groups:',
+        '  public:',
+        `    summary: ${JSON.stringify(manifest.groups.public.summary)}`,
+        '',
+        'commands: []',
+        '',
+    ].join('\n');
+}

package/library/manifest.d.ts

@@ -1,41 +1,5 @@
-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;
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export { commandSchema as CommandSchema, findConfiguration as findManifest, manifestSchema as ManifestSchema, readManifest, resolveCommand, } from './configuration.js';
 //# sourceMappingURL=manifest.d.ts.map

package/library/manifest.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../source/manifest.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,aAAa,IAAI,aAAa,EAC9B,iBAAiB,IAAI,YAAY,EACjC,cAAc,IAAI,cAAc,EAChC,YAAY,EACZ,cAAc,GACf,MAAM,oBAAoB,CAAA"}