@cargo-ai/cdk 1.0.3 → 1.0.5

package/build/src/cli/commands/types.js

@@ -0,0 +1,385 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { handleApiCall, info, success } from "../io.js";
+import { printJsonSchemaInput, printJsonSchemaType } from "./inputTypes.js";
+// Composite natives surfaced via dedicated SDK syntax / scope helpers —
+// excluded so we don't double-register them. Mirrors the codegen exclusion
+// list in `packages/workflow-sdk/scripts/generateNativeIntegration.ts`
+// (everything in the `logic` category gets dedicated syntax instead of
+// going through `native.<slug>`).
+const COMPOSITE_NATIVE = new Set([
+    "start",
+    "end",
+    "agent",
+    "balance",
+    "branch",
+    "delay",
+    "filter",
+    "group",
+    "humanReview",
+    "memory",
+    "split",
+    "switch",
+    "tool",
+    "variables",
+]);
+// Native actions the SDK already ships typed declarations + registrations
+// for (platform-level, identical in every workspace) — skipped so the
+// synced `.d.ts` doesn't redeclare `Native` properties with conflicting
+// (looser) types. Source of truth lives in
+// `packages/workflow-sdk/src/native/manifest.generated.ts`.
+const BUNDLED_NATIVE = new Set([
+    "note",
+    "python",
+    "scoring",
+    "script",
+]);
+export function registerTypesCommand(parent, getApi) {
+    parent
+        .command("types")
+        .description("Generate per-workspace TypeScript types for the Cargo CDK — typed defineConnector/defineModel config + integration actions in workflow bodies")
+        .option("--dir <path>", "Repo root the generated files are written into (default: cwd)")
+        .option("--out <dir>", "Output subdirectory for generated files (default: .cargo-ai)", ".cargo-ai")
+        .action(async (opts) => {
+        const api = getApi();
+        // Match the other `cdk` commands: `--dir` selects the repo root, and the
+        // generated `.cargo-ai` lands there (not wherever the CLI happens to run).
+        if (opts.dir !== undefined)
+            process.chdir(opts.dir);
+        const baseDir = process.cwd();
+        const outDir = resolve(baseDir, opts.out);
+        info(`Fetching workspace surface…`);
+        const payload = await fetchWorkspaceSurface(api);
+        mkdirSync(outDir, { recursive: true });
+        const typesPath = resolve(outDir, "cargo-types.d.ts");
+        writeFileSync(typesPath, renderTypes(payload));
+        success(`Wrote ${relativeToBase(baseDir, typesPath)}`);
+        const eagerPath = resolve(outDir, "cargo-register.ts");
+        writeFileSync(eagerPath, renderEagerRegistration(payload));
+        success(`Wrote ${relativeToBase(baseDir, eagerPath)}`);
+        info(``);
+        info([
+            `Next steps:`,
+            `  1. Add "${relativeToBase(baseDir, outDir)}/**/*.d.ts" to your tsconfig`,
+            `     include so the types are picked up (a bare dot-dir path is ignored by`,
+            `     TypeScript). Enables typed defineConnector/defineModel config.`,
+            `  2. To also type integration actions inside workflow bodies, add`,
+            `     \`import "./${relativeToBase(baseDir, eagerPath).replace(/\.ts$/, ".js")}";\``,
+            `     to your entry file so the workspace's integrations register at runtime.`,
+        ].join("\n"));
+        info(``);
+        const extractorCount = payload.extractorConfigs.reduce((n, e) => n + e.extractors.length, 0);
+        info(`Typed ${String(payload.connectorConfigs.length)} connector config(s), ${String(extractorCount)} extractor config(s), ${String(payload.integrations.length)} integration(s), ${String(payload.native.length)} native action(s).`);
+    });
+}
+async function fetchWorkspaceSurface(api) {
+    const integrationsResult = await handleApiCall(() => api.connection.integration.list({}));
+    const nativeIntegrationResult = await handleApiCall(() => api.connection.nativeIntegration.get());
+    const rawIntegrations = integrationsResult.integrations;
+    const integrations = collectIntegrations(rawIntegrations);
+    const native = collectNative(nativeIntegrationResult.nativeIntegration.actions);
+    const connectorConfigs = collectConnectorConfigs(rawIntegrations);
+    const extractorConfigs = collectExtractorConfigs(rawIntegrations);
+    return { integrations, native, connectorConfigs, extractorConfigs };
+}
+// integrationSlug → connector config type. Skips integrations whose schema
+// prints as a bare record (no typing gained — the builder already falls back to
+// that), keeping the generated file to connectors that actually add types.
+function collectConnectorConfigs(integrations) {
+    const out = [];
+    for (const integration of integrations) {
+        const schema = integration.connector?.config?.schema;
+        if (schema === undefined)
+            continue;
+        const typeSrc = printJsonSchemaType(schema);
+        if (typeSrc === "Record<string, unknown>")
+            continue;
+        out.push({
+            slug: integration.slug,
+            name: trimOrUndefined(integration.name),
+            typeSrc,
+        });
+    }
+    out.sort((a, b) => a.slug.localeCompare(b.slug));
+    return out;
+}
+// integrationSlug → its extractors' config types. Skips extractors whose schema
+// prints as a bare record, and integrations left with none.
+function collectExtractorConfigs(integrations) {
+    const out = [];
+    for (const integration of integrations) {
+        const extractors = [];
+        for (const [slug, extractor] of Object.entries(integration.extractors ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+            const schema = extractor.config?.schema;
+            if (schema === undefined)
+                continue;
+            const typeSrc = printJsonSchemaType(schema);
+            if (typeSrc === "Record<string, unknown>")
+                continue;
+            extractors.push({ slug, typeSrc });
+        }
+        if (extractors.length === 0)
+            continue;
+        out.push({ integrationSlug: integration.slug, extractors });
+    }
+    out.sort((a, b) => a.integrationSlug.localeCompare(b.integrationSlug));
+    return out;
+}
+function collectIntegrations(integrations) {
+    const out = [];
+    for (const integration of integrations) {
+        const actionEntries = Object.entries(integration.actions ?? {}).sort(([a], [b]) => a.localeCompare(b));
+        if (actionEntries.length === 0)
+            continue;
+        const actions = actionEntries.map(([slug, raw]) => {
+            const meta = raw;
+            return {
+                slug,
+                name: trimOrUndefined(meta.name),
+                description: trimOrUndefined(meta.description),
+                inputTypeSrc: printJsonSchemaInput(meta.config?.schema),
+            };
+        });
+        out.push({
+            slug: integration.slug,
+            name: trimOrUndefined(integration.name),
+            description: trimOrUndefined(integration.description),
+            actions,
+        });
+    }
+    out.sort((a, b) => a.slug.localeCompare(b.slug));
+    return out;
+}
+function collectNative(actions) {
+    const out = [];
+    for (const [slug, meta] of Object.entries(actions)) {
+        if (COMPOSITE_NATIVE.has(slug))
+            continue;
+        if (BUNDLED_NATIVE.has(slug))
+            continue;
+        const name = meta.name.length > 0 ? meta.name : slug;
+        out.push({
+            slug,
+            name,
+            description: trimOrUndefined(meta.description),
+        });
+    }
+    out.sort((a, b) => a.slug.localeCompare(b.slug));
+    return out;
+}
+function trimOrUndefined(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+const GENERATED_AT = new Date().toISOString();
+const HEADER = `// THIS FILE IS GENERATED by \`cargo-ai cdk types\`. Do not edit by hand.
+// Re-run the command to refresh after adding/removing workspace integrations
+// or connectors.
+// Last regenerated: ${GENERATED_AT}
+
+`;
+function renderTypes(payload) {
+    const blocks = [];
+    // ── @cargo-ai/cdk — typed define* config (connector + extractor schemas) ──
+    const cdkLines = [];
+    if (payload.connectorConfigs.length > 0) {
+        cdkLines.push(`  interface ConnectorConfigs {`);
+        for (const c of payload.connectorConfigs) {
+            const doc = formatJsDoc({ name: c.name ?? c.slug, updatedAt: GENERATED_AT }, "    ");
+            if (doc !== "")
+                cdkLines.push(doc.trimEnd());
+            cdkLines.push(`    ${jsonKey(c.slug)}: ${c.typeSrc};`);
+        }
+        cdkLines.push(`  }`);
+    }
+    if (payload.extractorConfigs.length > 0) {
+        cdkLines.push(`  interface ExtractorConfigs {`);
+        for (const e of payload.extractorConfigs) {
+            cdkLines.push(`    ${jsonKey(e.integrationSlug)}: {`);
+            for (const x of e.extractors) {
+                cdkLines.push(`      ${jsonKey(x.slug)}: ${x.typeSrc};`);
+            }
+            cdkLines.push(`    };`);
+        }
+        cdkLines.push(`  }`);
+    }
+    if (cdkLines.length > 0) {
+        blocks.push([`declare module "@cargo-ai/cdk" {`, ...cdkLines, `}`].join("\n"));
+    }
+    // ── @cargo-ai/workflow-sdk — integration actions + natives (workflow bodies) ──
+    const wfLines = [];
+    if (payload.integrations.length > 0) {
+        wfLines.push(`  interface Integrations {`);
+        for (const c of payload.integrations) {
+            const intDoc = formatJsDoc({
+                name: c.name ?? c.slug,
+                description: c.description,
+                updatedAt: GENERATED_AT,
+            }, "    ");
+            if (intDoc !== "")
+                wfLines.push(intDoc.trimEnd());
+            wfLines.push(`    ${jsonKey(c.slug)}: {`);
+            for (const action of c.actions) {
+                const actionDoc = formatJsDoc({
+                    name: action.name,
+                    description: action.description,
+                    category: c.slug,
+                    updatedAt: GENERATED_AT,
+                }, "      ");
+                if (actionDoc !== "")
+                    wfLines.push(actionDoc.trimEnd());
+                wfLines.push(`      ${jsonKey(action.slug)}: IntegrationAction<${action.inputTypeSrc}, Record<string, unknown>>;`);
+            }
+            wfLines.push(`    };`);
+        }
+        wfLines.push(`  }`);
+    }
+    if (payload.native.length > 0) {
+        wfLines.push(`  interface Native {`);
+        for (const n of payload.native) {
+            const doc = formatJsDoc({ name: n.name, description: n.description, updatedAt: GENERATED_AT }, "    ");
+            if (doc !== "")
+                wfLines.push(doc.trimEnd());
+            wfLines.push(`    ${jsonKey(n.slug)}: NativeAction<Record<string, unknown>, Record<string, unknown>>;`);
+        }
+        wfLines.push(`  }`);
+    }
+    // The workflow-sdk augmentation needs its builder types imported; `Ref` only
+    // when a typed action input references it.
+    const preamble = [];
+    // The cdk augmentation references `EncryptionRef` at encryption-typed fields.
+    if (cdkLines.some((l) => l.includes("EncryptionRef"))) {
+        preamble.push(`import type { EncryptionRef } from "@cargo-ai/cdk";`);
+    }
+    if (wfLines.length > 0) {
+        const wfBody = wfLines.join("\n");
+        const imports = [
+            "IntegrationAction",
+            "NativeAction",
+            ...(wfBody.includes("Ref<") ? ["Ref"] : []),
+        ];
+        preamble.push([
+            `import type {`,
+            ...imports.map((name) => `  ${name},`),
+            `} from "@cargo-ai/workflow-sdk";`,
+        ].join("\n"));
+        blocks.push([`declare module "@cargo-ai/workflow-sdk" {`, wfBody, `}`].join("\n"));
+    }
+    // `declare module` only *augments* an existing module when this file is itself
+    // a module. The workflow-sdk import makes it one; when only the cdk block is
+    // emitted there's no import, so force module mode with an empty export.
+    if (preamble.length === 0)
+        preamble.push(`export {};`);
+    return `${HEADER.trim()}\n\n${[...preamble, ...blocks].join("\n\n")}\n`;
+}
+function renderEagerRegistration(payload) {
+    const lines = [];
+    lines.push(HEADER.trim());
+    const imports = [];
+    if (payload.integrations.length > 0)
+        imports.push("registerIntegration");
+    if (payload.native.length > 0)
+        imports.push("registerNative");
+    if (imports.length === 0) {
+        lines.push(``);
+        lines.push(`// Workspace surface is empty (no custom integrations / natives).`);
+        lines.push(``);
+        return lines.join("\n");
+    }
+    lines.push(`import { ${imports.join(", ")} } from "@cargo-ai/workflow-sdk";`);
+    lines.push(``);
+    for (const c of payload.integrations) {
+        lines.push(`registerIntegration(${JSON.stringify(c.slug)}, {`);
+        for (const action of c.actions) {
+            const displayName = action.name !== undefined && action.name.length > 0
+                ? action.name
+                : `${capitalize(c.slug)} ${humanize(action.slug)}`;
+            lines.push(`  ${jsonKey(action.slug)}: { name: ${JSON.stringify(displayName)} },`);
+        }
+        lines.push(`});`);
+    }
+    for (const n of payload.native) {
+        lines.push(`registerNative(${JSON.stringify(n.slug)}, ${JSON.stringify(n.name)});`);
+    }
+    lines.push(``);
+    return lines.join("\n");
+}
+function jsonKey(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+}
+// Render a JSDoc block above a generated declaration so editors surface the
+// entry's metadata on hover. Returns "" when there's nothing to document.
+function formatJsDoc(doc, indent) {
+    const body = [];
+    if (doc.name !== undefined && doc.name.trim().length > 0) {
+        body.push(doc.name.trim());
+    }
+    if (doc.description !== undefined && doc.description.trim().length > 0) {
+        if (body.length > 0)
+            body.push("");
+        for (const line of doc.description.split("\n")) {
+            body.push(line.trimEnd());
+        }
+    }
+    const tags = [];
+    if (doc.category !== undefined) {
+        const cats = Array.isArray(doc.category)
+            ? doc.category.join(", ")
+            : String(doc.category);
+        if (cats.trim().length > 0) {
+            tags.push(`@category ${cats}`);
+        }
+    }
+    if (doc.author !== undefined && doc.author.trim().length > 0) {
+        tags.push(`@author ${doc.author.trim()}`);
+    }
+    if (doc.version !== undefined && String(doc.version).length > 0) {
+        tags.push(`@version ${String(doc.version)}`);
+    }
+    if (doc.updatedAt !== undefined && doc.updatedAt !== null) {
+        const date = doc.updatedAt instanceof Date ? doc.updatedAt : new Date(doc.updatedAt);
+        if (!Number.isNaN(date.getTime())) {
+            tags.push(`@updated ${date.toISOString().slice(0, 10)}`);
+        }
+    }
+    if (doc.see !== undefined && doc.see.trim().length > 0) {
+        tags.push(`@see ${doc.see.trim()}`);
+    }
+    if (body.length > 0 && tags.length > 0) {
+        body.push("");
+    }
+    body.push(...tags);
+    if (body.length === 0)
+        return "";
+    const out = [`${indent}/**`];
+    for (const line of body) {
+        const safe = line.replace(/\*\//g, "*\\/");
+        out.push(safe.length > 0 ? `${indent} * ${safe}` : `${indent} *`);
+    }
+    out.push(`${indent} */`);
+    return `${out.join("\n")}\n`;
+}
+function capitalize(s) {
+    if (s.length === 0)
+        return s;
+    const first = s[0];
+    if (first === undefined)
+        return s;
+    return first.toUpperCase() + s.slice(1);
+}
+function humanize(slug) {
+    return slug
+        .replace(/([A-Z])/g, " $1")
+        .replace(/[_-]+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+function relativeToBase(base, path) {
+    if (path.startsWith(base)) {
+        const rel = path.slice(base.length);
+        return rel.startsWith("/") ? rel.slice(1) : rel;
+    }
+    return path;
+}

package/build/src/cli/index.d.ts

@@ -0,0 +1,4 @@
+export { getApi, getConfig } from "./auth.js";
+export { registerCommands } from "./commands/index.js";
+export declare function runCdkBin(argv?: string[]): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/build/src/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAIvD,wBAAsB,SAAS,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5E"}

package/build/src/cli/index.js

@@ -0,0 +1,20 @@
+// Public entry for the Cargo CDK command layer: the standalone `cargo-cdk` bin
+// (`runCdkBin`) and the `registerCommands` that @cargo-ai/cli reuses for its
+// `cargo-ai cdk` alias.
+import { Command } from "commander";
+import { getApi as resolveApiFromCredentials } from "./auth.js";
+import { registerCommands } from "./commands/index.js";
+import { packageVersion } from "./version.js";
+export { getApi, getConfig } from "./auth.js";
+export { registerCommands } from "./commands/index.js";
+// Attach the commands to the bin's root program (→ `cargo-cdk deploy`, not
+// `cargo-cdk cdk deploy`). The caller (`bin.ts`) catches any rejection.
+export async function runCdkBin(argv = process.argv) {
+    const program = new Command();
+    program
+        .name("cargo-cdk")
+        .description("Cargo CDK — define your Cargo workspace in code and deploy it (init/types/plan/deploy). Shares the Cargo CLI login.")
+        .version(packageVersion());
+    registerCommands(program, resolveApiFromCredentials);
+    await program.parseAsync(argv);
+}

package/build/src/cli/io.d.ts

@@ -0,0 +1,38 @@
+export declare const ExitCodes: {
+    readonly Success: 0;
+    readonly GenericError: 1;
+    readonly InvalidUsage: 2;
+    readonly NotAuthenticated: 3;
+    readonly PermissionDenied: 4;
+    readonly NotFound: 5;
+};
+export type ExitCode = (typeof ExitCodes)[keyof typeof ExitCodes];
+export declare const colors: {
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    cyan: (s: string) => string;
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+};
+export declare function outputJson(value: unknown): void;
+export declare function info(message: string): void;
+export declare function success(message: string): void;
+export declare function confirm(question: string): Promise<boolean>;
+type FailWithOpts = {
+    code?: ExitCode;
+    extra?: Record<string, unknown>;
+};
+export declare function failWith(message: string, opts?: FailWithOpts): never;
+export type Spinner = {
+    update: (message: string) => void;
+    log: (line: string) => void;
+    stop: () => void;
+};
+export declare function startSpinner(message: string): Spinner;
+type HandleApiCallOpts = {
+    spinner?: string | false;
+};
+export declare function handleApiCall<T>(fn: () => Promise<T>, opts?: HandleApiCallOpts): Promise<T>;
+export {};
+//# sourceMappingURL=io.d.ts.map

package/build/src/cli/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../../src/cli/io.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,SAAS;;;;;;;CAOZ,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAclE,eAAO,MAAM,MAAM;aACR,MAAM,KAAG,MAAM;eACb,MAAM,KAAG,MAAM;gBACd,MAAM,KAAG,MAAM;cACjB,MAAM,KAAG,MAAM;aAChB,MAAM,KAAG,MAAM;cACd,MAAM,KAAG,MAAM;CAC1B,CAAC;AAEF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAM/C;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAID,wBAAsB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUhE;AAED,KAAK,YAAY,GAAG;IAClB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,KAAK,CAyBpE;AAKD,MAAM,MAAM,OAAO,GAAG;IAEpB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAGlC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA6CrD;AAED,KAAK,iBAAiB,GAAG;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC1B,CAAC;AAOF,wBAAsB,aAAa,CAAC,CAAC,EACnC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC,CAAC,CAAC,CAiDZ"}

package/build/src/cli/io.js

@@ -0,0 +1,226 @@
+// Terminal I/O helpers (colors, info/success, confirm, failWith, a spinner, and
+// API-error formatting) — a self-contained copy of the CLI's presentation helpers
+// so the command layer ships with @cargo-ai/cdk and needn't reach into the CLI.
+import { determineIfIsFetcherError } from "@cargo-ai/api";
+export const ExitCodes = {
+    Success: 0,
+    GenericError: 1,
+    InvalidUsage: 2,
+    NotAuthenticated: 3,
+    PermissionDenied: 4,
+    NotFound: 5,
+};
+const useColor = process.stderr.isTTY === true &&
+    process.env["NO_COLOR"] === undefined &&
+    process.env["CI"] !== "true";
+const colorize = (text, code) => {
+    if (useColor !== true) {
+        return text;
+    }
+    return `\x1B[${code}m${text}\x1B[0m`;
+};
+export const colors = {
+    red: (s) => colorize(s, "31"),
+    green: (s) => colorize(s, "32"),
+    yellow: (s) => colorize(s, "33"),
+    cyan: (s) => colorize(s, "36"),
+    dim: (s) => colorize(s, "2"),
+    bold: (s) => colorize(s, "1"),
+};
+export function outputJson(value) {
+    if (process.stdout.isTTY === true) {
+        process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+export function info(message) {
+    process.stderr.write(`${message}\n`);
+}
+export function success(message) {
+    process.stderr.write(`${colors.green("✓")} ${message}\n`);
+}
+// Ask a yes/no question on stderr (stdout stays reserved for JSON). Resolves
+// false on a non-TTY stdin (callers should require an explicit --yes there).
+export async function confirm(question) {
+    if (process.stdin.isTTY !== true)
+        return false;
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await rl.question(`${question} [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+export function failWith(message, opts) {
+    const code = opts !== undefined && opts.code !== undefined
+        ? opts.code
+        : ExitCodes.GenericError;
+    const extra = opts !== undefined ? opts.extra : undefined;
+    if (process.stderr.isTTY === true) {
+        process.stderr.write(`${colors.red("✗")} ${message}\n`);
+        if (extra !== undefined) {
+            for (const [key, value] of Object.entries(extra)) {
+                const valueStr = typeof value === "string" ? value : JSON.stringify(value);
+                process.stderr.write(`  ${colors.dim(`${key}:`)} ${valueStr}\n`);
+            }
+        }
+    }
+    else {
+        const payload = { error: message };
+        if (extra !== undefined) {
+            Object.assign(payload, extra);
+        }
+        process.stderr.write(`${JSON.stringify(payload)}\n`);
+    }
+    process.exit(code);
+}
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+export function startSpinner(message) {
+    if (process.stderr.isTTY !== true) {
+        // Non-TTY (CI, piped): no animation — just emit each line so progress is
+        // still visible in logs.
+        process.stderr.write(`${message}\n`);
+        return {
+            update: (m) => process.stderr.write(`${m}\n`),
+            log: (line) => process.stderr.write(`${line}\n`),
+            stop: () => undefined,
+        };
+    }
+    process.stderr.write("\x1B[?25l");
+    let current = message;
+    let frame = 0;
+    const render = () => {
+        const ch = SPINNER_FRAMES[frame % SPINNER_FRAMES.length];
+        if (ch !== undefined) {
+            // \x1B[K clears any stale characters when the message shrinks.
+            process.stderr.write(`\r\x1B[K${colors.cyan(ch)} ${colors.dim(current)}`);
+        }
+        frame += 1;
+    };
+    const id = setInterval(render, SPINNER_INTERVAL_MS);
+    let stopped = false;
+    return {
+        update: (m) => {
+            current = m;
+        },
+        log: (line) => {
+            // Wipe the spinner line, drop a permanent line, let the next frame redraw
+            // the spinner beneath it.
+            process.stderr.write(`\r\x1B[K${line}\n`);
+        },
+        stop: () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            clearInterval(id);
+            process.stderr.write("\r\x1B[K\x1B[?25h");
+        },
+    };
+}
+const SPINNER_DELAY_MS = 200;
+const DEFAULT_SPINNER_MESSAGE = "Loading...";
+// Run an API call, surfacing a delayed spinner and turning FetcherErrors into a
+// clean `failWith` with the right exit code. Used by `cdk types`.
+export async function handleApiCall(fn, opts) {
+    const spinnerMessage = opts !== undefined && opts.spinner === false
+        ? undefined
+        : opts !== undefined && typeof opts.spinner === "string"
+            ? opts.spinner
+            : DEFAULT_SPINNER_MESSAGE;
+    let spinner;
+    let startTimer;
+    if (spinnerMessage !== undefined) {
+        startTimer = setTimeout(() => {
+            spinner = startSpinner(spinnerMessage);
+        }, SPINNER_DELAY_MS);
+    }
+    const stopAll = () => {
+        if (startTimer !== undefined) {
+            clearTimeout(startTimer);
+        }
+        if (spinner !== undefined) {
+            spinner.stop();
+        }
+    };
+    try {
+        const result = await fn();
+        stopAll();
+        return result;
+    }
+    catch (error) {
+        stopAll();
+        if (determineIfIsFetcherError(error)) {
+            const parsedError = error;
+            const status = parsedError.status;
+            const body = parsedError.body !== undefined ? parsedError.body : String(error);
+            const { message, code } = describeApiError(status, body);
+            failWith(message, {
+                code,
+                extra: { status: status !== undefined ? status : "unknown", body },
+            });
+        }
+        throw error;
+    }
+}
+function describeApiError(status, body) {
+    const detail = extractApiErrorDetail(body);
+    const detailSuffix = detail !== undefined ? `: ${detail}` : "";
+    if (status === 401) {
+        return {
+            message: `Not authenticated${detailSuffix}. Run \`cargo-ai login\` to refresh credentials.`,
+            code: ExitCodes.NotAuthenticated,
+        };
+    }
+    if (status === 403) {
+        return {
+            message: `Permission denied${detailSuffix}. Check your workspace permissions or selected workspace UUID.`,
+            code: ExitCodes.PermissionDenied,
+        };
+    }
+    if (status === 404) {
+        return {
+            message: `Not found${detailSuffix}. Verify the UUID(s) you passed.`,
+            code: ExitCodes.NotFound,
+        };
+    }
+    if (status === 429) {
+        return {
+            message: `Rate limited${detailSuffix}. Retry in a moment.`,
+            code: ExitCodes.GenericError,
+        };
+    }
+    if (status !== undefined && status >= 500) {
+        return {
+            message: `Server error (${String(status)})${detailSuffix}. Retry shortly or check status.getcargo.io.`,
+            code: ExitCodes.GenericError,
+        };
+    }
+    return {
+        message: `API error (${status !== undefined ? String(status) : "unknown"})${detailSuffix}`,
+        code: ExitCodes.GenericError,
+    };
+}
+function extractApiErrorDetail(body) {
+    if (typeof body === "string" && body.length > 0) {
+        return body;
+    }
+    if (body !== null && typeof body === "object") {
+        const record = body;
+        if (typeof record["message"] === "string") {
+            return record["message"];
+        }
+        if (typeof record["reason"] === "string") {
+            return record["reason"];
+        }
+        if (typeof record["error"] === "string") {
+            return record["error"];
+        }
+    }
+    return undefined;
+}

package/build/src/cli/version.d.ts

@@ -0,0 +1,2 @@
+export declare function packageVersion(): string;
+//# sourceMappingURL=version.d.ts.map