@cargo-ai/cdk 0.1.1

package/templates/blank/README.md

@@ -0,0 +1,24 @@
+# **APP_NAME**
+
+A Cargo CDK project — define your Cargo resources in code and deploy them.
+
+## Commands
+
+```bash
+npm install
+cargo-ai login          # authenticate to your workspace
+cargo-ai cdk types      # generate typed connector/model config into .cargo-ai/
+cargo-ai cdk plan       # compile the resource tree and diff against cargo.state.json
+cargo-ai cdk deploy     # create/update resources and write cargo.state.json
+```
+
+## Layout
+
+- `cargo.ts` — your resources (`defineConnector`, `defineModel`, `defineTool`, …).
+- `cargo.state.json` — deploy state (uuids). Commit it: it's the only link from
+  code to the play/agent resources it created.
+- `.cargo-ai/` — generated types. Re-run `cargo-ai cdk types` after adding or
+  changing workspace integrations.
+
+Secrets referenced with `secret("ENV_VAR")` are read from the environment at
+deploy time — export them before running `cargo-ai cdk deploy`.

package/templates/blank/cargo.ts

@@ -0,0 +1,44 @@
+import {
+  defineConnector,
+  defineModel,
+  defineTool,
+  defineWorkflow,
+  secret,
+} from "@cargo-ai/cdk";
+import { z } from "zod";
+
+// A data-source connector. After `cargo-ai cdk types`, `config` is typed against
+// the integration's schema and `secret()` reads the value from the environment
+// at deploy time (kept out of the committed state + content hash).
+export const hubspot = defineConnector("hubspot", {
+  integration: "hubspot",
+  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
+});
+
+// A data model sourced from the connector's dataset by one of its extractors.
+export const contacts = defineModel("contacts", {
+  dataset: hubspot,
+  extractSlug: "fetchRecords",
+});
+
+// A tool backed by a workflow. The body is parsed at build time and lowered to
+// workflow nodes — never executed here. `ai(...)` becomes an inference node.
+const enrichFlow = defineWorkflow(
+  "enrich-contact",
+  {
+    input: z.object({ email: z.string() }),
+    output: z.object({ company: z.string() }),
+  },
+  ({ input, ai }) => {
+    const company = ai(
+      `What company owns the email domain of ${input.email}? Reply with just the company name.`,
+    );
+    return { company };
+  },
+);
+
+export const enrich = defineTool("enrich", {
+  workflow: enrichFlow,
+  description: "Enrich a contact with firmographic data.",
+  emojiSlug: "mag",
+});

package/templates/blank/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "types": "cargo-ai cdk types",
+    "plan": "cargo-ai cdk plan",
+    "deploy": "cargo-ai cdk deploy"
+  },
+  "dependencies": {
+    "@cargo-ai/cdk": "^0.1.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.2"
+  }
+}

package/templates/blank/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  // `.cargo-ai` holds the types `cargo-ai cdk types` generates — the explicit
+  // glob is required: a bare `.cargo-ai` (a dot-dir) isn't picked up by
+  // TypeScript's default include.
+  "include": ["*.ts", ".cargo-ai/**/*.d.ts"]
+}

package/templates/full/README.md

@@ -0,0 +1,69 @@
+# **APP_NAME** — a full GTM growth workspace
+
+A complete, runnable Cargo workspace defined entirely in code (the `full` CDK
+template — `cargo-ai cdk init <dir> --template full`). It exercises every resource
+type and wires them together with **handles** — you pass a `define*` handle
+(e.g. `dataset: hubspot`, `models: [{ ref: contacts }]`) into another builder,
+and the reconciler deploys them in dependency order and injects the real uuids.
+
+## The graph
+
+```
+hubspot (connector) ──dataset──▶ contacts (model) ──model──────────┬─▶ onboarding (play)
+                                                                    ├─▶ sdr (agent)
+openai (connector) ──connector──▶ enricher (agent) ──subAgent──▶ sdr│
+                    └────────connector──────────────────▶ sdr ─────┘
+enrich (tool, backed by a workflow) ─┐
+sdr (agent) ─────────────────────────┼─▶ crm (mcpServer)
+contacts (model) ────────────────────┘
+playbook (file)   webhook (worker)   dashboard (app)
+```
+
+## What each file shows
+
+| File                                    | Resource                        | Highlights                                                                                                            |
+| --------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `connectors/hubspot.ts`                 | `defineConnector`               | discriminated-union config + `secret()`; auto-creates a dataset                                                       |
+| `connectors/openai.ts`                  | `defineConnector`               | `adopt: true` to link an existing OAuth connector                                                                     |
+| `folders/crm.ts`                        | `defineFolder`                  | per-kind folders (model vs agent)                                                                                     |
+| `models/contacts.ts`                    | `defineModel`                   | `dataset` handle + `extractSlug` + cron schedule                                                                      |
+| `tools/enrich.ts`                       | `defineWorkflow` + `defineTool` | a tool backed by a workflow, with a cron trigger                                                                      |
+| `agents/enricher.ts`                    | `defineAgent`                   | a focused sub-agent (LLM via `connector`)                                                                             |
+| `agents/sdr.ts`                         | `defineAgent`                   | data model, sub-agent, trigger, evaluator                                                                             |
+| `plays/onboarding.ts`                   | `definePlay` + `defineWorkflow` | runs a per-row workflow as contacts change                                                                            |
+| `mcp/crm.ts`                            | `defineMcpServer`               | bundles tool + agent + model behind one endpoint                                                                      |
+| `context/context.ts` (+ `context/*.md`) | `defineContext`                 | syncs the GTM knowledge base (markdown/MDX) into the workspace's context repo                                         |
+| `files/playbook.ts`                     | `defineFile`                    | content uploaded from a local path                                                                                    |
+| `workers/webhook.ts` (+ `webhook/`)     | `defineWorker`                  | the worker _resource_; points at a built bundle (`index.js` + `manifest.json` + `package.json` + `package-lock.json`) |
+| `apps/dashboard.ts` (+ `dashboard/`)    | `defineApp`                     | a hosted Vite app (`index.html` + `package.json` + `package-lock.json`)                                               |
+
+`defineWorker` vs `createWorker`: `defineWorker` is the deployable **resource**
+(the hosted slot). `createWorker` (from `@cargo-ai/worker-sdk`) is what you use to
+author the worker's **runtime code** — the hosting build esbuilds the bundle's
+`index.js`, so author in TS and build to `index.js` before deploying. The CDK
+checks the required bundle files exist at define time. The worker/app
+sub-directories each have their own `package.json`, so the loader treats them as
+bundles to upload, not as resource files to import.
+
+## Try it
+
+From this project directory:
+
+```bash
+cargo-ai login          # authenticate to your workspace
+cargo-ai cdk types      # type defineConnector/defineModel config against your workspace
+cargo-ai cdk plan       # offline: compile the graph and diff against cargo.state.json
+cargo-ai cdk deploy     # create everything (needs a selected workspace)
+cargo-ai cdk destroy    # tear down everything recorded in state
+```
+
+Importing a file _is_ registration — there is no manifest. The loader imports
+every `.ts` under this directory (skipping the worker/app bundle sub-dirs), and
+each `define*` call registers itself as a side effect. Deploying writes
+`cargo.state.json` (uuids of what was created) — commit it so the next deploy
+diffs against it.
+
+Secrets referenced with `secret("HUBSPOT_API_KEY")` resolve from the environment
+at deploy time — export them before deploying — and stay out of the content hash,
+so rotating a token doesn't read as drift. Only `{hash, uuid, outputs}` land in
+state — secret values never do.

package/templates/full/agents/enricher.ts

@@ -0,0 +1,13 @@
+import { defineAgent } from "@cargo-ai/cdk";
+
+import { openai } from "../connectors/openai";
+
+// A focused sub-agent. The LLM is wired by `connector` (its integration slug is
+// resolved from the connector at deploy) + a `languageModel` slug.
+export const enricher = defineAgent("enricher", {
+  connector: openai,
+  languageModel: "gpt-4o",
+  systemPrompt: "You find and verify a contact's work email. Be precise.",
+  maxSteps: 6,
+  capabilities: ["webSearch"],
+});

package/templates/full/agents/sdr.ts

@@ -0,0 +1,28 @@
+import { defineAgent } from "@cargo-ai/cdk";
+
+import { openai } from "../connectors/openai";
+import { agentsFolder } from "../folders/crm";
+import { contacts } from "../models/contacts";
+import { enrich } from "../tools/enrich";
+import { enricher } from "./enricher";
+
+// The main agent. It references a data model (`models`), a tool (`tools`), a
+// sub-agent (`subAgents`), a connector action (`connectorActions`), and the LLM
+// connector — each passed as a handle (bare, or `{ ref, …options }` when it needs
+// per-call options), so the reconciler deploys them first and injects the uuids.
+export const sdr = defineAgent("sdr", {
+  color: "blue",
+  connector: openai,
+  languageModel: "gpt-4o",
+  systemPrompt:
+    "You qualify inbound leads, enrich missing contact info, and route hot leads to Slack.",
+  maxSteps: 12,
+  capabilities: ["webSearch", "memory"],
+  models: [{ ref: contacts, readOnly: true }],
+  tools: [enrich],
+  subAgents: [{ ref: enricher, waitUntilFinished: true }],
+  connectorActions: [{ integration: "hunter", actionSlug: "emailFinder" }],
+  folder: agentsFolder,
+  triggers: [{ type: "cron", cron: "0 9 * * *", text: "Daily qualification" }],
+  evaluator: { rubric: "Did it correctly qualify the lead?", threshold: 0.8 },
+});

package/templates/full/apps/dashboard/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Pipeline Dashboard</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>