@duyquangnvx/create-agent-cli 0.2.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
   "type": "module",
   "engines": {
@@ -19,7 +19,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@duyquangnvx/agent-cli": "0.2.1",
+    "@duyquangnvx/agent-cli": "0.4.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },

package/template/AGENTS.md

@@ -18,11 +18,13 @@ Greenfield with no deployments or users: change code directly. Breaking changes
 
 ## Coding standards
 
-- Every Command is declared in `src/cli.ts` with `defineCommand`: a description, realistic examples, Zod schemas for args and options (with `.describe()` on each field), and its Effect.
+- Every Command is declared in `src/cli.ts` with the `defineCommand` that `agentCli<Ports>()` returns: a description, realistic examples, Zod schemas for args and options (with `.describe()` on each field), and its Effect.
 - A Command never prints. A `read` Command returns data from `run` and turns it into short text in `render`. A `write` or `destructive` Command returns a Plan from `plan`, with no side effects, and performs it in `apply`; the Runtime adds `--dry-run`, and `--confirm` for a destructive one.
-- A failure the caller can act on is a `CliError` with a `code`, a `message`, a `hint` naming the command to run next, and `retryable`. Anything else becomes an internal error, whose stack trace `{{debugVariable}}=1` shows.
+- A Command that writes files names them in `outputs(plan)`, and the Runtime refuses to overwrite one without `--force`. A Command that costs money states it in `cost(plan)`, a sentence or `undefined` when cheap, and the Runtime refuses a costly run without `--yes`.
+- A Command reaches a remote service through a port: an interface in `src/ports.ts`, built by the `ports` factory passed to `defineCli` and read as `ctx.ports`. It writes files through `ctx.files` and runs programs through `ctx.spawn`, so a test replaces each of them.
+- Every error code is declared once in a `defineErrors` table passed to `defineCli({ errors })`, with the Exit class that must act on it and an optional `details` schema, and thrown through `cliError(errors, code, { message, hint })`, whose `hint` names the command to run next. An undeclared code, and anything else thrown, becomes an internal error (exit 70), whose stack trace `{{debugVariable}}=1` shows.
 - A Command that lists many items declares its row schema as `rows` and returns `paginate(items, { limit, cursor })`; the Runtime adds `--limit`, `--cursor` and `--fields`.
-- Tests drive the CLI through `runCli` and assert only stdout, stderr and the exit code, as `test/cli.test.ts` does.
+- Tests drive the CLI through `runCli`, replacing ports, files and the clock in its options, and assert stdout, stderr, the exit code and what the fakes recorded, as `test/cli.test.ts` does.
 - A change a user of `{{binName}}` would notice gets an entry under `## Unreleased` in `CHANGELOG.md`, in the format its opening paragraph states.
 
 ## Agent skills

package/template/skills/{{binName}}/SKILL.md

@@ -24,6 +24,7 @@ The line above should show 0.0.0, the version this skill describes. If it says {
 <!-- The tasks {{binName}} is for, and the nearby tasks it is not for. -->
 
 - Greeting someone by name.
+- Writing a greeting card to a file, in English for free or in another language at a cost.
 
 ## Workflows
 
@@ -34,17 +35,28 @@ The line above should show 0.0.0, the version this skill describes. If it says {
 1. Run `{{binName}} greet <name> --json`.
 2. Read `greeting` from the JSON on stdout.
 
-Pass `--json` whenever you parse the output: stdout then holds only the data. A Command that changes something takes `--dry-run`, which prints its Plan and changes nothing: run it first when unsure. A destructive Command also needs `--confirm=<target>`, and its error's hint gives the exact command.
+### Write a card
+
+1. Run `{{binName}} card <name> --language <code> --dry-run` to see the file it writes and what it costs.
+2. If it states a cost, ask the user before going on.
+3. Run it again without `--dry-run`, adding `--yes` once the user approved the cost.
+
+Pass `--json` whenever you parse the output: stdout then holds only the data. A Command that changes something takes `--dry-run`, which prints its Plan, the files it writes and its cost, and changes nothing: run it first when unsure. A destructive Command also needs `--confirm=<target>`, and its error's hint gives the exact command.
 
 ## Recovering from errors
 
-Errors go to stderr and end with a `hint:` line naming the next step. Under `--json` they are one object with `code`, `message`, `hint` and `retryable`. Match the first row that fits:
+Errors go to stderr and end with a `hint:` line naming the next step. Under `--json` they are `{ errors: [{ code, message, hint }] }`. Match the first row that fits:
 
 | Code or exit | What to do |
 |---|---|
-| exit 2 | You called it wrong. Fix the input the message names, as the hint says, and run it again. |
-| `INTERNAL` | A bug in {{binName}}. Run it once more with `{{debugVariable}}=1` for the stack trace, then give the user stderr verbatim. |
-| exit 1, `retryable: true` | Run it again once. |
-| exit 1 | Fix what the message and hint point at, then run it again. Ask the user when the fix is their choice. |
-
-<!-- Add a row for each CliError code {{binName}} throws, saying what to do about it. -->
+| `OUTPUT_EXISTS` | The run would overwrite a file. Ask the user before adding `--force`. |
+| `NOT_CONFIRMED` | The run costs money. Tell the user the cost from the message; add `--yes` only once they approve it. |
+| `LANGUAGE_UNSUPPORTED` | The greetings service lacks that language. Run the hint's English card, or ask the user for another language. |
+| exit 1 | You called it wrong. Fix what the message and hint point at, then run it again. |
+| exit 2 | Something on this machine needs a person. Tell the user what the hint says and ask them to fix it. |
+| exit 3 | The source it talks to is broken. Tell the user; running it again won't help. |
+| exit 75 | Nobody needs to act. Wait, then run it again, as the hint says. |
+| exit 70, `INTERNAL` | A bug in {{binName}}. Run it once more with `{{debugVariable}}=1` for the stack trace, then give the user stderr verbatim. |
+| exit 130 or 143 | It was interrupted. Run it again only if the user still wants it. |
+
+<!-- Add a row above the exit rows for each CliError code {{binName}} throws, saying what to do about it. -->

package/template/src/cli.ts

@@ -1,7 +1,14 @@
-import { defineCli, defineCommand } from "@duyquangnvx/agent-cli";
+import { agentCli, cliError } from "@duyquangnvx/agent-cli";
 import * as z from "zod";
 import manifest from "../package.json" with { type: "json" };
 import { build } from "./build.js";
+import { errors } from "./errors.js";
+import { type Ports, ports } from "./ports.js";
+
+const { defineCli, defineCommand } = agentCli<Ports>();
+
+const FREE_LANGUAGE = "en";
+const PRICE_PER_CARD = "$0.01";
 
 const greet = defineCommand({
   name: "greet",
@@ -18,6 +25,50 @@ const greet = defineCommand({
   render: ({ greeting }) => greeting,
 });
 
+const card = defineCommand({
+  name: "card",
+  description: "Write a greeting card to <name>.txt",
+  examples: [
+    { command: "{{binName}} card Ana", note: "write Ana.txt with an English greeting" },
+    {
+      command: "{{binName}} card Ana --language es --dry-run",
+      note: "show the file it would write and what it costs",
+    },
+  ],
+  effect: "write",
+  args: z.object({
+    name: z
+      .string()
+      .regex(/^[\w-]+$/, "letters, digits, - and _ only")
+      .describe("who the card is for; also the file's name"),
+  }),
+  options: z.object({
+    language: z
+      .string()
+      .default(FREE_LANGUAGE)
+      .describe("the greeting's language code, such as en, es or fr"),
+  }),
+  plan: ({ name, language }) => ({ name, language, file: `${name}.txt` }),
+  outputs: (plan) => [plan.file],
+  cost: (plan) =>
+    plan.language === FREE_LANGUAGE
+      ? undefined
+      : `A card in ${plan.language} costs ${PRICE_PER_CARD} on the greetings service.`,
+  apply: async (plan, ctx) => {
+    const greeting = await ctx.ports.greetings.greet(plan.name, plan.language);
+    if (greeting === undefined) {
+      throw cliError(errors, "LANGUAGE_UNSUPPORTED", {
+        message: `the greetings service has no ${plan.language} greeting`,
+        hint: `run \`{{binName}} card ${plan.name} --language ${FREE_LANGUAGE}\` for an English card`,
+      });
+    }
+    await ctx.files.write(plan.file, `${greeting}\n`);
+    return { file: plan.file, greeting };
+  },
+  render: ({ file }) => `Wrote ${file}`,
+  renderPlan: (plan) => `Would write ${plan.file}, a card for ${plan.name} in ${plan.language}`,
+});
+
 export const cli = defineCli({
   name: "{{binName}}",
   version: manifest.version,
@@ -28,5 +79,7 @@ export const cli = defineCli({
     registry: manifest.publishConfig.registry,
   },
   engines: manifest.engines,
-  commands: { greet },
+  errors,
+  ports,
+  commands: { greet, card },
 });

package/template/src/errors.ts

@@ -0,0 +1,5 @@
+import { defineErrors } from "@duyquangnvx/agent-cli";
+
+export const errors = defineErrors({
+  LANGUAGE_UNSUPPORTED: { class: "caller" },
+});

package/template/src/ports.ts

@@ -0,0 +1,23 @@
+/** A greetings service, billed per greeting outside English. */
+export interface Greetings {
+  /** The greeting for `name` in `language`, or undefined when the service lacks that language. */
+  greet(name: string, language: string): Promise<string | undefined>;
+}
+
+export interface Ports {
+  readonly greetings: Greetings;
+}
+
+const HELLO: Readonly<Record<string, string>> = { en: "Hello", es: "Hola", fr: "Bonjour" };
+
+// Stands in for a remote service: replace it with that service's client.
+const localGreetings: Greetings = {
+  greet: async (name, language) => {
+    const hello = HELLO[language];
+    return hello === undefined ? undefined : `${hello}, ${name}!`;
+  },
+};
+
+export function ports(): Ports {
+  return { greetings: localGreetings };
+}

package/template/test/cli.test.ts

@@ -1,27 +1,119 @@
-import { runCli } from "@duyquangnvx/agent-cli";
+import { resolve } from "node:path";
+import { type Files, runCli } from "@duyquangnvx/agent-cli";
 import { describe, expect, test } from "vitest";
 import { cli } from "../src/cli.ts";
+import type { Greetings } from "../src/ports.ts";
 
-const options = { env: {}, cwd: "." };
+const CWD = "/work";
+
+/** A file system holding `existing` (paths under CWD) that records each write. */
+function fakeFiles(existing: readonly string[] = []) {
+  const written = new Map<string, string>();
+  const files: Files = {
+    exists: async (path) => existing.some((name) => resolve(CWD, name) === path),
+    write: async (path, data) => {
+      written.set(path, String(data));
+    },
+    read: async (path) => {
+      const text = written.get(path);
+      if (text === undefined) {
+        throw Object.assign(new Error(`ENOENT: no such file, open '${path}'`), { code: "ENOENT" });
+      }
+      return new TextEncoder().encode(text);
+    },
+    list: async () => [],
+    remove: async (path) => {
+      written.delete(path);
+    },
+    mkdir: async () => {},
+  };
+  return { files, written };
+}
+
+/** The greetings service, faked: it knows English and Spanish and records every call. */
+function fakeGreetings() {
+  const calls: string[] = [];
+  const greetings: Greetings = {
+    greet: async (name, language) => {
+      calls.push(`${name}/${language}`);
+      return { en: `Hi ${name}`, es: `Hola ${name}` }[language];
+    },
+  };
+  return { greetings, calls };
+}
+
+function run(argv: string[], files = fakeFiles().files, greetings = fakeGreetings().greetings) {
+  return runCli(cli, argv, { env: {}, cwd: CWD, files, ports: { greetings } });
+}
 
 describe("greet", () => {
   test("prints the greeting", async () => {
-    const result = await runCli(cli, ["greet", "Ana"], options);
+    const result = await run(["greet", "Ana"]);
 
     expect(result).toEqual({ stdout: "Hello, Ana!\n", stderr: "", exitCode: 0 });
   });
 
   test("prints the data as JSON with --json", async () => {
-    const result = await runCli(cli, ["greet", "Ana", "--json"], options);
+    const result = await run(["greet", "Ana", "--json"]);
 
     expect(JSON.parse(result.stdout)).toEqual({ greeting: "Hello, Ana!" });
   });
 
   test("a missing name is a usage error", async () => {
-    const result = await runCli(cli, ["greet"], options);
+    const result = await run(["greet"]);
 
-    expect(result.exitCode).toBe(2);
+    expect(result.exitCode).toBe(1);
     expect(result.stdout).toBe("");
     expect(result.stderr).toMatch(/<name>: required/);
   });
 });
+
+describe("card", () => {
+  test("writes the service's greeting to <name>.txt", async () => {
+    const { files, written } = fakeFiles();
+
+    const result = await run(["card", "Ana"], files);
+
+    expect(result).toEqual({ stdout: "Wrote Ana.txt\n", stderr: "", exitCode: 0 });
+    expect(written).toEqual(new Map([[resolve(CWD, "Ana.txt"), "Hi Ana\n"]]));
+  });
+
+  test("refuses to overwrite an existing card without --force", async () => {
+    const { files, written } = fakeFiles(["Ana.txt"]);
+
+    const refused = await run(["card", "Ana"], files);
+
+    expect(refused.exitCode).toBe(1);
+    expect(refused.stderr).toMatch(/hint: .*`{{binName}} card Ana --force`/);
+    expect(written.size).toBe(0);
+
+    const forced = await run(["card", "Ana", "--force"], files);
+
+    expect(forced.exitCode).toBe(0);
+    expect(written.get(resolve(CWD, "Ana.txt"))).toBe("Hi Ana\n");
+  });
+
+  test("a card in another language costs, so it needs --yes before calling the service", async () => {
+    const { greetings, calls } = fakeGreetings();
+
+    const refused = await run(["card", "Ana", "--language", "es"], undefined, greetings);
+
+    expect(refused.exitCode).toBe(2);
+    expect(refused.stderr).toMatch(/hint: .*`{{binName}} card Ana --language es --yes`/);
+    expect(calls).toEqual([]);
+
+    const approved = await run(["card", "Ana", "--language", "es", "--yes"], undefined, greetings);
+
+    expect(approved).toEqual({ stdout: "Wrote Ana.txt\n", stderr: "", exitCode: 0 });
+    expect(calls).toEqual(["Ana/es"]);
+  });
+
+  test("a language the service does not know is LANGUAGE_UNSUPPORTED", async () => {
+    const result = await run(["card", "Ana", "--language", "xx", "--yes", "--json"]);
+
+    expect(result.exitCode).toBe(1);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      errors: [{ code: "LANGUAGE_UNSUPPORTED" }],
+    });
+  });
+});

package/template/tsdown.config.ts

@@ -17,6 +17,7 @@ function git(args: readonly string[]): string {
 const build = {
   sha: git(["rev-parse", "--short=7", "HEAD"]),
   dirty: git(["status", "--porcelain"]) !== "",
+  builtAt: new Date().toISOString(),
 };
 
 export default defineConfig({