@cargo-ai/cdk 1.0.5 → 1.0.7

package/README.md

@@ -3,7 +3,7 @@
 Define your entire Cargo workspace in code — connectors, models, plays, tools,
 agents, MCP servers, context, segments, capacities, territories, folders, files, workers and apps — and deploy it
 declaratively, the same way you'd manage cloud infrastructure with Pulumi or the
-AWS CDK. For a complete overview, see the [Cargo CDK docs](https://docs.getcargo.ai/cdk/overview).
+AWS CDK. For a complete overview, see the [Cargo CDK docs](https://docs.getcargo.ai/get-started/project-layout).
 
 ## Requirements
 
@@ -51,6 +51,9 @@ no global install:
 npx @cargo-ai/cdk init my-workspace --template full  # every resource type, wired up
 # or: npx @cargo-ai/cdk init my-workspace             # minimal 'blank' template
 # or: npx @cargo-ai/cdk init --list-templates         # see all templates
+# or: npx @cargo-ai/cdk init my-tam --from getcargohq/cargo-cookbooks/signal-based-tam
+#     scaffold from a GitHub source (owner/repo[/folder][@ref]); a cookbook
+#     folder also pulls its required siblings via the repo's cargo.scaffold.json
 cd my-workspace && npm install
 ```
 
@@ -130,15 +133,19 @@ const flow = defineWorkflow("enrich", { input, output }, ({ input, ai }) => …)
 export const enrich = defineTool("enrich", { workflow: flow, emojiSlug: "mag" });
 
 export const sdr = defineAgent("sdr", {
-  connector: openai,                              // handle (or connectorRef("…"))
+  connector: openai,                              // the LLM connector (or connectorRef("…"))
   languageModel: "gpt-4o",
   systemPrompt: "Qualify inbound leads.",
-  models: [{ ref: contacts, readOnly: true }],    // handle + options
-  tools: [enrich],                                // bare handle
+  // everything the agent can call or read — one array, kind inferred per handle
+  uses: [
+    { ref: contacts, readOnly: true },            // a data model (handle + options)
+    enrich,                                        // a tool (bare handle)
+    hunter.actions.findEmail,                              // an action off a connector handle
+  ],
 });
 ```
 
-See [Defining Resources](https://docs.getcargo.ai/cdk/resources) for every
+See [Defining Resources](https://docs.getcargo.ai/connectors/overview) for every
 builder (connectors, models, plays, tools, agents, MCP servers, context, segments,
 capacities, territories, folders, files, workers, apps) and the slug rules.
 
@@ -161,6 +168,49 @@ There is one context repo per workspace, so this is a singleton. On deploy it
 writes each changed file into the repo via the runtime — **additive**: files
 added elsewhere (the UI, other tooling) are left in place.
 
+### Unification
+
+A model can declare how it feeds Cargo's unified `Account` / `Contact` /
+`AccountEvent` / `ContactEvent` models. A connector model defaults to its
+integration's built-in mapping (`{ source: "integration" }`), so you only pass
+`unification` to override it or to unify a model the integration doesn't map on
+its own. A `custom` unification maps columns to shared references (`domain`,
+`email`, `linkedinId`, …) and can link a child to its parent by pointing at
+another model handle:
+
+```ts
+import { defineModel } from "@cargo-ai/cdk";
+
+export const accounts = defineModel("accounts", {
+  dataset: warehouse,
+  extractSlug: "runQuery",
+  unification: {
+    source: "custom",
+    type: "account",
+    uniqueColumns: [{ slug: "website", reference: "domain" }],
+  },
+});
+
+export const contacts = defineModel("contacts", {
+  dataset: warehouse,
+  extractSlug: "runQuery",
+  unification: {
+    source: "custom",
+    type: "contact",
+    uniqueColumns: [{ slug: "work_email", reference: "workEmail" }],
+    // link each contact to its unified account — pass the model handle, not a uuid
+    parent: { kind: "model", columnSlug: "account_id", parent: accounts },
+  },
+});
+```
+
+Unification isn't part of the create call, so the CDK applies it with a
+follow-up update once the model exists — including models the deploy adopts.
+Passing a parent handle makes the child depend on the parent, so the parent is
+created first and its uuid is injected. See
+[Unification](https://docs.getcargo.ai/models/unification) for the reference and
+priority rules.
+
 ## Commands
 
 In a scaffolded project, the everyday commands are `npm run` scripts:
@@ -174,7 +224,7 @@ npm run deploy    # create/update resources, write cargo.state.json
 Run any command — including the ones without a script — with `npx @cargo-ai/cdk`:
 
 ```bash
-npx @cargo-ai/cdk init <directory>      # scaffold from a template (--template, --list-templates)
+npx @cargo-ai/cdk init <directory>      # scaffold from a template (--template, --list-templates) or GitHub (--from owner/repo[/folder][@ref])
 npx @cargo-ai/cdk deploy --prune        # also delete resources removed from code
 npx @cargo-ai/cdk deploy --refresh      # re-read live resources, re-apply out-of-band changes
 npx @cargo-ai/cdk refresh               # read-only: report resources that drifted from code
@@ -189,7 +239,7 @@ CLI installed — same engine, same login.
 
 Common flags: `--dir <path>`, `--yes` (skip the prompt — required in CI),
 `--json`, and `--force` (steal a stale state lock). See
-[Deploying](https://docs.getcargo.ai/cdk/deploying).
+[Deploying](https://docs.getcargo.ai/deploy/deploying).
 
 ## State & drift
 
@@ -210,8 +260,8 @@ cargo.state.audit.jsonl
 
 `npx @cargo-ai/cdk refresh` reports resources changed or deleted outside the CDK
 (e.g. edited in the Cargo UI); `npx @cargo-ai/cdk deploy --refresh` re-applies your
-code over them. See [State & Drift](https://docs.getcargo.ai/cdk/state-and-drift).
+code over them. See [State & Drift](https://docs.getcargo.ai/deploy/state-and-drift).
 
 ## Documentation
 
-Full documentation: [docs.getcargo.ai/cdk](https://docs.getcargo.ai/cdk/overview).
+Full documentation: [docs.getcargo.ai/cdk](https://docs.getcargo.ai/get-started/project-layout).

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

@@ -0,0 +1,65 @@
+import { z } from "zod";
+export type FromRef = {
+    owner: string;
+    repo: string;
+    /** Repo-relative folder to scaffold ("" = the whole repo). */
+    subPath: string;
+    /** Branch or tag ("" = the repo's default branch). */
+    gitRef: string;
+};
+/** Reject absolute paths, `..`, `.`, and empty segments in repo-relative paths. */
+export declare function assertSafeRepoRelativePath(repoRelativePath: string, label: string): void;
+/** Join `relativePath` under `baseDir` and ensure the result cannot escape it. */
+export declare function resolveWithin(baseDir: string, relativePath: string): string;
+/**
+ * Parse a `--from` source. Accepts `owner/repo[/sub/path][@ref]`, the same
+ * with a `github.com` / `git@github.com:` prefix, and GitHub tree URLs
+ * (`github.com/owner/repo/tree/<ref>/<sub/path>`). Returns `undefined` when
+ * the source doesn't name a GitHub repo.
+ */
+export declare function parseFromRef(raw: string): FromRef | undefined;
+declare const manifestSchema: z.ZodObject<{
+    shared: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    folders: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        requires: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ScaffoldManifest = z.infer<typeof manifestSchema>;
+export declare const MANIFEST_FILENAME = "cargo.scaffold.json";
+/** Read and validate `cargo.scaffold.json` at the repo root, if present. */
+export declare function readManifest(repoDir: string): Promise<ScaffoldManifest | undefined>;
+export type CopyPlan = {
+    /** Repo-relative folders to copy, keeping their path under the target. */
+    folders: string[];
+    /** Repo-relative files to copy, keeping their path under the target. */
+    files: string[];
+    /** When true, the single folder's CONTENTS land at the target root. */
+    flatten: boolean;
+};
+/**
+ * Decide what to copy. A manifest-declared folder keeps the repo layout and
+ * brings its transitive `requires` plus the shared root files; anything else
+ * is a flat copy of the requested folder (or the whole repo).
+ */
+export declare function planCopies(manifest: ScaffoldManifest | undefined, subPath: string): CopyPlan;
+/**
+ * Shallow-clone the repo into a temp dir. Returns the dir and its cleanup.
+ * `remoteUrl` overrides the GitHub URL (tests clone from a local repo).
+ */
+export declare function cloneGitHubRepo(ref: FromRef, remoteUrl?: string): Promise<{
+    dir: string;
+    cleanup: () => Promise<void>;
+}>;
+/**
+ * Fetch the source and copy the planned folders/files into `targetDir`,
+ * substituting `__APP_NAME__`. Returns the copied repo-relative paths.
+ */
+export declare function scaffoldFromGitHub(payload: {
+    ref: FromRef;
+    targetDir: string;
+    appName: string;
+    /** Test-only override — clone from this URL/path instead of github.com. */
+    remoteUrl?: string;
+}): Promise<string[]>;
+export {};
+//# sourceMappingURL=from.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"from.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/from.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,MAAM,MAAM,OAAO,GAAG;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAIF,mFAAmF;AACnF,wBAAgB,0BAA0B,CACxC,gBAAgB,EAAE,MAAM,EACxB,KAAK,EAAE,MAAM,GACZ,IAAI,CAeN;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAW3E;AA0BD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAqD7D;AAED,QAAA,MAAM,cAAc;;;;;iBAKlB,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE9D,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD,4EAA4E;AAC5E,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAoCvC;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,OAAO,EAAE,MAAM,GACd,QAAQ,CAkBV;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,OAAO,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CA8BxD;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,GAAG,EAAE,OAAO,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsDpB"}

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

@@ -0,0 +1,275 @@
+// `cdk init <dir> --from <source>` — scaffold from a GitHub repo instead of a
+// bundled template. The source names a repo or a folder inside one
+// (`owner/repo`, `owner/repo/folder`, `owner/repo/folder@ref`, or a
+// github.com URL). The repo is fetched with a shallow `git clone`, so private
+// sources work through the user's existing git auth.
+//
+// The manifest is OPTIONAL — any repo/folder scaffolds without it. A repo of
+// composable folders (e.g. cargo-cookbooks) can ship a `cargo.scaffold.json`
+// at its root to declare cross-folder dependencies:
+//
+//   {
+//     "shared": ["package.json", "tsconfig.json"],
+//     "folders": { "signal-based-tam": { "requires": ["base-gtm"] } }
+//   }
+//
+// When the requested folder is declared there, the scaffold keeps the repo's
+// folder layout and also copies its `requires` folders (transitively) plus the
+// `shared` root files — so cross-folder imports like
+// `../base-gtm/models/accounts` keep resolving. Any other source copies the
+// folder's contents flat into the target directory.
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { copyDirectory } from "./templates.js";
+const execFileAsync = promisify(execFile);
+const SEGMENT_PATTERN = /^[\w][\w.-]*$/;
+/** Reject absolute paths, `..`, `.`, and empty segments in repo-relative paths. */
+export function assertSafeRepoRelativePath(repoRelativePath, label) {
+    if (repoRelativePath === "") {
+        return;
+    }
+    if (isAbsolute(repoRelativePath)) {
+        throw new Error(`Invalid ${label}: absolute paths are not allowed.`);
+    }
+    const segments = repoRelativePath.split(/[/\\]/);
+    for (const segment of segments) {
+        if (segment === "" || segment === "." || segment === "..") {
+            throw new Error(`Invalid ${label}: "${repoRelativePath}" contains an unsafe path segment.`);
+        }
+    }
+}
+/** Join `relativePath` under `baseDir` and ensure the result cannot escape it. */
+export function resolveWithin(baseDir, relativePath) {
+    const resolvedBase = resolve(baseDir);
+    const resolved = resolve(resolvedBase, relativePath);
+    const rel = relative(resolvedBase, resolved);
+    if (rel === "" || rel === ".") {
+        return resolvedBase;
+    }
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`Path "${relativePath}" escapes "${baseDir}".`);
+    }
+    return resolved;
+}
+function assertSafeSubPath(subPath) {
+    try {
+        assertSafeRepoRelativePath(subPath, "source folder");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function validateManifestPaths(manifest) {
+    for (const file of manifest.shared) {
+        assertSafeRepoRelativePath(file, `${MANIFEST_FILENAME} shared entry`);
+    }
+    for (const [folder, entry] of Object.entries(manifest.folders)) {
+        assertSafeRepoRelativePath(folder, `${MANIFEST_FILENAME} folder key`);
+        for (const required of entry.requires) {
+            assertSafeRepoRelativePath(required, `${MANIFEST_FILENAME} requires entry for "${folder}"`);
+        }
+    }
+}
+/**
+ * Parse a `--from` source. Accepts `owner/repo[/sub/path][@ref]`, the same
+ * with a `github.com` / `git@github.com:` prefix, and GitHub tree URLs
+ * (`github.com/owner/repo/tree/<ref>/<sub/path>`). Returns `undefined` when
+ * the source doesn't name a GitHub repo.
+ */
+export function parseFromRef(raw) {
+    const trimmed = raw.trim();
+    const isGitHubUrl = /^https?:\/\/(www\.)?github\.com\//.test(trimmed) ||
+        /^git@github\.com:/.test(trimmed);
+    const stripped = trimmed
+        .replace(/^git@github\.com:/, "")
+        .replace(/^https?:\/\/(www\.)?github\.com\//, "")
+        .replace(/\/+$/, "");
+    if (stripped.includes("://") || stripped.startsWith("git@")) {
+        return undefined;
+    }
+    const atIndex = stripped.lastIndexOf("@");
+    const path = atIndex === -1 ? stripped : stripped.slice(0, atIndex);
+    const refSuffix = atIndex === -1 ? "" : stripped.slice(atIndex + 1);
+    if (atIndex !== -1 && refSuffix === "")
+        return undefined;
+    const segments = path.split("/").filter((segment) => segment !== "");
+    const [owner, repoRaw] = segments;
+    if (owner === undefined || repoRaw === undefined)
+        return undefined;
+    const repo = repoRaw.replace(/\.git$/, "");
+    if (!SEGMENT_PATTERN.test(owner) || !SEGMENT_PATTERN.test(repo)) {
+        return undefined;
+    }
+    // A tree URL pins its ref in the path: owner/repo/tree/<ref>/<sub/path>.
+    // Only apply for full GitHub URLs — otherwise "tree" may be a real folder
+    // (e.g. owner/repo/tree/my-feature).
+    if (isGitHubUrl && segments[2] === "tree") {
+        const treeRef = segments[3];
+        if (treeRef === undefined || refSuffix !== "")
+            return undefined;
+        const subPath = segments.slice(4).join("/");
+        if (assertSafeSubPath(subPath) === false)
+            return undefined;
+        return {
+            owner,
+            repo,
+            subPath,
+            gitRef: treeRef,
+        };
+    }
+    const subPath = segments.slice(2).join("/");
+    if (assertSafeSubPath(subPath) === false)
+        return undefined;
+    return {
+        owner,
+        repo,
+        subPath,
+        gitRef: refSuffix,
+    };
+}
+const manifestSchema = z.object({
+    shared: z.array(z.string()).default([]),
+    folders: z
+        .record(z.string(), z.object({ requires: z.array(z.string()).default([]) }))
+        .default({}),
+});
+export const MANIFEST_FILENAME = "cargo.scaffold.json";
+/** Read and validate `cargo.scaffold.json` at the repo root, if present. */
+export async function readManifest(repoDir) {
+    const manifestPath = join(repoDir, MANIFEST_FILENAME);
+    let raw;
+    try {
+        raw = await fs.readFile(manifestPath, "utf-8");
+    }
+    catch (error) {
+        if (error !== null &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return undefined;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read ${MANIFEST_FILENAME} in the source repo: ${message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid ${MANIFEST_FILENAME} in the source repo: ${message}`);
+    }
+    const parsed = manifestSchema.safeParse(json);
+    if (parsed.success === false) {
+        throw new Error(`Invalid ${MANIFEST_FILENAME} in the source repo: ${z.prettifyError(parsed.error)}`);
+    }
+    validateManifestPaths(parsed.data);
+    return parsed.data;
+}
+/**
+ * Decide what to copy. A manifest-declared folder keeps the repo layout and
+ * brings its transitive `requires` plus the shared root files; anything else
+ * is a flat copy of the requested folder (or the whole repo).
+ */
+export function planCopies(manifest, subPath) {
+    const declared = manifest === undefined ? undefined : manifest.folders[subPath];
+    if (manifest === undefined || declared === undefined || subPath === "") {
+        return { folders: [subPath], files: [], flatten: true };
+    }
+    const folders = [];
+    const queue = [subPath];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined || folders.includes(current))
+            continue;
+        folders.push(current);
+        const entry = manifest.folders[current];
+        if (entry !== undefined)
+            queue.push(...entry.requires);
+    }
+    return { folders, files: manifest.shared, flatten: false };
+}
+/**
+ * Shallow-clone the repo into a temp dir. Returns the dir and its cleanup.
+ * `remoteUrl` overrides the GitHub URL (tests clone from a local repo).
+ */
+export async function cloneGitHubRepo(ref, remoteUrl) {
+    const dir = await fs.mkdtemp(join(tmpdir(), "cargo-cdk-from-"));
+    const url = remoteUrl === undefined
+        ? `https://github.com/${ref.owner}/${ref.repo}.git`
+        : remoteUrl;
+    const branchArgs = ref.gitRef === "" ? [] : ["--branch", ref.gitRef];
+    try {
+        await execFileAsync("git", [
+            "clone",
+            "--depth",
+            "1",
+            "--quiet",
+            ...branchArgs,
+            url,
+            dir,
+        ]);
+    }
+    catch (error) {
+        await fs.rm(dir, { recursive: true, force: true });
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not clone ${url}${ref.gitRef === "" ? "" : ` (ref ${ref.gitRef})`}. Is git installed and the repo accessible?\n${message}`);
+    }
+    // Drop the git metadata so a whole-repo copy never carries it over.
+    await fs.rm(join(dir, ".git"), { recursive: true, force: true });
+    return {
+        dir,
+        cleanup: () => fs.rm(dir, { recursive: true, force: true }),
+    };
+}
+/**
+ * Fetch the source and copy the planned folders/files into `targetDir`,
+ * substituting `__APP_NAME__`. Returns the copied repo-relative paths.
+ */
+export async function scaffoldFromGitHub(payload) {
+    const { ref, targetDir, appName, remoteUrl } = payload;
+    const rename = [{ from: "__APP_NAME__", to: appName }];
+    const { dir, cleanup } = await cloneGitHubRepo(ref, remoteUrl);
+    try {
+        if (ref.subPath !== "") {
+            assertSafeRepoRelativePath(ref.subPath, "source folder");
+            const subPathSrc = resolveWithin(dir, ref.subPath);
+            const stat = await fs.stat(subPathSrc).catch(() => undefined);
+            if (stat === undefined || stat.isDirectory() === false) {
+                throw new Error(`"${ref.subPath}" is not a folder in ${ref.owner}/${ref.repo}.`);
+            }
+        }
+        const manifest = await readManifest(dir);
+        const plan = planCopies(manifest, ref.subPath);
+        for (const folder of plan.folders) {
+            const src = resolveWithin(dir, folder);
+            const dest = plan.flatten ? targetDir : resolveWithin(targetDir, folder);
+            const stat = await fs.stat(src).catch(() => undefined);
+            if (stat === undefined || stat.isDirectory() === false) {
+                throw new Error(`Manifest folder "${folder}" is missing from ${ref.owner}/${ref.repo}.`);
+            }
+            await copyDirectory(src, dest, rename);
+        }
+        for (const file of plan.files) {
+            const src = resolveWithin(dir, file);
+            const stat = await fs.stat(src).catch(() => undefined);
+            if (stat === undefined || stat.isFile() === false) {
+                throw new Error(`Manifest shared file "${file}" is missing from ${ref.owner}/${ref.repo}.`);
+            }
+            const raw = await fs.readFile(src, "utf-8");
+            const replaced = rename.reduce((current, { from, to }) => current.split(from).join(to), raw);
+            const dest = resolveWithin(targetDir, file);
+            await fs.mkdir(dirname(dest), { recursive: true });
+            await fs.writeFile(dest, replaced, "utf-8");
+        }
+        return [...plan.folders, ...plan.files].filter((path) => path !== "");
+    }
+    finally {
+        await cleanup();
+    }
+}

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

@@ -1,3 +1,3 @@
-import type { Command } from "commander";
+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

@@ -1 +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"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,WAAW,CAAC;AAmBjD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAoGzD"}

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

@@ -1,11 +1,16 @@
 import { existsSync, readdirSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { Option } from "commander";
 import { ExitCodes, failWith, info, success } from "../io.js";
+import { parseFromRef, scaffoldFromGitHub } from "./from.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__`.
+// `cdk init <directory> [--template <slug>] [--from <source>]` — scaffold a
+// starter CDK project by copying one of `@cargo-ai/cdk`'s bundled templates
+// (see `--list-templates`) or fetching a GitHub source — e.g. a cookbook:
+// `cdk init my-tam --from getcargohq/cargo-cookbooks/signal-based-tam` — substituting
+// `__APP_NAME__`. Cookbook sources pull their required sibling folders via the
+// repo's `cargo.scaffold.json` (see `./from.ts`).
 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.",
@@ -14,7 +19,10 @@ 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")
+        .addOption(new Option("--template <slug>", "Template slug (default: blank)")
+        .default("blank")
+        .conflicts("from"))
+        .option("--from <source>", "GitHub source to scaffold from instead of a template — owner/repo[/folder][@ref] or a github.com URL. Cookbook folders also pull their required siblings (repo's cargo.scaffold.json).")
         .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")
@@ -28,11 +36,6 @@ export function registerInitCommand(parent) {
             }
             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 &&
@@ -40,10 +43,26 @@ export function registerInitCommand(parent) {
             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`);
+        if (opts.from !== undefined) {
+            const ref = parseFromRef(opts.from);
+            if (ref === undefined) {
+                failWith(`Could not parse --from "${opts.from}". Expected owner/repo[/folder][@ref] or a github.com URL.`, { code: ExitCodes.GenericError });
+            }
+            const copied = await scaffoldFromGitHub({ ref, targetDir, appName });
+            const detail = copied.length > 0 ? ` (${copied.join(", ")})` : "";
+            success(`Scaffolded ${directory} from ${ref.owner}/${ref.repo}${ref.subPath === "" ? "" : `/${ref.subPath}`}${detail}`);
+        }
+        else {
+            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 });
+            }
+            await copyDirectory(templateDir, targetDir, [
+                { from: "__APP_NAME__", to: appName },
+            ]);
+            success(`Scaffolded ${directory} from the "${opts.template}" template`);
+        }
         info(``);
         info([
             `Next steps:`,

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2FzC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CA8D7E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiHzC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAgE7E"}