@cargo-ai/cdk 1.0.2 → 1.0.4

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

@@ -0,0 +1,531 @@
+import { acquireLock, appendAudit, apply, compile, destroy, detectDrift, emptyState, formatPlan, importResource, liveExecutors, liveReaders, loadResources, newRunId, plan, readState, reconcileDrift, removeResources, restoreSnapshot, snapshotState, writeState, } from "../../deploy/index.js";
+import { getConfig } from "../auth.js";
+import { colors, confirm, ExitCodes, failWith, info, outputJson, startSpinner, success, } from "../io.js";
+// `plan / deploy / refresh / import / rollback / destroy` — the reconcile
+// commands. This layer parses args, authenticates via the injected `getApi`,
+// confirms, and prints; the engine (load / compile / apply / state) is the
+// package's `deploy/` module.
+export function registerDeployCommands(parent, getApi) {
+    parent
+        .command("plan")
+        .description("Compile the resource tree and diff against cargo.state.json. Offline — no API calls.")
+        .option("--dir <path>", "Repo root containing the resource files (default: cwd)")
+        .option("--json", "Output the raw plan result as JSON")
+        .action(async (opts) => {
+        // Run from the repo root so relative code paths (defineWorker/App/File)
+        // and cargo.state.json resolve against it.
+        if (opts.dir !== undefined)
+            process.chdir(opts.dir);
+        const root = ".";
+        let result;
+        try {
+            result = await plan(root);
+        }
+        catch (error) {
+            failWith(`Failed to load cdk repo: ${message(error)}`, {
+                code: ExitCodes.InvalidUsage,
+            });
+        }
+        if (opts.json === true)
+            outputJson(result);
+        else
+            process.stdout.write(`${formatPlan(result)}\n`);
+        if (result.errors.length > 0)
+            process.exitCode = ExitCodes.GenericError;
+    });
+    parent
+        .command("deploy")
+        .description("Deploy the resource tree to Cargo — create/update resources and write cargo.state.json.")
+        .option("--dir <path>", "Repo root containing the resource files (default: cwd)")
+        .option("--yes", "Skip the confirmation prompt")
+        .option("--dry-run", "Show the plan without applying")
+        .option("--prune", "Delete resources tracked in state but no longer in code")
+        .option("--refresh", "Re-read live resources first and re-apply any modified out-of-band")
+        .option("--recreate-deleted", "With --refresh, also restore resources deleted outside the CDK (off by default)")
+        .option("--force", "Steal the state lock held by another run")
+        .option("--json", "Output the deploy result as JSON")
+        .action(async (opts) => {
+        // Run from the repo root so relative code paths (defineWorker/App/File)
+        // and cargo.state.json resolve against it.
+        if (opts.dir !== undefined)
+            process.chdir(opts.dir);
+        const root = ".";
+        const workspaceUuid = await resolveWorkspaceUuid(getApi);
+        const runId = newRunId();
+        // Load the resource tree ONCE (loadResources resets the registry, so it
+        // must not run twice in a process), then reuse the nodes for plan + apply.
+        let nodes;
+        try {
+            nodes = await loadResources(root);
+        }
+        catch (error) {
+            failWith(`Failed to load cdk repo: ${message(error)}`, {
+                code: ExitCodes.InvalidUsage,
+            });
+        }
+        // Hold the state lock for the whole read→plan→apply sequence (not just
+        // the apply), so a concurrent run can't rewrite cargo.state.json between
+        // our read and our write. --dry-run is read-only, so it skips the lock.
+        if (opts.dryRun !== true) {
+            try {
+                acquireLock(root, "deploy", opts.force === true);
+            }
+            catch (error) {
+                failWith(message(error), { code: ExitCodes.GenericError });
+            }
+        }
+        const prior = readState(root);
+        if (prior !== undefined && prior.workspaceUuid !== workspaceUuid) {
+            failWith(`cargo.state.json belongs to workspace ${prior.workspaceUuid}, but the selected workspace is ${workspaceUuid}. Refusing to deploy (would orphan resources).`, { code: ExitCodes.InvalidUsage });
+        }
+        const baseState = prior ?? emptyState(workspaceUuid);
+        // Build the authenticated client lazily so a plain `--dry-run` stays
+        // offline; `--refresh` and the apply both reuse this one instance.
+        let apiClient;
+        const api = () => {
+            if (apiClient === undefined)
+                apiClient = getApi();
+            return apiClient;
+        };
+        // With --refresh, re-read the live resources and fold out-of-band drift
+        // into the state before planning: a resource edited in the UI re-applies
+        // (its code-hash is invalidated) and one deleted externally is recreated.
+        let state = baseState;
+        if (opts.refresh === true &&
+            Object.keys(baseState.resources).length > 0) {
+            let drift;
+            try {
+                drift = await detectDrift(baseState, liveReaders(api()));
+            }
+            catch (error) {
+                failWith(`Refresh failed: ${message(error)}`, {
+                    code: ExitCodes.GenericError,
+                });
+            }
+            const modifiedExternally = drift.filter((d) => d.status === "modified");
+            const deletedExternally = drift.filter((d) => d.status === "deleted");
+            const changed = [...modifiedExternally, ...deletedExternally];
+            if (changed.length === 0) {
+                info("Refresh: no out-of-band drift.");
+            }
+            else {
+                info(`Refresh found ${String(changed.length)} drifted resource(s):`);
+                for (const d of modifiedExternally) {
+                    info(`  modified externally: ${d.id}`);
+                }
+                for (const d of deletedExternally) {
+                    info(`  deleted externally: ${d.id}`);
+                }
+                // A resource present in code but deleted in the UI is ambiguous —
+                // an accident to restore, or an intentional removal. Don't silently
+                // recreate it; force the decision unless --recreate-deleted opts in.
+                if (deletedExternally.length > 0 && opts.recreateDeleted !== true) {
+                    failWith(`${String(deletedExternally.length)} resource(s) were deleted outside the CDK ` +
+                        `(${deletedExternally.map((d) => d.id).join(", ")}). Re-run with ` +
+                        `--recreate-deleted to restore them, or remove them from your code if ` +
+                        `the deletion was intentional.`, { code: ExitCodes.InvalidUsage });
+                }
+                // Modified always re-applies; deleted only reconciles (→ recreate)
+                // once the user has opted in above.
+                const effectiveDrift = opts.recreateDeleted === true ? drift : modifiedExternally;
+                state = reconcileDrift(baseState, effectiveDrift);
+            }
+        }
+        const planResult = compile({ nodes, state });
+        info(formatPlan(planResult));
+        if (planResult.errors.length > 0) {
+            failWith("Plan has errors — fix them before deploying.", {
+                code: ExitCodes.GenericError,
+            });
+        }
+        const deletes = planResult.plan.filter((e) => e.change === "delete");
+        const hasApplyWork = planResult.plan.some((e) => e.change === "create" || e.change === "update");
+        const willPrune = opts.prune === true && deletes.length > 0;
+        if (opts.dryRun === true) {
+            // Make the dry run reflect the --prune decision.
+            if (deletes.length > 0) {
+                info(willPrune
+                    ? `Would prune ${String(deletes.length)} resource(s): ${deletes.map((e) => e.id).join(", ")}`
+                    : `${String(deletes.length)} resource(s) would be left in place — add --prune to remove them.`);
+            }
+            return;
+        }
+        if (!hasApplyWork && !willPrune) {
+            if (deletes.length > 0) {
+                info(`${String(deletes.length)} resource(s) in state are no longer in code. Re-run with --prune to remove them.`);
+            }
+            else {
+                success("Nothing to deploy — everything is up to date.");
+            }
+            return;
+        }
+        if (opts.yes !== true) {
+            const ask = willPrune
+                ? `Deploy to workspace ${workspaceUuid} and prune ${String(deletes.length)} resource(s)?`
+                : `Deploy to workspace ${workspaceUuid}?`;
+            const ok = await confirm(ask);
+            if (!ok)
+                failWith("Aborted.", { code: ExitCodes.GenericError });
+        }
+        // Snapshot the pre-deploy state so `cdk rollback` can restore it.
+        snapshotState(root);
+        // Live progress: a spinner naming the resource currently being applied,
+        // leaving a ✓ line behind for each completed one. Suppressed for --json
+        // so machine output on stdout stays clean.
+        const spinner = opts.json === true ? undefined : startSpinner("Deploying…");
+        const onProgress = spinner === undefined
+            ? undefined
+            : (event) => {
+                if (event.phase === "start") {
+                    const verb = event.change === "create" ? "Creating" : "Updating";
+                    spinner.update(`${verb} ${colors.bold(event.id)} ${colors.dim(`(${event.index}/${event.total})`)}`);
+                }
+                else {
+                    const done = event.change === "create" ? "created" : "updated";
+                    spinner.log(`  ${colors.green("✓")} ${event.id} ${colors.dim(done)}`);
+                }
+            };
+        let result;
+        try {
+            result = await apply({ nodes, state }, liveExecutors(api()), // throws NotAuthenticated if not logged in
+            (next) => writeState(root, next), liveReaders(api()), // capture a live fingerprint for drift detection
+            onProgress);
+        }
+        catch (error) {
+            spinner?.stop();
+            appendAudit(root, {
+                runId,
+                at: new Date().toISOString(),
+                command: "deploy",
+                workspaceUuid,
+                ok: false,
+                error: message(error),
+            });
+            failWith(`Deploy failed: ${message(error)}`, {
+                code: ExitCodes.GenericError,
+                extra: {
+                    runId,
+                    hint: "Resources created before the failure were saved to cargo.state.json — fix the error and re-run to continue.",
+                },
+            });
+        }
+        spinner?.stop();
+        let pruned = {
+            removed: [],
+            released: [],
+        };
+        if (willPrune) {
+            try {
+                pruned = await removeResources(root, api(), deletes.map((e) => e.id));
+            }
+            catch (error) {
+                appendAudit(root, {
+                    runId,
+                    at: new Date().toISOString(),
+                    command: "deploy",
+                    workspaceUuid,
+                    ok: false,
+                    error: `prune: ${message(error)}`,
+                });
+                failWith(`Prune failed: ${message(error)}`, {
+                    code: ExitCodes.GenericError,
+                    extra: { runId },
+                });
+            }
+        }
+        const created = result.applied.filter((e) => e.change === "create").length;
+        const updated = result.applied.filter((e) => e.change === "update").length;
+        appendAudit(root, {
+            runId,
+            at: new Date().toISOString(),
+            command: "deploy",
+            workspaceUuid,
+            ok: true,
+            summary: {
+                created,
+                updated,
+                unchanged: result.skipped.length,
+                pruned: pruned.removed.length,
+                released: pruned.released.length,
+            },
+        });
+        if (opts.json === true) {
+            outputJson({
+                created,
+                updated,
+                skipped: result.skipped.length,
+                pruned: pruned.removed.length,
+                released: pruned.released.length,
+            });
+        }
+        else {
+            success(`${String(created)} created, ${String(updated)} updated, ${String(result.skipped.length)} unchanged.`);
+            if (pruned.removed.length > 0 || pruned.released.length > 0) {
+                info(`Pruned ${String(pruned.removed.length)}${pruned.released.length > 0 ? ` (released ${String(pruned.released.length)} adopted)` : ""}.`);
+            }
+            else if (deletes.length > 0) {
+                info(`${String(deletes.length)} resource(s) no longer in code — re-run with --prune to remove them.`);
+            }
+            // First deploy: nudge the user to commit state and ignore the lock.
+            if (prior === undefined) {
+                info("Wrote cargo.state.json — commit it (it links your code to deployed resources). Add cargo.state.lock to .gitignore.");
+            }
+        }
+    });
+    parent
+        .command("refresh")
+        .description("Re-read live resources and report drift from the last deploy (read-only).")
+        .option("--dir <path>", "Repo root (default: cwd)")
+        .option("--json", "Output the drift report as JSON")
+        .action(async (opts) => {
+        if (opts.dir !== undefined)
+            process.chdir(opts.dir);
+        const root = ".";
+        const workspaceUuid = await resolveWorkspaceUuid(getApi);
+        const state = readState(root);
+        if (state === undefined || Object.keys(state.resources).length === 0) {
+            info("No state — nothing to refresh.");
+            return;
+        }
+        // Reading another workspace's state against the selected one would report
+        // everything as deleted — refuse rather than print misleading drift.
+        if (state.workspaceUuid !== workspaceUuid) {
+            failWith(`cargo.state.json belongs to workspace ${state.workspaceUuid}, not the selected ${workspaceUuid}.`, { code: ExitCodes.InvalidUsage });
+        }
+        const api = getApi();
+        let drift;
+        try {
+            drift = await detectDrift(state, liveReaders(api));
+        }
+        catch (error) {
+            failWith(`Refresh failed: ${message(error)}`, {
+                code: ExitCodes.GenericError,
+            });
+        }
+        if (opts.json === true) {
+            outputJson(drift);
+            return;
+        }
+        const drifted = drift.filter((d) => d.status === "modified" || d.status === "deleted");
+        if (drifted.length === 0) {
+            success(`In sync — ${String(drift.length)} resource(s) match the last deploy.`);
+            return;
+        }
+        info(`${String(drifted.length)} resource(s) drifted from code:`);
+        for (const d of drifted) {
+            info(`  ${d.status === "deleted" ? "deleted externally" : "modified externally"}: ${d.id}`);
+        }
+        info("Run 'cdk deploy --refresh' to re-apply code over the drift.");
+    });
+    parent
+        .command("import")
+        .argument("<id>", "Code resource id to bind (e.g. agent:sdr)")
+        .argument("<uuid>", "The live resource's uuid in the workspace")
+        .description("Bind an existing live resource to a code resource in cargo.state.json.")
+        .option("--dir <path>", "Repo root (default: cwd)")
+        .option("--force", "Steal the state lock held by another run")
+        .option("--json", "Output the result as JSON")
+        .action(async (id, uuid, opts) => {
+        if (opts.dir !== undefined)
+            process.chdir(opts.dir);
+        const root = ".";
+        const workspaceUuid = await resolveWorkspaceUuid(getApi);
+        const api = getApi();
+        const runId = newRunId();
+        try {
+            acquireLock(root, "import", opts.force === true);
+        }
+        catch (error) {
+            failWith(message(error), { code: ExitCodes.GenericError });
+        }
+        snapshotState(root); // enable `cdk rollback`
+        let result;
+        try {
+            result = await importResource(root, api, workspaceUuid, id, uuid);
+        }
+        catch (error) {
+            appendAudit(root, {
+                runId,
+                at: new Date().toISOString(),
+                command: "import",
+                workspaceUuid,
+                ok: false,
+                error: message(error),
+            });
+            failWith(`Import failed: ${message(error)}`, {
+                code: ExitCodes.GenericError,
+                extra: { runId },
+            });
+        }
+        appendAudit(root, {
+            runId,
+            at: new Date().toISOString(),
+            command: "import",
+            workspaceUuid,
+            ok: true,
+            summary: { id, uuid, kind: result.kind },
+        });
+        if (opts.json === true)
+            outputJson(result);
+        else
+            success(`Imported ${id} → ${uuid} (${result.kind}).`);
+    });
+    parent
+        .command("rollback")
+        .description("Restore cargo.state.json from the snapshot taken before the last deploy/destroy/import.")
+        .option("--dir <path>", "Repo root (default: cwd)")
+        .option("--yes", "Skip the confirmation prompt")
+        .option("--force", "Steal the state lock held by another run")
+        .action(async (opts) => {
+        if (opts.dir !== undefined)
+            process.chdir(opts.dir);
+        const root = ".";
+        const workspaceUuid = await resolveWorkspaceUuid(getApi);
+        const runId = newRunId();
+        if (opts.yes !== true) {
+            const ok = await confirm("Restore cargo.state.json from the last snapshot? (restores the state file only — not live resources)");
+            if (!ok)
+                failWith("Aborted.", { code: ExitCodes.GenericError });
+        }
+        try {
+            acquireLock(root, "rollback", opts.force === true);
+        }
+        catch (error) {
+            failWith(message(error), { code: ExitCodes.GenericError });
+        }
+        if (!restoreSnapshot(root)) {
+            failWith("No snapshot found (cargo.state.bak.json) — nothing to roll back.", { code: ExitCodes.InvalidUsage });
+        }
+        appendAudit(root, {
+            runId,
+            at: new Date().toISOString(),
+            command: "rollback",
+            workspaceUuid,
+            ok: true,
+        });
+        success("Restored cargo.state.json from the snapshot. Run 'cargo-ai cdk deploy --refresh' to reconcile live resources to it.");
+    });
+    parent
+        .command("destroy")
+        .description("Tear down resources recorded in cargo.state.json (deletes by uuid).")
+        .option("--dir <path>", "Repo root (default: cwd)")
+        .option("--yes", "Skip the confirmation prompt")
+        .option("--target <id>", "Only destroy this resource id (e.g. play:welcome)")
+        .option("--all", "Destroy every state-tracked resource (required for blanket teardown)")
+        .option("--force", "Steal the state lock held by another run")
+        .option("--json", "Output the result as JSON")
+        .action(async (opts) => {
+        // Run from the repo root so relative code paths (defineWorker/App/File)
+        // and cargo.state.json resolve against it.
+        if (opts.dir !== undefined)
+            process.chdir(opts.dir);
+        const root = ".";
+        const api = getApi();
+        const workspaceUuid = await resolveWorkspaceUuid(getApi);
+        const runId = newRunId();
+        // Blanket teardown must be explicit — `--yes` alone can't nuke a whole
+        // workspace; you must opt in with --target <id> or --all.
+        if (opts.target === undefined && opts.all !== true) {
+            failWith("Specify --target <id> to remove one resource, or --all to remove everything in state.", { code: ExitCodes.InvalidUsage });
+        }
+        // Lock before reading state so the read→delete sequence is consistent.
+        try {
+            acquireLock(root, "destroy", opts.force === true);
+        }
+        catch (error) {
+            failWith(message(error), { code: ExitCodes.GenericError });
+        }
+        const state = readState(root);
+        if (state === undefined || Object.keys(state.resources).length === 0) {
+            info("Nothing to destroy — no state.");
+            return;
+        }
+        if (state.workspaceUuid !== workspaceUuid) {
+            failWith(`cargo.state.json belongs to workspace ${state.workspaceUuid}, not the selected ${workspaceUuid}.`, { code: ExitCodes.InvalidUsage });
+        }
+        const ids = opts.target !== undefined
+            ? opts.target in state.resources
+                ? [opts.target]
+                : []
+            : Object.keys(state.resources);
+        if (ids.length === 0) {
+            // An explicit --target that matches nothing is a usage error, not a
+            // success — a scripted `destroy --target X && deploy` must not believe
+            // X was torn down when the id was simply mistyped.
+            failWith(`"${String(opts.target)}" is not in state — nothing to destroy. Run \`cargo-ai cdk plan\` to see the tracked ids.`, { code: ExitCodes.InvalidUsage });
+        }
+        // Always show exactly what will be deleted, even with --yes.
+        info(`About to remove ${String(ids.length)} resource(s) from workspace ${workspaceUuid}:`);
+        for (const id of ids)
+            info(`  - ${id}`);
+        if (opts.yes !== true) {
+            const ok = await confirm(`Delete these ${String(ids.length)} resource(s)?`);
+            if (!ok)
+                failWith("Aborted.", { code: ExitCodes.GenericError });
+        }
+        snapshotState(root); // enable `cdk rollback`
+        let result;
+        try {
+            result = await destroy(root, api, { target: opts.target });
+        }
+        catch (error) {
+            appendAudit(root, {
+                runId,
+                at: new Date().toISOString(),
+                command: "destroy",
+                workspaceUuid,
+                ok: false,
+                error: message(error),
+            });
+            failWith(`Destroy failed: ${message(error)}`, {
+                code: ExitCodes.GenericError,
+                extra: {
+                    runId,
+                    hint: "Resources removed before the failure are gone and dropped from state — re-run to remove the rest.",
+                },
+            });
+        }
+        appendAudit(root, {
+            runId,
+            at: new Date().toISOString(),
+            command: "destroy",
+            workspaceUuid,
+            ok: true,
+            summary: {
+                removed: result.removed.length,
+                released: result.released.length,
+                ids: result.removed,
+            },
+        });
+        if (opts.json === true)
+            outputJson(result);
+        else {
+            success(result.removed.length === 0
+                ? "Nothing removed."
+                : `Removed ${String(result.removed.length)}: ${result.removed.join(", ")}`);
+            if (result.released.length > 0) {
+                info(`Released ${String(result.released.length)} adopted (left in place): ${result.released.join(", ")}`);
+            }
+        }
+    });
+}
+// Resolve the workspace to operate on. Prefers an explicit `CARGO_WORKSPACE_UUID`
+// / credentials-file workspace; otherwise falls back to the workspace the token
+// is bound to (the same lookup `cargo-ai whoami` uses), so a workspace-scoped
+// token "just works" without setting an env var.
+async function resolveWorkspaceUuid(getApi) {
+    const { workspaceUuid } = getConfig();
+    if (workspaceUuid !== undefined)
+        return workspaceUuid;
+    try {
+        const { workspace } = await getApi().workspaceManagement.workspace.getCurrent();
+        return workspace.uuid;
+    }
+    catch (error) {
+        failWith(`No workspace selected and couldn't resolve one from your credentials (${message(error)}). ` +
+            "Run 'cargo-ai login' or set CARGO_WORKSPACE_UUID.", { code: ExitCodes.NotAuthenticated });
+    }
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,4 @@
+import type { Api } from "@cargo-ai/api";
+import type { Command } from "commander";
+export declare function registerCommands(program: Command, getApi: () => Api): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAI1E"}

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

@@ -0,0 +1,11 @@
+import { registerDeployCommands } from "./deploy.js";
+import { registerInitCommand } from "./init.js";
+import { registerTypesCommand } from "./types.js";
+// Attach the cdk commands onto `program` — the root program for the standalone
+// `cargo-cdk` bin, or a `cdk` subcommand group created by @cargo-ai/cli. Kept
+// program-agnostic so both mount it the same way.
+export function registerCommands(program, getApi) {
+    registerInitCommand(program);
+    registerTypesCommand(program, getApi);
+    registerDeployCommands(program, getApi);
+}

package/build/src/cli/commands/init.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function registerInitCommand(parent: Command): void;
+//# sourceMappingURL=init.d.ts.map

package/build/src/cli/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAyEzD"}

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

@@ -0,0 +1,76 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ExitCodes, failWith, info, success } from "../io.js";
+import { copyDirectory, listTemplates } from "./templates.js";
+// `cdk init <directory> [--template <slug>]` — scaffold a starter CDK project by
+// copying one of `@cargo-ai/cdk`'s bundled templates (see `--list-templates`),
+// substituting `__APP_NAME__`.
+const TEMPLATE_DESCRIPTIONS = {
+    blank: "Minimal starter — one connector + model + a workflow-backed tool. Good starting point.",
+    full: "The full example — every resource type wired into a GTM growth workspace: connectors, models, plays, agents, an MCP server, context, tools, a worker, and a hosted app.",
+};
+export function registerInitCommand(parent) {
+    parent
+        .command("init <directory>")
+        .description("Scaffold a starter Cargo CDK project locally from a template (ready to plan/deploy).")
+        .option("--template <slug>", "Template slug (default: blank)", "blank")
+        .option("--name <name>", "Project name written into package.json")
+        .option("--list-templates", "Print available templates and exit")
+        .option("--force", "Write into a non-empty directory")
+        .action(async (directory, opts) => {
+        const templatesRoot = findTemplatesRoot();
+        if (opts.listTemplates === true) {
+            const slugs = await listTemplates(templatesRoot);
+            for (const slug of slugs) {
+                const desc = TEMPLATE_DESCRIPTIONS[slug] ?? "";
+                info(`${slug}${desc.length > 0 ? ` — ${desc}` : ""}`);
+            }
+            return;
+        }
+        const templateDir = join(templatesRoot, opts.template);
+        if (!existsSync(templateDir)) {
+            const slugs = await listTemplates(templatesRoot);
+            failWith(`Unknown template "${opts.template}". Available: ${slugs.join(", ")}`, { code: ExitCodes.GenericError });
+        }
+        const targetDir = resolve(process.cwd(), directory);
+        if (existsSync(targetDir) &&
+            readdirSync(targetDir).length > 0 &&
+            opts.force !== true) {
+            failWith(`Directory ${directory} is not empty. Pass --force to scaffold into it anyway.`, { code: ExitCodes.GenericError });
+        }
+        const appName = opts.name !== undefined ? opts.name : basename(targetDir);
+        await copyDirectory(templateDir, targetDir, [
+            { from: "__APP_NAME__", to: appName },
+        ]);
+        success(`Scaffolded ${directory} from the "${opts.template}" template`);
+        info(``);
+        info([
+            `Next steps:`,
+            `  cd ${relative(process.cwd(), targetDir)}`,
+            `  npm install`,
+            `  cargo-ai login                 # authenticate (or: export CARGO_API_TOKEN=<token>)`,
+            `  npm run types                  # generate typed connector/model config`,
+            `  npm run plan                   # preview the resource tree`,
+            `  npm run deploy                 # create it in the workspace`,
+        ].join("\n"));
+    });
+}
+// Templates ship inside this package at `<pkg-root>/templates`. This module runs
+// from `<pkg-root>/build/src/cli/`, so walk up until we find a `templates/` dir
+// that holds the `blank` template (the sentinel that distinguishes ours from any
+// unrelated `templates/` dir along the way). Works both from the monorepo build
+// output and an installed `node_modules/@cargo-ai/cdk`.
+function findTemplatesRoot() {
+    let cursor = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i += 1) {
+        const candidate = join(cursor, "templates");
+        if (existsSync(join(candidate, "blank")))
+            return candidate;
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    throw new Error("Could not locate the @cargo-ai/cdk templates directory. Reinstall @cargo-ai/cdk if this persists.");
+}

package/build/src/cli/commands/inputTypes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Fixed input shape of every agent node. Matches the SDK's `AgentInput`
+ * type and the engine's `AiUtils.agentConfig` schema.
+ */
+export declare const AGENT_INPUT_TYPE_SRC: string;
+/**
+ * Print an integration action's JSON Schema config as a TS input type.
+ * Returns `"Record<string, unknown>"` when the schema is missing or not an
+ * object schema we can render.
+ */
+export declare function printJsonSchemaInput(schema: unknown): string;
+/**
+ * Like {@link printJsonSchemaInput} but WITHOUT the top-level `Ref<T> | T`
+ * widening — for CDK connector/model config types, which are plain data (no
+ * workflow builder Refs). Used by `cargo-ai cdk types`.
+ */
+export declare function printJsonSchemaType(schema: unknown): string;
+/**
+ * Print a tool release's `formFields` as a TS input type. Returns
+ * `undefined` when the fields can't be interpreted (caller falls back to
+ * `Record<string, unknown>`).
+ */
+export declare function printFormFieldsInput(formFields: unknown): string | undefined;
+//# sourceMappingURL=inputTypes.d.ts.map

package/build/src/cli/commands/inputTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputTypes.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/inputTypes.ts"],"names":[],"mappings":"AAmCA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAE+D,CAAC;AAEjG;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAM5D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAQ3D;AAkMD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAU5E"}