@cargo-ai/cdk 1.0.2 → 1.0.4

package/README.md

@@ -1,10 +1,9 @@
 # Cargo CDK
 
 Define your entire Cargo workspace in code — connectors, models, plays, tools,
-agents, MCP servers, context, 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).
+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).
 
 ## Requirements
 
@@ -13,28 +12,45 @@ infrastructure with Pulumi or the AWS CDK. For a complete overview, see the
 
 ## Installation
 
-Install the CDK in your project (for the `define*` builders you import in your
-resource files):
+`@cargo-ai/cdk` gives you both the `define*` builders you import in your resource
+files **and** the `cargo-cdk` command to deploy them:
 
 ```bash
 npm install @cargo-ai/cdk
+npx @cargo-ai/cdk --help
 ```
 
-The `cargo-ai cdk` commands ship with the Cargo CLI — install it globally:
+`cargo-cdk` is a **project-local** tool — run it through the scaffolded `npm run`
+scripts or `npx @cargo-ai/cdk`, the way you'd use the AWS CDK or SST. Don't install
+it globally: a global `cargo-cdk` on your `PATH` would clash with the AWS CDK. (If you
+also use the AWS CDK inside the same project, always call this one as
+`npx @cargo-ai/cdk` to disambiguate.)
+
+Authenticate with the Cargo CLI (or set a token for CI):
 
 ```bash
-npm install -g @cargo-ai/cli
-cargo-ai login --token <your-api-token>
+npm install -g @cargo-ai/cli          # the Cargo CLI — `cargo-ai login` + the `cargo-ai cdk` alias
+cargo-ai login --oauth                # browser sign-in
+# …or, for CI / non-interactive (no CLI needed):
+export CARGO_API_TOKEN=<your-api-token>
 ```
 
+Login writes `~/.config/cargo-ai/credentials.json`, which `cargo-cdk` reads (along
+with the `CARGO_API_TOKEN` / `CARGO_WORKSPACE_UUID` env vars). Everywhere below you
+run the CDK one of two ways: **`npm run <script>`** for the everyday commands (a
+scaffolded project wires up `types` / `plan` / `deploy`), or **`npx
+@cargo-ai/cdk <command>`** for any command — both resolve the project-local
+`cargo-cdk` bin. The `cargo-ai cdk <command>` alias works too.
+
 ## Quick start
 
-Scaffold a starter project from a template:
+Scaffold a starter project from a template — `npx @cargo-ai/cdk` runs the CDK with
+no global install:
 
 ```bash
-cargo-ai cdk init my-workspace            # minimal 'blank' template (default)
-cargo-ai cdk init my-workspace --template full  # every resource type, wired up
-cargo-ai cdk init --list-templates        # see all templates
+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
 cd my-workspace && npm install
 ```
 
@@ -48,7 +64,7 @@ import { defineConnector, defineModel, secret } from "@cargo-ai/cdk";
 // `secret()` reads the value at deploy time and keeps it out of state and the
 // content hash — use it for credentials. The config shape is per-integration
 // (HubSpot takes a Private App token or an OAuth refresh token); run
-// `cargo-ai cdk types` to have it type-checked (see Typed config below).
+// `npx @cargo-ai/cdk types` to have it type-checked (see Typed config below).
 export const hubspot = defineConnector("hubspot", {
   integration: "hubspot",
   config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
@@ -63,11 +79,14 @@ export const contacts = defineModel("contacts", {
 ```
 
 ```bash
-export HUBSPOT_API_KEY=...                # secret() reads this at deploy time
-cargo-ai cdk plan   --dir my-workspace    # offline diff — no API calls
-cargo-ai cdk deploy --dir my-workspace    # create everything, write cargo.state.json
+export HUBSPOT_API_KEY=...        # secret() reads this at deploy time
+npm run plan                      # offline diff — no API calls   (runs `cargo-cdk plan`)
+npm run deploy                    # create everything, write cargo.state.json
 ```
 
+(The scaffolded `package.json` wires `npm run types` / `plan` / `deploy` to the
+project-local `cargo-cdk`. Or run any command directly with `npx @cargo-ai/cdk <command>`.)
+
 Re-running `deploy` only changes what changed; an unchanged workspace is a no-op.
 
 ## Typed config
@@ -76,7 +95,7 @@ Re-running `deploy` only changes what changed; an unchanged workspace is a no-op
 actual integration schemas. Generate the types once:
 
 ```bash
-cargo-ai cdk types --dir my-workspace
+npm run types          # or: npx @cargo-ai/cdk types
 ```
 
 They land in `.cargo-ai/`. Add it to your tsconfig `include` with an explicit
@@ -90,11 +109,11 @@ glob — a bare `.cargo-ai` (a dot-dir) is ignored by TypeScript:
 After that, `config` is checked against the integration's schema — e.g. HubSpot
 is a discriminated union, so the editor completes `method` and requires the
 matching credential, and `secret()` is accepted wherever a credential is
-expected. Re-run `cdk types` after adding or changing workspace integrations.
+expected. Re-run `npm run types` after adding or changing workspace integrations.
 
 Typing is a bonus, never a gate: an integration you haven't synced (or a custom
 one) falls back to a loose `Record<string, unknown>`, so `deploy` still works
-without ever running `cdk types`.
+without ever running `npm run types`.
 
 ## Defining resources
 
@@ -120,7 +139,7 @@ export const sdr = defineAgent("sdr", {
 ```
 
 See [Defining Resources](https://docs.getcargo.ai/cdk/resources) for every
-builder (connectors, models, plays, tools, agents, MCP servers, context,
+builder (connectors, models, plays, tools, agents, MCP servers, context, segments,
 capacities, territories, folders, files, workers, apps) and the slug rules.
 
 ### Context
@@ -144,29 +163,39 @@ added elsewhere (the UI, other tooling) are left in place.
 
 ## Commands
 
+In a scaffolded project, the everyday commands are `npm run` scripts:
+
 ```bash
-cargo-ai cdk init <directory>      # scaffold from a template (--template, --list-templates)
-cargo-ai cdk types                 # generate per-workspace types for typed config
-cargo-ai cdk plan                  # offline: diff the code against cargo.state.json
-cargo-ai cdk deploy                # create/update resources, write cargo.state.json
-cargo-ai cdk deploy --prune        # also delete resources removed from code
-cargo-ai cdk deploy --refresh      # re-read live resources, re-apply out-of-band changes
-cargo-ai cdk refresh               # read-only: report resources that drifted from code
-cargo-ai cdk import <id> <uuid>    # bind an existing live resource into state
-cargo-ai cdk rollback              # restore cargo.state.json from the pre-deploy snapshot
-cargo-ai cdk destroy --target <id> # tear down one resource
-cargo-ai cdk destroy --all         # tear down everything in state
+npm run types     # generate per-workspace types for typed config
+npm run plan      # offline: diff the code against cargo.state.json
+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 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
+npx @cargo-ai/cdk import <id> <uuid>    # bind an existing live resource into state
+npx @cargo-ai/cdk rollback              # restore cargo.state.json from the pre-deploy snapshot
+npx @cargo-ai/cdk destroy --target <id> # tear down one resource
+npx @cargo-ai/cdk destroy --all         # tear down everything in state
+```
+
+Every command also works as `cargo-ai cdk <command>` if you have the global Cargo
+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).
 
 ## State & drift
 
-`cargo-ai cdk deploy` writes `cargo.state.json` — the link from your code to the
+`npm run deploy` writes `cargo.state.json` — the link from your code to the
 resources Cargo created. **Commit it** (losing it orphans resources; recover a
-link with `cdk import`). It records only uuids, hashes and outputs — never
+link with `npx @cargo-ai/cdk import`). It records only uuids, hashes and outputs — never
 secret values.
 
 Git-ignore the generated types and the working files the CDK writes alongside it
@@ -179,8 +208,8 @@ cargo.state.bak.json
 cargo.state.audit.jsonl
 ```
 
-`cargo-ai cdk refresh` reports resources changed or deleted outside the CDK
-(e.g. edited in the Cargo UI); `cargo-ai cdk deploy --refresh` re-applies your
+`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).
 
 ## Documentation

package/build/src/cli/auth.d.ts

@@ -0,0 +1,9 @@
+import { type Api } from "@cargo-ai/api";
+export type Config = {
+    accessToken: string | undefined;
+    baseUrl: string;
+    workspaceUuid: string | undefined;
+};
+export declare function getConfig(): Config;
+export declare function getApi(): Api;
+//# sourceMappingURL=auth.d.ts.map

package/build/src/cli/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/cli/auth.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,GAAG,EAAkC,MAAM,eAAe,CAAC;AAuBzE,MAAM,MAAM,MAAM,GAAG;IACnB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC,CAAC;AAYF,wBAAgB,SAAS,IAAI,MAAM,CAoBlC;AA4DD,wBAAgB,MAAM,IAAI,GAAG,CAS5B"}

package/build/src/cli/auth.js

@@ -0,0 +1,100 @@
+// Authentication for the standalone `cargo-cdk` bin: reads the same credentials
+// `cargo-ai login` writes (`~/.config/cargo-ai/credentials.json`) plus the
+// `CARGO_*` env vars, so one login serves both `cargo-cdk` and `cargo-ai cdk`.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { buildApi } from "@cargo-ai/api";
+import { HttpProxyAgent } from "http-proxy-agent";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { ExitCodes, failWith } from "./io.js";
+import { packageVersion } from "./version.js";
+const ORIGIN = { name: "cargo-cdk", version: packageVersion() };
+const DEFAULT_BASE_URL = "https://api.getcargo.io";
+const CREDENTIALS_FILE = join(homedir(), ".config", "cargo-ai", "credentials.json");
+function loadCredentials() {
+    if (!existsSync(CREDENTIALS_FILE))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+// Resolve token / baseUrl / workspace, preferring env over the credentials file.
+export function getConfig() {
+    const credentials = loadCredentials();
+    const envToken = process.env["CARGO_API_TOKEN"];
+    const accessToken = envToken !== undefined ? envToken : credentials?.accessToken;
+    const envUrl = process.env["CARGO_BASE_URL"];
+    const baseUrl = envUrl !== undefined
+        ? envUrl
+        : credentials?.baseUrl !== undefined
+            ? credentials.baseUrl
+            : DEFAULT_BASE_URL;
+    const envUuid = process.env["CARGO_WORKSPACE_UUID"];
+    const workspaceUuid = envUuid !== undefined ? envUuid : credentials?.workspaceUuid;
+    return { accessToken, baseUrl, workspaceUuid };
+}
+// Tunnel through an HTTP/HTTPS proxy when one is configured via the standard env
+// vars (honoring NO_PROXY); returns undefined otherwise so egress stays direct.
+function getProxyTransport(targetUrl) {
+    const getEnv = (...names) => {
+        for (const name of names) {
+            const value = process.env[name];
+            if (value !== undefined && value.trim() !== "")
+                return value.trim();
+        }
+        return undefined;
+    };
+    const noProxy = getEnv("NO_PROXY", "no_proxy");
+    if (noProxy === "*")
+        return undefined;
+    if (noProxy !== undefined) {
+        let hostname = "";
+        try {
+            hostname = new URL(targetUrl).hostname;
+        }
+        catch {
+            hostname = "";
+        }
+        const bypass = noProxy
+            .split(",")
+            .map((e) => e.trim())
+            .filter((e) => e.length > 0)
+            .some((e) => {
+            const normalized = e.replace(/^\./, "");
+            return hostname === normalized || hostname.endsWith(`.${normalized}`);
+        });
+        if (bypass)
+            return undefined;
+    }
+    const isHttps = targetUrl.startsWith("https:");
+    const proxyUrl = isHttps
+        ? getEnv("HTTPS_PROXY", "https_proxy", "ALL_PROXY", "all_proxy")
+        : getEnv("HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy");
+    if (proxyUrl === undefined)
+        return undefined;
+    return {
+        httpAgent: new HttpProxyAgent(proxyUrl),
+        httpsAgent: new HttpsProxyAgent(proxyUrl),
+        proxy: false,
+    };
+}
+function createApi(opts) {
+    return buildApi({
+        baseUrl: opts.baseUrl,
+        workspaceUuid: opts.workspaceUuid,
+        accessToken: opts.accessToken,
+        origin: ORIGIN,
+        transport: getProxyTransport(opts.baseUrl),
+    });
+}
+export function getApi() {
+    const { baseUrl, accessToken, workspaceUuid } = getConfig();
+    if (accessToken === undefined) {
+        failWith("Not authenticated. Run 'cargo-ai login --token <token>' or 'cargo-ai login --oauth' (cargo-cdk shares the Cargo CLI login), or set CARGO_API_TOKEN.", { code: ExitCodes.NotAuthenticated });
+    }
+    return createApi({ baseUrl, accessToken, workspaceUuid });
+}

package/build/src/cli/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/build/src/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../../src/cli/bin.ts"],"names":[],"mappings":""}

package/build/src/cli/bin.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// The `cargo-cdk` executable — the standalone Cargo CDK CLI.
+import { runCdkBin } from "./index.js";
+import { failWith } from "./io.js";
+// Route any failure through `failWith` for structured stderr + exit code, rather
+// than an unhandled promise rejection.
+runCdkBin().catch((error) => {
+    failWith(error instanceof Error ? error.message : String(error));
+});

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

@@ -0,0 +1,4 @@
+import type { Api } from "@cargo-ai/api";
+import type { Command } from "commander";
+export declare function registerDeployCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=deploy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/deploy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0CzC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA0oBN"}