@ontologie/cli 0.1.0-preview.1

package/dist/output/envelope.schema.d.ts.map

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

package/dist/output/envelope.schema.js

@@ -0,0 +1,256 @@
+/**
+ * Zod runtime lock for CLI JSON Contract — `dataforge.cli.v1`.
+ *
+ * Canonical contract: `sdk/docs/cli-contract.md`
+ * Type definitions: `./types.ts`
+ *
+ * This module provides runtime validation so the contract cannot drift silently
+ * as commands evolve. Validation is invoked from `output/json.ts` before any
+ * envelope is written to stdout.
+ *
+ * Design:
+ *  - Every shape declared in `types.ts` has a matching Zod schema here.
+ *  - The schemas use `z.object(...).strict()` to reject unknown keys (avoids
+ *    silent contract drift via passthrough fields).
+ *  - `EnvelopeSchema` is the single entry point used by `validateEnvelope()`.
+ *  - On mismatch we throw `EnvelopeViolationError` rather than emitting a
+ *    malformed envelope (loud errors > silent fallbacks).
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// SOT primitives — owned by this file (Zod is the source of truth, TS derives)
+// ---------------------------------------------------------------------------
+/**
+ * Schema version literal — bumped on a breaking contract change.
+ * Owned here because `CliMetaSchema` consumes it at module-init via `z.literal`.
+ * Re-exported from `./types.ts` for external consumers.
+ */
+export const CLI_META_SCHEMA_VERSION = 'dataforge.cli.v1';
+/** `req_*`, `local_req_*`, `mock_req_*` — see cli-contract.md §3.1 */
+const RequestIdSchema = z
+    .string()
+    .regex(/^(req|local_req|mock_req)_[a-zA-Z0-9]+$/, {
+    message: 'requestId must match /^(req|local_req|mock_req)_[a-zA-Z0-9]+$/',
+});
+/** Workspace identifier string or null for auth-free commands. */
+const WorkspaceIdSchema = z
+    .string()
+    .min(1)
+    .nullable();
+/**
+ * Canonical environment classifier — see cli-contract.md §3.2.
+ * `CliEnvironment` (TS) is derived from this Zod enum (no manual mirror).
+ */
+const ENVIRONMENT_VALUES = ['local', 'dev', 'staging', 'prod'];
+const EnvironmentBaseSchema = z.enum(ENVIRONMENT_VALUES);
+const EnvironmentSchema = EnvironmentBaseSchema.nullable();
+/**
+ * Like z.unknown() but rejects undefined — ensures the value is
+ * JSON-serializable (null is allowed, undefined is not).
+ */
+const DefinedUnknownSchema = z
+    .unknown()
+    .refine((value) => value !== undefined, {
+    message: 'value must not be undefined (use null for absent values)',
+});
+/** Stable error code enum — see cli-contract-v1.md §4 */
+export const CliErrorCodeSchema = z.enum([
+    'INVALID_USAGE',
+    'AUTHENTICATION_ERROR',
+    'AUTHORIZATION_ERROR',
+    'POLICY_VIOLATION',
+    'WRITE_POLICY_VIOLATION',
+    'VALIDATION_ERROR',
+    'CAPABILITY_DRIFT_ERROR',
+    'SCHEMA_DRIFT_ERROR',
+    'QUOTA_EXCEEDED',
+    'BUDGET_EXCEEDED',
+    'RATE_LIMITED',
+    'CONFLICT_ERROR',
+    'PLAN_POLICY_MISMATCH',
+    'SOURCE_OF_TRUTH_CONFLICT',
+    'PLAN_CONTEXT_MISMATCH',
+    'PRECONDITION_FAILED',
+    'NETWORK_ERROR',
+    'TIMEOUT_ERROR',
+    'RUNTIME_UNAVAILABLE',
+    'NOT_FOUND',
+    'UNAVAILABLE',
+    'INTERNAL_ERROR',
+    'CONFIRMATION_REQUIRED',
+    'CONFIGURATION_ERROR',
+]);
+// ---------------------------------------------------------------------------
+// Composed schemas
+// ---------------------------------------------------------------------------
+export const CliWarningSchema = z
+    .object({
+    code: z.string().min(1),
+    message: z.string().min(1),
+    severity: z.enum(['info', 'warning', 'deprecated', 'danger']),
+    // Non-empty string. Either an absolute URL (`https://docs.dataforge.dev/...`)
+    // or a relative one (`/docs/migration`) — the contract in `cli-contract.md`
+    // does not require absolute URLs, so we keep this matching the TypeScript
+    // interface (`docsUrl?: string`) and avoid runtime rejection of valid
+    // relative paths.
+    docsUrl: z.string().min(1).optional(),
+})
+    .strict();
+export const CliMetaSchema = z
+    .object({
+    schemaVersion: z.literal(CLI_META_SCHEMA_VERSION),
+    command: z.string().min(1),
+    requestId: RequestIdSchema,
+    workspaceId: WorkspaceIdSchema,
+    environment: EnvironmentSchema,
+    manifestVersion: z.string().nullable(),
+    costUnits: z.number().int().min(0),
+    estimatedCostUnits: z.number().int().min(0).nullable(),
+    quotaRemaining: z.number().int().min(0).nullable(),
+    rateLimitRemaining: z.number().int().min(0).nullable(),
+    warnings: z.array(CliWarningSchema),
+})
+    .strict();
+export const CliErrorSchema = z
+    .object({
+    code: CliErrorCodeSchema,
+    message: z.string().min(1),
+    details: DefinedUnknownSchema,
+    retryable: z.boolean(),
+    correlationId: z.string().min(1),
+})
+    .strict();
+export const CliPageSchema = z
+    .object({
+    limit: z.number().int().min(0),
+    nextCursor: z.string().nullable(),
+    hasMore: z.boolean(),
+})
+    .strict();
+/**
+ * Top-level envelope schema. Enforces the cli-contract.md §2 invariants:
+ *  - `ok === true` → `data !== null`, `error === null`
+ *  - `ok === false` → `data === null`, `error !== null`
+ */
+export const EnvelopeSchema = z
+    .object({
+    ok: z.boolean(),
+    data: DefinedUnknownSchema.nullable(),
+    error: CliErrorSchema.nullable(),
+    page: CliPageSchema.nullable(),
+    meta: CliMetaSchema,
+})
+    .strict()
+    .superRefine((env, ctx) => {
+    if (env.ok === true) {
+        if (env.data === null) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['data'],
+                message: 'envelope.ok=true requires data !== null',
+            });
+        }
+        if (env.error !== null) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['error'],
+                message: 'envelope.ok=true requires error === null',
+            });
+        }
+    }
+    else {
+        if (env.data !== null) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['data'],
+                message: 'envelope.ok=false requires data === null',
+            });
+        }
+        if (env.error === null) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['error'],
+                message: 'envelope.ok=false requires error !== null',
+            });
+        }
+    }
+});
+// ---------------------------------------------------------------------------
+// JSONL event schemas (J1 — dev-mode validation for JSONL output)
+// ---------------------------------------------------------------------------
+export const JsonlStartedEventSchema = z.object({
+    type: z.literal('started'), meta: CliMetaSchema, total: z.number().nullable()
+}).strict();
+export const JsonlItemEventSchema = z.object({
+    type: z.literal('item'), data: DefinedUnknownSchema
+}).strict();
+export const JsonlCompletedEventSchema = z.object({
+    type: z.literal('completed'), meta: CliMetaSchema, summary: z.record(z.string(), z.unknown())
+}).strict();
+export const JsonlErrorEventSchema = z.object({
+    type: z.literal('error'), error: CliErrorSchema
+}).strict();
+export const JsonlProgressEventSchema = z.object({
+    type: z.literal('progress'),
+    current: z.number().int().min(0),
+    total: z.number().int().min(0).nullable(),
+    message: z.string(),
+}).strict();
+export const JsonlWarningEventSchema = z.object({
+    type: z.literal('warning'),
+    warning: CliWarningSchema,
+}).strict();
+export const JsonlEventSchema = z.discriminatedUnion('type', [
+    JsonlStartedEventSchema,
+    JsonlItemEventSchema,
+    JsonlCompletedEventSchema,
+    JsonlErrorEventSchema,
+    JsonlProgressEventSchema,
+    JsonlWarningEventSchema,
+]);
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when an envelope does not conform to `dataforge.cli.v1`. Surfaces
+ * the Zod issue list so the offending field/value is visible.
+ *
+ * Design choice (loud errors, no silent fallback):
+ *  - In `NODE_ENV !== 'production'` we throw immediately.
+ *  - In production we log to stderr and emit a synthesized error envelope
+ *    (handled by the caller in `output/json.ts`).
+ */
+export class EnvelopeViolationError extends Error {
+    issues;
+    constructor(issues) {
+        const summary = issues
+            .map((iss) => `${iss.path.join('.') || '<root>'}: ${iss.message}`)
+            .join('; ');
+        super(`CLI envelope violates dataforge.cli.v1 contract: ${summary}`);
+        this.name = 'EnvelopeViolationError';
+        this.issues = issues;
+    }
+}
+/**
+ * Parse + assert. Returns the envelope unchanged on success. Throws
+ * `EnvelopeViolationError` on contract violation.
+ */
+export function assertEnvelope(value) {
+    const parsed = EnvelopeSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new EnvelopeViolationError(parsed.error.issues);
+    }
+    return parsed.data;
+}
+/**
+ * Non-throwing variant. Returns `{ ok: true, value }` or `{ ok: false, issues }`.
+ * Use in production paths where we prefer to log + emit a synthesized error
+ * envelope rather than crash the CLI.
+ */
+export function tryAssertEnvelope(value) {
+    const parsed = EnvelopeSchema.safeParse(value);
+    if (!parsed.success)
+        return { ok: false, issues: parsed.error.issues };
+    return { ok: true, value: parsed.data };
+}
+//# sourceMappingURL=envelope.schema.js.map

package/dist/output/envelope.schema.js.map

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

package/dist/output/errors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * CLI error classification, structured output, and exit code resolution.
+ *
+ * Canonical reference: sdk/docs/cli-contract.md (Section 7)
+ */
+import type { CliError, CliErrorCode, CliMeta, CliEnvelope } from './types.js';
+interface ClassifiedError {
+    code: CliErrorCode;
+    message: string;
+    details: unknown;
+}
+/**
+ * Classify a caught error into a structured CliErrorCode.
+ * Replaces the string-matching in shared.ts and cli.ts.
+ */
+declare function redactSecrets(msg: string): string;
+export { redactSecrets };
+/**
+ * Thrown for user-caused errors (bad arguments, invalid input values).
+ * classifyError maps these to INVALID_USAGE.
+ */
+export declare class CliUsageError extends Error {
+    readonly cliCode: "INVALID_USAGE";
+    readonly details: unknown;
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Thrown when a precondition is not met (file exists, breaking changes, etc).
+ * classifyError maps these to PRECONDITION_FAILED.
+ */
+export declare class CliPreconditionError extends Error {
+    readonly cliCode: CliErrorCode;
+    readonly details: unknown;
+    constructor(message: string, details?: unknown, code?: CliErrorCode);
+}
+/**
+ * Recursively redact secrets from any value tree.
+ * Handles strings, arrays, and plain objects. Detects circular references.
+ */
+export declare function redactSecretsDeep(value: unknown, seen?: WeakSet<object>): unknown;
+export declare function classifyError(err: unknown): ClassifiedError;
+/**
+ * Build a CliError from a classified error and optional request context.
+ */
+export declare function buildCliError(classified: ClassifiedError, correlationId?: string): CliError;
+/**
+ * Build a complete error envelope.
+ */
+export declare function buildErrorEnvelope(error: CliError, meta: CliMeta): CliEnvelope<never>;
+/**
+ * Get the process exit code for an error code.
+ */
+export declare function getExitCode(code: CliErrorCode): number;
+/**
+ * Handle a CLI error: classify, format as JSON or stderr text, and exit.
+ */
+export declare function handleCliError(err: unknown, meta: CliMeta | null, format: 'json' | 'jsonl' | 'text'): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/output/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/output/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAqB,MAAM,YAAY,CAAC;AASlG,UAAU,eAAe;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAqED;;;GAGG;AAEH,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK1C;AAED,OAAO,EAAE,aAAa,EAAE,CAAC;AAMzB;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,OAAO,EAAG,eAAe,CAAU;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAK/C;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,GAAE,YAAoC;CAM3F;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,kBAAwB,GAAG,OAAO,CAsBvF;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CAmG3D;AAMD;;GAEG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,eAAe,EAC3B,aAAa,CAAC,EAAE,MAAM,GACrB,QAAQ,CAQV;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAQrF;AAMD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEtD;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,OAAO,GAAG,IAAI,EACpB,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAChC,KAAK,CAiCP"}

package/dist/output/errors.js

@@ -0,0 +1,339 @@
+/**
+ * CLI error classification, structured output, and exit code resolution.
+ *
+ * Canonical reference: sdk/docs/cli-contract.md (Section 7)
+ */
+import { ERROR_EXIT_MAP, isRetryable, generateRequestId } from './types.js';
+import { outputJsonlError } from './json.js';
+import { extractFsCode } from '../schema/helpers.js';
+// ---------------------------------------------------------------------------
+// Plan error code → CLI error code mapping
+// ---------------------------------------------------------------------------
+const PLAN_ERROR_TO_CLI = {
+    PLAN_NOT_FOUND: 'NOT_FOUND',
+    PLAN_EXPIRED: 'CONFLICT_ERROR',
+    PLAN_ALREADY_APPLIED: 'CONFLICT_ERROR',
+    PLAN_REVOKED: 'CONFLICT_ERROR',
+    PLAN_HASH_MISMATCH: 'VALIDATION_ERROR',
+    PLAN_SIGNATURE_INVALID: 'VALIDATION_ERROR',
+    PLAN_BODY_HASH_MISMATCH: 'VALIDATION_ERROR',
+    PLAN_WORKSPACE_MISMATCH: 'AUTHORIZATION_ERROR',
+    PLAN_ACTOR_MISMATCH: 'AUTHORIZATION_ERROR',
+    PLAN_POLICY_BLOCKED: 'POLICY_VIOLATION',
+    PLAN_WRITE_POLICY_VIOLATION: 'WRITE_POLICY_VIOLATION',
+    SOURCE_OF_TRUTH_CONFLICT: 'SOURCE_OF_TRUTH_CONFLICT',
+    PLAN_RISK_NOT_ACKNOWLEDGED: 'CONFIRMATION_REQUIRED',
+    PLAN_CONFIRMATION_REQUIRED: 'CONFIRMATION_REQUIRED',
+    PLAN_SCHEMA_VERSION_MISMATCH: 'PLAN_CONTEXT_MISMATCH',
+    PLAN_ACTION_VERSION_MISMATCH: 'PLAN_CONTEXT_MISMATCH',
+    PLAN_POLICY_MISMATCH: 'PLAN_POLICY_MISMATCH',
+    PLAN_DEPENDENCY_VERSION_MISMATCH: 'CONFLICT_ERROR',
+    PLAN_TARGET_VERSION_CONFLICT: 'CONFLICT_ERROR',
+    PLAN_EXPECTED_ABSENT_CONFLICT: 'CONFLICT_ERROR',
+    PLAN_IDEMPOTENCY_CONFLICT: 'CONFLICT_ERROR',
+    PLAN_QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',
+    PLAN_APPLY_FAILED: 'INTERNAL_ERROR',
+    PLAN_OPERATION_MISMATCH: 'INVALID_USAGE',
+    APPLY_PLAN_INPUT_NOT_ALLOWED: 'INVALID_USAGE',
+    PLAN_TARGET_NOT_FOUND: 'NOT_FOUND',
+    PLAN_AUTHORIZATION_CHANGED: 'AUTHORIZATION_ERROR',
+    PLAN_INPUT_ARTIFACT_MISMATCH: 'VALIDATION_ERROR',
+    PLAN_LOCAL_SCHEMA_MISMATCH: 'PLAN_CONTEXT_MISMATCH',
+    PLAN_INTERNAL_ERROR: 'INTERNAL_ERROR',
+    PLAN_EXECUTION_MODE_MISSING: 'VALIDATION_ERROR',
+    PLAN_EXECUTION_MODE_INVALID: 'VALIDATION_ERROR',
+    PLAN_EXECUTION_MODE_MISMATCH: 'CONFLICT_ERROR',
+    PLAN_EXECUTION_MODE_NOT_SUPPORTED: 'VALIDATION_ERROR',
+};
+function extractPlanErrorCode(err) {
+    if (!err || typeof err !== 'object')
+        return null;
+    // Check err.body.code or err.data.code (API response patterns)
+    for (const prop of ['body', 'data', 'response']) {
+        const container = err[prop];
+        if (container && typeof container === 'object') {
+            const code = container.code;
+            if (typeof code === 'string' && code in PLAN_ERROR_TO_CLI)
+                return code;
+            // Nested: err.response.data.code
+            const innerData = container.data;
+            if (innerData && typeof innerData === 'object') {
+                const innerCode = innerData.code;
+                if (typeof innerCode === 'string' && innerCode in PLAN_ERROR_TO_CLI)
+                    return innerCode;
+            }
+        }
+    }
+    // Direct code property
+    const directCode = err.code;
+    if (typeof directCode === 'string' && directCode in PLAN_ERROR_TO_CLI)
+        return directCode;
+    // Check error message for PLAN_* codes
+    const message = err instanceof Error ? err.message : String(err);
+    const match = message.match(/\b(PLAN_[A-Z_]+|APPLY_PLAN_[A-Z_]+)\b/);
+    if (match && match[1] in PLAN_ERROR_TO_CLI)
+        return match[1];
+    return null;
+}
+/**
+ * Classify a caught error into a structured CliErrorCode.
+ * Replaces the string-matching in shared.ts and cli.ts.
+ */
+// E2: Redact secrets from error messages to prevent API key / token leakage
+function redactSecrets(msg) {
+    return msg
+        .replace(/\b(df_[a-zA-Z0-9]{6,})\b/g, '[REDACTED:api_key]')
+        .replace(/Bearer\s+[a-zA-Z0-9._-]+/gi, 'Bearer [REDACTED]')
+        .replace(/([a-zA-Z0-9_-]*(?:key|token|secret|password)[a-zA-Z0-9_-]*)\s*[=:]\s*\S+/gi, '$1=[REDACTED]');
+}
+export { redactSecrets };
+// ---------------------------------------------------------------------------
+// Typed CLI error classes (thrown by commands, caught by classifyError)
+// ---------------------------------------------------------------------------
+/**
+ * Thrown for user-caused errors (bad arguments, invalid input values).
+ * classifyError maps these to INVALID_USAGE.
+ */
+export class CliUsageError extends Error {
+    cliCode = 'INVALID_USAGE';
+    details;
+    constructor(message, details) {
+        super(message);
+        this.name = 'CliUsageError';
+        this.details = details ?? null;
+    }
+}
+/**
+ * Thrown when a precondition is not met (file exists, breaking changes, etc).
+ * classifyError maps these to PRECONDITION_FAILED.
+ */
+export class CliPreconditionError extends Error {
+    cliCode;
+    details;
+    constructor(message, details, code = 'PRECONDITION_FAILED') {
+        super(message);
+        this.name = 'CliPreconditionError';
+        this.cliCode = code;
+        this.details = details ?? null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Deep secret redaction (recursive)
+// ---------------------------------------------------------------------------
+/**
+ * Recursively redact secrets from any value tree.
+ * Handles strings, arrays, and plain objects. Detects circular references.
+ */
+export function redactSecretsDeep(value, seen = new WeakSet()) {
+    if (typeof value === 'string')
+        return redactSecrets(value);
+    if (value === null || value === undefined || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSecretsDeep(item, seen));
+    }
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (/key|token|secret|password|authorization/i.test(key)) {
+            out[key] = '[REDACTED]';
+        }
+        else {
+            out[key] = redactSecretsDeep(child, seen);
+        }
+    }
+    return out;
+}
+export function classifyError(err) {
+    const message = redactSecrets(err instanceof Error ? err.message : String(err));
+    // Plan-specific error codes (highest priority — preserves PLAN_* detail)
+    const planCode = extractPlanErrorCode(err);
+    if (planCode) {
+        return { code: PLAN_ERROR_TO_CLI[planCode], message: `[${planCode}] ${message}`, details: { planErrorCode: planCode } };
+    }
+    // Typed CLI error classes (CliUsageError, CliPreconditionError)
+    if (err &&
+        typeof err === 'object' &&
+        'cliCode' in err &&
+        typeof err.cliCode === 'string') {
+        const code = err.cliCode;
+        const details = 'details' in err ? err.details : null;
+        return { code, message, details };
+    }
+    const statusCode = extractStatusCode(err);
+    // Status-code based classification (most reliable)
+    if (statusCode !== null) {
+        switch (statusCode) {
+            case 400: return { code: 'VALIDATION_ERROR', message, details: null };
+            case 401: return { code: 'AUTHENTICATION_ERROR', message, details: null };
+            case 403: return { code: 'AUTHORIZATION_ERROR', message, details: null };
+            case 404: return { code: 'NOT_FOUND', message, details: null };
+            case 409: return { code: 'CONFLICT_ERROR', message, details: null };
+            case 412: return { code: 'PRECONDITION_FAILED', message, details: null };
+            case 422: return { code: 'VALIDATION_ERROR', message, details: null };
+            case 429: return { code: 'RATE_LIMITED', message, details: null };
+            case 503: return { code: 'UNAVAILABLE', message, details: null };
+        }
+        if (statusCode >= 500)
+            return { code: 'INTERNAL_ERROR', message, details: null };
+    }
+    // String-based fallback classification
+    if (/\b(ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|fetch failed)\b/i.test(message)) {
+        return { code: 'NETWORK_ERROR', message, details: null };
+    }
+    if (/\b(ETIMEDOUT|timeout|timed?\s*out)\b/i.test(message)) {
+        return { code: 'TIMEOUT_ERROR', message, details: null };
+    }
+    if (/\b(401|Unauthorized|Authentication)\b/i.test(message)) {
+        return { code: 'AUTHENTICATION_ERROR', message, details: null };
+    }
+    if (/\b(403|Forbidden)\b/i.test(message)) {
+        return { code: 'AUTHORIZATION_ERROR', message, details: null };
+    }
+    if (/\b(404|Not Found)\b/i.test(message)) {
+        return { code: 'NOT_FOUND', message, details: null };
+    }
+    if (/\b(409|Conflict)\b/i.test(message)) {
+        return { code: 'CONFLICT_ERROR', message, details: null };
+    }
+    if (/\b(422|Validation)\b/i.test(message)) {
+        return { code: 'VALIDATION_ERROR', message, details: null };
+    }
+    if (/\b(429|Rate.?Limit|Too Many Requests)\b/i.test(message)) {
+        return { code: 'RATE_LIMITED', message, details: null };
+    }
+    if (/\b(quota|limit exceeded)\b/i.test(message)) {
+        return { code: 'QUOTA_EXCEEDED', message, details: null };
+    }
+    if (/\bschema.?drift\b/i.test(message)) {
+        return { code: 'SCHEMA_DRIFT_ERROR', message, details: null };
+    }
+    if (/\bwrite.?policy\b/i.test(message)) {
+        return { code: 'WRITE_POLICY_VIOLATION', message, details: null };
+    }
+    if (/\bpolicy.?violation\b/i.test(message)) {
+        return { code: 'POLICY_VIOLATION', message, details: null };
+    }
+    if (/\bbudget.?exceeded\b/i.test(message)) {
+        return { code: 'BUDGET_EXCEEDED', message, details: null };
+    }
+    if (/\bruntime.?unavailable\b/i.test(message)) {
+        return { code: 'RUNTIME_UNAVAILABLE', message, details: null };
+    }
+    // Filesystem errors
+    const fsCode = extractFsCode(err);
+    if (fsCode) {
+        switch (fsCode) {
+            case 'ENOENT':
+                return { code: 'NOT_FOUND', message, details: { fsCode } };
+            case 'EACCES':
+            case 'EPERM':
+                return { code: 'AUTHORIZATION_ERROR', message, details: { fsCode } };
+            case 'EISDIR':
+            case 'ENOTDIR':
+                return { code: 'INVALID_USAGE', message, details: { fsCode } };
+        }
+    }
+    return { code: 'INTERNAL_ERROR', message, details: null };
+}
+// ---------------------------------------------------------------------------
+// Error envelope builders
+// ---------------------------------------------------------------------------
+/**
+ * Build a CliError from a classified error and optional request context.
+ */
+export function buildCliError(classified, correlationId) {
+    return {
+        code: classified.code,
+        message: redactSecrets(classified.message),
+        details: redactSecretsDeep(classified.details),
+        retryable: isRetryable(classified.code),
+        correlationId: correlationId ?? generateRequestId(),
+    };
+}
+/**
+ * Build a complete error envelope.
+ */
+export function buildErrorEnvelope(error, meta) {
+    return {
+        ok: false,
+        data: null,
+        error,
+        page: null,
+        meta,
+    };
+}
+// ---------------------------------------------------------------------------
+// Exit code resolution
+// ---------------------------------------------------------------------------
+/**
+ * Get the process exit code for an error code.
+ */
+export function getExitCode(code) {
+    return ERROR_EXIT_MAP[code];
+}
+// ---------------------------------------------------------------------------
+// CLI error handler
+// ---------------------------------------------------------------------------
+/**
+ * Handle a CLI error: classify, format as JSON or stderr text, and exit.
+ */
+export function handleCliError(err, meta, format) {
+    const classified = classifyError(err);
+    const correlationId = meta?.requestId ?? generateRequestId();
+    const cliError = buildCliError(classified, correlationId);
+    const exitCode = getExitCode(classified.code);
+    // Build fallback meta when none is provided (e.g. error before API call)
+    const effectiveMeta = meta ?? {
+        schemaVersion: 'dataforge.cli.v1',
+        command: 'unknown',
+        requestId: correlationId,
+        workspaceId: null,
+        environment: null,
+        manifestVersion: null,
+        costUnits: 0,
+        estimatedCostUnits: null,
+        quotaRemaining: null,
+        rateLimitRemaining: null,
+        warnings: [],
+    };
+    if (format === 'json') {
+        const envelope = buildErrorEnvelope(cliError, effectiveMeta);
+        process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+    }
+    else if (format === 'jsonl') {
+        const started = { type: 'started', meta: effectiveMeta, total: null };
+        process.stdout.write(JSON.stringify(started) + '\n');
+        outputJsonlError(cliError);
+    }
+    else {
+        process.stderr.write(`Error [${classified.code}]: ${classified.message}\n`);
+    }
+    process.exit(exitCode);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractStatusCode(err) {
+    if (err && typeof err === 'object') {
+        // Axios-style: err.response.status
+        const response = err.response;
+        if (response && typeof response === 'object') {
+            const status = response.status;
+            if (typeof status === 'number')
+                return status;
+        }
+        // Direct status property
+        const status = err.status;
+        if (typeof status === 'number')
+            return status;
+        // statusCode property
+        const statusCode = err.statusCode;
+        if (typeof statusCode === 'number')
+            return statusCode;
+    }
+    return null;
+}
+//# sourceMappingURL=errors.js.map