@moda-ai/cli 1.22.1 → 1.23.0

package/dist/output.js

@@ -1,624 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { CliAccessError, CliAuthError, CliCancellationError, CliInputError, CliInputRequiredError, isApiLikeError, isNetworkLikeError, } from './errors.js';
-import { redactDeep } from './redact.js';
-export const AGENT_SCHEMA_VERSION = 'moda.agent.v1';
-export const AGENT_EVENT_SCHEMA_VERSION = 'moda.agent_event.v1';
-/**
- * One-line feedback nudge stamped into every non-feedback success envelope's
- * `meta.tip` (agents are the CLI's most common callers, and the envelope is
- * where they actually look). Deliberately conditional wording so agents flag
- * genuine observations instead of habitually running the command. The
- * human-TTY twin is printed on stderr by the dispatcher in cli.ts.
- */
-export const FEEDBACK_TIP = 'Help us improve! If a result in this response looks wrong or is missing data, flag it: moda feedback "<describe what looked wrong>" [--category=...] [--conversation-id=... | --cluster-id=... | --tool-name=...]. Only submit genuine observations.';
-/**
- * Stable process exit codes that an external agent can branch on:
- *   0  ok        — grounded answer from Moda Cloud intelligence.
- *   3  degraded  — answer produced from a local/degraded fallback (lower trust).
- *   1  error     — command/input/unexpected failure (see envelope `errors[]`).
- *   4  auth      — login or token renewal required before retrying.
- *   5  input     — non-interactive caller must choose and re-invoke.
- *   130 cancel   — interrupted or the output consumer closed the pipe.
- * `EXIT_DEGRADED` is intentionally distinct so a caller can tell a degraded
- * answer apart from both success and hard failure without parsing the payload.
- */
-export const EXIT_OK = 0;
-export const EXIT_ERROR = 1;
-export const EXIT_DEGRADED = 3;
-export const EXIT_AUTH_REQUIRED = 4;
-export const EXIT_INPUT_REQUIRED = 5;
-export const EXIT_CANCELLED = 130;
-export const AGENT_ERROR_CODES = [
-    'input_error',
-    'api_error',
-    'network_error',
-    'auth_required',
-    'input_required',
-    'cancelled',
-    'command_error',
-    'access_denied',
-    'unknown_error',
-    'cloud_unavailable',
-];
-const FALLBACK_RUN_ID = randomUUID();
-let fallbackSeq = 0;
-let stdoutClosed = false;
-let stderrClosed = false;
-process.stdout.on('error', (error) => {
-    if (error.code === 'EPIPE') {
-        stdoutClosed = true;
-        process.exitCode = EXIT_CANCELLED;
-        return;
-    }
-    throw error;
-});
-process.stderr.on('error', (error) => {
-    if (error.code === 'EPIPE') {
-        stderrClosed = true;
-        process.exitCode = EXIT_CANCELLED;
-        return;
-    }
-    throw error;
-});
-/**
- * True once an EPIPE from a closed stdout/stderr consumer has been observed.
- * The stream error listeners above own this state; expose it so callers can
- * detect consumer-cancelled runs explicitly instead of sniffing the global
- * `process.exitCode`.
- */
-export function wasOutputCancelled() {
-    return stdoutClosed || stderrClosed;
-}
-export function safeWriteStdout(text) {
-    if (stdoutClosed)
-        return false;
-    try {
-        if (process.env.NODE_ENV === 'test') {
-            console.log(text.endsWith('\n') ? text.slice(0, -1) : text);
-        }
-        else {
-            process.stdout.write(text);
-        }
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'EPIPE') {
-            stdoutClosed = true;
-            process.exitCode = EXIT_CANCELLED;
-            return false;
-        }
-        throw error;
-    }
-}
-export function safeWriteStderr(text) {
-    if (stderrClosed)
-        return false;
-    try {
-        if (process.env.NODE_ENV === 'test') {
-            console.error(text.endsWith('\n') ? text.slice(0, -1) : text);
-        }
-        else {
-            process.stderr.write(text);
-        }
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'EPIPE') {
-            stderrClosed = true;
-            process.exitCode = EXIT_CANCELLED;
-            return false;
-        }
-        throw error;
-    }
-}
-/**
- * Output mode requested by explicit flags only, or `undefined` when the caller
- * did not pick one. Explicit flags always win over auto-detection.
- */
-function explicitModeFromFlags(flags) {
-    if (flags.agent === 'true' && (flags.stream === 'true' || flags.format === 'ndjson'))
-        return 'agent-stream';
-    if (flags.agent === 'true')
-        return 'agent';
-    if (flags.json === 'true')
-        return 'json';
-    if (flags.human === 'true' || flags.prose === 'true')
-        return 'human';
-    return undefined;
-}
-/** Flag-only resolution (default human). Kept for callers that only have flags. */
-export function outputModeFromFlags(flags) {
-    return explicitModeFromFlags(flags) ?? 'human';
-}
-function outputModeFromEnv(env) {
-    const fmt = (env.MODA_FORMAT ?? '').trim().toLowerCase();
-    if (fmt === 'human' || fmt === 'json' || fmt === 'agent')
-        return fmt;
-    if (fmt === 'agent-stream' || fmt === 'ndjson')
-        return 'agent-stream';
-    return undefined;
-}
-function truthyEnv(value) {
-    return value != null && value !== '' && value !== '0' && value.toLowerCase() !== 'false';
-}
-/**
- * True when the process appears to be driven by an agent / automation rather
- * than an interactive human (Claude Code, Cursor, generic CI, or an explicit
- * `MODA_AGENT` opt-in). Such callers get machine-parseable output by default.
- */
-function isAgentEnvironment(env) {
-    return (truthyEnv(env.CLAUDECODE) ||
-        truthyEnv(env.CURSOR) ||
-        truthyEnv(env.CI) ||
-        truthyEnv(env.MODA_AGENT));
-}
-/**
- * Resolve the effective output mode for a real CLI invocation, in priority
- * order: explicit flags -> `MODA_FORMAT` -> agent-environment detection ->
- * TTY detection (piped/redirected => agent JSON) -> human prose. This is what
- * makes the CLI agent-safe: a piped/automated caller gets structured output
- * with zero flags, while a human at a terminal still gets prose.
- */
-export function resolveOutputMode(flags, opts = {}) {
-    const explicit = explicitModeFromFlags(flags);
-    if (explicit)
-        return explicit;
-    const env = opts.env ?? process.env;
-    const fromEnv = outputModeFromEnv(env);
-    if (fromEnv)
-        return fromEnv;
-    if (isAgentEnvironment(env))
-        return 'agent';
-    const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY);
-    if (!isTTY)
-        return 'agent';
-    return 'human';
-}
-export function createCliOutput(options) {
-    const state = {
-        runId: options.runId ?? randomUUID(),
-        seq: 0,
-        started: false,
-        terminal: false,
-        startedAt: Date.now(),
-        lastEventAt: Date.now(),
-    };
-    const emitEvent = (event) => {
-        if (options.quiet || options.mode !== 'agent-stream')
-            return;
-        if (state.terminal)
-            return;
-        if (event.event === 'started' && state.started)
-            return;
-        if (event.event === 'started')
-            state.started = true;
-        if (isTerminalEvent(event.event)) {
-            state.terminal = true;
-            clearHeartbeat(state);
-        }
-        state.lastEventAt = Date.now();
-        safeWriteStdout(`${JSON.stringify(createAgentEvent(options.command, event, state))}\n`);
-    };
-    const ensureStarted = () => {
-        if (options.mode !== 'agent-stream' || state.started || options.quiet)
-            return;
-        startHeartbeat(options.command, state);
-        emitEvent({
-            event: 'started',
-            phase: options.command,
-            message: `Starting ${options.command}.`,
-            elapsed_ms: 0,
-        });
-    };
-    const writeEnvelope = (data, writeOptions = {}) => {
-        return createAgentEnvelope({
-            command: options.command,
-            status: writeOptions.status === 'error'
-                ? 'error'
-                : writeOptions.status === 'degraded'
-                    ? 'degraded'
-                    : 'ok',
-            data,
-            meta: {
-                ...(writeOptions.meta ?? {}),
-                run_id: state.runId,
-                // No tip on the feedback command itself; it would point at the
-                // command that just ran.
-                ...(options.command === 'feedback' ? {} : { tip: FEEDBACK_TIP }),
-            },
-            summary: writeOptions.summary,
-            findings: writeOptions.findings,
-            evidenceRefs: writeOptions.evidenceRefs,
-            recommendedActions: writeOptions.recommendedActions,
-            nextCommands: writeOptions.nextCommands,
-            artifacts: writeOptions.artifacts,
-            warnings: writeOptions.warnings,
-            errors: writeOptions.errors,
-        });
-    };
-    const output = {
-        mode: options.mode,
-        quiet: options.quiet === true,
-        writeData(data, writeOptions = {}) {
-            if (options.quiet)
-                return;
-            if (options.mode === 'agent' || options.mode === 'agent-stream') {
-                if (state.terminal)
-                    return;
-                const envelope = writeEnvelope(data, writeOptions);
-                if (options.mode === 'agent-stream') {
-                    ensureStarted();
-                    emitEvent({
-                        event: envelope.status === 'error' ? 'error' : 'completed',
-                        status: envelope.status,
-                        result: envelope,
-                        ...(envelope.errors[0] ? { error: envelope.errors[0] } : {}),
-                    });
-                }
-                else {
-                    state.terminal = true;
-                    safeWriteStdout(`${JSON.stringify(envelope)}\n`);
-                }
-                return;
-            }
-            safeWriteStdout(`${JSON.stringify(redactDeep(data), null, 2)}\n`);
-        },
-        writeEvent(event) {
-            if (options.quiet)
-                return;
-            if (options.mode !== 'agent-stream')
-                return;
-            if (event.event === 'started') {
-                startHeartbeat(options.command, state);
-                emitEvent(event);
-                return;
-            }
-            ensureStarted();
-            emitEvent(event);
-        },
-        writeError(error) {
-            if (options.quiet || state.terminal)
-                return;
-            const agentError = errorToAgentError(error);
-            const envelope = createAgentErrorEnvelope(options.command || 'unknown', agentError, state.runId);
-            if (options.mode === 'agent-stream') {
-                ensureStarted();
-                if (error instanceof CliInputRequiredError) {
-                    emitEvent({
-                        event: 'needs_input',
-                        status: 'error',
-                        message: error.message,
-                        error: agentError,
-                        input_request: error.input_request,
-                        result: envelope,
-                    });
-                    return;
-                }
-                if (error instanceof CliAuthError) {
-                    emitEvent({
-                        event: 'auth_required',
-                        status: 'error',
-                        message: error.message,
-                        error: agentError,
-                        auth: error.auth,
-                        result: envelope,
-                    });
-                    return;
-                }
-                if (error instanceof CliCancellationError) {
-                    emitEvent({
-                        event: 'cancelled',
-                        status: 'error',
-                        message: error.message,
-                        error: agentError,
-                        result: envelope,
-                    });
-                    return;
-                }
-                emitEvent({
-                    event: 'error',
-                    status: 'error',
-                    message: agentError.message,
-                    error: agentError,
-                    result: envelope,
-                });
-                return;
-            }
-            if (options.mode === 'agent' || options.mode === 'json') {
-                state.terminal = true;
-                safeWriteStdout(`${JSON.stringify(envelope)}\n`);
-            }
-        },
-        writeCancelled(reason = 'Command cancelled.') {
-            output.writeError(new CliCancellationError(reason));
-        },
-        hasTerminalOutput() {
-            return state.terminal;
-        },
-        close() {
-            clearHeartbeat(state);
-        },
-    };
-    return output;
-}
-export function createAgentEnvelope(options) {
-    const safeData = redactDeep(options.data);
-    const bounded = boundForAgent(safeData);
-    const envelope = {
-        schema_version: AGENT_SCHEMA_VERSION,
-        command: options.command,
-        status: options.status,
-        generated_at: new Date().toISOString(),
-        ...(options.profile ? { profile: options.profile } : {}),
-        summary: normalizeSummary(options.summary, options.command, options.status, safeData),
-        findings: options.findings ?? [],
-        evidence_refs: options.evidenceRefs ?? [],
-        recommended_actions: options.recommendedActions ?? [],
-        next_commands: normalizeNextCommands(options.nextCommands ?? []),
-        artifacts: options.artifacts ?? [],
-        warnings: options.warnings ?? inferWarnings(safeData),
-        errors: options.errors ?? [],
-        data: bounded.data,
-        ...(options.meta ? { meta: options.meta } : {}),
-        ...(bounded.truncation ? { truncation: bounded.truncation } : {}),
-    };
-    return redactDeep(envelope);
-}
-export function createAgentErrorEnvelope(command, error, runId) {
-    return createAgentEnvelope({
-        command,
-        status: 'error',
-        data: null,
-        meta: runId ? { run_id: runId } : undefined,
-        summary: {
-            text: error.message,
-            confidence: 'high',
-        },
-        errors: [error],
-        nextCommands: (error.suggested_commands ?? []).map((commandText) => ({
-            command: commandText,
-            purpose: 'Suggested recovery command.',
-            mutability: commandText.includes(' sync') || commandText.startsWith('moda sync') ? 'sync' : 'read',
-            requires_approval: commandText.includes(' --yes') || commandText.includes(' sync'),
-        })),
-    });
-}
-export function createAgentEvent(command, event, state) {
-    const stamped = {
-        schema_version: AGENT_EVENT_SCHEMA_VERSION,
-        command,
-        generated_at: new Date().toISOString(),
-        run_id: state?.runId ?? FALLBACK_RUN_ID,
-        seq: state ? ++state.seq : ++fallbackSeq,
-        event_version: event.event_version ?? 1,
-        ...event,
-    };
-    return redactDeep(stamped);
-}
-export function errorToAgentError(error) {
-    if (error instanceof CliInputRequiredError) {
-        return {
-            code: 'input_required',
-            message: error.message,
-            cause: error.usage,
-            suggested_commands: error.input_request.resume_command
-                ? [error.input_request.resume_command.join(' ')]
-                : undefined,
-            input_request: error.input_request,
-            blocking: true,
-        };
-    }
-    if (error instanceof CliAuthError) {
-        const suggested = [error.auth.login_command.join(' ')];
-        if (error.auth.resume_command)
-            suggested.push(error.auth.resume_command.join(' '));
-        return {
-            code: 'auth_required',
-            message: error.message,
-            cause: error.usage,
-            suggested_commands: suggested,
-            auth: error.auth,
-            blocking: true,
-        };
-    }
-    if (error instanceof CliCancellationError) {
-        return {
-            code: 'cancelled',
-            message: error.message,
-            blocking: true,
-        };
-    }
-    if (error instanceof CliAccessError) {
-        // Access problem (missing organization or insufficient role), not
-        // auth-missing: exit stays EXIT_ERROR and no login command is suggested.
-        return {
-            code: 'access_denied',
-            message: error.message,
-            cause: error.guidance,
-            blocking: true,
-        };
-    }
-    if (error instanceof Error) {
-        if (error instanceof CliInputError || error.name === 'ZodError') {
-            return {
-                code: 'input_error',
-                message: error.message,
-                cause: 'usage' in error && typeof error.usage === 'string' ? error.usage : undefined,
-                suggested_commands: 'usage' in error && typeof error.usage === 'string'
-                    ? extractSuggestedCommands(error.usage)
-                    : undefined,
-                blocking: true,
-            };
-        }
-        if (isApiLikeError(error)) {
-            const statusCode = 'statusCode' in error ? error.statusCode : undefined;
-            return {
-                code: 'api_error',
-                message: error.message,
-                cause: typeof statusCode === 'number' ? `HTTP ${statusCode}` : undefined,
-                blocking: true,
-            };
-        }
-        if (isNetworkLikeError(error)) {
-            return {
-                code: 'network_error',
-                message: error.message,
-                blocking: true,
-            };
-        }
-        return {
-            code: 'command_error',
-            message: error.message,
-            cause: 'usage' in error && typeof error.usage === 'string' ? error.usage : undefined,
-            suggested_commands: 'usage' in error && typeof error.usage === 'string'
-                ? extractSuggestedCommands(error.usage)
-                : undefined,
-            blocking: true,
-        };
-    }
-    return {
-        code: 'unknown_error',
-        message: String(error),
-        blocking: true,
-    };
-}
-function isTerminalEvent(event) {
-    return event === 'completed' ||
-        event === 'error' ||
-        event === 'cancelled' ||
-        event === 'needs_input' ||
-        event === 'auth_required';
-}
-function startHeartbeat(command, state) {
-    if (state.heartbeat)
-        return;
-    const intervalMs = Number(process.env.MODA_HEARTBEAT_MS ?? 10_000);
-    if (!Number.isFinite(intervalMs) || intervalMs <= 0)
-        return;
-    state.heartbeat = setInterval(() => {
-        if (state.terminal || stdoutClosed)
-            return;
-        const now = Date.now();
-        if (now - state.lastEventAt < intervalMs)
-            return;
-        state.lastEventAt = now;
-        safeWriteStdout(`${JSON.stringify(createAgentEvent(command, {
-            event: 'heartbeat',
-            elapsed_ms: now - state.startedAt,
-        }, state))}\n`);
-    }, intervalMs);
-    state.heartbeat.unref();
-}
-function clearHeartbeat(state) {
-    if (!state.heartbeat)
-        return;
-    clearInterval(state.heartbeat);
-    state.heartbeat = undefined;
-}
-function normalizeSummary(summary, command, status, data) {
-    if (typeof summary === 'string') {
-        return { text: summary, confidence: 'high' };
-    }
-    if (summary?.text) {
-        return {
-            text: summary.text,
-            confidence: summary.confidence ?? 'high',
-        };
-    }
-    return inferSummary(command, status, data);
-}
-function inferSummary(command, status, data) {
-    const record = asRecord(data);
-    if (status === 'error') {
-        return { text: `${command} failed.`, confidence: 'high' };
-    }
-    const summary = asRecord(record?.summary);
-    if (summary) {
-        const statusValue = typeof summary.status === 'string' ? summary.status : undefined;
-        const fail = typeof summary.fail === 'number' ? summary.fail : undefined;
-        const warning = typeof summary.warning === 'number' ? summary.warning : undefined;
-        if (statusValue && fail !== undefined && warning !== undefined) {
-            return {
-                text: `${command} completed with status ${statusValue}: ${fail} failing checks and ${warning} warnings.`,
-                confidence: 'high',
-            };
-        }
-        const runtimeAgentCount = typeof summary.runtimeAgentCount === 'number'
-            ? summary.runtimeAgentCount
-            : undefined;
-        if (runtimeAgentCount !== undefined) {
-            return {
-                text: `${command} completed. Harness summary includes ${runtimeAgentCount} runtime agent(s).`,
-                confidence: 'high',
-            };
-        }
-    }
-    if (typeof record?.status === 'string') {
-        return { text: `${command} completed with status ${record.status}.`, confidence: 'high' };
-    }
-    return { text: `${command} completed.`, confidence: 'medium' };
-}
-function normalizeNextCommands(commands) {
-    return commands.map((command) => {
-        if (typeof command !== 'string')
-            return command;
-        return {
-            command,
-            purpose: 'Suggested next Moda command.',
-            mutability: inferMutability(command),
-            requires_approval: command.includes(' --yes') || command.includes(' sync'),
-        };
-    });
-}
-function inferMutability(command) {
-    if (/\b(sync|approve|init|install|pull|gen|remove|promote)\b/.test(command)) {
-        if (/\bsync\b/.test(command))
-            return 'sync';
-        return 'write';
-    }
-    return 'read';
-}
-function inferWarnings(data) {
-    const record = asRecord(data);
-    const direct = record?.warnings;
-    if (Array.isArray(direct))
-        return direct.filter((item) => typeof item === 'string');
-    const validation = asRecord(record?.validation);
-    if (Array.isArray(validation?.warnings)) {
-        return validation.warnings.filter((item) => typeof item === 'string');
-    }
-    return [];
-}
-function boundForAgent(data) {
-    const maxBytes = Number(process.env.MODA_AGENT_MAX_OUTPUT_BYTES ?? 200_000);
-    const serialized = JSON.stringify(data);
-    const bytes = Buffer.byteLength(serialized, 'utf8');
-    if (bytes <= maxBytes)
-        return { data };
-    const preview = serialized.slice(0, Math.max(0, maxBytes - 256));
-    return {
-        data: {
-            truncated: true,
-            original_bytes: bytes,
-            max_bytes: maxBytes,
-            preview,
-        },
-        truncation: {
-            data: {
-                original_bytes: bytes,
-                max_bytes: maxBytes,
-                reason: 'agent_output_byte_limit',
-            },
-        },
-    };
-}
-function asRecord(value) {
-    return value && typeof value === 'object' && !Array.isArray(value)
-        ? value
-        : undefined;
-}
-function extractSuggestedCommands(text) {
-    const commands = [...text.matchAll(/`(moda [^`]+)`/g)].map((match) => match[1]);
-    return commands.length > 0 ? commands : undefined;
-}
-//# sourceMappingURL=output.js.map