@cargo-ai/cli 1.0.72 → 1.0.73

package/build/commands/start/brief.js

@@ -0,0 +1,222 @@
+// The pure half of `start`: what it knows, turned into prose.
+//
+// Kept apart from the flow so the interesting decisions — what a coding agent
+// is told, where the palette opens, what `--continue` accepts — are testable
+// without a terminal, the way `planRevocation` and `collectSetupIssues` are.
+import { CANONICAL_SKILLS_DIRECTORY, CDK_SKILL, SKILLS_INSTALL_COMMAND, } from "@cargo-ai/cdk/cli";
+/**
+ * The command group "Explore in the CLI" opens the palette on. The action
+ * catalog is the shortest path from a menu to something real: search one, run
+ * one, see a result.
+ */
+export const EXPLORE_PATH = ["orchestration", "action"];
+export const ROUTER_SKILL = "cargo";
+export const DEMO_SKILL = "cargo-quickstart";
+export { CDK_SKILL };
+/**
+ * `--continue <where>` as a destination. Agents are named the way a person
+ * refers to them ("cursor"), not the way they are installed ("cursor-agent"),
+ * and one that is not on this machine is a usage error rather than a silent
+ * fallback to something else.
+ */
+export function parseDestination(value, agents) {
+    const wanted = value.trim().toLowerCase();
+    if (wanted === "code") {
+        return { kind: "code" };
+    }
+    if (wanted === "cli") {
+        return { kind: "cli" };
+    }
+    if (wanted === "demo") {
+        return { kind: "demo" };
+    }
+    if (wanted === "none") {
+        return { kind: "none" };
+    }
+    const agent = agents.find((candidate) => candidate.bin === wanted ||
+        candidate.bin.replace(/-agent$/, "") === wanted);
+    if (agent === undefined) {
+        return undefined;
+    }
+    return { kind: "agent", agent };
+}
+/**
+ * The brief a coding agent is opened with. An agent launched in a bare
+ * directory has to rediscover the workspace, the skills and the cost rules;
+ * this is the whole reason the handoff beats telling someone to open Claude
+ * Code themselves.
+ *
+ * What it says depends on `project` — see `ProjectContext` for why all three
+ * cases need different words rather than one brief and a different skill name.
+ */
+export function buildBrief(facts, skill, project = { kind: "none" }) {
+    return [
+        ...opening(project),
+        "",
+        `Workspace: ${facts.workspace.name} (${facts.workspace.uuid})`,
+        "",
+        "## Start here",
+        "",
+        ...startSteps(facts, skill),
+        ...firstMove(project),
+        "",
+        ...RULES,
+    ].join("\n");
+}
+/** What the agent has been opened on, in the first two sentences. */
+function opening(project) {
+    if (project.kind === "none") {
+        return [
+            "Work with the user on their Cargo workspace.",
+            "",
+            "Cargo is GTM infrastructure: connectors to the systems they sell with,",
+            "models holding the data, plays and agents that act on it. The `cargo-ai`",
+            "CLI is installed and signed in.",
+        ];
+    }
+    return [
+        "Work with the user on the Cargo workspace declared in this repo.",
+        "",
+        "This is a Cargo CDK project: the workspace — connectors, models, plays,",
+        "tools and agents — is defined in files under `infra/` and applied with",
+        "`npm run deploy`. Read what is declared before changing anything; the",
+        "repo, not the workspace, is the source of truth.",
+    ];
+}
+/**
+ * Step 3: the one thing to do first, which is the whole point of branching.
+ *
+ * Outside a project that is a conversation. Inside one it is reading — and
+ * inside one with a cookbook it is that cookbook's own procedure, which is
+ * more specific than anything this brief could restate.
+ */
+function firstMove(project) {
+    if (project.kind === "none") {
+        return [
+            "3. Ask what they are trying to do before building anything. If they are",
+            "   not sure, `npx @cargo-ai/cdk cookbook list` is the menu of worked",
+            "   pipelines, and `cargo-ai orchestration action list <query>` is the",
+            "   catalog of individual actions.",
+        ];
+    }
+    const company = project.companyContextPath === undefined
+        ? []
+        : [
+            `4. Read \`${project.companyContextPath}\` — the user has already`,
+            "   answered who they are and who they sell to. Expand it with them",
+            "   rather than asking again.",
+        ];
+    if (project.kind === "cookbook") {
+        return [
+            `3. This project has ${project.cookbooks.length === 1 ? "a cookbook" : "cookbooks"} installed:`,
+            ...project.cookbooks.map((name) => `   - \`${name}\` — its procedure is \`${CANONICAL_SKILLS_DIRECTORY}/${name}/SKILL.md\``),
+            "   Read that first and follow it. It is the authority on this pipeline,",
+            "   including what it needs from the user. Do not re-derive the intent or",
+            "   go looking for a different cookbook.",
+            ...company,
+        ];
+    }
+    return [
+        "3. Run `npm run info` to see every resource this project declares, which",
+        "   file declares it, and whether it is deployed. That is the fastest way",
+        "   to understand the workspace, and it is offline. Then ask what they want",
+        "   to change.",
+        ...company,
+    ];
+}
+/**
+ * The brief behind the guided demo.
+ *
+ * It names `cargo-quickstart` rather than describing the demo, because that
+ * skill *is* this demo — a persona, ~25 leads, a cost receipt, then saving the
+ * pull as a play. Describing the outcome instead is what cost the first version
+ * half its runtime (see `HandoffSkill`), so this brief spends its length on
+ * pointing at the procedure and forbidding the detour.
+ */
+export function buildDemoBrief(facts, icp) {
+    return [
+        "Run the Cargo quickstart demo for the user, now.",
+        "",
+        `Workspace: ${facts.workspace.name} (${facts.workspace.uuid})`,
+        icp === undefined
+            ? "They have not said who they sell to yet — ask, in one question."
+            : `Who they sell to, in their words: ${icp}`,
+        "",
+        "## How",
+        "",
+        ...startSteps(facts, DEMO_SKILL),
+        `3. Follow \`${DEMO_SKILL}\` exactly. It is the procedure for this — a`,
+        "   persona, around 25 matching leads, a cost receipt, and saving the pull",
+        "   as a recurring play. Do not re-derive it, and do not route to a",
+        "   different skill because the market sounds specific.",
+        "",
+        "## Do not go exploring",
+        "",
+        "This is a two-minute demo and discovery is what kills it. The skill names",
+        "the actions and their inputs; take them from there rather than:",
+        "",
+        "- guessing action names with repeated `orchestration action list` calls,",
+        "- dumping `connection integration get <slug>` to find a config schema,",
+        "- reading `--help` for commands the skill already spells out.",
+        "",
+        "If something genuinely is not in the skill, say so and ask the user rather",
+        "than spelunking. Their first impression of Cargo is how long this takes.",
+        "",
+        ...RULES,
+    ].join("\n");
+}
+/** The block printed when nobody wanted a handoff. */
+export function formatStartNextSteps(facts) {
+    const lines = [
+        "Next steps:",
+        "  cargo-ai whoami                          # confirm the workspace",
+        "  cargo-ai orchestration action list enrich  # find something to run",
+        "  cargo-ai cdk init                        # set the workspace up as code",
+        "  cargo-ai                                 # the command palette",
+    ];
+    if (facts.skillsInstalled === false) {
+        lines.push(`  ${SKILLS_INSTALL_COMMAND}   # teach your coding agent this CLI`);
+    }
+    return lines.join("\n");
+}
+/**
+ * The two steps every brief opens with: get the skills, confirm the ground.
+ *
+ * `skill` is the one the handoff picked, which is not always the router: a
+ * CDK repo gets `cargo-cdk` and the demo gets `cargo-quickstart`. It has to be
+ * threaded here rather than assumed — see `HandoffSkill`.
+ */
+function startSteps(facts, skill) {
+    // The router earns a sentence about routing; a skill that owns the task
+    // outright does not, and saying so invites the hop this is avoiding.
+    const loadLine = skill === ROUTER_SKILL
+        ? `Load the \`${ROUTER_SKILL}\` skill and let it route you to the right one.`
+        : `Load the \`${skill}\` skill — it owns this, so do not route elsewhere.`;
+    const install = facts.skillsInstalled === false
+        ? [
+            "1. Install the Cargo skills, which are the authority on every command:",
+            `   \`${SKILLS_INSTALL_COMMAND}\`. ${loadLine}`,
+        ]
+        : [`1. ${loadLine} It is already installed.`];
+    return [
+        ...install,
+        "2. Run `cargo-ai whoami` to confirm the workspace, and",
+        "   `cargo-ai billing subscription get` so you know what there is to spend.",
+        "",
+    ];
+}
+/**
+ * The part of every brief that never varies. An agent that deploys or emails
+ * unasked spends the user's money or their reputation.
+ */
+const RULES = [
+    "## Rules",
+    "",
+    "- Connector actions cost credits. Price a run with",
+    "  `cargo-ai orchestration action list` before fanning it out, sample before",
+    "  volume, and tell the user what it cost.",
+    "- Never deploy, never run a batch, and never send anything to a person",
+    "  without the user asking for it in that turn.",
+    "- Anything touching a named person needs a lawful basis and a suppression",
+    "  check. Sourcing people in order to message them without one is refused.",
+];

package/build/commands/start/index.d.ts

@@ -0,0 +1,44 @@
+import type { Command } from "commander";
+import type { Api } from "../../api.js";
+import { type ProjectContext } from "./brief.js";
+export type StartOptions = {
+    email?: string;
+    oauth?: boolean;
+    workspaceName?: string;
+    workspaceUuid?: string;
+    code?: string;
+    continue?: string;
+    directory?: string;
+    icp?: string;
+    baseUrl?: string;
+};
+/** What the flow needs from the program it was registered on. */
+export type StartDeps = {
+    /** The script `cdk init` is re-run through — normally `process.argv[1]`. */
+    binPath: string;
+    /** Opens the command palette, part-way down the tree. */
+    openPalette: (startPath: readonly string[]) => Promise<void>;
+};
+/**
+ * Where the agent is about to be opened. Three cases, all decided locally —
+ * this runs before every handoff, including from the palette, so it must not
+ * touch the network.
+ *
+ * Exported for tests; `go` is the only production caller.
+ */
+export declare function resolveProjectContext(cwd: string): ProjectContext;
+export declare function registerStartCommand(program: Command, getApi: () => Api, deps: StartDeps): void;
+export declare function runStart(getApi: () => Api, deps: StartDeps, opts: StartOptions): Promise<void>;
+/**
+ * The command that finishes what this run started, for a machine with no
+ * terminal to type the emailed code into.
+ *
+ * It has to be `start` rather than `login`: `login --code` signs the user in
+ * and stops, so the destination this run was headed for is lost and re-running
+ * `start --email` issues a second code instead of spending the first. Every
+ * flag that decided where this was going is carried over.
+ *
+ * Exported for tests; `signIn` is the only production caller.
+ */
+export declare function resumeCommand(email: string, opts: StartOptions): string;
+//# sourceMappingURL=index.d.ts.map

package/build/commands/start/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/start/index.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAcxC,OAAO,EAUL,KAAK,cAAc,EAGpB,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,SAAS,GAAG;IACtB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,WAAW,EAAE,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D,CAAC;AAKF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAiBjE;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,EACjB,IAAI,EAAE,SAAS,GACd,IAAI,CAmDN;AAED,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,GAAG,EACjB,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CAmDf;AAqPD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAkBvE"}