@cleocode/cleo 2026.4.57 → 2026.4.59

package/dist/cli/help-generator.js

@@ -0,0 +1,229 @@
+/**
+ * ParamDef-driven Commander help generator.
+ *
+ * Provides two functions:
+ *  - `buildOperationHelp()` — emits a multi-section help string (Description,
+ *    USAGE, ARGUMENTS, OPTIONS, PRECONDITIONS) from a ParamDef array and the
+ *    static LAFS gate table.
+ *  - `applyParamDefsToCommand()` — replaces hand-written `.option()` chains on
+ *    a ShimCommand with generated calls derived from the same ParamDef array.
+ *
+ * Both functions read exactly the same source of truth that the dispatch
+ * registry and `cleo schema` use, eliminating the duplication that caused
+ * missing enum values, absent required indicators, and hidden gate docs.
+ *
+ * Gate lookup uses `describeOperation()` from `@cleocode/lafs`, which is the
+ * public API over the static LAFS gate table in `operation-gates.ts`.
+ *
+ * @module
+ * @epic T335
+ * @task T339
+ */
+import { describeOperation } from '@cleocode/lafs';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a camelCase identifier to kebab-case CLI flag name.
+ *
+ * @param name - camelCase string (e.g. `"dryRun"`)
+ * @returns kebab-case string (e.g. `"dry-run"`)
+ */
+function toKebab(name) {
+    return name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+/**
+ * Retrieve precondition gates for an operation key using the public
+ * `describeOperation()` API from `@cleocode/lafs`.
+ *
+ * Parses `"tasks.add"` → `{ domain: "tasks", operation: "add" }` and calls
+ * `describeOperation` with the minimum required fields so that the static
+ * LAFS gate table lookup succeeds.
+ *
+ * @param operationKey - Fully-qualified operation key, e.g. `"tasks.add"`.
+ * @param params - ParamDef array for the operation (may be empty).
+ * @returns Array of {@link OperationGateSchema} entries, possibly empty.
+ */
+function getGatesForOperation(operationKey, params) {
+    const dotIdx = operationKey.indexOf('.');
+    if (dotIdx === -1)
+        return [];
+    const domain = operationKey.slice(0, dotIdx);
+    const operation = operationKey.slice(dotIdx + 1);
+    const schema = describeOperation({
+        gateway: 'query',
+        domain,
+        operation,
+        description: '',
+        params: params,
+        requiredParams: [],
+    }, { includeGates: true });
+    return schema.gates ?? [];
+}
+// ---------------------------------------------------------------------------
+// buildOperationHelp
+// ---------------------------------------------------------------------------
+/**
+ * Build a multi-section Commander-compatible help string from a ParamDef
+ * array and the static LAFS gate table.
+ *
+ * Sections emitted:
+ * - `Description:` — one-line operation summary
+ * - `USAGE:` — positional args listed in required/optional angle/square brackets
+ * - `ARGUMENTS:` — positional params with descriptions (omitted when none)
+ * - `OPTIONS:` — flag params with type, enum values, and required indicator
+ * - `PRECONDITIONS:` — gates sourced from `packages/lafs/src/operation-gates.ts`
+ *   via `describeOperation()` (omitted when the gate table has no entry for
+ *   this operation key)
+ * - `Examples:` — pre-canned examples for the five seeded operations
+ *
+ * @param operationKey - Fully-qualified operation key, e.g. `"tasks.add"`.
+ * @param description - One-line summary of the operation.
+ * @param params - ParamDef array for the operation.
+ * @returns Multi-line help string.
+ */
+export function buildOperationHelp(operationKey, description, params) {
+    // Derive the CLI noun from the operation key ("tasks.add" → "add")
+    const cliName = operationKey.split('.').slice(1).join('.');
+    const positionals = params.filter((p) => p.cli?.positional && !p.hidden);
+    const flags = params.filter((p) => !p.cli?.positional && !p.hidden);
+    // --- USAGE line ---
+    const argTokens = positionals.map((p) => (p.required ? `<${p.name}>` : `[${p.name}]`)).join(' ');
+    const usageLine = `USAGE: cleo ${cliName}` +
+        (flags.length > 0 ? ' [OPTIONS]' : '') +
+        (argTokens ? ` ${argTokens}` : '');
+    const lines = [];
+    lines.push(`Description: ${description}`);
+    lines.push('');
+    lines.push(usageLine);
+    // --- ARGUMENTS section ---
+    if (positionals.length > 0) {
+        lines.push('');
+        lines.push('ARGUMENTS:');
+        for (const p of positionals) {
+            const indicator = p.required ? '(required)' : '(optional)';
+            const namePad = p.name.padEnd(16);
+            lines.push(`  ${namePad} ${p.description}  ${indicator}`);
+        }
+    }
+    // --- OPTIONS section ---
+    if (flags.length > 0) {
+        lines.push('');
+        lines.push('OPTIONS:');
+        for (const p of flags) {
+            const flagName = p.cli?.flag ?? toKebab(p.name);
+            const short = p.cli?.short;
+            const typeLabel = p.type !== 'boolean' ? ` <${p.type}>` : '';
+            const flagStr = short
+                ? `${short}, --${flagName}${typeLabel}`
+                : `    --${flagName}${typeLabel}`;
+            const enumSuffix = p.enum && p.enum.length > 0 ? `  [enum: ${p.enum.join('|')}]` : '';
+            const reqSuffix = p.required ? '  [required]' : '';
+            lines.push(`  ${flagStr.padEnd(32)} ${p.description}${enumSuffix}${reqSuffix}`);
+        }
+    }
+    // --- PRECONDITIONS section ---
+    const gates = getGatesForOperation(operationKey, params);
+    if (gates.length > 0) {
+        lines.push('');
+        lines.push('PRECONDITIONS (gates that may fire):');
+        for (const gate of gates) {
+            lines.push(`  - ${gate.errorCode} [${gate.name}]: ${gate.description}`);
+            for (const trigger of gate.triggers) {
+                lines.push(`      * ${trigger}`);
+            }
+        }
+    }
+    // --- Examples section ---
+    const EXAMPLES = {
+        'tasks.add': [
+            "  cleo add 'My task title'",
+            "  cleo add 'My task' --priority high --parent T100",
+            "  cleo add 'Fix login bug' --type bug --size small --acceptance 'Reproducer passes|CI green'",
+        ],
+        'tasks.complete': [
+            '  cleo complete T123',
+            '  cleo complete T123 --force',
+            "  cleo complete T123 --verification-note 'All ACs verified in PR #456'",
+        ],
+        'tasks.show': ['  cleo show T123'],
+        'tasks.find': ['  cleo find "auth"', '  cleo find --status active --limit 10'],
+        'tasks.list': ['  cleo list --parent T100', '  cleo list --status active --priority high'],
+    };
+    const examples = EXAMPLES[operationKey];
+    if (examples && examples.length > 0) {
+        lines.push('');
+        lines.push('Examples:');
+        for (const ex of examples) {
+            lines.push(ex);
+        }
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// applyParamDefsToCommand
+// ---------------------------------------------------------------------------
+/**
+ * Register Commander options and positional arguments on a ShimCommand from
+ * a ParamDef array.
+ *
+ * Replaces hand-written `.option(...)` chains with a single call.
+ *
+ * Handles:
+ * - Positional args (`cli.positional === true`) → `.argument()`
+ * - Short aliases (`cli.short`) → `-s, --flag <type>`
+ * - Flag name overrides (`cli.flag`) → `--custom-flag`
+ * - Boolean flags (type === `'boolean'`) → no value placeholder
+ * - Custom parse functions (`cli.parse`) → forwarded to `.option()`
+ * - Enum constraints surfaced in the option description
+ * - Required vs optional indicators appended to the description
+ *
+ * **Note:** The caller is still responsible for the `.action(...)` callback
+ * because action bodies are command-specific and cannot be auto-generated.
+ *
+ * **Hybrid pattern:** Some commands keep hand-written `.option()` calls after
+ * this call for options that have no ParamDef entry (e.g. `--dry-run`,
+ * `--field`, `--format`, `--desc`). That is intentional — those options are
+ * CLI-surface-only and do not belong in the dispatch registry.
+ *
+ * @param command - The ShimCommand returned by `.command(nameAndArgs)`.
+ * @param params - The ParamDef array for this operation.
+ * @param operationKey - `"tasks.add"` etc. Reserved for future hook or tracing
+ *   use; currently not mutated on the shim since ShimCommand has no first-class
+ *   help-text override API.
+ */
+export function applyParamDefsToCommand(command, params, operationKey) {
+    // operationKey is reserved for future tracing/hook use.
+    void operationKey;
+    for (const p of params) {
+        // Hidden params have no CLI surface — skip entirely.
+        if (p.hidden)
+            continue;
+        if (p.cli?.positional) {
+            // Positional arguments are registered via .argument()
+            const spec = p.required ? `<${p.name}>` : `[${p.name}]`;
+            command.argument(spec, p.description);
+            continue;
+        }
+        // Build the flag string
+        const flagName = p.cli?.flag ?? toKebab(p.name);
+        const short = p.cli?.short;
+        const typeLabel = p.type !== 'boolean' ? ` <${p.type}>` : '';
+        const flagPart = short ? `${short}, --${flagName}${typeLabel}` : `--${flagName}${typeLabel}`;
+        // Augment description with enum hint so agents see allowed values in --help
+        const enumHint = p.enum && p.enum.length > 0 ? ` (${p.enum.join('|')})` : '';
+        const reqHint = p.required ? ' [required]' : '';
+        const fullDescription = `${p.description}${enumHint}${reqHint}`;
+        if (p.required && p.type !== 'boolean') {
+            // Use requiredOption for non-boolean required flags
+            command.requiredOption(flagPart, fullDescription);
+        }
+        else if (p.cli?.parse) {
+            command.option(flagPart, fullDescription, p.cli.parse);
+        }
+        else {
+            command.option(flagPart, fullDescription);
+        }
+    }
+}
+//# sourceMappingURL=help-generator.js.map

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

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

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

@@ -0,0 +1,28 @@
+/**
+ * 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';
+import type { ShimCommand } from './commander-shim.js';
+/**
+ * Build alias lookup: alias name -> primary command name.
+ * Includes both `.alias()` registrations and implicit aliases.
+ */
+export declare function buildAliasMap(shims: ShimCommand[]): Map<string, string>;
+/**
+ * Render grouped help text for the root CLEO command.
+ */
+export declare function renderGroupedHelp(version: string, shims: ShimCommand[], 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`.
+ */
+export declare function createCustomShowUsage(version: string, shims: ShimCommand[], 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;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AA6KvD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAavE;AAqBD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,EAAE,EACpB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,MAAM,CA+ER;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,EAAE,EACpB,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,301 @@
+/**
+ * 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 `.command()` 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',
+};
+/**
+ * Descriptions for native citty commands that bypass the commander-shim.
+ * These have no ShimCommand entry so must be provided explicitly.
+ */
+const NATIVE_COMMAND_DESCS = {
+    version: 'Display CLEO version',
+    code: 'Code analysis via tree-sitter AST',
+};
+/**
+ * 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', 'phases', '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',
+            'validate',
+            'verify',
+            'testing',
+            'compliance',
+            'implementation',
+            'specification',
+            'consensus',
+            'contribution',
+            'decomposition',
+            'backfill',
+        ],
+    },
+    {
+        name: 'Code & Documentation',
+        commands: ['code', 'docs', 'detect-drift', 'map'],
+    },
+    {
+        name: 'Research & Orchestration',
+        commands: ['research', 'orchestrate'],
+    },
+    {
+        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',
+            'env',
+            'admin',
+            'doctor',
+            'upgrade',
+            'self-update',
+            'commands',
+            'ops',
+            'schema',
+            'log',
+            'sequence',
+            'adr',
+            'cant',
+            'token',
+            'otel',
+            'migrate',
+            'detect',
+            'generate-changelog',
+            'issue',
+            'skills',
+            'web',
+            'backup',
+            'restore',
+        ],
+    },
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build alias lookup: alias name -> primary command name.
+ * Includes both `.alias()` registrations and implicit aliases.
+ */
+export function buildAliasMap(shims) {
+    const map = new Map();
+    for (const shim of shims) {
+        for (const alias of shim._aliases) {
+            map.set(alias, shim._name);
+        }
+    }
+    // Add implicit aliases (commands registered as separate .command() 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 shim's description.
+ *
+ * Commands that use `buildOperationHelp()` have multi-line descriptions
+ * starting with `"Description: <one-liner>"`. This extracts just that 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.
+ */
+export function renderGroupedHelp(version, shims, aliasMap) {
+    // Build command -> short description map
+    const descMap = new Map();
+    for (const shim of shims) {
+        descMap.set(shim._name, getShortDescription(shim._description));
+    }
+    // Add native citty commands that bypass the commander-shim
+    for (const [name, desc] of Object.entries(NATIVE_COMMAND_DESCS)) {
+        if (!descMap.has(name)) {
+            descMap.set(name, desc);
+        }
+    }
+    // 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, ...shims.map((s) => s._name), 'version'])];
+    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 shim of shims) {
+        if (!rendered.has(shim._name) && !aliasMap.has(shim._name)) {
+            ungrouped.push(shim._name);
+        }
+    }
+    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`.
+ */
+export function createCustomShowUsage(version, shims, 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, shims, 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,9 @@
+/**
+ * CLEO CLI - Main entry point
+ *
+ * Bridges commander-shim commands to citty for execution.
+ *
+ * TODO: Migrate all 89 commands to native citty pattern (epic T5730)
+ */
+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":"AAAA;;;;;;GAMG"}

package/dist/cli/logger-bootstrap.d.ts

@@ -0,0 +1,6 @@
+import type { LoggerConfig } from '@cleocode/core';
+/**
+ * Initialize CLI logger with optional projectHash correlation context.
+ */
+export declare function initCliLogger(cwd: string, loggingConfig: LoggerConfig): void;
+//# sourceMappingURL=logger-bootstrap.d.ts.map

package/dist/cli/logger-bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-bootstrap.d.ts","sourceRoot":"","sources":["../../src/cli/logger-bootstrap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,GAAG,IAAI,CAG5E"}

package/dist/cli/logger-bootstrap.js

@@ -0,0 +1,10 @@
+import { join } from 'node:path';
+import { getProjectInfoSync, initLogger } from '@cleocode/core';
+/**
+ * Initialize CLI logger with optional projectHash correlation context.
+ */
+export function initCliLogger(cwd, loggingConfig) {
+    const projectInfo = getProjectInfoSync(cwd);
+    initLogger(join(cwd, '.cleo'), loggingConfig, projectInfo?.projectHash);
+}
+//# sourceMappingURL=logger-bootstrap.js.map

package/dist/cli/logger-bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-bootstrap.js","sourceRoot":"","sources":["../../src/cli/logger-bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,aAA2B;IACpE,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAC5C,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;AAC1E,CAAC"}

package/dist/cli/middleware/output-format.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared CLI middleware for resolving output format from --human/--json/--quiet flags.
+ *
+ * Delegates to LAFS protocol's resolveOutputFormat() for canonical flag resolution,
+ * and provides a Commander.js-compatible helper to extract flag values from opts.
+ *
+ * @task T4703
+ * @epic T4663
+ */
+import { type FlagResolution } from '@cleocode/lafs';
+export type { FlagResolution };
+/**
+ * Resolve output format from Commander.js option values.
+ *
+ * Reads --json, --human, and --quiet flags and delegates to
+ * the canonical LAFS resolveOutputFormat(). Project/user defaults
+ * can be passed via the optional `defaults` parameter.
+ *
+ * @param opts - Commander.js parsed options object
+ * @param defaults - Optional project/user defaults
+ * @returns Resolved format with source provenance
+ *
+ * @task T4703
+ * @epic T4663
+ */
+export declare function resolveFormat(opts: Record<string, unknown>, defaults?: {
+    projectDefault?: 'json' | 'human';
+    userDefault?: 'json' | 'human';
+}): FlagResolution;
+//# sourceMappingURL=output-format.d.ts.map

package/dist/cli/middleware/output-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-format.d.ts","sourceRoot":"","sources":["../../../src/cli/middleware/output-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAkB,KAAK,cAAc,EAAuB,MAAM,gBAAgB,CAAC;AAE1F,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAC/E,cAAc,CAUhB"}