@cleocode/cleo 2026.4.158 → 2026.5.0

package/dist/cli/progress.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Progress indicator utilities for CLI commands.
+ * Provides human-friendly progress output for long-running operations.
+ *
+ * @task T5243
+ */
+export interface ProgressOptions {
+    /** Whether to show progress (true for human mode, false for JSON mode) */
+    enabled: boolean;
+    /** Prefix for progress messages */
+    prefix?: string;
+}
+/**
+ * Simple progress tracker for CLI operations.
+ */
+export declare class ProgressTracker {
+    private enabled;
+    private prefix;
+    private currentStep;
+    private totalSteps;
+    private steps;
+    constructor(options: ProgressOptions & {
+        steps: string[];
+    });
+    /**
+     * Start the progress tracker.
+     */
+    start(): void;
+    /**
+     * Update to a specific step.
+     */
+    step(index: number, message?: string): void;
+    /**
+     * Move to next step.
+     */
+    next(message?: string): void;
+    /**
+     * Mark as complete with optional summary.
+     *
+     * @remarks
+     * Writes to stderr (not stdout) so that progress messages never pollute
+     * the machine-readable JSON envelope on stdout. Stdout MUST contain exactly
+     * one JSON object per CLI invocation (ADR-039 / T927).
+     */
+    complete(summary?: string): void;
+    /**
+     * Report an error.
+     */
+    error(message: string): void;
+}
+/**
+ * Simple spinner for indeterminate progress.
+ */
+export declare class Spinner {
+    private enabled;
+    private message;
+    private timer;
+    private frames;
+    private frameIndex;
+    constructor(options: {
+        enabled: boolean;
+        message: string;
+    });
+    /**
+     * Start the spinner.
+     */
+    start(): void;
+    /**
+     * Stop the spinner.
+     */
+    stop(finalMessage?: string): void;
+    /**
+     * Update the spinner message.
+     */
+    update(message: string): void;
+}
+/**
+ * Create a progress tracker for self-update operations.
+ */
+export declare function createSelfUpdateProgress(enabled: boolean): ProgressTracker;
+/**
+ * Create a progress tracker for doctor operations.
+ */
+export declare function createDoctorProgress(enabled: boolean): ProgressTracker;
+/**
+ * Create a progress tracker for upgrade operations.
+ */
+export declare function createUpgradeProgress(enabled: boolean): ProgressTracker;
+//# sourceMappingURL=progress.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/cli/progress.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAW;gBAEZ,OAAO,EAAE,eAAe,GAAG;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE;IAO1D;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ3C;;OAEG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI5B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAShC;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAI7B;AAED;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,MAAM,CAWZ;IACF,OAAO,CAAC,UAAU,CAAK;gBAEX,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAK1D;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACH,IAAI,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI;IAajC;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAG9B;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAa1E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAYtE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAYvE"}

package/dist/cli/progress.js

@@ -0,0 +1,185 @@
+/**
+ * Progress indicator utilities for CLI commands.
+ * Provides human-friendly progress output for long-running operations.
+ *
+ * @task T5243
+ */
+import { stderr } from 'node:process';
+/**
+ * Simple progress tracker for CLI operations.
+ */
+export class ProgressTracker {
+    enabled;
+    prefix;
+    currentStep = 0;
+    totalSteps;
+    steps;
+    constructor(options) {
+        this.enabled = options.enabled;
+        this.prefix = options.prefix ?? 'CLEO';
+        this.steps = options.steps;
+        this.totalSteps = options.steps.length;
+    }
+    /**
+     * Start the progress tracker.
+     */
+    start() {
+        if (!this.enabled)
+            return;
+        this.currentStep = 0;
+        stderr.write(`\n${this.prefix}: Starting...\n`);
+    }
+    /**
+     * Update to a specific step.
+     */
+    step(index, message) {
+        if (!this.enabled)
+            return;
+        this.currentStep = index;
+        const stepName = this.steps[index] ?? message ?? 'Working...';
+        const progress = `[${index + 1}/${this.totalSteps}]`;
+        stderr.write(`  ${progress} ${stepName}...\n`);
+    }
+    /**
+     * Move to next step.
+     */
+    next(message) {
+        this.step(this.currentStep + 1, message);
+    }
+    /**
+     * Mark as complete with optional summary.
+     *
+     * @remarks
+     * Writes to stderr (not stdout) so that progress messages never pollute
+     * the machine-readable JSON envelope on stdout. Stdout MUST contain exactly
+     * one JSON object per CLI invocation (ADR-039 / T927).
+     */
+    complete(summary) {
+        if (!this.enabled)
+            return;
+        if (summary) {
+            stderr.write(`\n${this.prefix}: \u2713 ${summary}\n\n`);
+        }
+        else {
+            stderr.write(`\n${this.prefix}: \u2713 Complete\n\n`);
+        }
+    }
+    /**
+     * Report an error.
+     */
+    error(message) {
+        if (!this.enabled)
+            return;
+        stderr.write(`\n${this.prefix}: \u2717 ${message}\n\n`);
+    }
+}
+/**
+ * Simple spinner for indeterminate progress.
+ */
+export class Spinner {
+    enabled;
+    message;
+    timer = null;
+    frames = [
+        '\u280b',
+        '\u2819',
+        '\u2839',
+        '\u2838',
+        '\u283c',
+        '\u2834',
+        '\u2826',
+        '\u2827',
+        '\u2807',
+        '\u280f',
+    ];
+    frameIndex = 0;
+    constructor(options) {
+        this.enabled = options.enabled;
+        this.message = options.message;
+    }
+    /**
+     * Start the spinner.
+     */
+    start() {
+        if (!this.enabled)
+            return;
+        this.timer = setInterval(() => {
+            const frame = this.frames[this.frameIndex];
+            stderr.write(`\r${frame} ${this.message}`);
+            this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+        }, 80);
+    }
+    /**
+     * Stop the spinner.
+     */
+    stop(finalMessage) {
+        if (!this.enabled)
+            return;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (finalMessage) {
+            stderr.write(`\r\u2713 ${finalMessage}\n`);
+        }
+        else {
+            stderr.write('\r'.padEnd(this.message.length + 2) + '\r');
+        }
+    }
+    /**
+     * Update the spinner message.
+     */
+    update(message) {
+        this.message = message;
+    }
+}
+/**
+ * Create a progress tracker for self-update operations.
+ */
+export function createSelfUpdateProgress(enabled) {
+    return new ProgressTracker({
+        enabled,
+        prefix: 'CLEO',
+        steps: [
+            'Detecting installation type',
+            'Checking current version',
+            'Querying npm registry',
+            'Comparing versions',
+            'Running post-update checks',
+            'Finalizing',
+        ],
+    });
+}
+/**
+ * Create a progress tracker for doctor operations.
+ */
+export function createDoctorProgress(enabled) {
+    return new ProgressTracker({
+        enabled,
+        prefix: 'CLEO Doctor',
+        steps: [
+            'Checking CLEO directory',
+            'Verifying tasks database',
+            'Checking configuration',
+            'Validating schemas',
+            'Running health checks',
+        ],
+    });
+}
+/**
+ * Create a progress tracker for upgrade operations.
+ */
+export function createUpgradeProgress(enabled) {
+    return new ProgressTracker({
+        enabled,
+        prefix: 'CLEO Upgrade',
+        steps: [
+            'Analyzing current state',
+            'Checking storage migration needs',
+            'Validating schemas',
+            'Applying fixes',
+            'Verifying results',
+        ],
+    });
+}
+//# sourceMappingURL=progress.js.map

package/dist/cli/progress.js.map

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

package/dist/cli/renderers/colors.d.ts

@@ -0,0 +1,32 @@
+export declare const BOLD: string;
+export declare const DIM: string;
+export declare const NC: string;
+export declare const RED: string;
+export declare const GREEN: string;
+export declare const YELLOW: string;
+export declare const BLUE: string;
+export declare const MAGENTA: string;
+export declare const CYAN: string;
+/** Map task status to a display symbol. Falls back to '?' for unknown values. */
+export declare function statusSymbol(status: string): string;
+/** Map task status to a color escape. */
+export declare function statusColor(status: string): string;
+/** Map task priority to a display symbol. */
+export declare function prioritySymbol(priority: string): string;
+/** Map task priority to a color escape. */
+export declare function priorityColor(priority: string): string;
+export declare const BOX: {
+    tl: string;
+    tr: string;
+    bl: string;
+    br: string;
+    h: string;
+    v: string;
+    ml: string;
+    mr: string;
+};
+/** Create a horizontal rule with box-drawing characters. */
+export declare function hRule(width?: number): string;
+/** Format a date string as YYYY-MM-DD. */
+export declare function shortDate(isoDate: string | null | undefined): string;
+//# sourceMappingURL=colors.d.ts.map

package/dist/cli/renderers/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../../src/cli/renderers/colors.ts"],"names":[],"mappings":"AAyCA,eAAO,MAAM,IAAI,QAAkB,CAAC;AACpC,eAAO,MAAM,GAAG,QAAkB,CAAC;AACnC,eAAO,MAAM,EAAE,QAAkB,CAAC;AAClC,eAAO,MAAM,GAAG,QAAqB,CAAC;AACtC,eAAO,MAAM,KAAK,QAAqB,CAAC;AACxC,eAAO,MAAM,MAAM,QAAqB,CAAC;AACzC,eAAO,MAAM,IAAI,QAAqB,CAAC;AACvC,eAAO,MAAM,OAAO,QAAqB,CAAC;AAC1C,eAAO,MAAM,IAAI,QAAqB,CAAC;AAMvC,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiBlD;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA2BvD;AAED,2CAA2C;AAC3C,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAatD;AAMD,eAAO,MAAM,GAAG;;;;;;;;;CAW4D,CAAC;AAE7E,4DAA4D;AAC5D,wBAAgB,KAAK,CAAC,KAAK,GAAE,MAAW,GAAG,MAAM,CAEhD;AAED,0CAA0C;AAC1C,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGpE"}

package/dist/cli/renderers/colors.js

@@ -0,0 +1,141 @@
+/**
+ * Terminal color and symbol utilities for human-readable CLI output.
+ *
+ * Respects NO_COLOR (https://no-color.org) and FORCE_COLOR env vars.
+ * Falls back to plain ASCII when color is not supported.
+ *
+ * Status symbols are sourced from the registry (TASK_STATUS_SYMBOLS_UNICODE /
+ * TASK_STATUS_SYMBOLS_ASCII) to keep icon definitions co-located with the
+ * status values they describe.
+ *
+ * @task T4666
+ * @epic T4663
+ */
+import { TASK_STATUS_SYMBOLS_ASCII, TASK_STATUS_SYMBOLS_UNICODE, } from '@cleocode/contracts';
+/** Whether ANSI color escape codes should be used. */
+const colorsEnabled = (() => {
+    if (process.env['NO_COLOR'] !== undefined)
+        return false;
+    if (process.env['FORCE_COLOR'] !== undefined)
+        return true;
+    return process.stdout.isTTY === true;
+})();
+/** Whether Unicode box-drawing and emoji are supported. */
+const unicodeEnabled = (() => {
+    const lang = process.env['LANG'] ?? '';
+    if (lang === 'C' || lang === 'POSIX')
+        return false;
+    return lang.includes('UTF') || process.platform === 'darwin';
+})();
+// ---------------------------------------------------------------------------
+// ANSI escape helpers
+// ---------------------------------------------------------------------------
+function ansi(code) {
+    return colorsEnabled ? code : '';
+}
+export const BOLD = ansi('\x1b[1m');
+export const DIM = ansi('\x1b[2m');
+export const NC = ansi('\x1b[0m'); // reset
+export const RED = ansi('\x1b[0;31m');
+export const GREEN = ansi('\x1b[0;32m');
+export const YELLOW = ansi('\x1b[1;33m');
+export const BLUE = ansi('\x1b[0;34m');
+export const MAGENTA = ansi('\x1b[0;35m');
+export const CYAN = ansi('\x1b[0;36m');
+// ---------------------------------------------------------------------------
+// Status symbols and colors
+// ---------------------------------------------------------------------------
+/** Map task status to a display symbol. Falls back to '?' for unknown values. */
+export function statusSymbol(status) {
+    const map = unicodeEnabled ? TASK_STATUS_SYMBOLS_UNICODE : TASK_STATUS_SYMBOLS_ASCII;
+    return map[status] ?? '?';
+}
+/** Map task status to a color escape. */
+export function statusColor(status) {
+    switch (status) {
+        case 'pending':
+            return CYAN;
+        case 'active':
+            return GREEN;
+        case 'blocked':
+            return RED;
+        case 'done':
+            return DIM;
+        case 'cancelled':
+            return DIM;
+        case 'archived':
+            return DIM;
+        default:
+            return '';
+    }
+}
+/** Map task priority to a display symbol. */
+export function prioritySymbol(priority) {
+    if (unicodeEnabled) {
+        switch (priority) {
+            case 'critical':
+                return '\uD83D\uDD34'; // red circle emoji
+            case 'high':
+                return '\uD83D\uDFE1'; // yellow circle emoji
+            case 'medium':
+                return '\uD83D\uDD35'; // blue circle emoji
+            case 'low':
+                return '\u26AA'; // white circle emoji
+            default:
+                return '';
+        }
+    }
+    switch (priority) {
+        case 'critical':
+            return '!';
+        case 'high':
+            return 'H';
+        case 'medium':
+            return 'M';
+        case 'low':
+            return 'L';
+        default:
+            return '';
+    }
+}
+/** Map task priority to a color escape. */
+export function priorityColor(priority) {
+    switch (priority) {
+        case 'critical':
+            return RED;
+        case 'high':
+            return YELLOW;
+        case 'medium':
+            return BLUE;
+        case 'low':
+            return DIM;
+        default:
+            return '';
+    }
+}
+// ---------------------------------------------------------------------------
+// Box drawing
+// ---------------------------------------------------------------------------
+export const BOX = unicodeEnabled
+    ? {
+        tl: '\u256D',
+        tr: '\u256E',
+        bl: '\u2570',
+        br: '\u256F',
+        h: '\u2500',
+        v: '\u2502',
+        ml: '\u251C',
+        mr: '\u2524',
+    }
+    : { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|', ml: '+', mr: '+' };
+/** Create a horizontal rule with box-drawing characters. */
+export function hRule(width = 65) {
+    return BOX.h.repeat(width);
+}
+/** Format a date string as YYYY-MM-DD. */
+export function shortDate(isoDate) {
+    if (!isoDate)
+        return '';
+    return isoDate.split('T')[0] ?? isoDate;
+}
+//# sourceMappingURL=colors.js.map

package/dist/cli/renderers/colors.js.map

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

package/dist/cli/renderers/error.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Structured markdown error renderer for CLI output.
+ *
+ * Renders CleoError instances as human-readable markdown for terminal display.
+ *
+ * @task T5240
+ */
+import type { CleoError } from '@cleocode/core';
+/**
+ * Render a CleoError as structured markdown for CLI display.
+ */
+export declare function renderErrorMarkdown(error: CleoError): string;
+//# sourceMappingURL=error.d.ts.map

package/dist/cli/renderers/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/cli/renderers/error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAkC5D"}

package/dist/cli/renderers/error.js

@@ -0,0 +1,42 @@
+/**
+ * Structured markdown error renderer for CLI output.
+ *
+ * Renders CleoError instances as human-readable markdown for terminal display.
+ *
+ * @task T5240
+ */
+import { getExitCodeName } from '@cleocode/contracts';
+import { getErrorDefinition } from '@cleocode/core';
+/**
+ * Render a CleoError as structured markdown for CLI display.
+ */
+export function renderErrorMarkdown(error) {
+    const def = getErrorDefinition(error.code);
+    const name = getExitCodeName(error.code);
+    const lines = [];
+    lines.push(`**Error ${error.code}**: ${name}`);
+    lines.push('');
+    lines.push(error.message);
+    if (def?.category) {
+        lines.push('');
+        lines.push(`Category: ${def.category}`);
+    }
+    const fix = error.fix ?? def?.fix;
+    if (fix) {
+        lines.push('');
+        lines.push(`**Fix**: ${fix}`);
+    }
+    if (error.alternatives && error.alternatives.length > 0) {
+        lines.push('');
+        lines.push('**Alternatives**:');
+        for (const alt of error.alternatives) {
+            lines.push(`  - ${alt.action}: \`${alt.command}\``);
+        }
+    }
+    if (def?.recoverable) {
+        lines.push('');
+        lines.push('This error is recoverable -- retrying may succeed.');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=error.js.map

package/dist/cli/renderers/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../src/cli/renderers/error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,MAAM,GAAG,GAAG,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,IAAI,OAAO,IAAI,EAAE,CAAC,CAAC;IAC/C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE1B,IAAI,GAAG,EAAE,QAAQ,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,aAAa,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,GAAG,EAAE,GAAG,CAAC;IAClC,IAAI,GAAG,EAAE,CAAC;QACR,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAChC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,MAAM,OAAO,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED,IAAI,GAAG,EAAE,WAAW,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

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

@@ -0,0 +1,90 @@
+/**
+ * Central output dispatch for V2 CLI commands.
+ *
+ * Provides cliOutput() which replaces `console.log(formatSuccess(data))`.
+ * Checks the resolved format (JSON/human/quiet) and dispatches to either
+ * the LAFS JSON envelope (formatSuccess) or a human-readable renderer.
+ *
+ * Commands call:
+ *   cliOutput(data, { command: 'show', message, operation, page })
+ *
+ * @task T4665
+ * @task T4666
+ * @task T4813
+ * @epic T4663
+ */
+import { type FormatOptions } from '@cleocode/core';
+import type { CliMeta } from '@cleocode/lafs';
+import { renderWaves } from './system.js';
+export type { RenderWavesMode, RenderWavesOptions } from './system.js';
+export { renderWaves };
+export interface CliOutputOptions {
+    /** Command name (used to pick the correct human renderer). */
+    command: string;
+    /** Optional success message for JSON envelope (attached to `meta.message`). */
+    message?: string;
+    /** Operation name for canonical envelope `meta.operation` (e.g. `"tasks.show"`). */
+    operation?: string;
+    /** Pagination metadata for canonical envelope `page` field. */
+    page?: FormatOptions['page'];
+    /** Extra metadata extensions merged into `meta`. */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Output data to stdout in the resolved format (JSON or human-readable).
+ *
+ * Replaces `console.log(formatSuccess(data))` in all V2 commands.
+ * When format is 'human', normalizes the data shape then dispatches to
+ * the appropriate renderer.
+ * When format is 'json', delegates to existing formatSuccess().
+ *
+ * @task T4665
+ * @task T4666
+ * @task T4813
+ */
+export declare function cliOutput(data: unknown, opts: CliOutputOptions): void;
+/**
+ * Error details for structured error output.
+ *
+ * Carries the full LAFS-compatible error context forwarded by the dispatch
+ * adapter from {@link DispatchError}. All fields are optional — only present
+ * fields are emitted in the output envelope.
+ *
+ * @see packages/cleo/src/dispatch/types.ts DispatchError
+ */
+export interface CliErrorDetails {
+    /** Machine-readable error code name (e.g. `E_NOT_FOUND`). */
+    name?: string;
+    /** Additional structured details from the error. */
+    details?: unknown;
+    /** Copy-paste fix hint for the operator or agent. */
+    fix?: unknown;
+    /** Alternative actions the caller can try. */
+    alternatives?: Array<{
+        action: string;
+        command: string;
+    }>;
+}
+/**
+ * Output an error in the resolved format.
+ *
+ * In JSON format (default / agent mode): emits a canonical `CliEnvelope` error
+ * envelope to stdout. The envelope always includes `meta` (ADR-039).
+ * All optional fields (`codeName`, `fix`, `alternatives`, `details`) are
+ * included only when they are actually present — no `undefined` keys are emitted.
+ *
+ * In human format: prints a plain error line to stderr and, when
+ * `details.fix` is a string, appends a `Fix: <hint>` line.
+ *
+ * @param message - Human-readable error message.
+ * @param code    - Numeric exit code or string error code.
+ * @param details - Optional structured details (codeName, fix, alternatives, …).
+ * @param meta    - Optional partial meta to merge into the error envelope.
+ *
+ * @task T4666
+ * @task T4813
+ * @task T336
+ * @task T338
+ */
+export declare function cliError(message: string, code?: number | string, details?: CliErrorDetails, meta?: Partial<CliMeta>): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/renderers/index.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AACnE,OAAO,KAAK,EAAe,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAO3D,OAAO,EAcL,WAAW,EACZ,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,CAAC;AAgEvB,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAsIrE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,8CAA8C;IAC9C,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,eAAe,EACzB,IAAI,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GACtB,IAAI,CA0CN"}