@cleocode/cleo 2026.4.161 → 2026.5.0

package/dist/cli/field-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI field extraction context.
+ *
+ * Singleton that holds the resolved field extraction options for the current
+ * CLI invocation. Set once in the Commander.js preAction hook; read by
+ * dispatchFromCli() to apply field filtering and MVI control universally
+ * across all commands.
+ *
+ * Delegates to @cleocode/lafs v1.5.0 resolveFieldExtraction()
+ * for canonical conflict detection, flag parsing, and type resolution.
+ * Mirrors the format-context.ts pattern for --json/--human/--quiet.
+ *
+ * @epic T4953
+ * @task T4979
+ */
+import { type FieldExtractionResolution } from '@cleocode/lafs';
+export type { FieldExtractionResolution as FieldContext };
+/**
+ * Set the field extraction context for this CLI invocation.
+ * Called once from the preAction hook in src/cli/index.ts.
+ */
+export declare function setFieldContext(ctx: FieldExtractionResolution): void;
+/**
+ * Get the current field extraction context.
+ */
+export declare function getFieldContext(): FieldExtractionResolution;
+/**
+ * Parse global field options from Commander.js parsed opts and resolve via
+ * the canonical LAFS SDK resolver (conflict detection, type narrowing).
+ */
+export declare function resolveFieldContext(opts: Record<string, unknown>): FieldExtractionResolution;
+//# sourceMappingURL=field-context.d.ts.map

package/dist/cli/field-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-context.d.ts","sourceRoot":"","sources":["../../src/cli/field-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAEL,KAAK,yBAAyB,EAE/B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,yBAAyB,IAAI,YAAY,EAAE,CAAC;AAQ1D;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,yBAAyB,GAAG,IAAI,CAEpE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,yBAAyB,CAE3D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,yBAAyB,CAO5F"}

package/dist/cli/field-context.js

@@ -0,0 +1,47 @@
+/**
+ * CLI field extraction context.
+ *
+ * Singleton that holds the resolved field extraction options for the current
+ * CLI invocation. Set once in the Commander.js preAction hook; read by
+ * dispatchFromCli() to apply field filtering and MVI control universally
+ * across all commands.
+ *
+ * Delegates to @cleocode/lafs v1.5.0 resolveFieldExtraction()
+ * for canonical conflict detection, flag parsing, and type resolution.
+ * Mirrors the format-context.ts pattern for --json/--human/--quiet.
+ *
+ * @epic T4953
+ * @task T4979
+ */
+import { resolveFieldExtraction, } from '@cleocode/lafs';
+let currentContext = {
+    mvi: 'minimal',
+    mviSource: 'default',
+    expectsCustomMvi: false,
+};
+/**
+ * Set the field extraction context for this CLI invocation.
+ * Called once from the preAction hook in src/cli/index.ts.
+ */
+export function setFieldContext(ctx) {
+    currentContext = ctx;
+}
+/**
+ * Get the current field extraction context.
+ */
+export function getFieldContext() {
+    return currentContext;
+}
+/**
+ * Parse global field options from Commander.js parsed opts and resolve via
+ * the canonical LAFS SDK resolver (conflict detection, type narrowing).
+ */
+export function resolveFieldContext(opts) {
+    const input = {
+        fieldFlag: typeof opts['field'] === 'string' ? opts['field'] : undefined,
+        fieldsFlag: typeof opts['fields'] === 'string' ? opts['fields'] : undefined,
+        mviFlag: typeof opts['mvi'] === 'string' ? opts['mvi'] : undefined,
+    };
+    return resolveFieldExtraction(input);
+}
+//# sourceMappingURL=field-context.js.map

package/dist/cli/field-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-context.js","sourceRoot":"","sources":["../../src/cli/field-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAIxB,IAAI,cAAc,GAA8B;IAC9C,GAAG,EAAE,SAAS;IACd,SAAS,EAAE,SAAS;IACpB,gBAAgB,EAAE,KAAK;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAA8B;IAC5D,cAAc,GAAG,GAAG,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA6B;IAC/D,MAAM,KAAK,GAAyB;QAClC,SAAS,EAAE,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;QACxE,UAAU,EAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;QAC3E,OAAO,EAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;KACnE,CAAC;IACF,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/cli/format-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI output format resolution context.
+ *
+ * Singleton that holds the resolved output format for the current CLI invocation.
+ * Set once in the Commander.js preAction hook; read by cliOutput() and renderers.
+ *
+ * @task T4665
+ * @epic T4663
+ */
+import type { FlagResolution } from '@cleocode/lafs';
+/**
+ * Set the resolved format for this CLI invocation.
+ * Called once from the preAction hook in src/cli/index.ts.
+ */
+export declare function setFormatContext(resolution: FlagResolution): void;
+/**
+ * Get the current resolved format.
+ */
+export declare function getFormatContext(): FlagResolution;
+/**
+ * Check if output should be JSON format.
+ */
+export declare function isJsonFormat(): boolean;
+/**
+ * Check if output should be human-readable format.
+ */
+export declare function isHumanFormat(): boolean;
+/**
+ * Check if quiet mode is enabled (suppress non-essential output).
+ */
+export declare function isQuiet(): boolean;
+//# sourceMappingURL=format-context.d.ts.map

package/dist/cli/format-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-context.d.ts","sourceRoot":"","sources":["../../src/cli/format-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAYrD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAEjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,CAEjD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAEjC"}

package/dist/cli/format-context.js

@@ -0,0 +1,50 @@
+/**
+ * CLI output format resolution context.
+ *
+ * Singleton that holds the resolved output format for the current CLI invocation.
+ * Set once in the Commander.js preAction hook; read by cliOutput() and renderers.
+ *
+ * @task T4665
+ * @epic T4663
+ */
+/**
+ * Current resolved format for this CLI invocation.
+ * Defaults to JSON (agent-first) until resolved by preAction hook.
+ */
+let currentResolution = {
+    format: 'json',
+    source: 'default',
+    quiet: false,
+};
+/**
+ * Set the resolved format for this CLI invocation.
+ * Called once from the preAction hook in src/cli/index.ts.
+ */
+export function setFormatContext(resolution) {
+    currentResolution = resolution;
+}
+/**
+ * Get the current resolved format.
+ */
+export function getFormatContext() {
+    return currentResolution;
+}
+/**
+ * Check if output should be JSON format.
+ */
+export function isJsonFormat() {
+    return currentResolution.format === 'json';
+}
+/**
+ * Check if output should be human-readable format.
+ */
+export function isHumanFormat() {
+    return currentResolution.format === 'human';
+}
+/**
+ * Check if quiet mode is enabled (suppress non-essential output).
+ */
+export function isQuiet() {
+    return currentResolution.quiet;
+}
+//# sourceMappingURL=format-context.js.map

package/dist/cli/format-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-context.js","sourceRoot":"","sources":["../../src/cli/format-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;GAGG;AACH,IAAI,iBAAiB,GAAmB;IACtC,MAAM,EAAE,MAAM;IACd,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,KAAK;CACb,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA0B;IACzD,iBAAiB,GAAG,UAAU,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,iBAAiB,CAAC,MAAM,KAAK,MAAM,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,iBAAiB,CAAC,MAAM,KAAK,OAAO,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO;IACrB,OAAO,iBAAiB,CAAC,KAAK,CAAC;AACjC,CAAC"}

package/dist/cli/help-renderer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Custom grouped help renderer for the root `cleo --help` command.
+ *
+ * Replaces citty's default flat subcommand listing with domain-grouped,
+ * alias-aware, short-description output. Sub-command help (e.g.
+ * `cleo add --help`) still uses citty's built-in renderer.
+ *
+ * @module
+ */
+import type { ArgsDef, CommandDef } from 'citty';
+/**
+ * Build alias lookup: alias name -> primary command name.
+ *
+ * Detects entries in `subCommands` whose name differs from their key (i.e.
+ * alias slots that point to an already-registered primary command).
+ * Also merges in hard-coded implicit aliases.
+ *
+ * @param subCommands - The `subCommands` record from the root `defineCommand`.
+ */
+export declare function buildAliasMap(subCommands: Record<string, CommandDef>): Map<string, string>;
+/**
+ * Render grouped help text for the root CLEO command.
+ *
+ * @param version - CLI version string.
+ * @param subCommands - The `subCommands` record from the root `defineCommand`.
+ * @param aliasMap - Alias name → primary command name (from `buildAliasMap`).
+ */
+export declare function renderGroupedHelp(version: string, subCommands: Record<string, CommandDef>, aliasMap: Map<string, string>): string;
+/**
+ * Create a custom `showUsage` function that renders grouped help for the
+ * root command and delegates to citty's default for sub-commands.
+ *
+ * Passed to `runMain(cmd, { showUsage })` so citty uses it for `--help`.
+ *
+ * @param version - CLI version string.
+ * @param subCommands - The `subCommands` record from the root `defineCommand`.
+ * @param aliasMap - Alias name → primary command name (from `buildAliasMap`).
+ */
+export declare function createCustomShowUsage(version: string, subCommands: Record<string, CommandDef>, aliasMap: Map<string, string>): <T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>, parent?: CommandDef<T>) => Promise<void>;
+//# sourceMappingURL=help-renderer.d.ts.map

package/dist/cli/help-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-renderer.d.ts","sourceRoot":"","sources":["../../src/cli/help-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAkLjD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAwB1F;AAqBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACvC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,MAAM,CA2ER;AAMD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACvC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAa5F"}

package/dist/cli/help-renderer.js

@@ -0,0 +1,325 @@
+/**
+ * Custom grouped help renderer for the root `cleo --help` command.
+ *
+ * Replaces citty's default flat subcommand listing with domain-grouped,
+ * alias-aware, short-description output. Sub-command help (e.g.
+ * `cleo add --help`) still uses citty's built-in renderer.
+ *
+ * @module
+ */
+import { showUsage as cittyShowUsage } from 'citty';
+// ---------------------------------------------------------------------------
+// ANSI helpers — matches citty's internal palette so output is visually
+// consistent between grouped root help and per-command help.
+// ---------------------------------------------------------------------------
+const noColor = (() => {
+    const env = globalThis.process?.env ?? {};
+    return env.NO_COLOR === '1' || env.TERM === 'dumb' || env.TEST || env.CI;
+})();
+const ansi = (code, reset = 39) => (t) => noColor ? t : `\x1b[${code}m${t}\x1b[${reset}m`;
+const bold = ansi(1, 22);
+const cyan = ansi(36);
+const gray = ansi(90);
+const underline = ansi(4, 24);
+/**
+ * Commands registered as separate subcommand entries but semantically
+ * aliases of another command. These are shown as `(alias)` next to the
+ * primary command and hidden from the main listing.
+ */
+const IMPLICIT_ALIASES = {
+    tags: 'labels',
+};
+/**
+ * Ordered domain groups for the root help display.
+ * Commands not listed here appear under "Other" at the bottom.
+ */
+const COMMAND_GROUPS = [
+    {
+        name: 'Task Management',
+        commands: [
+            'add',
+            'show',
+            'find',
+            'list',
+            'update',
+            'complete',
+            'delete',
+            'start',
+            'stop',
+            'current',
+            'next',
+            'exists',
+            'bug',
+        ],
+    },
+    {
+        name: 'Task Organization',
+        commands: [
+            'archive',
+            'labels',
+            'promote',
+            'relates',
+            'reorder',
+            'reparent',
+            'deps',
+            'tree',
+            'blockers',
+        ],
+    },
+    {
+        name: 'Sessions & Planning',
+        commands: ['session', 'briefing', 'dash', 'plan', 'safestop', 'context'],
+    },
+    {
+        name: 'Phases & Lifecycle',
+        commands: ['phase', 'lifecycle', 'release', 'roadmap'],
+    },
+    {
+        name: 'Memory & Notes',
+        commands: ['memory', 'brain', 'refresh-memory', 'sticky', 'reason'],
+    },
+    {
+        name: 'Analysis & Stats',
+        commands: ['analyze', 'stats', 'history', 'archive-stats'],
+    },
+    {
+        name: 'Validation & Compliance',
+        commands: [
+            'check',
+            'verify',
+            'testing',
+            'compliance',
+            'consensus',
+            'contribution',
+            'decomposition',
+            'backfill',
+        ],
+    },
+    {
+        name: 'Code & Documentation',
+        commands: ['code', 'docs', 'detect-drift', 'map'],
+    },
+    {
+        name: 'Research & Orchestration',
+        commands: ['research', 'orchestrate', 'conduit'],
+    },
+    {
+        name: 'Import / Export',
+        commands: ['export', 'import', 'export-tasks', 'import-tasks', 'snapshot', 'inject'],
+    },
+    {
+        name: 'Collaboration',
+        commands: ['nexus', 'remote', 'push', 'pull', 'checkpoint'],
+    },
+    {
+        name: 'Agents',
+        commands: ['agent', 'grade'],
+    },
+    {
+        name: 'System & Admin',
+        commands: [
+            'version',
+            'init',
+            'config',
+            'admin',
+            'doctor',
+            'upgrade',
+            'self-update',
+            'ops',
+            'schema',
+            'log',
+            'sequence',
+            'adr',
+            'cant',
+            'token',
+            'otel',
+            'migrate',
+            'detect',
+            'generate-changelog',
+            'issue',
+            'skills',
+            'web',
+            'backup',
+            'restore',
+        ],
+    },
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a CommandDef's meta to a plain object synchronously.
+ * citty allows `meta` to be either a plain object or a function returning one.
+ * We avoid awaiting here to keep help rendering synchronous.
+ */
+function resolveMeta(cmd) {
+    if (typeof cmd.meta === 'function') {
+        // meta() may be async; we call it synchronously and take the resolved value
+        // only if it is not a Promise (i.e. the command returns a plain object).
+        const result = cmd.meta();
+        if (result && typeof result === 'object' && !('then' in result)) {
+            return result;
+        }
+        return {};
+    }
+    return cmd.meta ?? {};
+}
+/**
+ * Build alias lookup: alias name -> primary command name.
+ *
+ * Detects entries in `subCommands` whose name differs from their key (i.e.
+ * alias slots that point to an already-registered primary command).
+ * Also merges in hard-coded implicit aliases.
+ *
+ * @param subCommands - The `subCommands` record from the root `defineCommand`.
+ */
+export function buildAliasMap(subCommands) {
+    const map = new Map();
+    // Detect alias entries: a key that registers the exact same CommandDef
+    // object as another key is an alias (e.g. 'done' -> completeCommand).
+    // We use identity comparison — two keys pointing to the same reference are
+    // treated as primary + alias.
+    const seen = new Map();
+    for (const [key, def] of Object.entries(subCommands)) {
+        const existing = seen.get(def);
+        if (existing !== undefined) {
+            // 'key' is an alias of 'existing' (primary registered first)
+            map.set(key, existing);
+        }
+        else {
+            seen.set(def, key);
+        }
+    }
+    // Add implicit aliases (commands registered as separate entries but
+    // semantically aliases, e.g. `tags` → `labels`)
+    for (const [alias, primary] of Object.entries(IMPLICIT_ALIASES)) {
+        map.set(alias, primary);
+    }
+    return map;
+}
+/**
+ * Extract a short one-line description from a CommandDef's meta.
+ *
+ * Some commands have multi-line descriptions starting with
+ * `"Description: <one-liner>"`. This extracts just that first line.
+ * Other commands already have a one-liner.
+ */
+function getShortDescription(desc) {
+    if (!desc)
+        return '';
+    const match = desc.match(/^Description:\s*(.+)/);
+    if (match)
+        return match[1].trim();
+    const firstLine = desc.split('\n').find((l) => l.trim().length > 0);
+    return firstLine?.trim() ?? desc.trim();
+}
+// ---------------------------------------------------------------------------
+// Grouped help renderer
+// ---------------------------------------------------------------------------
+/**
+ * Render grouped help text for the root CLEO command.
+ *
+ * @param version - CLI version string.
+ * @param subCommands - The `subCommands` record from the root `defineCommand`.
+ * @param aliasMap - Alias name → primary command name (from `buildAliasMap`).
+ */
+export function renderGroupedHelp(version, subCommands, aliasMap) {
+    // Build command -> short description map from CommandDef.meta
+    const descMap = new Map();
+    for (const [key, def] of Object.entries(subCommands)) {
+        if (aliasMap.has(key))
+            continue; // skip alias entries
+        const meta = resolveMeta(def);
+        descMap.set(key, getShortDescription(meta.description));
+    }
+    // Build command -> aliases map (reverse of aliasMap)
+    const cmdAliases = new Map();
+    for (const [alias, primary] of aliasMap) {
+        const existing = cmdAliases.get(primary) ?? [];
+        existing.push(alias);
+        cmdAliases.set(primary, existing);
+    }
+    // Compute max display width for column alignment
+    let maxCmdWidth = 0;
+    const allGroupedCmds = COMMAND_GROUPS.flatMap((g) => g.commands);
+    const allCmds = [...new Set([...allGroupedCmds, ...descMap.keys()])];
+    for (const cmd of allCmds) {
+        if (!descMap.has(cmd) || aliasMap.has(cmd))
+            continue;
+        const aliases = cmdAliases.get(cmd);
+        const display = aliases && aliases.length > 0 ? `${cmd} (${aliases.join(', ')})` : cmd;
+        if (display.length > maxCmdWidth)
+            maxCmdWidth = display.length;
+    }
+    const lines = [];
+    // Header
+    lines.push(gray(`CLEO V2 - Task management for AI coding agents (cleo v${version})`));
+    lines.push('');
+    lines.push(`${underline(bold('USAGE'))} ${cyan('cleo <command> [OPTIONS]')}`);
+    lines.push('');
+    const rendered = new Set();
+    for (const group of COMMAND_GROUPS) {
+        const groupLines = [];
+        for (const cmd of group.commands) {
+            if (!descMap.has(cmd))
+                continue;
+            rendered.add(cmd);
+            const aliases = cmdAliases.get(cmd);
+            const display = aliases && aliases.length > 0 ? `${cmd} (${aliases.join(', ')})` : cmd;
+            const desc = descMap.get(cmd) ?? '';
+            groupLines.push(`  ${cyan(display.padEnd(maxCmdWidth + 2))}${desc}`);
+        }
+        if (groupLines.length > 0) {
+            lines.push(underline(bold(group.name.toUpperCase())));
+            lines.push(...groupLines);
+            lines.push('');
+        }
+    }
+    // Catch commands not in any group (safety net for new commands)
+    const ungrouped = [];
+    for (const key of descMap.keys()) {
+        if (!rendered.has(key) && !aliasMap.has(key)) {
+            ungrouped.push(key);
+        }
+    }
+    if (ungrouped.length > 0) {
+        lines.push(underline(bold('OTHER')));
+        for (const cmd of ungrouped) {
+            const aliases = cmdAliases.get(cmd);
+            const display = aliases && aliases.length > 0 ? `${cmd} (${aliases.join(', ')})` : cmd;
+            const desc = descMap.get(cmd) ?? '';
+            lines.push(`  ${cyan(display.padEnd(maxCmdWidth + 2))}${desc}`);
+        }
+        lines.push('');
+    }
+    lines.push(`Use ${cyan('cleo <command> --help')} for more information about a command.`);
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Custom showUsage factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a custom `showUsage` function that renders grouped help for the
+ * root command and delegates to citty's default for sub-commands.
+ *
+ * Passed to `runMain(cmd, { showUsage })` so citty uses it for `--help`.
+ *
+ * @param version - CLI version string.
+ * @param subCommands - The `subCommands` record from the root `defineCommand`.
+ * @param aliasMap - Alias name → primary command name (from `buildAliasMap`).
+ */
+export function createCustomShowUsage(version, subCommands, aliasMap) {
+    return async (cmd, parent) => {
+        // Root command (no parent) → show grouped help
+        if (!parent) {
+            const meta = await (typeof cmd.meta === 'function' ? cmd.meta() : cmd.meta);
+            if (meta?.name === 'cleo') {
+                console.log(renderGroupedHelp(version, subCommands, aliasMap) + '\n');
+                return;
+            }
+        }
+        // Sub-commands → citty's default renderer
+        await cittyShowUsage(cmd, parent);
+    };
+}
+//# sourceMappingURL=help-renderer.js.map

package/dist/cli/help-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-renderer.js","sourceRoot":"","sources":["../../src/cli/help-renderer.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * CLEO CLI - Main entry point
+ *
+ * Native citty command dispatch — all commands use defineCommand.
+ *
+ * T1138: SQLite warning suppression for CLI consumers is handled by the
+ * esbuild banner, which patches process.emitWarning before ESM imports are
+ * hoisted. See build.mjs for the banner configuration. The import from
+ * @cleocode/core/internal below will trigger the warning's emission, but
+ * the banner will have already patched process.emitWarning to suppress it.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}