@cargo-ai/cdk 0.1.1

package/build/src/deploy/import.js

@@ -0,0 +1,87 @@
+// `cdk import` — bind an existing live resource to a code resource by writing a
+// state entry (kind:slug → uuid + outputs + live fingerprint). Recovers the
+// link to uuid-only resources (play/agent/tool/file/mcpServer) when the state
+// file is lost, or brings already-existing infra under CDK management.
+//
+// The entry's hash is the resource's CURRENT code hash, so a subsequent plain
+// deploy treats it as up to date (no rebuild). Future edits — in code or out of
+// band (via `refresh`) — diff against it normally.
+import { compile } from "./compile.js";
+import { loadResources } from "./load.js";
+import { liveReaders } from "./readers.live.js";
+import { emptyState, readState, writeState } from "./state.js";
+// Reconstruct the outputs an apply would have produced for this kind, so tokens
+// its dependents reference (connector.datasetUuid, tool/play.workflowUuid,
+// worker/app.url) still resolve.
+async function importOutputs(api, kind, uuid) {
+    const outputs = { uuid };
+    if (kind === "connector") {
+        const { datasets } = await api.storage.dataset.all();
+        const match = datasets.find((d) => d["kind"] === "connector" && d["connectorUuid"] === uuid);
+        if (match !== undefined)
+            outputs["datasetUuid"] = match["uuid"];
+    }
+    else if (kind === "play") {
+        const { plays } = await api.orchestration.play.list();
+        const play = plays.find((p) => p["uuid"] === uuid);
+        const wf = play === undefined ? undefined : play["workflowUuid"];
+        if (typeof wf === "string")
+            outputs["workflowUuid"] = wf;
+    }
+    else if (kind === "tool") {
+        const { tools } = await api.orchestration.tool.all();
+        const tool = tools.find((t) => t["uuid"] === uuid);
+        const wf = tool === undefined ? undefined : tool["workflowUuid"];
+        if (typeof wf === "string")
+            outputs["workflowUuid"] = wf;
+    }
+    else if (kind === "worker") {
+        const { worker } = await api.hosting.worker.get(uuid);
+        const url = worker["url"];
+        if (typeof url === "string" && url !== "")
+            outputs["url"] = url;
+    }
+    else if (kind === "app") {
+        const { app } = await api.hosting.app.get(uuid);
+        const url = app["url"];
+        if (typeof url === "string" && url !== "")
+            outputs["url"] = url;
+    }
+    return outputs;
+}
+/**
+ * Import the live resource `uuid` as the code resource `id` (e.g. "agent:sdr").
+ * Loads the repo to confirm the id exists and capture its current hash, verifies
+ * the live resource is reachable, then writes/overwrites its state entry.
+ */
+export async function importResource(root, api, workspaceUuid, id, uuid, 
+// The repo's resources. Defaults to loading them from `root`; injectable so
+// the import logic is testable without the tsx file loader.
+nodes) {
+    const resolved = nodes ?? (await loadResources(root));
+    const entry = compile({ nodes: resolved }).plan.find((p) => p.id === id);
+    if (entry === undefined) {
+        throw new Error(`no resource "${id}" found in code — import targets a code resource id like "agent:sdr".`);
+    }
+    const kind = entry.kind;
+    const outputs = await importOutputs(api, kind, uuid);
+    // Imported resources are treated as adopted: a later `destroy` releases them
+    // (drops from state) rather than deleting infra the CDK didn't create.
+    outputs["adopted"] = "true";
+    const stateEntry = { hash: entry.hash, uuid, outputs };
+    // Confirm it's actually there (and capture a drift baseline).
+    const live = await liveReaders(api)[kind](stateEntry);
+    if (!live.exists) {
+        throw new Error(`${kind} ${uuid} was not found in the workspace — nothing to import.`);
+    }
+    if (live.fingerprint !== undefined)
+        stateEntry.live = live.fingerprint;
+    const prior = readState(root);
+    const state = prior !== undefined ? prior : emptyState(workspaceUuid);
+    if (prior !== undefined && prior.workspaceUuid !== workspaceUuid) {
+        throw new Error(`cargo.state.json belongs to workspace ${prior.workspaceUuid}, not the selected ${workspaceUuid}.`);
+    }
+    state.resources[id] = stateEntry;
+    writeState(root, state);
+    return { kind, outputs };
+}

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

@@ -0,0 +1,39 @@
+import { type Executors } from "./apply.js";
+import { type CompileResult, type State } from "./compile.js";
+export type { ApplyProgress, ApplyResult, Executors, Outputs, } from "./apply.js";
+export { apply } from "./apply.js";
+export type { AuditEntry } from "./audit.js";
+export { appendAudit, newRunId } from "./audit.js";
+export type { ChangeType, CompileInput, CompileResult, PlanEntry, State, StateEntry, ValidationError, } from "./compile.js";
+export { compile } from "./compile.js";
+export type { DestroyResult } from "./destroy.js";
+export { destroy, removeResources } from "./destroy.js";
+export { liveExecutors } from "./executors.live.js";
+export type { ImportResult } from "./import.js";
+export { importResource } from "./import.js";
+export { loadResources } from "./load.js";
+export type { Lock } from "./lock.js";
+export { acquireLock } from "./lock.js";
+export { formatPlan } from "./plan.js";
+export { liveReaders } from "./readers.live.js";
+export type { DriftEntry, DriftStatus, LiveRead, LiveReader, LiveReaders, } from "./refresh.js";
+export { detectDrift, fingerprint, reconcileDrift } from "./refresh.js";
+export { emptyState, readState, restoreSnapshot, snapshotState, writeState, } from "./state.js";
+/**
+ * Load a repo's resource definitions, read its cargo.state.json, and compile a
+ * plan — the offline diff. No side effects on the workspace.
+ */
+export declare function plan(root: string): Promise<CompileResult>;
+export type DeployResult = {
+    state: State;
+    applied: number;
+    updated: number;
+    skipped: number;
+};
+/**
+ * Load → compile → apply against `executors`, persisting cargo.state.json after
+ * every resource. Seeds from the existing state, or an empty state bound to
+ * `workspaceUuid` on the first deploy. Throws on validation errors.
+ */
+export declare function deploy(root: string, workspaceUuid: string, executors: Executors): Promise<DeployResult>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/deploy/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAIvE,YAAY,EACV,aAAa,EACb,WAAW,EACX,SAAS,EACT,OAAO,GACR,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,SAAS,EACT,KAAK,EACL,UAAU,EACV,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EACL,UAAU,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAG/D;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,MAAM,CAC1B,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,YAAY,CAAC,CAyBvB"}

package/build/src/deploy/index.js

@@ -0,0 +1,51 @@
+// The deploy engine — the reconciler. Programmatic `plan` + `apply` + `deploy`
+// over a repo of resource definitions, plus the lower-level pieces for hosts.
+import { apply } from "./apply.js";
+import { compile } from "./compile.js";
+import { loadResources } from "./load.js";
+import { emptyState, readState, writeState } from "./state.js";
+export { apply } from "./apply.js";
+export { appendAudit, newRunId } from "./audit.js";
+export { compile } from "./compile.js";
+export { destroy, removeResources } from "./destroy.js";
+export { liveExecutors } from "./executors.live.js";
+export { importResource } from "./import.js";
+export { loadResources } from "./load.js";
+export { acquireLock } from "./lock.js";
+export { formatPlan } from "./plan.js";
+export { liveReaders } from "./readers.live.js";
+export { detectDrift, fingerprint, reconcileDrift } from "./refresh.js";
+export { emptyState, readState, restoreSnapshot, snapshotState, writeState, } from "./state.js";
+/**
+ * Load a repo's resource definitions, read its cargo.state.json, and compile a
+ * plan — the offline diff. No side effects on the workspace.
+ */
+export async function plan(root) {
+    const nodes = await loadResources(root);
+    return compile({ nodes, state: readState(root) });
+}
+/**
+ * Load → compile → apply against `executors`, persisting cargo.state.json after
+ * every resource. Seeds from the existing state, or an empty state bound to
+ * `workspaceUuid` on the first deploy. Throws on validation errors.
+ */
+export async function deploy(root, workspaceUuid, executors) {
+    const prior = readState(root);
+    // Refuse a state bound to a different workspace — deploying it would create
+    // and orphan resources across workspaces. (The CLI enforces this too; keeping
+    // it in the engine protects programmatic/host callers.) Checked before the
+    // resource files load, so it fails fast.
+    if (prior !== undefined && prior.workspaceUuid !== workspaceUuid) {
+        throw new Error(`cargo.state.json belongs to workspace ${prior.workspaceUuid}, not the ` +
+            `selected ${workspaceUuid} — refusing to deploy (would orphan resources).`);
+    }
+    const nodes = await loadResources(root);
+    const state = prior ?? emptyState(workspaceUuid);
+    const result = await apply({ nodes, state }, executors, (next) => writeState(root, next));
+    return {
+        state: result.state,
+        applied: result.applied.filter((e) => e.change === "create").length,
+        updated: result.applied.filter((e) => e.change === "update").length,
+        skipped: result.skipped.length,
+    };
+}

package/build/src/deploy/load.d.ts

@@ -0,0 +1,7 @@
+import { type ResourceNode } from "../core.js";
+/**
+ * Reset the registry, import every resource module under `root` (which registers
+ * each define*'d resource), and return the registered nodes.
+ */
+export declare function loadResources(root: string): Promise<ResourceNode[]>;
+//# sourceMappingURL=load.d.ts.map

package/build/src/deploy/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/deploy/load.ts"],"names":[],"mappings":"AASA,OAAO,EAAiB,KAAK,YAAY,EAAa,MAAM,YAAY,CAAC;AA+BzE;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAmBzE"}

package/build/src/deploy/load.js

@@ -0,0 +1,58 @@
+// Loads a Cargo repo: imports every resource `.ts` file under a root directory,
+// transpiled on the fly via the tsx ESM loader. Each `define*` call registers
+// its resource into the core module's registry as a side effect of being
+// imported, so loading IS discovery — there is no manifest to read.
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { resetRegistry, resources } from "../core.js";
+function tsFilesIn(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        if (entry.startsWith(".") ||
+            entry === "node_modules" ||
+            entry === "build") {
+            continue;
+        }
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory()) {
+            // A nested package.json marks a sub-bundle (worker/app runtime code,
+            // referenced by `defineWorker`/`defineApp` via its path). Its files are
+            // deployed by upload, not imported as resource definitions — skip them.
+            if (existsSync(join(full, "package.json")))
+                continue;
+            out.push(...tsFilesIn(full));
+        }
+        else if (entry.endsWith(".ts") &&
+            !entry.endsWith(".test.ts") &&
+            !entry.endsWith(".d.ts")) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+/**
+ * Reset the registry, import every resource module under `root` (which registers
+ * each define*'d resource), and return the registered nodes.
+ */
+export async function loadResources(root) {
+    const rootDir = isAbsolute(root) ? root : resolve(process.cwd(), root);
+    if (!existsSync(rootDir)) {
+        throw new Error(`Resource directory not found: ${rootDir}`);
+    }
+    resetRegistry();
+    // Load each resource file through tsx's `tsImport`, which transpiles .ts on the
+    // fly and works whether @cargo-ai/cdk runs from source (monorepo) or as a built,
+    // installed package — unlike a process-wide `register()` + plain `import()`,
+    // which trips Node's require(esm)-cycle guard when a resource file imports the
+    // already-loaded built package. tsImport cache-busts, so a file imported both
+    // directly and transitively evaluates twice; `register()` dedupes that by hash,
+    // so each resource still lands once.
+    const { tsImport } = await import("tsx/esm/api");
+    for (const file of tsFilesIn(rootDir).sort()) {
+        await tsImport(pathToFileURL(file).href, import.meta.url);
+    }
+    return resources();
+}

package/build/src/deploy/lock.d.ts

@@ -0,0 +1,10 @@
+export type Lock = {
+    release: () => void;
+};
+/**
+ * Acquire the state lock for `root`. Throws if another live run holds it (unless
+ * `force`). Releases automatically on process exit; the returned `release` lets
+ * callers free it early. Stale locks (dead holder) are stolen.
+ */
+export declare function acquireLock(root: string, command: string, force?: boolean): Lock;
+//# sourceMappingURL=lock.d.ts.map

package/build/src/deploy/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../src/deploy/lock.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AAsC3C;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,UAAQ,GACZ,IAAI,CA6DN"}

package/build/src/deploy/lock.js

@@ -0,0 +1,101 @@
+// A coarse advisory lock around the committed cargo.state.json so two concurrent
+// deploy/destroy/import runs can't interleave writes and corrupt it. The lock is
+// a sibling `cargo.state.lock` file holding the holder's pid/host/time; it is
+// created atomically (O_EXCL) and released on process exit. A lock whose holder
+// is no longer alive (same host) or older than STALE_MS (cross host) is stolen,
+// so a crashed run never wedges the repo.
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+const LOCK_FILE = "cargo.state.lock";
+const STALE_MS = 60 * 60 * 1000; // 1h
+function lockPath(root) {
+    const dir = isAbsolute(root) ? root : resolve(process.cwd(), root);
+    return join(dir, LOCK_FILE);
+}
+function readLock(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+// Is the lock still held by a live process? Same-host: probe the pid. Cross-host:
+// we can't, so fall back to age.
+function isHeld(info) {
+    if (info.host === hostname()) {
+        try {
+            process.kill(info.pid, 0);
+            return true;
+        }
+        catch (error) {
+            // EPERM → pid exists but isn't ours (still held); ESRCH → gone.
+            return error.code === "EPERM";
+        }
+    }
+    const age = Date.now() - Date.parse(info.startedAt);
+    return Number.isFinite(age) && age < STALE_MS;
+}
+/**
+ * Acquire the state lock for `root`. Throws if another live run holds it (unless
+ * `force`). Releases automatically on process exit; the returned `release` lets
+ * callers free it early. Stale locks (dead holder) are stolen.
+ */
+export function acquireLock(root, command, force = false) {
+    const path = lockPath(root);
+    const me = {
+        pid: process.pid,
+        host: hostname(),
+        startedAt: new Date().toISOString(),
+        command,
+    };
+    const payload = `${JSON.stringify(me, null, 2)}\n`;
+    let attempts = 0;
+    for (;;) {
+        try {
+            writeFileSync(path, payload, { flag: "wx" }); // atomic create-or-fail
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            // The lock file exists (EEXIST). Only steal it when we can positively
+            // confirm it's free, or the caller forced it.
+            const existing = readLock(path);
+            if (!force) {
+                if (existing === undefined) {
+                    // Present but unreadable — a live holder mid-write, or a corrupt
+                    // file. Fail closed: never steal a lock we can't inspect.
+                    throw new Error(`cargo.state is locked — cargo.state.lock exists but couldn't be read ` +
+                        `(another run may be writing it, or it's corrupt). If no run is ` +
+                        `active, re-run with --force.`);
+                }
+                if (isHeld(existing)) {
+                    throw new Error(`cargo.state is locked by '${existing.command}' (pid ${existing.pid} on ${existing.host}) since ${existing.startedAt}. ` +
+                        `If that run is no longer active, re-run with --force.`);
+                }
+            }
+            rmSync(path, { force: true }); // forced, or readable + confirmed stale
+            attempts += 1;
+            if (attempts > 5) {
+                throw new Error("could not acquire the cargo.state lock");
+            }
+        }
+    }
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        const current = readLock(path);
+        if (current !== undefined &&
+            current.pid === me.pid &&
+            current.host === me.host) {
+            rmSync(path, { force: true });
+        }
+    };
+    // Covers both normal completion and the CLI's process.exit-based failures.
+    process.on("exit", release);
+    return { release };
+}

package/build/src/deploy/plan.d.ts

@@ -0,0 +1,3 @@
+import type { CompileResult } from "./compile.js";
+export declare function formatPlan(result: CompileResult): string;
+//# sourceMappingURL=plan.d.ts.map

package/build/src/deploy/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/deploy/plan.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAc,aAAa,EAAa,MAAM,cAAc,CAAC;AAazE,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAoCxD"}

package/build/src/deploy/plan.js

@@ -0,0 +1,39 @@
+// Human-readable formatting of a CompileResult — the `cargo-ai framework plan`
+// output. Pure (string in / string out) so it is unit-testable.
+const SYMBOL = {
+    create: "+",
+    update: "~",
+    noop: "=",
+    delete: "-",
+};
+function line(entry) {
+    return `  ${SYMBOL[entry.change]} ${entry.change.padEnd(6)} ${entry.id}`;
+}
+export function formatPlan(result) {
+    const out = [];
+    if (result.errors.length > 0) {
+        out.push("Validation errors:");
+        for (const error of result.errors) {
+            out.push(`  ✗ ${error.id}: ${error.message}`);
+        }
+        out.push("");
+        out.push("Plan aborted — fix the errors above.");
+        return out.join("\n");
+    }
+    if (result.plan.length === 0) {
+        return "No resources found.";
+    }
+    out.push("Plan (apply order):");
+    for (const entry of result.plan)
+        out.push(line(entry));
+    const counts = result.plan.reduce((acc, entry) => {
+        acc[entry.change] += 1;
+        return acc;
+    }, { create: 0, update: 0, noop: 0, delete: 0 });
+    out.push("");
+    const summary = `${String(counts.create)} to create, ${String(counts.update)} to update, ${String(counts.noop)} unchanged`;
+    out.push(counts.delete > 0
+        ? `${summary}, ${String(counts.delete)} to prune.`
+        : `${summary}.`);
+    return out.join("\n");
+}

package/build/src/deploy/readers.live.d.ts

@@ -0,0 +1,4 @@
+import type { Api } from "@cargo-ai/api";
+import { type LiveReaders } from "./refresh.js";
+export declare function liveReaders(api: Api): LiveReaders;
+//# sourceMappingURL=readers.live.d.ts.map

package/build/src/deploy/readers.live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readers.live.d.ts","sourceRoot":"","sources":["../../../src/deploy/readers.live.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAA8B,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAoD5E,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,WAAW,CAoOjD"}