@duyquangnvx/create-agent-cli 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.22.0 (2026-11-02)
+
+### Added
+
+- The hint of `UNKNOWN_OPTION`, `UNKNOWN_COMMAND` and `INVALID_INPUT` names each Skill copy whose `metadata.version` differs from the build's, for a Skill Hub or a Packaged skill, and says to run `doctor` to update it. A CLI's skill can drop its line on a flag or Command it names that the CLI does not know.
+- The scaffolded setup reference of a Global install says what to do when the user installed the CLI but the shell finds none, under nvm. A CLI's skill can drop its own `command not found` row.
+
+### Changed
+
+- `REGISTRY_AUTH` from npm's `E403` under a Coding agent hints that the agent's sandbox may refuse the registry: the user types `!` and runs it again, or allows the registry in the sandbox's network list, and logs in only if it fails outside the sandbox too. `update`, the install and `doctor`'s `registry` row all give it. A CLI's skill can drop its row saying that `REGISTRY_AUTH` is no refused login, and its `INTERNAL` row too: that hint already names `<NAME>_DEBUG=1`.
+- The scaffolded skill drops what the agent sees anyway: `SKILL.md` loses its When to use section, which belongs in the description, its paragraph on `--json`, `--dry-run` and `--confirm`, and its description of the error format; the setup reference's Check no longer describes `doctor`'s rows. The shipping guide says a skill line earns its place only when no `--help`, output, hint or `doctor` row says it.
+
 ## v0.21.0 (2026-10-29)
 
 ### Added

package/dist/bin.js

@@ -7081,9 +7081,9 @@ function secretRows(secrets, commands) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "75fd8d7",
+		"sha": "4664298",
 		"dirty": false,
-		"builtAt": "2026-10-29T03:29:07.000Z"
+		"builtAt": "2026-11-02T04:03:08.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -7092,6 +7092,40 @@ function versionLine({ version }) {
 	return build === void 0 ? version : `${version} (${build.sha}${build.dirty ? "+dirty" : ""}) built ${build.builtAt}`;
 }
 //#endregion
+//#region ../agent-cli/dist/context/agent.js
+const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
+const isSet = (name) => (env) => (env[name] ?? "") !== "";
+const equals = (name, value) => (env) => env[name] === value;
+const MARKERS = [
+	(env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
+	equals("AGENT", "amp"),
+	isSet("CODEX_SANDBOX"),
+	isSet("CODEX_CI"),
+	isSet("CODEX_THREAD_ID"),
+	isSet("GEMINI_CLI"),
+	isSet("COPILOT_CLI"),
+	isSet("OPENCODE"),
+	isSet("ANTIGRAVITY_AGENT"),
+	isSet("AUGMENT_AGENT"),
+	isSet("REPL_ID"),
+	isSet("CLAUDE_CODE_IS_COWORK"),
+	isSet("CLAUDECODE"),
+	isSet("CLAUDE_CODE"),
+	isSet("CURSOR_TRACE_ID"),
+	isSet("CURSOR_AGENT"),
+	equals("CURSOR_EXTENSION_HOST_ROLE", "agent-exec"),
+	equals("TERM_PROGRAM", "kiro"),
+	(env) => ["/.pi/agent", "\\.pi\\agent"].some((dir) => (env.PATH ?? "").includes(dir)),
+	isSet("GOOSE_PROVIDER")
+];
+/**
+* Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
+* in a PTY, so a TTY alone doesn't mean a person is watching.
+*/
+function isAgent(env) {
+	return MARKERS.some((marker) => marker(env));
+}
+//#endregion
 //#region ../agent-cli/dist/built-ins/semver.js
 const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
 const ENGINE = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
@@ -7231,8 +7265,14 @@ function tail$1(stderr) {
 	const lines = lastLines(stderr, STDERR_TAIL_LINES);
 	return lines === "" ? "" : `\n${lines}`;
 }
+function authHint(code, ctx) {
+	const { label: registry, loginHint } = ctx.registry;
+	const login = `${loginHint}, then ${RUN_AGAIN}`;
+	if (code !== "E403" || !isAgent(ctx.env)) return login;
+	return `a Coding agent's sandbox may refuse ${registry} with a 403: ask your user to type ! and ${RUN_AGAIN}, or to allow ${registry} in the sandbox's network list; if it fails outside the sandbox too, ${login}`;
+}
 function failureOf(call, answer, ctx) {
-	const { label: registry, package: name, loginHint, unreachableHint } = ctx.registry;
+	const { label: registry, package: name, unreachableHint } = ctx.registry;
 	const code = NPM_CODE.exec(answer.stderr)?.[1];
 	const output = tail$1(answer.stderr);
 	const next = [ctx.rerun];
@@ -7245,7 +7285,7 @@ function failureOf(call, answer, ctx) {
 	if (code !== void 0 && AUTH_CODES.has(code)) return new CliError({
 		code: REGISTRY_AUTH,
 		message: `${registry} refused npm's credentials (${code})${output}`,
-		hint: `${loginHint}, then ${RUN_AGAIN}`,
+		hint: authHint(code, ctx),
 		next
 	});
 	if (call === "view" && code === "E404") return noLatest(ctx, `npm found no ${name}@latest on ${registry}: no version of it is published there`);
@@ -7669,6 +7709,7 @@ function hubSkill(cli, from) {
 			run: async (ctx) => findingOf(await skillCopies(cli.name, cli.version, ctx))
 		}],
 		notice: async () => {},
+		differing: async (place) => (await skillCopies(cli.name, cli.version, place)).filter(({ state }) => state !== "current" && state !== "unreadable").map(describeCopy),
 		nextAt: async (version, ctx) => {
 			const copies = await skillCopies(cli.name, version, ctx);
 			const fix = fixFor(cli.name, copies, from);
@@ -7751,40 +7792,6 @@ function agentsRow(agents, install) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/context/agent.js
-const AGENT_NAME = /^[a-zA-Z0-9_-]+$/u;
-const isSet = (name) => (env) => (env[name] ?? "") !== "";
-const equals = (name, value) => (env) => env[name] === value;
-const MARKERS = [
-	(env) => AGENT_NAME.test(env.AI_AGENT ?? ""),
-	equals("AGENT", "amp"),
-	isSet("CODEX_SANDBOX"),
-	isSet("CODEX_CI"),
-	isSet("CODEX_THREAD_ID"),
-	isSet("GEMINI_CLI"),
-	isSet("COPILOT_CLI"),
-	isSet("OPENCODE"),
-	isSet("ANTIGRAVITY_AGENT"),
-	isSet("AUGMENT_AGENT"),
-	isSet("REPL_ID"),
-	isSet("CLAUDE_CODE_IS_COWORK"),
-	isSet("CLAUDECODE"),
-	isSet("CLAUDE_CODE"),
-	isSet("CURSOR_TRACE_ID"),
-	isSet("CURSOR_AGENT"),
-	equals("CURSOR_EXTENSION_HOST_ROLE", "agent-exec"),
-	equals("TERM_PROGRAM", "kiro"),
-	(env) => ["/.pi/agent", "\\.pi\\agent"].some((dir) => (env.PATH ?? "").includes(dir)),
-	isSet("GOOSE_PROVIDER")
-];
-/**
-* Whether a Coding agent, not a person, is running the Agent CLI. Some Coding agents run commands
-* in a PTY, so a TTY alone doesn't mean a person is watching.
-*/
-function isAgent(env) {
-	return MARKERS.some((marker) => marker(env));
-}
-//#endregion
 //#region ../agent-cli/dist/context/errno.js
 const PERMISSION_DENIED = "PERMISSION_DENIED";
 const DISK_FULL = "DISK_FULL";
@@ -8305,6 +8312,15 @@ function packagedSkill(cli, { packaged: folder, agents: text }, install) {
 			run: (ctx) => findingOf(cli, folder, install, ctx)
 		}, ...agents === void 0 ? [] : [agentsRow(agents, install)]],
 		notice: (launch, ctx) => notice(cli, folder, install, launch, ctx),
+		differing: async ({ cwd, packageRoot }) => {
+			const { copy } = await skillCopyOf(cli, cwd);
+			const { copyVersion, packageVersion, same } = await skillVersionsOf(join(packageRoot, folder), copy);
+			return copyVersion === void 0 || same ? [] : [compared(cli.name, {
+				copy,
+				copyVersion,
+				packageVersion
+			}, false)];
+		},
 		nextAt: async (_version, ctx) => {
 			const { fix } = await findingOf(cli, folder, install, ctx);
 			return fix === void 0 ? [] : [fix];
@@ -9356,6 +9372,30 @@ function startSideTask(sideTask, runWith, { clock, failed }) {
 	};
 }
 //#endregion
+//#region ../agent-cli/dist/built-ins/skill/usage-hint.js
+const SKILL_USAGE_CODES = /* @__PURE__ */ new Set([
+	UNKNOWN_OPTION,
+	UNKNOWN_COMMAND,
+	INVALID_INPUT
+]);
+/** A usage error whose hint names each Skill copy that differs from this build, since one may have named the input. */
+async function withDifferingSkill(error, cli, place, runAs) {
+	if (!(error instanceof UsageError) || !SKILL_USAGE_CODES.has(error.code)) return error;
+	let differing;
+	try {
+		differing = await skillOf$1(cli, installOf(cli)).differing(place);
+	} catch (lookup) {
+		if (errnoOf(lookup) === void 0) throw lookup;
+		return error;
+	}
+	if (differing.length === 0) return error;
+	return new UsageError({
+		code: error.code,
+		message: error.message,
+		hint: `${error.hint}; the ${cli.name} skill may name what this build does not know: ${differing.join("; ")}; run \`${runAs} doctor\` to see how to update it`
+	});
+}
+//#endregion
 //#region ../agent-cli/dist/command-line/suggest.js
 const MAX_DISTANCE = 3;
 const MIN_SIMILARITY = .4;
@@ -11066,7 +11106,11 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			});
 		});
 	} catch (error) {
-		return failed(error, noSideTask);
+		return failed(await withDifferingSkill(error, cli, {
+			cwd,
+			env,
+			packageRoot
+		}, invocation.runAs), noSideTask);
 	}
 	const { input, flags } = parsed;
 	resumed = command.deadline?.resume(input, rerunOf);
@@ -11278,10 +11322,16 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 			...format,
 			json: routed.json
 		}));
-		case "usage error": return ranAlone(errorResult(routed.error, {
-			...misused(routed.node),
-			json: routed.json
-		}));
+		case "usage error": {
+			const place = {
+				...options,
+				packageRoot: packageRootOf(options.bin, options.cwd)
+			};
+			return ranAlone(errorResult(await withDifferingSkill(routed.error, cli, place, runAs), {
+				...misused(routed.node),
+				json: routed.json
+			}));
+		}
 		case "command": return whileStopping(options.signal, stopNotice === void 0 ? void 0 : () => write.stderr(stopLine(stopNotice, routed.json)), () => runCommand(cli, routed, options, write, misused(routed.spec)));
 	}
 }
@@ -11344,7 +11394,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.21.0",
+	version: "0.22.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },

package/package.json

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

package/partials/global/installSteps.md

@@ -1,6 +1,6 @@
 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.
+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. That is also why a {{binName}} the user installed can be missing from this shell: ask which Node their terminal runs before installing again.
 2. Hand the user the install line to type, as [Sandbox](#sandbox) says:
 
    `! npm install --global {{packageName}}@latest`

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

@@ -7,7 +7,7 @@ metadata:
   version: "0.0.0"
 ---
 
-<!-- A skeleton to rewrite around {{binName}}'s real Commands. Leave flags out: `--help` is generated from the code and stays in sync with it, this file does not. -->
+<!-- A skeleton to rewrite around {{binName}}'s real Commands. A line earns its place only when no `--help`, output, hint or `doctor` row tells the agent the same thing: write down what costs it turns to work out, such as a convention, a reason, a trap, or a step that needs the user's consent. Leave flags out: `--help` is generated from the code and stays in sync with it, this file does not. What {{binName}} is for, and the nearby tasks it is not for, go in the description, which the agent always sees. -->
 
 # {{binName}}
 
@@ -19,13 +19,6 @@ metadata:
 
 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
-
-<!-- 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
 
 <!-- Each main task as steps naming the Commands it runs, in order. Move a long workflow to a file under references/ and link it. -->
@@ -43,11 +36,9 @@ 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 Next step gives the exact command.
-
 ## Recovering from errors
 
-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. Do what the hint says, except for a code below:
+Do what the error's hint says, except for a code below:
 
 | Code | What to do |
 |---|---|

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

@@ -8,11 +8,9 @@ Work through a section in order and stop at a step that fails. Ask the user to d
 
 ## Check
 
-Run `{{runAs}} doctor --json`. It checks the setup without changing anything and prints `{ rows, next }`.
+Run `{{runAs}} doctor --json`, which changes nothing. Hand the user each line of its `next` to type with `!`, in order, then run `doctor` again.
 
-- 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.
-- {{skillCheck}} 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.
 
 `{{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.