@cargo-ai/cdk 1.0.11 → 1.0.12

package/build/src/deploy/pull/mappers.js

@@ -0,0 +1,689 @@
+// Pure live-row → IRResource mappers, one per supported kind. These invert the
+// stored-spec field renames the define* builders apply (integrationSlug →
+// integration, datasetUuid → dataset, extractorSlug → extractSlug, modelUuid →
+// model, folderUuid → folder, parentUuid → parent, …) and embed RefMarker /
+// SecretMarker where a raw value can't be printed as JSON.
+//
+// Unlike the drift readers (readers.live.ts), which project only the *updatable*
+// fields, these emit the full *create* spec — including immutable fields like
+// folder.kind — because the generated code must reproduce the resource, not just
+// its editable surface.
+//
+// A mapper returns `null` when the live resource can't be faithfully expressed by
+// its define* (e.g. a unified model, which has no source connector) — the caller
+// skips and reports it rather than emitting code that wouldn't deploy.
+//
+// Rule for optional fields: include iff the live value is non-null/defined. A
+// null live field maps to the define* default (also null), so omitting it keeps
+// the content hash identical — which is what makes a post-pull `plan` a no-op.
+import { deepOmit } from "../readers.live.js";
+import { call, isCallMarker, isRefMarker, isSecretMarker, ref, } from "./ir.js";
+function defined(value) {
+    return value !== null && value !== undefined;
+}
+// Markers are opaque leaves to spec normalization — a call marker's workflow
+// wire nodes keep their canvas positions etc. (draftRelease.deploy expects the
+// full graph back), and a ref's fallback expression ships verbatim.
+function isMarker(value) {
+    return isRefMarker(value) || isSecretMarker(value) || isCallMarker(value);
+}
+// Strip the shared VOLATILE keys (per-resource ids, canvas coords) that leak
+// into config/schedule, so the generated spec is stable and hash-matches the
+// drift readers' projection.
+function stripVolatile(value) {
+    return deepOmit(value, isMarker);
+}
+// Derive a valid define* slug from a name (for kinds with no server slug, e.g.
+// folders). Base slug rule: /^[a-z0-9][a-z0-9_-]*$/.
+function slugify(name) {
+    const base = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (base.length === 0)
+        return "resource";
+    return /^[0-9]/.test(base) ? `f_${base}` : base;
+}
+// Name for kinds with no server-side slug — the slug is derived from it.
+function nameOr(row, fallback) {
+    return defined(row["name"]) ? String(row["name"]) : fallback;
+}
+// What can print as bare property access / a bare object key.
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function screaming(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/[^A-Za-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .toUpperCase();
+}
+function isEncryptionEnvelope(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.type === "encryption");
+}
+// Replace every encrypted credential field in a connector config with a
+// `secret("NAME")` placeholder — the plaintext is never returned by the API.
+function maskSecrets(value, slug, path) {
+    if (isEncryptionEnvelope(value)) {
+        const marker = {
+            __secret: true,
+            envName: [screaming(slug), ...path.map(screaming)].join("_"),
+        };
+        return marker;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => maskSecrets(item, slug, [...path, String(index)]));
+    }
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [key, inner] of Object.entries(value)) {
+            out[key] = maskSecrets(inner, slug, [...path, key]);
+        }
+        return out;
+    }
+    return value;
+}
+// Assign `spec[key] = value` only when the live value is meaningful (non-nullish).
+function put(spec, key, value) {
+    if (defined(value))
+        spec[key] = value;
+}
+// The pervasive `<key>Uuid → handle-or-literal` inversion: assign a ref marker
+// when the live row carries a uuid, omit otherwise.
+function putRef(spec, key, uuid, fallbackFn) {
+    if (typeof uuid === "string")
+        spec[key] = ref(uuid, fallbackFn);
+}
+// Omit a define-time default so simple resources stay minimal (and the content
+// hash matches the define* default).
+function putUnlessDefault(spec, key, value, defaultValue) {
+    if (defined(value) && value !== defaultValue)
+        spec[key] = value;
+}
+// Copy a row keeping only non-nullish fields (the optional-field rule).
+function cleanRow(row) {
+    const out = {};
+    for (const [key, value] of Object.entries(row))
+        put(out, key, value);
+    return out;
+}
+// Where a pulled file's content lives, derived from its (dedupe-final) slug.
+// Shared with generateFiles' post-dedupe fixup so the rule has one home.
+export function fileAssetPath(slug, sourceName) {
+    const extension = /\.[A-Za-z0-9]+$/.exec(sourceName);
+    return `files/assets/${slug}${extension === null ? "" : extension[0]}`;
+}
+const connector = (row) => {
+    const slug = String(row["slug"]);
+    const spec = { integration: row["integrationSlug"] };
+    put(spec, "name", row["name"]);
+    const config = row["config"];
+    if (defined(config))
+        spec["config"] = maskSecrets(config, slug, []);
+    put(spec, "rateLimit", row["rateLimit"]);
+    put(spec, "cacheTtlMilliseconds", row["cacheTtlMilliseconds"]);
+    // A pulled connector's credentials are never recoverable (secrets are masked),
+    // so the generated code links the live connector instead of re-creating it.
+    spec["adopt"] = true;
+    return { kind: "connector", slug, uuid: String(row["uuid"]), spec };
+};
+// Native models produced by unification (not user-authored — the backend
+// rejects creating models with these extractors, they come from syncUnifyModel).
+export const UNIFY_EXTRACTOR_SLUGS = new Set([
+    "unifyAccounts",
+    "unifyAccountEvents",
+    "unifyContacts",
+    "unifyContactEvents",
+]);
+const model = (row) => {
+    // A unify model is auto-generated from its sources' unification config — it
+    // can't be created through the API, so it can't be represented in code. Skip.
+    if (UNIFY_EXTRACTOR_SLUGS.has(String(row["extractorSlug"])))
+        return null;
+    const slug = String(row["slug"]);
+    const spec = {};
+    put(spec, "name", row["name"]);
+    put(spec, "description", row["description"]);
+    const connectorUuid = row["connectorUuid"];
+    const datasetUuid = row["datasetUuid"];
+    if (typeof connectorUuid === "string") {
+        // Authored as the source connector's handle; if that connector isn't in the
+        // pull, fall back to a literal datasetRef(datasetUuid).
+        spec["dataset"] = ref(connectorUuid, "datasetRef", {
+            fallbackUuid: typeof datasetUuid === "string" ? datasetUuid : connectorUuid,
+        });
+    }
+    else {
+        // A native model (kind "native" — no connectorUuid key at all) has no
+        // connector to reference: a dataset uuid never matches a pulled resource,
+        // so this always prints as the literal datasetRef.
+        spec["dataset"] = ref(String(datasetUuid), "datasetRef");
+    }
+    put(spec, "extractSlug", row["extractorSlug"]);
+    put(spec, "config", row["config"]);
+    put(spec, "schedule", row["schedule"]);
+    putRef(spec, "folder", row["folderUuid"], "folderRef");
+    const additionalColumns = row["additionalColumns"];
+    if (Array.isArray(additionalColumns) && additionalColumns.length > 0) {
+        spec["additionalColumns"] = additionalColumns.map((column) => mapAdditionalColumn(column));
+    }
+    const unification = row["unification"];
+    // `{source:"integration"}` is every source's default — omitting it keeps the
+    // spec at the define* default (undefined = keep the source's mapping), so
+    // only a custom unification is worth authoring.
+    if (defined(unification) && unification["source"] === "custom") {
+        spec["unification"] = mapUnification(unification);
+    }
+    return { kind: "model", slug, uuid: String(row["uuid"]), spec };
+};
+// Invert `compileUnification`: everything passes through except a `model`-kind
+// parent, whose `parentModelUuid` becomes a model ref (a handle import when the
+// parent is also pulled).
+function mapUnification(unification) {
+    const spec = { source: "custom" };
+    put(spec, "type", unification["type"]);
+    put(spec, "uniqueColumns", unification["uniqueColumns"]);
+    put(spec, "selectedColumnSlugs", unification["selectedColumnSlugs"]);
+    put(spec, "timeColumnSlug", unification["timeColumnSlug"]);
+    put(spec, "filter", unification["filter"]);
+    const parent = unification["parent"];
+    if (defined(parent)) {
+        spec["parent"] =
+            parent["kind"] === "model"
+                ? {
+                    kind: "model",
+                    columnSlug: parent["columnSlug"],
+                    parent: ref(String(parent["parentModelUuid"]), "modelRef"),
+                }
+                : parent;
+    }
+    return spec;
+}
+// The spec fields each column kind accepts — live rows can carry extra server
+// fields, and passing them through would make the generated spec fail tsc.
+const COLUMN_BASE_KEYS = [
+    "kind",
+    "slug",
+    "type",
+    "label",
+    "description",
+    "properties",
+];
+const COLUMN_KEYS = {
+    custom: COLUMN_BASE_KEYS,
+    computed: [...COLUMN_BASE_KEYS, "expression", "columnsUsed"],
+    metric: [...COLUMN_BASE_KEYS, "aggregation", "filter"],
+    lookup: [...COLUMN_BASE_KEYS, "extractColumnSlug", "filter"],
+};
+// Invert `compileAdditionalColumn`. Both cross-resource references print as
+// LITERAL calls, never handle imports: a metric's relationship points back at
+// the model declaring the column, and two models' lookups can point at each
+// other — either way a handle import would be a module cycle that fails to
+// load. Only the kind's known spec fields are kept, nullish dropped (the
+// optional-field rule).
+function mapAdditionalColumn(raw) {
+    const keys = COLUMN_KEYS[String(raw["kind"])];
+    const column = {};
+    for (const key of keys === undefined ? Object.keys(raw) : keys) {
+        put(column, key, raw[key]);
+    }
+    if (column["kind"] === "metric") {
+        column["relationship"] = call("relationshipRef", [
+            String(raw["relationshipUuid"]),
+        ]);
+    }
+    if (column["kind"] === "lookup") {
+        const join = raw["join"];
+        column["join"] = {
+            model: call("modelRef", [String(join["toModelUuid"])]),
+            fromColumnSlug: join["fromColumnSlug"],
+            toColumnSlug: join["toColumnSlug"],
+        };
+    }
+    return column;
+}
+const segment = (row) => {
+    // A play's hidden backing segment is managed by the play (pull folds it into
+    // the play spec via __segment); the backend rejects direct updates to it.
+    if (row["fromPlay"] === true)
+        return null;
+    const slug = String(row["slug"]);
+    const spec = {};
+    put(spec, "name", row["name"]);
+    putRef(spec, "model", row["modelUuid"], "modelRef");
+    put(spec, "filter", row["filter"]);
+    put(spec, "sort", row["sort"]);
+    put(spec, "limit", row["limit"]);
+    put(spec, "trackingColumnSlugs", row["trackingColumnSlugs"]);
+    put(spec, "columnSlugs", row["columnSlugs"]);
+    return { kind: "segment", slug, uuid: String(row["uuid"]), spec };
+};
+const folder = (row) => {
+    const spec = {};
+    put(spec, "kind", row["kind"]); // required create field, named `kind` on the row
+    put(spec, "name", row["name"]);
+    put(spec, "emojiSlug", row["emojiSlug"]);
+    putRef(spec, "parent", row["parentUuid"], "folderRef");
+    return {
+        kind: "folder",
+        slug: slugify(nameOr(row, "folder")),
+        uuid: String(row["uuid"]),
+        spec,
+    };
+};
+const capacity = (row) => {
+    // Capacities have no server-side slug — derive one from the name.
+    const slug = slugify(nameOr(row, "capacity"));
+    const spec = {};
+    put(spec, "name", row["name"]);
+    put(spec, "color", row["color"]);
+    put(spec, "description", row["description"]);
+    putRef(spec, "model", row["modelUuid"], "modelRef");
+    put(spec, "idColumnSlug", row["idColumnSlug"]);
+    put(spec, "timeColumnSlug", row["timeColumnSlug"]);
+    put(spec, "memberCapacity", row["memberCapacity"]);
+    put(spec, "allocationExpirationPolicy", row["allocationExpirationPolicy"]);
+    put(spec, "filter", row["filter"]);
+    return { kind: "capacity", slug, uuid: String(row["uuid"]), spec };
+};
+const relationship = (row) => {
+    // Relationships auto-generated by unification (either endpoint is a unify
+    // model — flagged by enumerate, which has the model rows) aren't authorable.
+    if (row["__touchesUnifyModel"] === true)
+        return null;
+    // No server-side slug — derive a readable local id from the join columns.
+    const slug = slugify(`${String(row["fromColumnSlug"])}_to_${String(row["toColumnSlug"])}`);
+    const endpoint = (side) => {
+        const out = {
+            model: ref(String(row[`${side}ModelUuid`]), "modelRef"),
+            column: row[`${side}ColumnSlug`],
+        };
+        put(out, "property", row[`${side}PropertySlug`]);
+        return out;
+    };
+    const spec = {
+        from: endpoint("from"),
+        to: endpoint("to"),
+        relation: row["relation"],
+    };
+    return { kind: "relationship", slug, uuid: String(row["uuid"]), spec };
+};
+const customIntegration = (row) => {
+    // Only worker-backed custom integrations have a builder; the `external`
+    // (baseUrl) variant can't be expressed in code yet.
+    if (row["kind"] !== "worker")
+        return null;
+    const spec = {
+        worker: ref(String(row["workerUuid"]), "workerRef"),
+    };
+    return {
+        kind: "customIntegration",
+        slug: String(row["slug"]),
+        uuid: String(row["uuid"]),
+        spec,
+    };
+};
+const territory = (row) => {
+    // Territories have no server-side slug — derive one from the label.
+    const slug = slugify(defined(row["label"]) ? String(row["label"]) : "territory");
+    const spec = {};
+    put(spec, "label", row["label"]);
+    put(spec, "color", row["color"]);
+    put(spec, "description", row["description"]);
+    const members = row["members"];
+    if (Array.isArray(members) && members.length > 0) {
+        // Members aren't a pulled resource — always literal memberRefs.
+        spec["members"] = members.map((member) => {
+            const entry = {
+                ref: ref(String(member["uuid"]), "memberRef"),
+            };
+            put(entry, "weight", member["weight"]);
+            return entry;
+        });
+    }
+    putRef(spec, "fallback", row["fallbackMemberUuid"], "memberRef");
+    return { kind: "territory", slug, uuid: String(row["uuid"]), spec };
+};
+// A play/tool's workflow body — the deployed release's wire nodes, embedded
+// verbatim as `defineWorkflowFromNodes(slug, { nodes, formFields })`.
+function workflowCall(slug, workflow) {
+    const formFields = workflow["formFields"];
+    return call("defineWorkflowFromNodes", [
+        slug,
+        {
+            nodes: workflow["nodes"],
+            formFields: defined(formFields) ? formFields : [],
+        },
+    ]);
+}
+// Wrap a use ref with its options — a bare ref when every option is default.
+function wrapUse(refValue, opts) {
+    return Object.keys(opts).length === 0 ? refValue : { ref: refValue, ...opts };
+}
+// A release's connector action, in the friendliest printable form: the typed
+// `hubspot.actions.emailFinder` accessor when the connector is pulled AND the
+// slug is identifier-safe (a kebab-case slug as bare property access would be
+// a syntax error); else the literal `connectorActionRef(connectorRef("uuid"),
+// slug, integration)`. A null connectorUuid (integration default) has no ref
+// helper — emit the raw ConnectorActionRef object shape.
+function connectorActionMarker(connectorUuid, actionSlug, integration) {
+    if (typeof connectorUuid !== "string") {
+        return { resource: "connectorAction", integration, actionSlug };
+    }
+    const literal = call("connectorActionRef", [
+        call("connectorRef", [connectorUuid]),
+        actionSlug,
+        integration,
+    ]);
+    if (!IDENTIFIER.test(actionSlug))
+        return literal;
+    return ref(connectorUuid, "connectorActionRef", {
+        accessor: `.actions.${actionSlug}`,
+        fallbackExpr: literal,
+    });
+}
+// Invert `normalizeUses` + the executor's release mapping: re-collapse a
+// release's `resources` (data models) and `actions` (tool / agent / connector
+// kinds) into the single `uses` array defineAgent/defineMcpServer take.
+function mapUses(resources, actions) {
+    const uses = [];
+    const resourceRows = Array.isArray(resources) ? resources : [];
+    for (const resource of resourceRows) {
+        if (resource["kind"] !== "model")
+            continue;
+        const opts = {};
+        if (resource["isReadOnly"] === false)
+            opts["readOnly"] = false;
+        put(opts, "columns", resource["selectedColumnSlugs"]);
+        put(opts, "prompt", resource["prompt"]);
+        uses.push(wrapUse(ref(String(resource["modelUuid"]), "modelRef"), opts));
+    }
+    const actionRows = Array.isArray(actions) ? actions : [];
+    for (const action of actionRows) {
+        const opts = {};
+        put(opts, "name", action["name"]);
+        put(opts, "description", action["description"]);
+        if (action["isBulkAllowed"] === true)
+            opts["isBulkAllowed"] = true;
+        if (action["kind"] === "tool" || action["kind"] === "agent") {
+            if (action["waitUntilFinished"] === false) {
+                opts["waitUntilFinished"] = false;
+            }
+            const marker = action["kind"] === "tool"
+                ? ref(String(action["toolUuid"]), "toolRef")
+                : ref(String(action["agentUuid"]), "agentRef");
+            uses.push(wrapUse(marker, opts));
+            continue;
+        }
+        if (action["kind"] === "connector") {
+            const config = action["config"];
+            if (defined(config) && Object.keys(config).length > 0) {
+                opts["config"] = config;
+            }
+            const marker = connectorActionMarker(action["connectorUuid"], String(action["actionSlug"]), String(action["integrationSlug"]));
+            uses.push(wrapUse(marker, opts));
+        }
+    }
+    return uses;
+}
+// Live tool trigger rows carry executor-side defaults (name falls back to the
+// cron expression, data to {}); invert both so the spec stays minimal.
+function mapToolTriggers(triggers) {
+    const rows = Array.isArray(triggers) ? triggers : [];
+    if (rows.length === 0)
+        return undefined;
+    return rows.map((trigger) => {
+        const out = { cron: trigger["cron"] };
+        if (trigger["name"] !== trigger["cron"])
+            put(out, "name", trigger["name"]);
+        put(out, "description", trigger["description"]);
+        const data = trigger["data"];
+        if (defined(data) && Object.keys(data).length > 0)
+            out["data"] = data;
+        return out;
+    });
+}
+const tool = (row) => {
+    // Template-installed tools are read-only; a tool with no deployed release
+    // (enumerate attaches __workflow) has no body to reproduce.
+    if (row["isReadOnly"] === true)
+        return null;
+    const workflow = row["__workflow"];
+    if (!defined(workflow))
+        return null;
+    const slug = slugify(nameOr(row, "tool"));
+    const spec = {};
+    put(spec, "name", row["name"]);
+    put(spec, "description", row["description"]);
+    const icon = row["icon"];
+    if (defined(icon))
+        put(spec, "emojiSlug", icon["emojiSlug"]);
+    putRef(spec, "folder", row["folderUuid"], "folderRef");
+    put(spec, "triggers", mapToolTriggers(row["triggers"]));
+    put(spec, "publicForm", row["publicForm"]);
+    spec["workflow"] = workflowCall(slug, workflow);
+    return { kind: "tool", slug, uuid: String(row["uuid"]), spec };
+};
+// Invert `toWireSchedule`: a dependency schedule's playUuid becomes a play ref;
+// a watch schedule's server-managed `meta` is dropped.
+function mapPlaySchedule(schedule) {
+    if (schedule["type"] === "dependency") {
+        return {
+            type: "dependency",
+            play: ref(String(schedule["playUuid"]), "playRef"),
+        };
+    }
+    const { meta: _meta, ...rest } = schedule;
+    return cleanRow(rest);
+}
+const play = (row) => {
+    const slug = slugify(nameOr(row, "play"));
+    const spec = {};
+    put(spec, "name", row["name"]);
+    put(spec, "description", row["description"]);
+    spec["model"] = ref(String(row["modelUuid"]), "modelRef");
+    // Omit define-time defaults so simple plays stay minimal.
+    const changeKinds = row["changeKinds"];
+    if (Array.isArray(changeKinds) &&
+        JSON.stringify(changeKinds) !== JSON.stringify(["added"])) {
+        spec["changeKinds"] = changeKinds;
+    }
+    putUnlessDefault(spec, "runCreationRule", row["runCreationRule"], "always");
+    // filter/sort/limit/trackingColumnSlugs live on the play's backing segment —
+    // enumerate attaches that row as __segment.
+    const segmentRow = row["__segment"];
+    if (defined(segmentRow)) {
+        put(spec, "filter", segmentRow["filter"]);
+        put(spec, "sort", segmentRow["sort"]);
+        put(spec, "limit", segmentRow["limit"]);
+        put(spec, "trackingColumnSlugs", segmentRow["trackingColumnSlugs"]);
+    }
+    const schedule = row["schedule"];
+    if (defined(schedule))
+        spec["schedule"] = mapPlaySchedule(schedule);
+    putRef(spec, "folder", row["folderUuid"], "folderRef");
+    const workflow = row["__workflow"];
+    if (defined(workflow))
+        spec["workflow"] = workflowCall(slug, workflow);
+    return { kind: "play", slug, uuid: String(row["uuid"]), spec };
+};
+const mcpServer = (row) => {
+    // Template-installed servers aren't user-authored config.
+    if (defined(row["templateSlug"]))
+        return null;
+    if (row["isReadOnly"] === true)
+        return null;
+    const slug = slugify(nameOr(row, "mcp_server"));
+    const spec = {};
+    put(spec, "name", row["name"]);
+    put(spec, "description", row["description"]);
+    const uses = mapUses(row["resources"], row["actions"]);
+    if (uses.length > 0)
+        spec["uses"] = uses;
+    putRef(spec, "folder", row["folderUuid"], "folderRef");
+    return { kind: "mcpServer", slug, uuid: String(row["uuid"]), spec };
+};
+// Invert `normalizeTriggers`: a connector trigger's connectorUuid becomes a
+// connector ref; cron triggers pass through (nullish fields dropped).
+function mapAgentTriggers(triggers) {
+    const rows = Array.isArray(triggers) ? triggers : [];
+    if (rows.length === 0)
+        return undefined;
+    return rows.map((trigger) => {
+        if (trigger["type"] !== "connector")
+            return cleanRow(trigger);
+        const { connectorUuid, ...rest } = trigger;
+        const out = cleanRow(rest);
+        putRef(out, "connector", connectorUuid, "connectorRef");
+        return out;
+    });
+}
+const agent = (row) => {
+    // An agent that was never deployed has no release — nothing to reproduce.
+    const release = row["deployedRelease"];
+    if (!defined(release))
+        return null;
+    // defineAgent (and the deploy executor) require a full LLM binding; a release
+    // without a connector (a Cargo-managed default) can't be expressed yet.
+    if (typeof release["connectorUuid"] !== "string" ||
+        typeof release["languageModelSlug"] !== "string") {
+        return null;
+    }
+    const slug = slugify(nameOr(row, "agent"));
+    const spec = {};
+    put(spec, "name", row["name"]);
+    put(spec, "description", row["description"]);
+    const icon = row["icon"];
+    if (defined(icon))
+        putUnlessDefault(spec, "color", icon["color"], "grey");
+    putRef(spec, "connector", release["connectorUuid"], "connectorRef");
+    put(spec, "languageModel", release["languageModelSlug"]);
+    put(spec, "systemPrompt", release["systemPrompt"]);
+    // Omit define-time defaults (temperature 0.2, maxSteps 8, reasoning off).
+    putUnlessDefault(spec, "temperature", release["temperature"], 0.2);
+    putUnlessDefault(spec, "maxSteps", release["maxSteps"], 8);
+    if (release["withReasoning"] === true)
+        spec["withReasoning"] = true;
+    const capabilities = release["capabilities"];
+    if (Array.isArray(capabilities) && capabilities.length > 0) {
+        spec["capabilities"] = capabilities;
+    }
+    put(spec, "triggers", mapAgentTriggers(row["triggers"]));
+    const uses = mapUses(release["resources"], release["actions"]);
+    if (uses.length > 0)
+        spec["uses"] = uses;
+    const mcpClients = release["mcpClients"];
+    if (Array.isArray(mcpClients) && mcpClients.length > 0) {
+        spec["mcpClients"] = mcpClients;
+    }
+    const output = release["output"];
+    // {type:"text"} is the define default.
+    if (defined(output) && output["type"] !== "text")
+        spec["output"] = output;
+    put(spec, "heartbeat", release["heartbeat"]);
+    put(spec, "evaluator", release["evaluator"]);
+    putRef(spec, "folder", row["folderUuid"], "folderRef");
+    return { kind: "agent", slug, uuid: String(row["uuid"]), spec };
+};
+// ── code-backed kinds: the define references files written alongside it ──────
+const file = (row) => {
+    // Content downloaded by enumerate; unreadable file → nothing to author.
+    const bytes = row["__bytes"];
+    if (!(bytes instanceof Uint8Array))
+        return null;
+    const name = nameOr(row, "file");
+    const slug = slugify(name);
+    const assetPath = fileAssetPath(slug, name);
+    const spec = { path: assetPath };
+    put(spec, "name", row["name"]);
+    putRef(spec, "folder", row["folderUuid"], "folderRef");
+    return {
+        kind: "file",
+        slug,
+        uuid: String(row["uuid"]),
+        spec,
+        assets: [{ path: assetPath, bytes }],
+    };
+};
+// Shared by worker/app: the promoted deployment's source tree (downloaded and
+// extracted by enumerate) is written under `<dir>/<slug>/` and referenced as
+// the bundle `path`. Env-var VALUES are not recoverable from the API, so `env`
+// is omitted — fill it in before changing and re-deploying the bundle.
+function hostingMapper(kind, dir) {
+    return (row) => {
+        const sourceFiles = row["__sourceFiles"];
+        if (!Array.isArray(sourceFiles) || sourceFiles.length === 0)
+            return null;
+        const slug = String(row["slug"]);
+        const path = `${dir}/${slug}`;
+        const spec = { path };
+        put(spec, "name", row["name"]);
+        put(spec, "description", row["description"]);
+        putRef(spec, "folder", row["folderUuid"], "folderRef");
+        if (kind === "worker") {
+            const triggers = row["triggers"];
+            if (Array.isArray(triggers) && triggers.length > 0) {
+                spec["triggers"] = triggers.map((trigger) => cleanRow(trigger));
+            }
+        }
+        return {
+            kind,
+            slug,
+            uuid: String(row["uuid"]),
+            spec,
+            assets: sourceFiles.map((sourceFile) => ({
+                path: `${path}/${sourceFile.path}`,
+                bytes: sourceFile.bytes,
+            })),
+        };
+    };
+}
+const worker = hostingMapper("worker", "workers");
+const app = hostingMapper("app", "apps");
+const context = (row) => {
+    // The repo's markdown files, read by enumerate. An empty repo has nothing to
+    // author (and defineContext would throw on a missing dir).
+    const files = row["__files"];
+    if (files === undefined || Object.keys(files).length === 0)
+        return null;
+    const encoder = new TextEncoder();
+    return {
+        kind: "context",
+        slug: "repository",
+        uuid: String(row["uuid"]),
+        spec: { dir: "context/files" },
+        assets: Object.entries(files).map(([path, content]) => ({
+            path: `context/files/${path}`,
+            bytes: encoder.encode(content),
+        })),
+    };
+};
+export const MAPPERS = {
+    connector,
+    customIntegration,
+    model,
+    relationship,
+    segment,
+    folder,
+    capacity,
+    territory,
+    tool,
+    play,
+    mcpServer,
+    agent,
+    file,
+    worker,
+    app,
+    context,
+};
+export function mapRow(kind, row) {
+    const mapper = MAPPERS[kind];
+    if (mapper === undefined) {
+        throw new Error(`cdk pull: no mapper for kind "${kind}"`);
+    }
+    const ir = mapper(row);
+    if (ir === null)
+        return null;
+    return { ...ir, spec: stripVolatile(ir.spec) };
+}