@skhema/cli 0.3.1

package/dist/lib/api/command-helpers.js

@@ -0,0 +1,77 @@
+import fs from 'fs';
+import { getDefaultWorkspaceId } from '../config-store.js';
+import { UsageError } from './run-command.js';
+/**
+ * Resolve the target workspace for a workspace-scoped command: the explicit
+ * `--workspace` flag wins, else the stored default (`skhema workspace use`).
+ * Throws a {@link UsageError} (exit 2) when neither is set.
+ */
+export function resolveWorkspaceId(flag) {
+    const workspaceId = flag ?? getDefaultWorkspaceId();
+    if (!workspaceId) {
+        throw new UsageError('No workspace. Pass --workspace <id> or set a default with `skhema workspace use <id>`.');
+    }
+    return workspaceId;
+}
+/**
+ * Read a full JSON request payload from `--file <path>` (or `-` for stdin).
+ * Returns `undefined` when no path is given. A malformed file is a usage error.
+ */
+export function readPayloadFile(filePath) {
+    if (!filePath)
+        return undefined;
+    let raw;
+    try {
+        // fd 0 = stdin, so `--file -` reads a piped payload.
+        raw = fs.readFileSync(filePath === '-' ? 0 : filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new UsageError(`Could not read payload file "${filePath}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('expected a JSON object');
+        }
+        return parsed;
+    }
+    catch (err) {
+        throw new UsageError(`Invalid JSON in payload file "${filePath}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Build a request body from an optional `--file` base merged with field flags.
+ * Flag values that are `undefined` are dropped, so explicit flags override the
+ * file and unset flags leave the file's value intact.
+ */
+export function buildBody(base, fields) {
+    const body = { ...(base ?? {}) };
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined)
+            body[key] = value;
+    }
+    return body;
+}
+/** Narrow an unknown value to a plain record for defensive field access. */
+export function asRecord(value) {
+    return value && typeof value === 'object'
+        ? value
+        : {};
+}
+/**
+ * Coerce a list-shaped API response to an array. The gateway wraps collections
+ * under a resource key (`{ workspaces: [...] }`); fall back to the first array
+ * property, or the value itself when it is already an array.
+ */
+export function coerceList(value, key) {
+    if (Array.isArray(value))
+        return value;
+    const record = asRecord(value);
+    if (key && Array.isArray(record[key]))
+        return record[key];
+    for (const v of Object.values(record)) {
+        if (Array.isArray(v))
+            return v;
+    }
+    return [];
+}

package/dist/lib/api/credential-context.d.ts

@@ -0,0 +1,3 @@
+export declare function setApiKeyFlag(value: string | undefined): void;
+export declare function getApiKeyFlag(): string | undefined;
+//# sourceMappingURL=credential-context.d.ts.map

package/dist/lib/api/credential-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-context.d.ts","sourceRoot":"","sources":["../../../src/lib/api/credential-context.ts"],"names":[],"mappings":"AAQA,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAE7D;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD"}

package/dist/lib/api/credential-context.js

@@ -0,0 +1,13 @@
+/**
+ * Holds the value of the global `--api-key` flag for the lifetime of one CLI
+ * invocation. Set once from the root command's `preAction` hook (mirroring
+ * `setGlobalOptions`), then read by `resolveCredential()` as the highest-priority
+ * credential source.
+ */
+let apiKeyFlag;
+export function setApiKeyFlag(value) {
+    apiKeyFlag = value;
+}
+export function getApiKeyFlag() {
+    return apiKeyFlag;
+}

package/dist/lib/api/export-cli.d.ts

@@ -0,0 +1,14 @@
+import type { ExportResult } from './transfer.js';
+/**
+ * Validate export output flags before any API call:
+ * - `--out -` streams raw binary to stdout, which would corrupt the `--json`
+ *   envelope, so the two are mutually exclusive.
+ * - `--out` and `--email` are two different deliveries; pick one.
+ */
+export declare function assertExportOutput(opts: {
+    out?: string;
+    email?: string;
+}): void;
+/** Human summary line for a completed export. */
+export declare function reportExport(result: ExportResult): void;
+//# sourceMappingURL=export-cli.d.ts.map

package/dist/lib/api/export-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-cli.d.ts","sourceRoot":"","sources":["../../../src/lib/api/export-cli.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,GAAG,IAAI,CASP;AAED,iDAAiD;AACjD,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAMvD"}

package/dist/lib/api/export-cli.js

@@ -0,0 +1,26 @@
+import chalk from 'chalk';
+import { getGlobalOptions, log } from '../output.js';
+import { UsageError } from './run-command.js';
+/**
+ * Validate export output flags before any API call:
+ * - `--out -` streams raw binary to stdout, which would corrupt the `--json`
+ *   envelope, so the two are mutually exclusive.
+ * - `--out` and `--email` are two different deliveries; pick one.
+ */
+export function assertExportOutput(opts) {
+    if (opts.out === '-' && getGlobalOptions().json === true) {
+        throw new UsageError('Cannot combine --json with --out - (raw binary to stdout).');
+    }
+    if (opts.email && opts.out) {
+        throw new UsageError('Use either --out or --email, not both.');
+    }
+}
+/** Human summary line for a completed export. */
+export function reportExport(result) {
+    if (result.delivered === 'email') {
+        log(chalk.green(`Emailed ${result.format} export to ${result.recipient}`));
+    }
+    else {
+        log(chalk.green(`Wrote ${result.format} export to ${result.path}`));
+    }
+}

package/dist/lib/api/formats.d.ts

@@ -0,0 +1,12 @@
+/** Single-document export formats (component / strategy). */
+export declare const DOCUMENT_FORMATS: readonly ["pdf", "docx", "md", "json"];
+/** Full-portability workspace export formats. */
+export declare const WORKSPACE_FORMATS: readonly ["xlsx", "csv", "json"];
+export type DocumentFormat = (typeof DOCUMENT_FORMATS)[number];
+export type WorkspaceFormat = (typeof WORKSPACE_FORMATS)[number];
+/**
+ * Validate a `--format` value client-side against the accepted set, so a typo
+ * fails fast with exit 2 rather than a round-trip. Returns the narrowed value.
+ */
+export declare function assertFormat<T extends string>(value: string | undefined, allowed: readonly T[]): T;
+//# sourceMappingURL=formats.d.ts.map

package/dist/lib/api/formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../../../src/lib/api/formats.ts"],"names":[],"mappings":"AAEA,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,wCAAyC,CAAA;AACtE,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,kCAAmC,CAAA;AAEjE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAC9D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEhE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,SAAS,CAAC,EAAE,GACpB,CAAC,CAUH"}

package/dist/lib/api/formats.js

@@ -0,0 +1,18 @@
+import { UsageError } from './run-command.js';
+/** Single-document export formats (component / strategy). */
+export const DOCUMENT_FORMATS = ['pdf', 'docx', 'md', 'json'];
+/** Full-portability workspace export formats. */
+export const WORKSPACE_FORMATS = ['xlsx', 'csv', 'json'];
+/**
+ * Validate a `--format` value client-side against the accepted set, so a typo
+ * fails fast with exit 2 rather than a round-trip. Returns the narrowed value.
+ */
+export function assertFormat(value, allowed) {
+    if (!value) {
+        throw new UsageError(`--format is required (one of ${allowed.join(', ')}).`);
+    }
+    if (!allowed.includes(value)) {
+        throw new UsageError(`Invalid --format "${value}". Expected one of: ${allowed.join(', ')}.`);
+    }
+    return value;
+}

package/dist/lib/api/passthrough.d.ts

@@ -0,0 +1,34 @@
+import type { HttpMethod } from '@skhema/sdk';
+/**
+ * Validate and normalize a method token (case-insensitive) to an
+ * {@link HttpMethod}. Throws {@link UsageError} (exit 2) on anything else.
+ */
+export declare function normalizeMethod(raw: string): HttpMethod;
+/**
+ * Normalize a caller-supplied path to an absolute, `/v1`-prefixed gateway path.
+ *
+ * Accepts `workspaces`, `/workspaces`, `/v1/workspaces`, or a full
+ * `https://api.skhema.com/v1/...` URL whose host matches `apiBaseUrl`. Any other
+ * host is refused (the passthrough only reaches the Skhema gateway). Preserves a
+ * query string already present in the path.
+ */
+export declare function normalizePath(raw: string, apiBaseUrl: string): string;
+/**
+ * Resolve the `--data` argument into a JSON body. Forms:
+ * - `@path` — read JSON from a file (via `readFile`).
+ * - `-` — read JSON from stdin (via `readStdin`).
+ * - anything else — parse the literal as JSON.
+ *
+ * Returns `undefined` when `raw` is undefined. Throws {@link UsageError} on
+ * invalid JSON or a non-object top-level value.
+ */
+export declare function resolveDataBody(raw: string | undefined, io: {
+    readFile: (path: string) => Promise<string>;
+    readStdin: () => Promise<string>;
+}): Promise<Record<string, unknown> | undefined>;
+/**
+ * Parse repeated `--query k=v` tokens into an entry list (preserving repeats and
+ * order). A token missing `=` is a usage error.
+ */
+export declare function parseQueryPairs(raw: string[] | undefined): Array<[string, string]>;
+//# sourceMappingURL=passthrough.d.ts.map

package/dist/lib/api/passthrough.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passthrough.d.ts","sourceRoot":"","sources":["../../../src/lib/api/passthrough.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAW7C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAQvD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAyBrE;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,EAAE,EAAE;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3C,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CACjC,GACA,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CA+B9C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EAAE,GAAG,SAAS,GACxB,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CASzB"}

package/dist/lib/api/passthrough.js

@@ -0,0 +1,106 @@
+import { UsageError } from './run-command.js';
+/** HTTP verbs the raw `skhema api` passthrough accepts. */
+const SUPPORTED_METHODS = [
+    'GET',
+    'POST',
+    'PUT',
+    'DELETE',
+];
+/**
+ * Validate and normalize a method token (case-insensitive) to an
+ * {@link HttpMethod}. Throws {@link UsageError} (exit 2) on anything else.
+ */
+export function normalizeMethod(raw) {
+    const upper = raw.toUpperCase();
+    if (!SUPPORTED_METHODS.includes(upper)) {
+        throw new UsageError(`Unsupported method "${raw}". Use one of: ${SUPPORTED_METHODS.join(', ')}.`);
+    }
+    return upper;
+}
+/**
+ * Normalize a caller-supplied path to an absolute, `/v1`-prefixed gateway path.
+ *
+ * Accepts `workspaces`, `/workspaces`, `/v1/workspaces`, or a full
+ * `https://api.skhema.com/v1/...` URL whose host matches `apiBaseUrl`. Any other
+ * host is refused (the passthrough only reaches the Skhema gateway). Preserves a
+ * query string already present in the path.
+ */
+export function normalizePath(raw, apiBaseUrl) {
+    let pathPart = raw.trim();
+    if (/^https?:\/\//i.test(pathPart)) {
+        let url;
+        try {
+            url = new URL(pathPart);
+        }
+        catch {
+            throw new UsageError(`Invalid URL: ${raw}`);
+        }
+        const expectedHost = new URL(apiBaseUrl).host;
+        if (url.host !== expectedHost) {
+            throw new UsageError(`Refusing to call host "${url.host}". \`skhema api\` only reaches the Skhema gateway (${expectedHost}).`);
+        }
+        pathPart = `${url.pathname}${url.search}`;
+    }
+    if (!pathPart.startsWith('/'))
+        pathPart = `/${pathPart}`;
+    // Leading /v1 is optional in the caller's path; add it when missing.
+    if (!/^\/v1(\/|$|\?)/.test(pathPart)) {
+        pathPart = `/v1${pathPart}`;
+    }
+    return pathPart;
+}
+/**
+ * Resolve the `--data` argument into a JSON body. Forms:
+ * - `@path` — read JSON from a file (via `readFile`).
+ * - `-` — read JSON from stdin (via `readStdin`).
+ * - anything else — parse the literal as JSON.
+ *
+ * Returns `undefined` when `raw` is undefined. Throws {@link UsageError} on
+ * invalid JSON or a non-object top-level value.
+ */
+export async function resolveDataBody(raw, io) {
+    if (raw === undefined)
+        return undefined;
+    let text;
+    if (raw === '-') {
+        text = await io.readStdin();
+    }
+    else if (raw.startsWith('@')) {
+        const path = raw.slice(1);
+        try {
+            text = await io.readFile(path);
+        }
+        catch (err) {
+            throw new UsageError(`Could not read --data file "${path}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    else {
+        text = raw;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new UsageError('--data is not valid JSON.');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new UsageError('--data must be a JSON object.');
+    }
+    return parsed;
+}
+/**
+ * Parse repeated `--query k=v` tokens into an entry list (preserving repeats and
+ * order). A token missing `=` is a usage error.
+ */
+export function parseQueryPairs(raw) {
+    if (!raw || raw.length === 0)
+        return [];
+    return raw.map((pair) => {
+        const eq = pair.indexOf('=');
+        if (eq <= 0) {
+            throw new UsageError(`Invalid --query "${pair}". Expected key=value.`);
+        }
+        return [pair.slice(0, eq), pair.slice(eq + 1)];
+    });
+}

package/dist/lib/api/payload.d.ts

@@ -0,0 +1,16 @@
+import type { RequestBody } from '@skhema/sdk';
+/** Read a file path, or all of stdin when `source` is `-`. */
+export declare function readFileOrStdin(source: string): string;
+/** Parse a JSON object from a `--file` argument (path or `-` for stdin). */
+export declare function parseJsonFile(source: string): RequestBody;
+/**
+ * Build a request body from an optional `--file` base payload overlaid with
+ * explicit field flags (flags win). Used by the create/update verbs so an agent
+ * can hand over a full JSON payload while a human can pass a couple of flags.
+ * Throws when the result is empty (nothing to send).
+ */
+export declare function resolveBody(options: {
+    file?: string;
+    fields?: RequestBody;
+}): RequestBody;
+//# sourceMappingURL=payload.d.ts.map

package/dist/lib/api/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/lib/api/payload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAI9C,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAatD;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAczD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,GAAG,WAAW,CAad"}

package/dist/lib/api/payload.js

@@ -0,0 +1,53 @@
+import fs from 'fs';
+import { UsageError } from './run-command.js';
+/** Read a file path, or all of stdin when `source` is `-`. */
+export function readFileOrStdin(source) {
+    if (source === '-') {
+        try {
+            return fs.readFileSync(0, 'utf-8');
+        }
+        catch {
+            throw new UsageError('Failed to read payload from stdin.');
+        }
+    }
+    try {
+        return fs.readFileSync(source, 'utf-8');
+    }
+    catch {
+        throw new UsageError(`Cannot read payload file: ${source}`);
+    }
+}
+/** Parse a JSON object from a `--file` argument (path or `-` for stdin). */
+export function parseJsonFile(source) {
+    const raw = readFileOrStdin(source);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError(`Payload in ${source === '-' ? 'stdin' : source} is not valid JSON.`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new UsageError('Payload must be a JSON object.');
+    }
+    return parsed;
+}
+/**
+ * Build a request body from an optional `--file` base payload overlaid with
+ * explicit field flags (flags win). Used by the create/update verbs so an agent
+ * can hand over a full JSON payload while a human can pass a couple of flags.
+ * Throws when the result is empty (nothing to send).
+ */
+export function resolveBody(options) {
+    const base = options.file ? parseJsonFile(options.file) : {};
+    const fields = options.fields ?? {};
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    if (Object.keys(merged).length === 0) {
+        throw new UsageError('Nothing to send. Provide field flags or --file <path|-> with a JSON payload.');
+    }
+    return merged;
+}

package/dist/lib/api/run-command.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Deterministic process exit codes. Agents branch on these, so they are a stable
+ * contract (spec §3.3).
+ */
+export declare const ExitCode: {
+    /** Success. */
+    readonly Ok: 0;
+    /** Generic or API error (non-specific 4xx/5xx, unexpected failure). */
+    readonly Error: 1;
+    /** Usage error — bad/missing arguments, resolved before any API call. */
+    readonly Usage: 2;
+    /** No usable credential — the caller must authenticate. */
+    readonly AuthRequired: 3;
+    /** Permission or plan denied (HTTP 403 or 402). */
+    readonly Denied: 4;
+    /** Rate limited (HTTP 429). */
+    readonly RateLimited: 5;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+/** A caller-input error (missing flag, bad value). Maps to {@link ExitCode.Usage}. */
+export declare class UsageError extends Error {
+    readonly code = "usage_error";
+    constructor(message: string);
+}
+/** No credential available. Maps to {@link ExitCode.AuthRequired}. */
+export declare class AuthRequiredError extends Error {
+    readonly code = "auth_required";
+    constructor(message: string);
+}
+/** Stable machine envelope emitted under `--json` (spec §3.3). */
+export interface JsonEnvelope<T = unknown> {
+    ok: boolean;
+    command: string;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        requestId?: string;
+    };
+}
+/** Emit `{ ok: true, command, data }` when `--json` is active. */
+export declare function emitSuccess<T>(command: string, data: T): void;
+/** Emit `{ ok: false, command, error }` when `--json` is active. */
+export declare function emitErrorEnvelope(command: string, error: {
+    code: string;
+    message: string;
+    requestId?: string;
+}): void;
+export interface MappedError {
+    exitCode: ExitCodeValue;
+    error: {
+        code: string;
+        message: string;
+        requestId?: string;
+    };
+}
+/**
+ * Map any thrown value to an exit code + a stable error envelope. Pure and
+ * exported so the mapping is unit-testable without spawning a process.
+ */
+export declare function mapError(err: unknown): MappedError;
+/**
+ * Run a command body with unified error handling. On success, emits the JSON
+ * success envelope (when `--json`) with whatever `fn` returns; human output is
+ * `fn`'s own responsibility. On failure, maps the error to an exit code, emits
+ * the JSON error envelope (or a red line), and exits.
+ */
+export declare function runCommand<T>(command: string, fn: () => Promise<T>): Promise<void>;
+//# sourceMappingURL=run-command.d.ts.map

package/dist/lib/api/run-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-command.d.ts","sourceRoot":"","sources":["../../../src/lib/api/run-command.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB,eAAe;;IAEf,uEAAuE;;IAEvE,yEAAyE;;IAEzE,2DAA2D;;IAE3D,mDAAmD;;IAEnD,+BAA+B;;CAEvB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAA;AAEpE,sFAAsF;AACtF,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,iBAAgB;gBACjB,OAAO,EAAE,MAAM;CAI5B;AAED,sEAAsE;AACtE,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,mBAAkB;gBACnB,OAAO,EAAE,MAAM;CAI5B;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,CAAC,CAAA;IACR,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9D;AAMD,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAK7D;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3D,IAAI,CAKN;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,aAAa,CAAA;IACvB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CA8ClD;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/lib/api/run-command.js

@@ -0,0 +1,127 @@
+import { AuthError, RateLimitedError, SkhemaApiError, WriteLockedError, } from '@skhema/sdk';
+import chalk from 'chalk';
+import { getGlobalOptions } from '../output.js';
+/**
+ * Deterministic process exit codes. Agents branch on these, so they are a stable
+ * contract (spec §3.3).
+ */
+export const ExitCode = {
+    /** Success. */
+    Ok: 0,
+    /** Generic or API error (non-specific 4xx/5xx, unexpected failure). */
+    Error: 1,
+    /** Usage error — bad/missing arguments, resolved before any API call. */
+    Usage: 2,
+    /** No usable credential — the caller must authenticate. */
+    AuthRequired: 3,
+    /** Permission or plan denied (HTTP 403 or 402). */
+    Denied: 4,
+    /** Rate limited (HTTP 429). */
+    RateLimited: 5,
+};
+/** A caller-input error (missing flag, bad value). Maps to {@link ExitCode.Usage}. */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'usage_error';
+        this.name = 'UsageError';
+    }
+}
+/** No credential available. Maps to {@link ExitCode.AuthRequired}. */
+export class AuthRequiredError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'auth_required';
+        this.name = 'AuthRequiredError';
+    }
+}
+function jsonEnabled() {
+    return getGlobalOptions().json === true;
+}
+/** Emit `{ ok: true, command, data }` when `--json` is active. */
+export function emitSuccess(command, data) {
+    if (jsonEnabled()) {
+        const envelope = { ok: true, command, data };
+        console.log(JSON.stringify(envelope, null, 2));
+    }
+}
+/** Emit `{ ok: false, command, error }` when `--json` is active. */
+export function emitErrorEnvelope(command, error) {
+    if (jsonEnabled()) {
+        const envelope = { ok: false, command, error };
+        console.log(JSON.stringify(envelope, null, 2));
+    }
+}
+/**
+ * Map any thrown value to an exit code + a stable error envelope. Pure and
+ * exported so the mapping is unit-testable without spawning a process.
+ */
+export function mapError(err) {
+    // Order matters: subclasses (AuthError/WriteLockedError/RateLimitedError)
+    // are all `instanceof SkhemaApiError`, so check them first.
+    if (err instanceof AuthError) {
+        return {
+            exitCode: ExitCode.AuthRequired,
+            error: { code: err.code, message: err.message, requestId: err.requestId },
+        };
+    }
+    if (err instanceof WriteLockedError) {
+        return {
+            exitCode: ExitCode.Denied,
+            error: { code: err.code, message: err.message, requestId: err.requestId },
+        };
+    }
+    if (err instanceof RateLimitedError) {
+        return {
+            exitCode: ExitCode.RateLimited,
+            error: { code: err.code, message: err.message, requestId: err.requestId },
+        };
+    }
+    if (err instanceof SkhemaApiError) {
+        return {
+            exitCode: err.status === 403 ? ExitCode.Denied : ExitCode.Error,
+            error: { code: err.code, message: err.message, requestId: err.requestId },
+        };
+    }
+    if (err instanceof AuthRequiredError) {
+        return {
+            exitCode: ExitCode.AuthRequired,
+            error: { code: err.code, message: err.message },
+        };
+    }
+    if (err instanceof UsageError) {
+        return {
+            exitCode: ExitCode.Usage,
+            error: { code: err.code, message: err.message },
+        };
+    }
+    return {
+        exitCode: ExitCode.Error,
+        error: {
+            code: 'error',
+            message: err instanceof Error ? err.message : String(err),
+        },
+    };
+}
+/**
+ * Run a command body with unified error handling. On success, emits the JSON
+ * success envelope (when `--json`) with whatever `fn` returns; human output is
+ * `fn`'s own responsibility. On failure, maps the error to an exit code, emits
+ * the JSON error envelope (or a red line), and exits.
+ */
+export async function runCommand(command, fn) {
+    try {
+        const data = await fn();
+        emitSuccess(command, data);
+    }
+    catch (err) {
+        const mapped = mapError(err);
+        if (jsonEnabled()) {
+            emitErrorEnvelope(command, mapped.error);
+        }
+        else {
+            console.error(chalk.red(`Error: ${mapped.error.message}`));
+        }
+        process.exit(mapped.exitCode);
+    }
+}

package/dist/lib/api/scope.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolve the target workspace for a workspace-scoped command: the explicit
+ * `--workspace <id>` flag wins, otherwise the stored default (`skhema workspace
+ * use <id>`). Throws {@link UsageError} (exit 2) when neither is present so the
+ * caller never silently hits the wrong workspace.
+ */
+export declare function resolveWorkspaceId(flag: string | undefined): string;
+//# sourceMappingURL=scope.d.ts.map

package/dist/lib/api/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/lib/api/scope.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CASnE"}

package/dist/lib/api/scope.js

@@ -0,0 +1,16 @@
+import { getDefaultWorkspaceId } from '../config-store.js';
+import { UsageError } from './run-command.js';
+/**
+ * Resolve the target workspace for a workspace-scoped command: the explicit
+ * `--workspace <id>` flag wins, otherwise the stored default (`skhema workspace
+ * use <id>`). Throws {@link UsageError} (exit 2) when neither is present so the
+ * caller never silently hits the wrong workspace.
+ */
+export function resolveWorkspaceId(flag) {
+    const id = flag ?? getDefaultWorkspaceId();
+    if (!id) {
+        throw new UsageError('No workspace specified. Pass --workspace <id> or set a default with ' +
+            '`skhema workspace use <id>`.');
+    }
+    return id;
+}