@duyquangnvx/create-agent-cli 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.5.0",
+  "version": "0.7.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.5.0",
+    "@duyquangnvx/agent-cli": "0.7.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
 

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

@@ -91,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";
 
@@ -155,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}"]`,
+    );
+  });
+});