@duyquangnvx/create-agent-cli 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
   "type": "module",
   "engines": {
@@ -13,6 +13,7 @@
     "dist",
     "partials",
     "template",
+    "agents-section.md",
     "CHANGELOG.md"
   ],
   "publishConfig": {
@@ -20,11 +21,11 @@
     "access": "public"
   },
   "devDependencies": {
-    "@duyquangnvx/agent-cli": "0.17.0",
+    "@duyquangnvx/agent-cli": "0.19.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },
   "scripts": {
-    "build": "tsdown"
+    "build": "node -e \"require('node:fs').copyFileSync('../agent-cli/agents-section.md', 'agents-section.md')\" && tsdown"
   }
 }

package/partials/global/skillCheck.md

@@ -1 +1 @@
-The `skill` row names every installed copy of this skill against the installed CLI. A missing copy, or one that states no version, is installed afresh with its `npx -y skills add` fix, since `npx skills update` skips a copy it did not install. After a fix that runs the `skills` installer, load this skill again.
+The `skill` row names every installed copy of this skill against the installed CLI. A missing copy, or one that states no version, is installed afresh with the row's fix, since `npx skills update` skips a copy it did not install. After a fix that runs the `skills` installer, load this skill again.

package/template/AGENTS.md

@@ -18,15 +18,12 @@ Greenfield with no deployments or users: change code directly. Breaking changes
 
 ## Coding standards
 
-- 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`. An `act` Command, which changes the state of a program already running rather than files or services, does the same with no Plan. 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 `serve` Command returns data from `start` and keeps running until `ctx.signal` aborts.
-- 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 })`, or `page(items, next)` with the source's own cursor when the source pages itself; the Runtime adds `--limit`, `--cursor` and `--fields`.
-- 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.
+Follow the rules in `~/.claude/rules/harness/`. Biome enforces the mechanical ones.
+
 - 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
 
 `skills/{{binName}}/SKILL.md` is the agent skill: when to use `{{binName}}`, its workflows and how to recover from its errors. Update it with any change to those, and leave flag details to `--help`. Its `references/setup.md` installs, checks and updates `{{binName}}`; `test/cli.test.ts` fails when its install line, or the README's, differs from what `doctor` gives.
+
+{{agentsSection}}

package/template/package.json

@@ -29,7 +29,7 @@
     "@biomejs/biome": "2.5.15",
     "@duyquangnvx/agent-cli": "{{runtimeVersion}}",
     "@duyquangnvx/harness": "0.3.1",
-    "@duyquangnvx/release": "0.4.0",
+    "@duyquangnvx/release": "0.5.0",
     "@types/node": "^22.19.0",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",

package/template/scripts/release.ts

@@ -1,6 +1,6 @@
 import { release } from "@duyquangnvx/release";
 
-process.exitCode = release({
+process.exitCode = await release({
   skill: "skills/{{binName}}/SKILL.md",
   smoke: { cli: true },
 });

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

@@ -43,17 +43,17 @@ The line above should show 0.0.0, the version this skill describes. If it says {
 
 To put a message under the greeting, pass `-` after the name and pipe the message in with a heredoc, so its quotes and newlines reach the card intact.
 
-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.
+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 Next step gives the exact command.
 
 ## Recovering from errors
 
-Errors go to stderr and end with a `hint:` line naming the next step. Under `--json`, every stderr line is one JSON object: `{"progress":"..."}` or `{"notice":"..."}` while it runs, then `{ errors: [{ code, message, hint }] }` as the last line. Match the first row that fits:
+Errors go to stderr and end with a `hint:` line, then a `run:` line for each command to run next, in order. Under `--json`, every stderr line is one JSON object: `{"progress":"..."}` or `{"notice":"..."}` while it runs, then `{ errors: [{ code, message, hint, next }] }` as the last line, `next` holding those commands when there are any. Match the first row that fits:
 
 | Code or exit | What to do |
 |---|---|
 | `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. |
+| `LANGUAGE_UNSUPPORTED` | The greetings service lacks that language. Run the Next step'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. |

package/template/src/cli.ts

@@ -1,25 +1,23 @@
-import { agentCli, cliError, orStdin } from "@duyquangnvx/agent-cli";
+import { agentCli, orStdin } 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";
+import { ports } from "./ports.js";
 
-const { defineCli, defineCommand } = agentCli<Ports>();
+const { defineCli, defineCommand } = agentCli({ errors, ports });
 
 const FREE_LANGUAGE = "en";
 const PRICE_PER_CARD = "$0.01";
 
 const greet = defineCommand({
-  name: "greet",
   description: "Greet someone by name",
   examples: [
     {
-      command: "{{runAs}} greet Ana",
+      command: "{{binName}} greet Ana",
       note: "say hello to Ana",
     },
     {
-      command: "{{runAs}} greet Ana --json",
+      command: "{{binName}} greet Ana --json",
       note: "get the greeting as JSON",
     },
   ],
@@ -28,30 +26,29 @@ const greet = defineCommand({
     name: z.string().min(1).describe("who to greet"),
   }),
   run: ({ name }) => ({ greeting: `Hello, ${name}!` }),
-  render: ({ greeting }) => greeting,
 });
 
 const card = defineCommand({
-  name: "card",
   description: "Write a greeting card to <name>.txt",
   help:
     `A card in English is free; one in another language costs ${PRICE_PER_CARD} and needs --yes. ` +
     "Give - as the message to read it from stdin: `{{runAs}} card Ana - < note.txt`.",
   examples: [
     {
-      command: "{{runAs}} card Ana",
+      command: "{{binName}} card Ana",
       note: "write Ana.txt with an English greeting",
     },
     {
-      command: "{{runAs}} card Ana --language es --dry-run",
+      command: "{{binName}} card Ana --language es --dry-run",
       note: "show the file it would write and what it costs",
     },
     {
-      command: "{{runAs}} card Ana --from Ben --from Cy",
+      command: "{{binName}} card Ana --from Ben --from Cy",
       note: "sign the card from Ben and Cy",
     },
   ],
   effect: "write",
+  errors: ["LANGUAGE_UNSUPPORTED"],
   args: z.object({
     name: z
       .string()
@@ -83,9 +80,10 @@ const card = defineCommand({
   apply: async (plan, ctx) => {
     const greeting = await ctx.ports.greetings.greet(plan.name, plan.language);
     if (greeting === undefined) {
-      throw cliError(errors, "LANGUAGE_UNSUPPORTED", {
+      throw ctx.fail("LANGUAGE_UNSUPPORTED", {
         message: `the greetings service has no ${plan.language} greeting`,
-        hint: `run \`{{runAs}} card ${plan.name} --language ${FREE_LANGUAGE}\` for an English card`,
+        hint: "run the Next step for an English card",
+        next: [["card", plan.name, "--language", FREE_LANGUAGE]],
       });
     }
     const parts = [
@@ -101,17 +99,7 @@ const card = defineCommand({
 });
 
 export const cli = defineCli({
-  name: "{{binName}}",
-  version: manifest.version,
-  description: manifest.description,
-  build,
-  install: {
-    mode: "global",
-    package: manifest.name,
-    registry: manifest.publishConfig.registry,
-  },
-  engines: manifest.engines,
-  errors,
-  ports,
+  manifest,
+  install: "global",
   commands: { greet, card },
 });

package/template/test/cli.test.ts

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { type Files, runCli } from "@duyquangnvx/agent-cli";
+import { checkExamples } from "@duyquangnvx/agent-cli/testing";
 import { describe, expect, test } from "vitest";
 import manifest from "../package.json" with { type: "json" };
 import { cli } from "../src/cli.ts";
@@ -53,8 +54,11 @@ function fakeGreetings() {
   return { greetings, calls };
 }
 
-function hintOf(stderr: string): string | undefined {
-  return stderr.split("\n").find((line) => line.startsWith("hint: "));
+function nextOf(stderr: string): string[] {
+  return stderr
+    .split("\n")
+    .filter((line) => line.startsWith("run: "))
+    .map((line) => line.slice("run: ".length));
 }
 
 function run(
@@ -63,14 +67,18 @@ function run(
   greetings = fakeGreetings().greetings,
   stdin?: string,
 ) {
-  return runCli(cli, argv, { env: {}, cwd: CWD, files, ports: { greetings }, stdin });
+  return runCli(cli, argv, { cwd: CWD, files, ports: { greetings }, stdin });
 }
 
+test("every example parses, names a Command and passes its schemas", async () => {
+  await checkExamples(cli);
+});
+
 describe("greet", () => {
   test("prints the greeting", async () => {
     const result = await run(["greet", "Ana"]);
 
-    expect(result).toEqual({ stdout: "Hello, Ana!\n", stderr: "", exitCode: 0 });
+    expect(result).toEqual({ stdout: 'greeting: "Hello, Ana!"\n', stderr: "", exitCode: 0 });
   });
 
   test("prints the data as JSON with --json", async () => {
@@ -133,7 +141,7 @@ describe("card", () => {
     const refused = await run(["card", "Ana"], files);
 
     expect(refused.exitCode).toBe(1);
-    expect(hintOf(refused.stderr)).toContain(`\`${RUN_AS} card Ana --force\``);
+    expect(nextOf(refused.stderr)).toEqual([`${RUN_AS} card Ana --force`]);
     expect(written.size).toBe(0);
 
     const forced = await run(["card", "Ana", "--force"], files);
@@ -148,7 +156,7 @@ describe("card", () => {
     const refused = await run(["card", "Ana", "--language", "es"], undefined, greetings);
 
     expect(refused.exitCode).toBe(2);
-    expect(hintOf(refused.stderr)).toContain(`\`${RUN_AS} card Ana --language es --yes\``);
+    expect(nextOf(refused.stderr)).toEqual([`${RUN_AS} card Ana --language es --yes`]);
     expect(calls).toEqual([]);
 
     const approved = await run(["card", "Ana", "--language", "es", "--yes"], undefined, greetings);
@@ -170,8 +178,8 @@ describe("card", () => {
 describe("install lines", () => {
   const root = fileURLToPath(new URL("..", import.meta.url));
 
-  /** Each doctor row's fix, run from a pnpm project lacking the CLI, with no npm on PATH and no skill installed. */
-  async function doctorFixes(): Promise<Record<string, string | undefined>> {
+  /** Each doctor row, run from a pnpm project lacking the CLI, with no npm on PATH and no skill installed. */
+  async function doctorRows(): Promise<Record<string, { message: string; fix?: string }>> {
     const home = await mkdtemp(join(tmpdir(), "{{binName}}-home-"));
     const project = await mkdtemp(join(tmpdir(), "{{binName}}-project-"));
     await writeFile(join(project, "package.json"), "{}\n");
@@ -181,8 +189,10 @@ describe("install lines", () => {
       cwd: project,
       bin: DOCTOR_BIN === "" ? undefined : join(root, DOCTOR_BIN),
     });
-    const { rows } = JSON.parse(result.stdout) as { rows: { check: string; fix?: string }[] };
-    return Object.fromEntries(rows.map(({ check, fix }) => [check, fix]));
+    const { rows } = JSON.parse(result.stdout) as {
+      rows: { check: string; message: string; fix?: string }[];
+    };
+    return Object.fromEntries(rows.map((row) => [row.check, row]));
   }
 
   async function text(path: string): Promise<string> {
@@ -190,7 +200,7 @@ describe("install lines", () => {
   }
 
   test("the setup reference and the README install the CLI with doctor's install line", async () => {
-    const { install } = await doctorFixes();
+    const install = (await doctorRows()).install?.fix;
 
     expect(install).toBeDefined();
     expect(await text("skills/{{binName}}/references/setup.md")).toContain(`\`! ${install}\``);
@@ -200,10 +210,10 @@ describe("install lines", () => {
   test.skipIf(cli.skill === undefined)(
     "the README installs the skill with doctor's skill line",
     async () => {
-      const { skill } = await doctorFixes();
+      const fix = (await doctorRows()).skill?.fix;
 
-      expect(skill).toBeDefined();
-      expect(await text("README.md")).toContain(`\`! ${skill}\``);
+      expect(fix).toBeDefined();
+      expect(await text("README.md")).toContain(`\`! ${fix}\``);
     },
   );
 

package/template/tsdown.config.ts

@@ -29,5 +29,5 @@ export default defineConfig({
   fixedExtension: false,
   // The bin bundles the Runtime and zod, so only this CLI's own release changes its behaviour.
   deps: { onlyBundle: false },
-  define: { __BUILD__: JSON.stringify(build) },
+  define: { __AGENT_CLI_BUILD__: JSON.stringify(build) },
 });

package/template/src/build.ts

@@ -1,6 +0,0 @@
-import type { Cli } from "@duyquangnvx/agent-cli";
-
-// tsdown.config.ts stamps this into the bundle; the source run unbundled, as in tests, has none.
-declare const __BUILD__: Cli["build"];
-
-export const build: Cli["build"] = typeof __BUILD__ === "undefined" ? undefined : __BUILD__;