@cargo-ai/cdk 1.0.4 → 1.0.6

package/build/src/cli/typesCommand.js

@@ -1,385 +0,0 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { printJsonSchemaInput, printJsonSchemaType } from "./inputTypes.js";
-import { handleApiCall, info, success } from "./io.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;
-}