@duyquangnvx/create-agent-cli 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.15.0 (2026-10-27)
+
+### Added
+
+- A Packaged-skill CLI gives the `skill` row's problem as a Notice before every Command run from an install, Built-in Commands aside: a missing copy or one of another `metadata.version` (with ``run `<run-as> skill install` ``), or a personal copy under `~/.claude/skills`. A file it cannot read gives a Notice that the copy could not be checked, and the Command still runs.
+- `doctor` of a Packaged-skill CLI has an advisory `agents` row: a project root `AGENTS.md` without the CLI's block, or with one `skill install` would rewrite, is a problem whose fix is `<run-as> skill install`; a `CLAUDE.md` without an `@AGENTS.md` line is one with no fix. The agent-cli skill says a CLI need not check either itself.
+- An Error table entry can name a string key of its `details` in `print`, such as `print: "stack"`, which text mode prints between the message and the hint, so a CLI need not repeat it in the message. `--json` and help JSON are unchanged. The agent-cli skill covers it.
+
+### Upgrade from v0.14.0
+
+- A Packaged-skill CLI that gives its own Notice of an outdated Skill copy, or has its own `doctor` row for its `AGENTS.md` block, deletes it: the Runtime now gives both.
+
 ## v0.14.0 (2026-10-27)
 
 ### Added

package/dist/bin.js

@@ -5869,13 +5869,22 @@ function debugTrace(error, format) {
 function errorsOf(error) {
 	return error instanceof AggregateError && error.errors.length > 0 ? error.errors.flatMap(errorsOf) : [error];
 }
+/** The `details` field that `error`'s code declares for text mode to print, when it holds a string. */
+function printedDetail(error, format) {
+	if (!(error instanceof CliError)) return void 0;
+	const key = format.errors[error.code]?.print;
+	const { details } = error;
+	if (key === void 0 || typeof details !== "object" || details === null) return void 0;
+	const value = Reflect.get(details, key);
+	return typeof value === "string" ? value : void 0;
+}
 function errorLines(error, format) {
 	const fields = fieldsOf$1(error, format);
-	const stack = debugTrace(error, format);
+	const blocks = [printedDetail(error, format), debugTrace(error, format)].filter((block) => block !== void 0);
 	const { style } = format;
 	const label = style.red(format.isBug(error) ? "internal error:" : "error:");
-	const trace = stack === void 0 ? "" : `${stack}\n`;
-	return `${label} ${fields.message}\n${trace}${style.cyan("hint:")} ${fields.hint}\n`;
+	const between = blocks.map((block) => `${block}\n`).join("");
+	return `${label} ${fields.message}\n${between}${style.cyan("hint:")} ${fields.hint}\n`;
 }
 function formatRuntimeError(error, format) {
 	const errors = errorsOf(error);
@@ -7435,6 +7444,87 @@ function dependencyRelease(cli, install, { cwd, root, standing }) {
 	};
 }
 //#endregion
+//#region ../agent-cli/dist/built-ins/agents-md.js
+/** One paragraph telling every session that the CLI exists, how to run it and which skill to load. */
+function agentsBlock(cli) {
+	const { install } = cli;
+	const where = install?.mode === "dependency" ? `, and only from a package that has \`${install.package}\` in its dependencies; from anywhere else npx reports the package missing` : "";
+	const what = cli.description.replace(/\.$/, "");
+	return `\`${cli.name}\`: ${what}. Run it as \`${runAsOf(cli)}\`${where}. Load the \`${cli.name}\` skill before using it.`;
+}
+function markersOf(name) {
+	return {
+		begin: `<!-- BEGIN:${name} -->`,
+		end: `<!-- END:${name} -->`
+	};
+}
+/** `text` with the CLI's block between its markers, appended when they are missing; nothing else changes. */
+function withBlock(cli, text) {
+	const { begin, end } = markersOf(cli.name);
+	const whole = `${begin}\n${agentsBlock(cli)}\n${end}`;
+	const start = text.indexOf(begin);
+	const stop = start === -1 ? -1 : text.indexOf(end, start);
+	if (stop !== -1) return `${text.slice(0, start)}${whole}${text.slice(stop + end.length)}`;
+	if (text === "") return `${whole}\n`;
+	return `${text}${text.endsWith("\n") ? "" : "\n"}\n${whole}\n`;
+}
+async function agentsMdAt(cli, root) {
+	const path = join(root, "AGENTS.md");
+	const existing = await orMissing(readFile(path, "utf8"));
+	const block = agentsBlock(cli);
+	if (existing === void 0) return {
+		path,
+		block,
+		change: "create"
+	};
+	if (withBlock(cli, existing) === existing) return {
+		path,
+		block,
+		change: null
+	};
+	return {
+		path,
+		block,
+		change: existing.includes(markersOf(cli.name).begin) ? "rewrite" : "add"
+	};
+}
+async function handEditsAt(root) {
+	const claudeMd = join(root, "CLAUDE.md");
+	const text = await orMissing(readFile(claudeMd, "utf8"));
+	if (text === void 0 || text.split(/\r?\n/).some((line) => line.trim() === "@AGENTS.md")) return [];
+	return [`add a line \`@AGENTS.md\` to ${claudeMd}, so Claude Code reads AGENTS.md`];
+}
+function agentsRow(cli) {
+	return {
+		name: "agents",
+		advisory: true,
+		run: async (ctx) => {
+			const root = await projectRootOf(ctx.cwd);
+			const { path, change } = await agentsMdAt(cli, root);
+			const fix = `${runAsOf(cli)} skill install`;
+			if (change === "rewrite") return {
+				state: "problem",
+				message: `${path} holds a ${cli.name} block other than the one ${fix} writes`,
+				fix
+			};
+			if (change !== null) return {
+				state: "problem",
+				message: `${path} holds no ${cli.name} block, so sessions in this repo do not know ${cli.name}`,
+				fix
+			};
+			const holds = `${path} holds the ${cli.name} block`;
+			const [edit] = await handEditsAt(root);
+			return edit === void 0 ? {
+				state: "ok",
+				message: holds
+			} : {
+				state: "problem",
+				message: `${holds}; ${edit}`
+			};
+		}
+	};
+}
+//#endregion
 //#region ../agent-cli/dist/built-ins/skills.js
 const SKILL_DIRS = [[".claude", "skills"], [".agents", "skills"]];
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
@@ -7584,6 +7674,22 @@ async function packagedSkillFinding(cli, folder, ctx) {
 		skill
 	};
 }
+/** Gives a Packaged skill's `skill` row problem as a Notice, since an agent rarely runs `doctor`. */
+async function noticeSkillCopy(cli, { builtIn, bin }, ctx) {
+	if (builtIn || bin === void 0 || cli.commands === void 0) return;
+	const folder = packagedFolderOf(cli);
+	if (folder === void 0) return;
+	let finding;
+	try {
+		finding = await packagedSkillFinding(cli, folder, ctx);
+	} catch (error) {
+		if (errnoOf(error) === void 0) throw error;
+		ctx.notice(`could not check the ${cli.name} skill: ${messageOf(error)}`);
+		return;
+	}
+	if (finding.state !== "problem") return;
+	ctx.notice(finding.fix === void 0 ? finding.message : `${finding.message}; run \`${finding.fix}\``);
+}
 //#endregion
 //#region ../agent-cli/dist/built-ins/doctor-rows.js
 function ok(message) {
@@ -7778,7 +7884,8 @@ function doctorChecks(cli, launch, read) {
 		...toolRows(cli.tools ?? [], cli.commands),
 		installRow(cli, launch, survey),
 		registryRow(cli, launch, survey),
-		skillRow(cli)
+		skillRow(cli),
+		...packagedFolderOf(cli) === void 0 ? [] : [agentsRow(cli)]
 	];
 }
 //#endregion
@@ -8245,46 +8352,11 @@ async function sameContent(left, right) {
 	const [a, b] = await Promise.all([readFile(left), readFile(right)]);
 	return a.equals(b);
 }
-/** One paragraph telling every session that the CLI exists, how to run it and which skill to load. */
-function agentsBlock(cli) {
-	const { install } = cli;
-	const where = install?.mode === "dependency" ? `, and only from a package that has \`${install.package}\` in its dependencies; from anywhere else npx reports the package missing` : "";
-	const what = cli.description.replace(/\.$/, "");
-	return `\`${cli.name}\`: ${what}. Run it as \`${runAsOf(cli)}\`${where}. Load the \`${cli.name}\` skill before using it.`;
-}
-function markersOf(name) {
-	return {
-		begin: `<!-- BEGIN:${name} -->`,
-		end: `<!-- END:${name} -->`
-	};
-}
-/** `text` with the block between its markers, appended when they are missing; nothing else changes. */
-function withBlock(text, block, { begin, end }) {
-	const whole = `${begin}\n${block}\n${end}`;
-	const start = text.indexOf(begin);
-	const stop = start === -1 ? -1 : text.indexOf(end, start);
-	if (stop !== -1) return `${text.slice(0, start)}${whole}${text.slice(stop + end.length)}`;
-	if (text === "") return `${whole}\n`;
-	return `${text}${text.endsWith("\n") ? "" : "\n"}\n${whole}\n`;
-}
-function blockChangeOf(existing, block, markers) {
-	if (existing === void 0) return "create";
-	if (withBlock(existing, block, markers) === existing) return null;
-	return existing.includes(markers.begin) ? "rewrite" : "add";
-}
-async function handEditsAt(root) {
-	const claudeMd = join(root, "CLAUDE.md");
-	const text = await orMissing(readFile(claudeMd, "utf8"));
-	if (text === void 0 || text.split(/\r?\n/).some((line) => line.trim() === "@AGENTS.md")) return [];
-	return [`add a line \`@AGENTS.md\` to ${claudeMd}, so Claude Code reads AGENTS.md`];
-}
 async function planOf(cli, folder, cwd, packageRoot) {
 	const source = join(packageRoot, folder);
 	const { root, copy } = await skillCopyOf(cli, cwd);
 	const [shipped, present] = await Promise.all([filesIn(source), filesIn(copy)]);
 	const differs = await Promise.all(shipped.map(async (file) => present.includes(file) && !await sameContent(join(source, file), join(copy, file))));
-	const agentsPath = join(root, "AGENTS.md");
-	const block = agentsBlock(cli);
 	return {
 		source,
 		copy,
@@ -8292,11 +8364,7 @@ async function planOf(cli, folder, cwd, packageRoot) {
 		replace: shipped.filter((_file, index) => differs[index]),
 		remove: present.filter((file) => !shipped.includes(file)),
 		sameVersion: (await skillVersionsOf(source, copy)).same,
-		agentsMd: {
-			path: agentsPath,
-			block,
-			change: blockChangeOf(await orMissing(readFile(agentsPath, "utf8")), block, markersOf(cli.name))
-		},
+		agentsMd: await agentsMdAt(cli, root),
 		handEdits: await handEditsAt(root)
 	};
 }
@@ -8357,10 +8425,10 @@ function skillInstallCommand(cli, folder) {
 			if (plan.sameVersion && plan.remove.length > 0 && !ctx.force) throw editedRemovals(plan, ctx);
 			for (const file of [...plan.write, ...plan.replace]) await ctx.files.write(join(plan.copy, file), await readFile(join(plan.source, file)));
 			for (const file of plan.remove) await ctx.files.remove(join(plan.copy, file));
-			const { path, block, change } = plan.agentsMd;
+			const { path, change } = plan.agentsMd;
 			if (change !== null) {
 				const existing = await orMissing(readFile(path, "utf8")) ?? "";
-				await ctx.files.write(path, withBlock(existing, block, markersOf(cli.name)));
+				await ctx.files.write(path, withBlock(cli, existing));
 			}
 			return {
 				copy: plan.copy,
@@ -8860,7 +8928,10 @@ function agentCli() {
 }
 //#endregion
 //#region ../agent-cli/dist/error-table.js
-/** Keeps each code's literal class and `details` schema, so `cliError` can type its throw sites. */
+/**
+* Keeps each code's literal class and `details` schema, so `cliError` can type its throw sites;
+* `print` must name a string key of the code's `details`.
+*/
 function defineErrors(table) {
 	return table;
 }
@@ -9952,7 +10023,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	let served = false;
 	let settled;
 	try {
-		const outcome = await control.settle(execute(command, input, ctx, {
+		const outcome = await control.settle(noticeSkillCopy(cli, {
+			builtIn,
+			bin: options.bin
+		}, ctx).then(() => execute(command, input, ctx, {
 			dryRun: flags.dryRun,
 			confirm: flags.confirm,
 			yes: flags.yes,
@@ -9965,7 +10039,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			},
 			files,
 			guardOutputs: outputs.guard
-		}));
+		})));
 		if (served) return {
 			result: STOPPED_RESULT,
 			finishSideTask
@@ -10148,14 +10222,14 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.14.0";
+var version$1 = "0.15.0";
 var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "f114cf0",
+	"sha": "cd3df50",
 	"dirty": false,
-	"builtAt": "2026-10-27T02:06:04.000Z"
+	"builtAt": "2026-10-27T04:23:15.000Z"
 };
 //#endregion
 //#region src/fill.ts

package/package.json

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