@moda-ai/cli 1.9.0 → 1.10.0

package/dist/config.js

@@ -1,11 +1,11 @@
 import { readFileSync } from 'node:fs';
-import { DEFAULT_INGEST_URL, PROD_BASE_URL, getLegacyConfigPath, loadLegacyCliConfig, resolveApiKeyFromActiveProfile, resolveBaseUrl, resolveIngestUrlFromActiveProfile, resolveTenantIdFromActiveProfile, syncLegacyConfigToProfile, writeLegacyCliConfig, } from './profiles.js';
+import { DEFAULT_INGEST_URL, PROD_BASE_URL, getLegacyConfigPath, loadLegacyCliConfig, resolveApiKeyFromActiveProfile, resolveBaseUrl, resolveIngestUrl as resolveProfileIngestUrl, resolveTenantIdFromActiveProfile, syncLegacyConfigToProfile, writeLegacyCliConfig, } from './profiles.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = pkg.version;
-// Canonical host is www.moda.dev. The apex `moda.dev` 308-redirects to it, and
+// Canonical host is moda.dev. The www host 308-redirects to the apex, and
 // cross-host redirects strip the Authorization header (fetch/undici), so using
-// the apex breaks `moda init`'s authenticated calls with a 401. Default to the
-// canonical host directly.
+// www breaks `moda init`'s authenticated calls with a 401. Default to the
+// canonical host directly; resolveBaseUrl() also rewrites legacy www URLs.
 export const MODA_BASE_URL = resolveBaseUrl();
 export function loadCliConfig(options = {}) {
     return loadLegacyCliConfig(options);
@@ -38,14 +38,11 @@ export function resolveApiKey(options = {}) {
 }
 /**
  * Resolve the ingest worker base URL used by `moda workspace snapshot`.
- * Env override -> persisted config -> production default.
+ * Env override -> active profile -> legacy config -> production default.
+ * Loopback URLs are rejected unless the active profile is `local`.
  */
 export function resolveIngestUrl(options = {}) {
-    const env = options.env ?? process.env;
-    return (env.MODA_INGEST_URL ||
-        resolveIngestUrlFromActiveProfile(options) ||
-        loadCliConfig(options).ingest_url ||
-        DEFAULT_INGEST_URL);
+    return resolveProfileIngestUrl(options);
 }
 /**
  * Resolve the active tenant id: env override first, then the persisted

package/dist/intelligence-schema.d.ts

@@ -0,0 +1,349 @@
+/**
+ * moda.intelligence.v1 — the unified Moda intelligence wire format (MODA-388).
+ *
+ * ONE versioned payload that every surface projects from:
+ *   - CLI `moda ask --json` / `--agent` (the agent-facing contract),
+ *   - the backend `POST /api/cli/ask` response,
+ *   - the (future) MCP server's `structuredContent`,
+ *   - the dashboard UI.
+ *
+ * Design rules:
+ *   - snake_case everywhere (no mixed casing — the prior split between the
+ *     snake_case envelope and the camelCase `production_ask.v0.1` data payload
+ *     was the main source of agent-integration pain).
+ *   - It is a SUPERSET. Differentiation between a human reader and an agent is a
+ *     RENDERING concern at the edge, not a forked schema:
+ *       · human projection  → narrative `answer_markdown`, `summary.confidence`
+ *                             as a word, raw ids/anchors hidden.
+ *       · agent projection  → full `evidence_refs` (with `anchor` + `grounding`),
+ *                             `answer_claims` (claim → evidence), structured
+ *                             `next_commands`.
+ *   - Additive evolution only within v1; breaking changes bump the version.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the shape. The backend mirrors
+ * these field names on the wire and the contract tests validate real CLI output
+ * against {@link MODA_INTELLIGENCE_V1_JSON_SCHEMA}.
+ */
+export declare const INTELLIGENCE_SCHEMA_VERSION: "moda.intelligence.v1";
+export type IntelligenceConfidence = 'high' | 'medium' | 'low' | 'unknown';
+/** Where the answer came from. `local_fallback` ⇒ degraded (lower trust). */
+export type IntelligenceSource = 'cloud' | 'local_fallback';
+/** How a signal was derived — a measured fact vs a model/heuristic estimate. */
+export type Provenance = 'measured' | 'inferred';
+/** Whether a suggested command reads, writes, or syncs state. */
+export type CommandMutability = 'read' | 'write' | 'sync' | 'unknown';
+/** Classification of a single quantitative/factual claim in the answer. */
+export type ClaimKind = 'percentage' | 'count' | 'qualitative';
+/**
+ * Verdict for one claim made in the answer, checked against the structured tool
+ * data the agent actually saw (MODA-377/378). `unverifiable` means the claim is
+ * not a checkable figure (or there was no tool data to check it against).
+ */
+export type ClaimStatus = 'grounded' | 'ungrounded' | 'unverifiable';
+export interface IntelligenceSummary {
+    text: string;
+    confidence: IntelligenceConfidence;
+}
+/**
+ * A structured locator so a surface can deep-link a piece of evidence. All
+ * fields optional — different evidence kinds populate different anchors.
+ */
+export interface EvidenceAnchor {
+    conversation_id?: string;
+    message_index?: number;
+    run_id?: string;
+    tool_name?: string;
+}
+export interface IntelligenceEvidenceRef {
+    /** Stable id, referenced by `findings[].evidence_ref_ids` and `answer_claims[].evidence_ref_ids`. */
+    id: string;
+    /** 'overview' | 'conversation' | 'message' | 'tool_failure' | 'run' | 'frustration' | 'cluster' | ... */
+    kind: string;
+    label: string;
+    anchor?: EvidenceAnchor;
+    /** Short human-readable excerpt of the underlying value. */
+    snippet?: string;
+    /** measured (exact) vs inferred (model-derived estimate) — MODA-379. */
+    grounding: Provenance;
+}
+/**
+ * A claim extracted from the answer with its grounding verdict. `value` is set
+ * for numeric claims; `evidence_ref_ids` links to the evidence that supports it
+ * (empty when ungrounded/unverifiable).
+ */
+export interface IntelligenceClaim {
+    text: string;
+    value?: number;
+    kind: ClaimKind;
+    status: ClaimStatus;
+    evidence_ref_ids: string[];
+    /** Path into the structured tool data where the value matched, when grounded. */
+    matched_path?: string;
+}
+export interface IntelligenceRecommendedAction {
+    id: string;
+    title: string;
+    rationale?: string;
+    command?: string;
+    mutability: CommandMutability;
+    requires_approval: boolean;
+}
+export interface IntelligenceFinding {
+    id: string;
+    title: string;
+    severity?: 'critical' | 'high' | 'medium' | 'low' | 'info';
+    description?: string;
+    evidence_ref_ids: string[];
+    recommended_actions: IntelligenceRecommendedAction[];
+}
+export interface IntelligenceNextCommand {
+    command: string;
+    purpose?: string;
+    mutability: CommandMutability;
+    requires_approval: boolean;
+}
+/**
+ * The canonical `moda.intelligence.v1` payload. Emitted by the backend ask
+ * endpoint and surfaced as the CLI agent envelope's `data` (and by `--json`).
+ */
+export interface ModaIntelligenceV1 {
+    schema_version: typeof INTELLIGENCE_SCHEMA_VERSION;
+    generated_at: string;
+    /** The originating command, e.g. "ask". */
+    command: string;
+    source: IntelligenceSource;
+    /** True when the answer was NOT produced by Moda Cloud intelligence. */
+    degraded: boolean;
+    question: string;
+    summary: IntelligenceSummary;
+    /** Full markdown answer (the human-facing narrative). */
+    answer_markdown: string;
+    /** Per-claim grounding verdicts (agent projection). */
+    answer_claims: IntelligenceClaim[];
+    /** Ranked findings; may be empty for a plain `ask`. */
+    findings: IntelligenceFinding[];
+    evidence_refs: IntelligenceEvidenceRef[];
+    next_commands: IntelligenceNextCommand[];
+    warnings: string[];
+    meta?: Record<string, unknown>;
+}
+/**
+ * Published draft-07 JSON Schema for {@link ModaIntelligenceV1}. This is what
+ * `moda --json-schemas` emits and what the contract tests validate CLI/backend
+ * output against. Keep in lockstep with the interfaces above.
+ */
+export declare const MODA_INTELLIGENCE_V1_JSON_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "moda.intelligence.v1";
+    readonly title: "Moda Intelligence v1";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schema_version", "generated_at", "command", "source", "degraded", "question", "summary", "answer_markdown", "answer_claims", "findings", "evidence_refs", "next_commands", "warnings"];
+    readonly properties: {
+        readonly schema_version: {
+            readonly const: "moda.intelligence.v1";
+        };
+        readonly generated_at: {
+            readonly type: "string";
+            readonly format: "date-time";
+        };
+        readonly command: {
+            readonly type: "string";
+        };
+        readonly source: {
+            readonly type: "string";
+            readonly enum: readonly ["cloud", "local_fallback"];
+        };
+        readonly degraded: {
+            readonly type: "boolean";
+        };
+        readonly question: {
+            readonly type: "string";
+        };
+        readonly summary: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["text", "confidence"];
+            readonly properties: {
+                readonly text: {
+                    readonly type: "string";
+                };
+                readonly confidence: {
+                    readonly type: "string";
+                    readonly enum: readonly ["high", "medium", "low", "unknown"];
+                };
+            };
+        };
+        readonly answer_markdown: {
+            readonly type: "string";
+        };
+        readonly answer_claims: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["text", "kind", "status", "evidence_ref_ids"];
+                readonly properties: {
+                    readonly text: {
+                        readonly type: "string";
+                    };
+                    readonly value: {
+                        readonly type: "number";
+                    };
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly enum: readonly ["percentage", "count", "qualitative"];
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["grounded", "ungrounded", "unverifiable"];
+                    };
+                    readonly evidence_ref_ids: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly matched_path: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly findings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "title", "evidence_ref_ids", "recommended_actions"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly severity: {
+                        readonly type: "string";
+                        readonly enum: readonly ["critical", "high", "medium", "low", "info"];
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly evidence_ref_ids: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly recommended_actions: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "title", "mutability", "requires_approval"];
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                };
+                                readonly title: {
+                                    readonly type: "string";
+                                };
+                                readonly rationale: {
+                                    readonly type: "string";
+                                };
+                                readonly command: {
+                                    readonly type: "string";
+                                };
+                                readonly mutability: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["read", "write", "sync", "unknown"];
+                                };
+                                readonly requires_approval: {
+                                    readonly type: "boolean";
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly evidence_refs: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "kind", "label", "grounding"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly kind: {
+                        readonly type: "string";
+                    };
+                    readonly label: {
+                        readonly type: "string";
+                    };
+                    readonly anchor: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly conversation_id: {
+                                readonly type: "string";
+                            };
+                            readonly message_index: {
+                                readonly type: "number";
+                            };
+                            readonly run_id: {
+                                readonly type: "string";
+                            };
+                            readonly tool_name: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly snippet: {
+                        readonly type: "string";
+                    };
+                    readonly grounding: {
+                        readonly type: "string";
+                        readonly enum: readonly ["measured", "inferred"];
+                    };
+                };
+            };
+        };
+        readonly next_commands: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["command", "mutability", "requires_approval"];
+                readonly properties: {
+                    readonly command: {
+                        readonly type: "string";
+                    };
+                    readonly purpose: {
+                        readonly type: "string";
+                    };
+                    readonly mutability: {
+                        readonly type: "string";
+                        readonly enum: readonly ["read", "write", "sync", "unknown"];
+                    };
+                    readonly requires_approval: {
+                        readonly type: "boolean";
+                    };
+                };
+            };
+        };
+        readonly warnings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly meta: {
+            readonly type: "object";
+        };
+    };
+};
+//# sourceMappingURL=intelligence-schema.d.ts.map

package/dist/intelligence-schema.js

@@ -0,0 +1,174 @@
+/**
+ * moda.intelligence.v1 — the unified Moda intelligence wire format (MODA-388).
+ *
+ * ONE versioned payload that every surface projects from:
+ *   - CLI `moda ask --json` / `--agent` (the agent-facing contract),
+ *   - the backend `POST /api/cli/ask` response,
+ *   - the (future) MCP server's `structuredContent`,
+ *   - the dashboard UI.
+ *
+ * Design rules:
+ *   - snake_case everywhere (no mixed casing — the prior split between the
+ *     snake_case envelope and the camelCase `production_ask.v0.1` data payload
+ *     was the main source of agent-integration pain).
+ *   - It is a SUPERSET. Differentiation between a human reader and an agent is a
+ *     RENDERING concern at the edge, not a forked schema:
+ *       · human projection  → narrative `answer_markdown`, `summary.confidence`
+ *                             as a word, raw ids/anchors hidden.
+ *       · agent projection  → full `evidence_refs` (with `anchor` + `grounding`),
+ *                             `answer_claims` (claim → evidence), structured
+ *                             `next_commands`.
+ *   - Additive evolution only within v1; breaking changes bump the version.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the shape. The backend mirrors
+ * these field names on the wire and the contract tests validate real CLI output
+ * against {@link MODA_INTELLIGENCE_V1_JSON_SCHEMA}.
+ */
+export const INTELLIGENCE_SCHEMA_VERSION = 'moda.intelligence.v1';
+// ───────────────────────────── JSON Schema (draft-07) ─────────────────────────
+const provenanceSchema = { type: 'string', enum: ['measured', 'inferred'] };
+const mutabilitySchema = {
+    type: 'string',
+    enum: ['read', 'write', 'sync', 'unknown'],
+};
+const confidenceSchema = {
+    type: 'string',
+    enum: ['high', 'medium', 'low', 'unknown'],
+};
+/**
+ * Published draft-07 JSON Schema for {@link ModaIntelligenceV1}. This is what
+ * `moda --json-schemas` emits and what the contract tests validate CLI/backend
+ * output against. Keep in lockstep with the interfaces above.
+ */
+export const MODA_INTELLIGENCE_V1_JSON_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: 'moda.intelligence.v1',
+    title: 'Moda Intelligence v1',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schema_version',
+        'generated_at',
+        'command',
+        'source',
+        'degraded',
+        'question',
+        'summary',
+        'answer_markdown',
+        'answer_claims',
+        'findings',
+        'evidence_refs',
+        'next_commands',
+        'warnings',
+    ],
+    properties: {
+        schema_version: { const: 'moda.intelligence.v1' },
+        generated_at: { type: 'string', format: 'date-time' },
+        command: { type: 'string' },
+        source: { type: 'string', enum: ['cloud', 'local_fallback'] },
+        degraded: { type: 'boolean' },
+        question: { type: 'string' },
+        summary: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['text', 'confidence'],
+            properties: { text: { type: 'string' }, confidence: confidenceSchema },
+        },
+        answer_markdown: { type: 'string' },
+        answer_claims: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['text', 'kind', 'status', 'evidence_ref_ids'],
+                properties: {
+                    text: { type: 'string' },
+                    value: { type: 'number' },
+                    kind: { type: 'string', enum: ['percentage', 'count', 'qualitative'] },
+                    status: {
+                        type: 'string',
+                        enum: ['grounded', 'ungrounded', 'unverifiable'],
+                    },
+                    evidence_ref_ids: { type: 'array', items: { type: 'string' } },
+                    matched_path: { type: 'string' },
+                },
+            },
+        },
+        findings: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'title', 'evidence_ref_ids', 'recommended_actions'],
+                properties: {
+                    id: { type: 'string' },
+                    title: { type: 'string' },
+                    severity: {
+                        type: 'string',
+                        enum: ['critical', 'high', 'medium', 'low', 'info'],
+                    },
+                    description: { type: 'string' },
+                    evidence_ref_ids: { type: 'array', items: { type: 'string' } },
+                    recommended_actions: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['id', 'title', 'mutability', 'requires_approval'],
+                            properties: {
+                                id: { type: 'string' },
+                                title: { type: 'string' },
+                                rationale: { type: 'string' },
+                                command: { type: 'string' },
+                                mutability: mutabilitySchema,
+                                requires_approval: { type: 'boolean' },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        evidence_refs: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'kind', 'label', 'grounding'],
+                properties: {
+                    id: { type: 'string' },
+                    kind: { type: 'string' },
+                    label: { type: 'string' },
+                    anchor: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            conversation_id: { type: 'string' },
+                            message_index: { type: 'number' },
+                            run_id: { type: 'string' },
+                            tool_name: { type: 'string' },
+                        },
+                    },
+                    snippet: { type: 'string' },
+                    grounding: provenanceSchema,
+                },
+            },
+        },
+        next_commands: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['command', 'mutability', 'requires_approval'],
+                properties: {
+                    command: { type: 'string' },
+                    purpose: { type: 'string' },
+                    mutability: mutabilitySchema,
+                    requires_approval: { type: 'boolean' },
+                },
+            },
+        },
+        warnings: { type: 'array', items: { type: 'string' } },
+        meta: { type: 'object' },
+    },
+};
+//# sourceMappingURL=intelligence-schema.js.map

package/dist/output.d.ts

@@ -1,7 +1,18 @@
 export type CliOutputMode = 'human' | 'json' | 'agent' | 'agent-stream';
 export declare const AGENT_SCHEMA_VERSION = "moda.agent.v1";
 export declare const AGENT_EVENT_SCHEMA_VERSION = "moda.agent_event.v1";
-export type AgentStatus = 'ok' | 'error';
+/**
+ * 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[]`).
+ * `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 declare const EXIT_OK = 0;
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_DEGRADED = 3;
+export type AgentStatus = 'ok' | 'degraded' | 'error';
 export type AgentConfidence = 'high' | 'medium' | 'low' | 'unknown';
 export interface AgentSummary {
     text: string;
@@ -94,12 +105,24 @@ export interface CliOutput {
     mode: CliOutputMode;
     quiet: boolean;
     writeData(data: unknown, options?: {
-        status?: 'success' | 'error';
+        status?: 'success' | 'degraded' | 'error';
         meta?: Record<string, unknown>;
     } & AgentWriteOptions): void;
     writeEvent(event: Omit<AgentEvent, 'schema_version' | 'command' | 'generated_at'>): void;
 }
+/** Flag-only resolution (default human). Kept for callers that only have flags. */
 export declare function outputModeFromFlags(flags: Record<string, string>): CliOutputMode;
+/**
+ * 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 declare function resolveOutputMode(flags: Record<string, string>, opts?: {
+    isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): CliOutputMode;
 export declare function createCliOutput(options: {
     command: string;
     mode: CliOutputMode;