@duyquangnvx/create-agent-cli 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.4.0",
+  "version": "0.6.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.4.0",
+    "@duyquangnvx/agent-cli": "0.6.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },

package/template/AGENTS.md

@@ -23,10 +23,10 @@ Greenfield with no deployments or users: change code directly. Breaking changes
 - 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`.
+- 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.
 - 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`.
+`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.

package/template/README.md

@@ -2,6 +2,14 @@
 
 {{description}}
 
+## Install
+
+Install the skill first, so that the coding agent loading it can install and check the CLI. In Claude Code, type each line in the prompt:
+
+{{skillInstall}}
+
+`! npm install --global {{packageName}}@latest`
+
 Built on [`@duyquangnvx/agent-cli`](https://www.npmjs.com/package/@duyquangnvx/agent-cli): declare Commands in `src/cli.ts` and test them through `runCli`, as `test/cli.test.ts` does.
 
 ```sh

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

@@ -17,7 +17,7 @@ metadata:
 
 !`{{binName}} --version 2>&1 || echo "{{binName}}: not installed"`
 
-The line above should show 0.0.0, the version this skill describes. If it says {{binName}} is not installed or shows another version, tell the user before going on.
+The line above should show 0.0.0, the version this skill describes. If it says {{binName}} is not installed or shows another version, read [setup](references/setup.md) before anything else.
 
 ## When to use
 
@@ -41,11 +41,13 @@ The line above should show 0.0.0, the version this skill describes. If it says {
 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.
 
+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.
 
 ## Recovering from errors
 
-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:
+Errors go to stderr and end with a `hint:` line naming the next step. Under `--json`, every stderr line is one JSON object: `{"progress":"..."}` while it runs, then `{ errors: [{ code, message, hint }] }` as the last line. Match the first row that fits:
 
 | Code or exit | What to do |
 |---|---|

package/template/skills/{{binName}}/references/setup.md

@@ -0,0 +1,47 @@
+# Setup
+
+Checking, installing and updating {{binName}}, and letting it work inside Claude Code's sandbox. Using it is in [SKILL.md](../SKILL.md).
+
+Work through a section in order and stop at a step that fails. Ask the user to do what only they can do, such as typing an install line, and wait until they say it is done.
+
+<!-- Add a section for each step {{binName}} needs before its first run, such as a sign-in or an API key, and a trial run if a cheap Command makes one. -->
+
+## Check
+
+Run `{{binName}} doctor --json`. It checks the setup without changing anything and prints `{ rows, next }`.
+
+- Each row has a `check`, a `state` (`ok`, `problem` or `skipped`) and a `message` saying what it found. A row that has a `fix` names the command that fixes it.
+- `next` lists every fix in order. Hand the user each one to type with `!`, then run `doctor` 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 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. If the session does not show it, ask the user to type `/reload-skills`, and failing that to restart Claude Code.
+
+`{{binName}} --version` names on its second line the `CHANGELOG.md` installed with the CLI. When the user asks what changed, read it from the top, newest first, down to the version in question.
+
+## Install
+
+This installs the CLI. The user has installed this skill already.
+
+1. Run `node --version` and compare it with the range `npm view {{packageName}} engines.node` prints, which `doctor`'s `node` row also checks once the CLI is installed. Under nvm every Node version has its own global packages, so {{binName}} lands under the Node this shell runs. If that Node is too old, or is not the one the user's terminal runs, tell the user and let them choose before going on.
+2. Hand the user the install line to type, as [Sandbox](#sandbox) says:
+
+   `! npm install --global {{packageName}}@latest`
+
+   Never run `npx {{binName}}`: that runs whatever npm package holds the name.
+3. If `{{binName}} --version` then shows an older version than this skill describes, npm answered from a stale cache. Hand the user the same line with `--cache "$(mktemp -d)"` appended.
+4. Finish with [Check](#check). {{binName}} is ready when `doctor` exits 0 with nothing in `next`: a row that only advises, such as `install`, leaves the exit code at 0.
+
+## Update
+
+1. Run `{{binName}} update --dry-run` to see the version it would install. If it fails to reach the registry, the sandbox refused the host, as [Sandbox](#sandbox) says: go on to the next step.
+2. Ask the user to type `! {{binName}} update`; never run it yourself. It installs the latest release and prints what changed since the version it replaced: under `--json`, `upgrades` lists each release's notes, oldest first. Do each upgrade step those notes give, oldest first.
+3. Hand the user each line in `next` to type with `!`: they bring this skill to the version `update` installed, or to the latest release when it installed nothing, as `doctor`'s `skill` row would. Load this skill again after, as [Check](#check) says.
+4. Confirm the new version with `{{binName}} --version`.
+
+## Sandbox
+
+Claude Code's sandbox never lets a command write npm's global folder, `~/.claude/skills` or `~/.agents/skills`, so the install line, `{{binName}} update` and `npx skills` fail inside it. Hand the user the line to type with `!` in this session, which runs it outside the sandbox under the Node this shell runs.
+
+`doctor`'s `registry` row, `update` and `npm view` ask the registry {{binName}} is published to for its latest release. If the sandbox refuses that host, `doctor` still passes with only that row failing, and `update --dry-run` fails. If the user wants it to work inside the sandbox, give them this block for their Claude Code settings, naming the registry's host, and let them decide:
+
+```json
+{ "sandbox": { "network": { "allowedDomains": ["registry.npmjs.org"] } } }
+```

package/template/src/cli.ts

@@ -1,4 +1,4 @@
-import { agentCli, cliError } from "@duyquangnvx/agent-cli";
+import { agentCli, cliError, orStdin } from "@duyquangnvx/agent-cli";
 import * as z from "zod";
 import manifest from "../package.json" with { type: "json" };
 import { build } from "./build.js";
@@ -28,12 +28,16 @@ const greet = defineCommand({
 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: `{{binName}} card Ana - < note.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",
     },
+    { command: "{{binName}} card Ana --from Ben --from Cy", note: "sign the card from Ben and Cy" },
   ],
   effect: "write",
   args: z.object({
@@ -41,14 +45,24 @@ const card = defineCommand({
       .string()
       .regex(/^[\w-]+$/, "letters, digits, - and _ only")
       .describe("who the card is for; also the file's name"),
+    message: orStdin(z.string().min(1))
+      .optional()
+      .describe("a message to write under the greeting; - reads it from stdin"),
   }),
   options: z.object({
     language: z
       .string()
       .default(FREE_LANGUAGE)
       .describe("the greeting's language code, such as en, es or fr"),
+    from: z.array(z.string().min(1)).default([]).describe("who signs the card; repeat for each"),
+  }),
+  plan: ({ name, message, language, from }) => ({
+    name,
+    message,
+    language,
+    from,
+    file: `${name}.txt`,
   }),
-  plan: ({ name, language }) => ({ name, language, file: `${name}.txt` }),
   outputs: (plan) => [plan.file],
   cost: (plan) =>
     plan.language === FREE_LANGUAGE
@@ -62,7 +76,12 @@ const card = defineCommand({
         hint: `run \`{{binName}} card ${plan.name} --language ${FREE_LANGUAGE}\` for an English card`,
       });
     }
-    await ctx.files.write(plan.file, `${greeting}\n`);
+    const parts = [
+      greeting,
+      ...(plan.message === undefined ? [] : [plan.message.trimEnd()]),
+      ...(plan.from.length === 0 ? [] : [`From ${plan.from.join(", ")}`]),
+    ];
+    await ctx.files.write(plan.file, `${parts.join("\n\n")}\n`);
     return { file: plan.file, greeting };
   },
   render: ({ file }) => `Wrote ${file}`,
@@ -72,6 +91,7 @@ const card = defineCommand({
 export const cli = defineCli({
   name: "{{binName}}",
   version: manifest.version,
+  description: manifest.description,
   build,
   install: {
     mode: "global",

package/template/test/cli.test.ts

@@ -1,6 +1,10 @@
-import { resolve } from "node:path";
+import { mkdtemp, readFile } from "node:fs/promises";
+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 { describe, expect, test } from "vitest";
+import manifest from "../package.json" with { type: "json" };
 import { cli } from "../src/cli.ts";
 import type { Greetings } from "../src/ports.ts";
 
@@ -26,6 +30,10 @@ function fakeFiles(existing: readonly string[] = []) {
       written.delete(path);
     },
     mkdir: async () => {},
+    stat: async (path) => {
+      const text = written.get(path);
+      return text === undefined ? undefined : { size: text.length, id: path };
+    },
   };
   return { files, written };
 }
@@ -42,8 +50,13 @@ function fakeGreetings() {
   return { greetings, calls };
 }
 
-function run(argv: string[], files = fakeFiles().files, greetings = fakeGreetings().greetings) {
-  return runCli(cli, argv, { env: {}, cwd: CWD, files, ports: { greetings } });
+function run(
+  argv: string[],
+  files = fakeFiles().files,
+  greetings = fakeGreetings().greetings,
+  stdin?: string,
+) {
+  return runCli(cli, argv, { env: {}, cwd: CWD, files, ports: { greetings }, stdin });
 }
 
 describe("greet", () => {
@@ -78,6 +91,35 @@ describe("card", () => {
     expect(written).toEqual(new Map([[resolve(CWD, "Ana.txt"), "Hi Ana\n"]]));
   });
 
+  test("- reads a message for under the greeting from stdin", async () => {
+    const { files, written } = fakeFiles();
+
+    const result = await run(
+      ["card", "Ana", "-"],
+      files,
+      undefined,
+      "Happy birthday!\nSee you soon.\n",
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(written.get(resolve(CWD, "Ana.txt"))).toBe("Hi Ana\n\nHappy birthday!\nSee you soon.\n");
+  });
+
+  test("--from, repeated, signs the card from each name", async () => {
+    const { files, written } = fakeFiles();
+
+    const result = await run(["card", "Ana", "--from", "Ben", "--from", "Cy"], files);
+
+    expect(result.exitCode).toBe(0);
+    expect(written.get(resolve(CWD, "Ana.txt"))).toBe("Hi Ana\n\nFrom Ben, Cy\n");
+  });
+
+  test("--help ends its options with a paragraph on cost and stdin", async () => {
+    const result = await run(["card", "--help"]);
+
+    expect(result.stdout).toMatch(/Options:[\s\S]*\n\nA card in English is free; /);
+  });
+
   test("refuses to overwrite an existing card without --force", async () => {
     const { files, written } = fakeFiles(["Ana.txt"]);
 
@@ -117,3 +159,48 @@ describe("card", () => {
     });
   });
 });
+
+describe("install lines", () => {
+  const root = fileURLToPath(new URL("..", import.meta.url));
+
+  /** Each doctor row's fix, run from this checkout with no npm on PATH and no skill installed. */
+  async function doctorFixes(): Promise<Record<string, string | undefined>> {
+    const home = await mkdtemp(join(tmpdir(), "{{binName}}-home-"));
+    const result = await runCli(cli, ["doctor", "--json"], {
+      env: { HOME: home, PATH: "" },
+      cwd: root,
+    });
+    const { rows } = JSON.parse(result.stdout) as { rows: { check: string; fix?: string }[] };
+    return Object.fromEntries(rows.map(({ check, fix }) => [check, fix]));
+  }
+
+  async function text(path: string): Promise<string> {
+    return readFile(join(root, path), "utf8");
+  }
+
+  test("the setup reference and the README install the CLI with doctor's install line", async () => {
+    const { install } = await doctorFixes();
+
+    expect(install).toBeDefined();
+    expect(await text("skills/{{binName}}/references/setup.md")).toContain(`\`! ${install}\``);
+    expect(await text("README.md")).toContain(`\`! ${install}\``);
+  });
+
+  test.skipIf(!("repository" in manifest))(
+    "the README installs the skill with doctor's skill line",
+    async () => {
+      const { skill } = await doctorFixes();
+
+      expect(skill).toBeDefined();
+      expect(await text("README.md")).toContain(`\`! ${skill}\``);
+    },
+  );
+
+  test("the setup reference names the registry's host for the sandbox to allow", async () => {
+    const { host } = new URL(manifest.publishConfig.registry);
+
+    expect(await text("skills/{{binName}}/references/setup.md")).toContain(
+      `"allowedDomains": ["${host}"]`,
+    );
+  });
+});