@duyquangnvx/create-agent-cli 0.13.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
   "type": "module",
   "engines": {
@@ -11,6 +11,7 @@
   },
   "files": [
     "dist",
+    "partials",
     "template",
     "CHANGELOG.md"
   ],
@@ -19,7 +20,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@duyquangnvx/agent-cli": "0.13.1",
+    "@duyquangnvx/agent-cli": "0.14.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },

package/partials/dependency/installLines.md

@@ -0,0 +1,7 @@
+Add the CLI to each project that uses it, then copy its skill into that project. In Claude Code, type each line in the prompt, in the project's folder:
+
+`! pnpm add -D {{packageName}}`
+
+`! {{runAs}} skill install`
+
+With npm, the first line is `! npm install -D {{packageName}}`.

package/partials/dependency/installSteps.md

@@ -0,0 +1,12 @@
+This installs the project's copy of {{binName}}. Always run it as `{{runAs}}`: a bare `npx {{binName}}` runs whatever npm package holds the name.
+
+1. When `{{runAs}}` stops with npx's `missing packages` error, no copy is installed at or above the working directory. Read the `package.json` files from the working directory up, and hand the user one line to type in the project's folder, as [Sandbox](#sandbox) says:
+   - When one lists {{packageName}} in `dependencies` or `devDependencies`, the project's install line, `! pnpm install` or `! npm install`, which installs the version the project pins.
+   - Otherwise the line that adds it as a devDependency, at the version the project then pins:
+
+     `! pnpm add -D {{packageName}}`
+
+     and with npm `! npm install -D {{packageName}}`.
+
+   With yarn or bun, hand the user that package manager's own line.
+2. Finish with [Check](#check): its `skill` row brings this skill to the installed version. {{binName}} is ready when `doctor` exits 0 with nothing in `next`.

package/partials/dependency/sandbox.md

@@ -0,0 +1,3 @@
+Adding or moving {{binName}} fetches it from the registry, which Claude Code's sandbox may refuse. Hand the user the line to type with `!` in this session, which runs it outside the sandbox.
+
+`doctor`'s `registry` row asks the registry {{binName}} is published to for its latest release. If the sandbox refuses that host, `doctor` still passes with only that row failing. If the user wants the row to work inside the sandbox, give them this block for their Claude Code settings, naming the registry's host, and let them decide:

package/partials/dependency/skillCheck.md

@@ -0,0 +1 @@
+The `skill` row compares this skill's copy at the project root, `.claude/skills/{{binName}}`, with the one the project's {{binName}} ships. When the copy is missing or differs, as after an update, run its `{{runAs}} skill install` fix, then load this skill again. A copy under `~/.claude/skills/{{binName}}` shadows the project's: ask the user to remove it.

package/partials/dependency/updateSteps.md

@@ -0,0 +1,4 @@
+1. Run `{{runAs}} doctor --json` and read its `registry` row. When it reports no newer release, {{binName}} is current: stop here. When a newer release exists, the row's fix is the line that moves {{packageName}} to it; with yarn or bun the row names the version without a line, so use that package manager's own line for it. If the row fails to reach the registry, the sandbox refused the host, as [Sandbox](#sandbox) says.
+2. Hand the user that line to type with `!`.
+3. Read the `CHANGELOG.md` that `{{runAs}} --version` names, from the top down to the version the project left, and do each upgrade step it lists, oldest first.
+4. Finish with [Check](#check): its `skill` row brings this skill to the new version.

package/partials/global/installLines.md

@@ -0,0 +1,5 @@
+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:
+
+{{skillLine}}
+
+`! npm install --global {{packageName}}@latest`

package/partials/global/installSteps.md

@@ -0,0 +1,10 @@
+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.

package/partials/global/sandbox.md

@@ -0,0 +1,3 @@
+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 these to work inside the sandbox, give them this block for their Claude Code settings, naming the registry's host, and let them decide:

package/partials/global/skillCheck.md

@@ -0,0 +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.

package/partials/global/updateSteps.md

@@ -0,0 +1,4 @@
+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, for each release since the version it replaced, oldest first, the upgrade steps it asks of the user, or its whole notes when it lists none: under `--json`, each entry of `upgrades` holds `steps` or `notes`. Do each step, oldest first, and any the notes give.
+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`.

package/template/README.md

@@ -4,11 +4,7 @@
 
 ## 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`
+{{installLines}}
 
 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.
 

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

@@ -2,7 +2,7 @@
 name: {{binName}}
 description: >-
   {{description}} Use when a task needs what `{{binName}}` does, or when a `{{binName}}` command fails.
-allowed-tools: Bash({{binName}} --version)
+allowed-tools: Bash({{runAs}} --version)
 metadata:
   version: "0.0.0"
 ---
@@ -11,11 +11,11 @@ metadata:
 
 # {{binName}}
 
-`{{binName}} --help` lists the Commands, and `{{binName}} <command> --help` shows a Command's examples, args, options and the flags the Runtime adds. This file covers the work around them.
+`{{runAs}} --help` lists the Commands, and `{{runAs}} <command> --help` shows a Command's examples, args, options and the flags the Runtime adds. This file covers the work around them.
 
 ## Installed CLI
 
-!`{{binName}} --version 2>&1 || echo "{{binName}}: not installed"`
+!`{{runAs}} --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, read [setup](references/setup.md) before anything else.
 
@@ -32,12 +32,12 @@ The line above should show 0.0.0, the version this skill describes. If it says {
 
 ### Greet someone
 
-1. Run `{{binName}} greet <name> --json`.
+1. Run `{{runAs}} greet <name> --json`.
 2. Read `greeting` from the JSON on stdout.
 
 ### Write a card
 
-1. Run `{{binName}} card <name> --language <code> --dry-run` to see the file it writes and what it costs.
+1. Run `{{runAs}} 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.
 
@@ -47,7 +47,7 @@ Pass `--json` whenever you parse the output: stdout then holds only the data. A
 
 ## 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":"..."}` 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 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:
 
 | Code or exit | What to do |
 |---|---|

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

@@ -8,39 +8,25 @@ Work through a section in order and stop at a step that fails. Ask the user to d
 
 ## Check
 
-Run `{{binName}} doctor --json`. It checks the setup without changing anything and prints `{ rows, next }`.
+Run `{{runAs}} 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.
+- {{skillCheck}} 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.
+`{{runAs}} --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.
+{{installSteps}}
 
 ## 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, for each release since the version it replaced, oldest first, the upgrade steps it asks of the user, or its whole notes when it lists none: under `--json`, each entry of `upgrades` holds `steps` or `notes`. Do each step, oldest first, and any the notes give.
-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`.
+{{updateSteps}}
 
 ## 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:
+{{sandbox}}
 
 ```json
 { "sandbox": { "network": { "allowedDomains": ["registry.npmjs.org"] } } }

package/template/src/cli.ts

@@ -14,8 +14,14 @@ const greet = defineCommand({
   name: "greet",
   description: "Greet someone by name",
   examples: [
-    { command: "{{binName}} greet Ana", note: "say hello to Ana" },
-    { command: "{{binName}} greet Ana --json", note: "get the greeting as JSON" },
+    {
+      command: "{{runAs}} greet Ana",
+      note: "say hello to Ana",
+    },
+    {
+      command: "{{runAs}} greet Ana --json",
+      note: "get the greeting as JSON",
+    },
   ],
   effect: "read",
   args: z.object({
@@ -30,14 +36,20 @@ const card = defineCommand({
   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`.",
+    "Give - as the message to read it from stdin: `{{runAs}} 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",
+      command: "{{runAs}} card Ana",
+      note: "write Ana.txt with an English greeting",
+    },
+    {
+      command: "{{runAs}} 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" },
+    {
+      command: "{{runAs}} card Ana --from Ben --from Cy",
+      note: "sign the card from Ben and Cy",
+    },
   ],
   effect: "write",
   args: z.object({
@@ -73,7 +85,7 @@ const card = defineCommand({
     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`,
+        hint: `run \`{{runAs}} card ${plan.name} --language ${FREE_LANGUAGE}\` for an English card`,
       });
     }
     const parts = [

package/template/test/cli.test.ts

@@ -1,4 +1,4 @@
-import { mkdtemp, readFile } from "node:fs/promises";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -9,6 +9,9 @@ import { cli } from "../src/cli.ts";
 import type { Greetings } from "../src/ports.ts";
 
 const CWD = "/work";
+const RUN_AS = "{{runAs}}";
+// doctor finds a Dependency install's copy from the script it runs as, so it gets one; a Global install gets none, as running from source counts as not installed.
+const DOCTOR_BIN: string = "{{doctorBin}}";
 
 /** A file system holding `existing` (paths under CWD) that records each write. */
 function fakeFiles(existing: readonly string[] = []) {
@@ -50,6 +53,10 @@ function fakeGreetings() {
   return { greetings, calls };
 }
 
+function hintOf(stderr: string): string | undefined {
+  return stderr.split("\n").find((line) => line.startsWith("hint: "));
+}
+
 function run(
   argv: string[],
   files = fakeFiles().files,
@@ -126,7 +133,7 @@ describe("card", () => {
     const refused = await run(["card", "Ana"], files);
 
     expect(refused.exitCode).toBe(1);
-    expect(refused.stderr).toMatch(/hint: .*`{{binName}} card Ana --force`/);
+    expect(hintOf(refused.stderr)).toContain(`\`${RUN_AS} card Ana --force\``);
     expect(written.size).toBe(0);
 
     const forced = await run(["card", "Ana", "--force"], files);
@@ -141,7 +148,7 @@ describe("card", () => {
     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(hintOf(refused.stderr)).toContain(`\`${RUN_AS} card Ana --language es --yes\``);
     expect(calls).toEqual([]);
 
     const approved = await run(["card", "Ana", "--language", "es", "--yes"], undefined, greetings);
@@ -163,12 +170,16 @@ 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. */
+  /** 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>> {
     const home = await mkdtemp(join(tmpdir(), "{{binName}}-home-"));
+    const project = await mkdtemp(join(tmpdir(), "{{binName}}-project-"));
+    await writeFile(join(project, "package.json"), "{}\n");
+    await writeFile(join(project, "pnpm-lock.yaml"), "");
     const result = await runCli(cli, ["doctor", "--json"], {
       env: { HOME: home, PATH: "" },
-      cwd: root,
+      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]));