@codespar/cli 0.13.0 → 0.14.1

package/templates/collections-agent/packages/agent-core/test/state-machine.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { canTransition, IllegalTransitionError, isTerminal, transition, TRANSITIONS, type Execution } from "../src/state-machine.js";
+import type { Actor } from "../src/types.js";
+
+const actor: Actor = { type: "agent", agent: "bills-agent@0.1.0", on_behalf_of: "usr_test" };
+
+function drafted(): Execution<"drafted"> {
+  return {
+    id: "exe_1",
+    run_id: "run_1",
+    state: "drafted",
+    mode: "human",
+    actor,
+    items: [],
+    total: 0,
+    currency: "BRL",
+    items_hash: "sha256:x",
+    mandate: { id: "mdt_1", version: 1 },
+    idempotency_key: "idk_1",
+    blocking_reasons: [],
+    outcomes: [],
+    history: [],
+    created_at: "2026-09-23T10:00:00.000Z",
+    updated_at: "2026-09-23T10:00:00.000Z",
+  };
+}
+
+describe("section 4.1: closed state machine", () => {
+  it("has exactly the table of the spec plus the 4.2 return and the 4.7 exits", () => {
+    expect(TRANSITIONS).toEqual({
+      drafted: ["awaiting_approval", "approved", "denied", "expired"],
+      awaiting_approval: ["approved", "denied", "expired"],
+      approved: ["executing", "awaiting_approval", "denied", "expired"],
+      executing: ["settled", "failed"],
+      settled: [],
+      failed: [],
+      denied: [],
+      expired: [],
+    });
+  });
+
+  it("walks the happy path and appends every step to history", () => {
+    const at = "2026-09-23T10:01:00.000Z";
+    const a = transition(drafted(), "awaiting_approval", { at, actor });
+    const b = transition(a, "approved", { at, actor });
+    const c = transition(b, "executing", { at, actor });
+    const d = transition(c, "settled", { at, actor });
+    expect(d.state).toBe("settled");
+    expect(d.history.map((h) => h.to)).toEqual(["awaiting_approval", "approved", "executing", "settled"]);
+    expect(isTerminal(d.state)).toBe(true);
+  });
+
+  it("refuses a transition outside the table at runtime even when the types were bypassed", () => {
+    const settled = { ...drafted(), state: "settled" as const };
+    expect(() => transition(settled as unknown as Execution<"drafted">, "awaiting_approval", { at: "x", actor })).toThrow(IllegalTransitionError);
+    expect(canTransition("executing", "denied")).toBe(false);
+    expect(canTransition("drafted", "executing")).toBe(false);
+    expect(canTransition("settled", "failed")).toBe(false);
+  });
+
+  it("terminal states have no exits", () => {
+    for (const s of ["settled", "failed", "denied", "expired"] as const) {
+      expect(TRANSITIONS[s]).toEqual([]);
+      expect(isTerminal(s)).toBe(true);
+    }
+  });
+});

package/templates/collections-agent/packages/agent-core/test/transitions.type-test.ts

@@ -0,0 +1,59 @@
+/**
+ * Section 15: "a transition outside section 4.1 does not compile". This
+ * file is compiled by `npm run typecheck`; every `@ts-expect-error` below
+ * is a transition the table forbids. If one of them ever compiles, tsc
+ * reports an unused directive and the check fails.
+ */
+import { transition, type Execution } from "../src/state-machine.js";
+import type { Actor } from "../src/types.js";
+
+declare const actor: Actor;
+declare const at: string;
+declare const drafted: Execution<"drafted">;
+declare const awaiting: Execution<"awaiting_approval">;
+declare const approved: Execution<"approved">;
+declare const executing: Execution<"executing">;
+declare const settled: Execution<"settled">;
+declare const failed: Execution<"failed">;
+declare const denied: Execution<"denied">;
+declare const expired: Execution<"expired">;
+
+// Allowed, for contrast.
+transition(drafted, "awaiting_approval", { at, actor });
+transition(drafted, "approved", { at, actor });
+transition(drafted, "denied", { at, actor });
+transition(awaiting, "approved", { at, actor });
+transition(approved, "executing", { at, actor });
+transition(approved, "awaiting_approval", { at, actor });
+transition(executing, "settled", { at, actor });
+transition(executing, "failed", { at, actor });
+
+// The model cannot skip the core: nothing goes straight to executing.
+// @ts-expect-error drafted -> executing is not in the table
+transition(drafted, "executing", { at, actor });
+// @ts-expect-error awaiting_approval -> executing is not in the table
+transition(awaiting, "executing", { at, actor });
+// @ts-expect-error drafted -> settled is not in the table
+transition(drafted, "settled", { at, actor });
+// @ts-expect-error awaiting_approval -> settled is not in the table
+transition(awaiting, "settled", { at, actor });
+
+// Executing closes only by the rail's event.
+// @ts-expect-error executing -> denied is not in the table
+transition(executing, "denied", { at, actor });
+// @ts-expect-error executing -> expired is not in the table
+transition(executing, "expired", { at, actor });
+// @ts-expect-error executing -> approved is not in the table
+transition(executing, "approved", { at, actor });
+
+// Terminal states have no exits. Repeating does not reopen.
+// @ts-expect-error settled is terminal
+transition(settled, "executing", { at, actor });
+// @ts-expect-error failed is terminal
+transition(failed, "executing", { at, actor });
+// @ts-expect-error denied is terminal
+transition(denied, "approved", { at, actor });
+// @ts-expect-error expired is terminal
+transition(expired, "awaiting_approval", { at, actor });
+// @ts-expect-error settled is terminal
+transition(settled, "settled", { at, actor });

package/templates/collections-agent/packages/agent-core/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts"
+  ]
+}

package/templates/collections-agent/tsconfig.base.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["node"]
+  }
+}

package/templates/collections-agent/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["packages/*/test/**/*.test.ts", "agents/*/test/**/*.test.ts"],
+    pool: "forks",
+    maxWorkers: 1,
+    minWorkers: 1,
+    fileParallelism: false,
+    testTimeout: 30000,
+  },
+});

package/templates/kits.lock.json

@@ -0,0 +1,41 @@
+{
+  "format": 1,
+  "kits_repo": "https://github.com/codespar/agent-starter-kits",
+  "kits_ref": "778223274a5df3521d9ef9f33a21446868482391",
+  "commit": "778223274a5df3521d9ef9f33a21446868482391",
+  "agent_core": {
+    "source": "packages/agent-core",
+    "version": "0.1.0"
+  },
+  "templates": {
+    "bills-agent": {
+      "source": "agents/bills-agent",
+      "description": "The consumer delegates the month's bills to an agent that pays under a signed mandate: per-payment cap, monthly cap, named payees, expiry. Every payment returns a receipt.",
+      "version": "0.1.0",
+      "cli": "@codespar/cli@0.13.0",
+      "mcp": "@codespar/mcp@0.5.8",
+      "agent_core": "0.1.0",
+      "next_steps": [
+        "cp agents/bills-agent/.env.example agents/bills-agent/.env   # then fill in your keys",
+        "npm install",
+        "npm run consent -- --yes",
+        "npm start"
+      ],
+      "hash": "sha256:6cc725fc673f19f855a480163e463da121fe964db89320e587260097215b4f41"
+    },
+    "collections-agent": {
+      "source": "agents/collections-agent",
+      "description": "The merchant's agent that collects: agrees terms with the payer inside a negotiation envelope, issues one bolepix per instalment with an idempotency key, presents the QR and the copy-and-paste in the conversation, and closes the cycle on commerce.charge.paid or commerce.charge.expired.",
+      "version": "0.1.0",
+      "cli": "@codespar/cli@0.13.0",
+      "mcp": "@codespar/mcp@0.5.8",
+      "agent_core": "0.1.0",
+      "next_steps": [
+        "cp agents/collections-agent/.env.example agents/collections-agent/.env   # then fill in your keys",
+        "npm install",
+        "npm start"
+      ],
+      "hash": "sha256:149b22e812a97b35f90b42fed6a38261975346035abec05e779f938b5148c131"
+    }
+  }
+}