@duyquangnvx/create-agent-cli 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.8.0 (2026-10-20)
+
+### Changed
+
+- **Breaking:** `update` shows only the Upgrade steps of a skipped release whose CHANGELOG section lists them under `### Upgrade from v<version>`, under `upgrade steps for <version>:`. A release whose only step is `Nothing to do.` is left out, and one without the heading still shows its whole section under `changes in <version>:`.
+- **Breaking:** each entry of `upgrades` in `update --json` is `{ version, steps }` or `{ version, notes }`.
+- The scaffolded template's CHANGELOG asks each release from the second on to hold `### Upgrade from v<the release below>`, and its setup reference tells the agent to do the steps `update` prints. The agent-cli skill's shipping reference explains the convention.
+
+## v0.7.0 (2026-10-20)
+
+### Added
+
+- Every Runtime code is exported under its name: `OUTPUT_EXISTS`, `PROJECT_INVALID`, `INVALID_INPUT`, `UNKNOWN_OPTION`, `UNKNOWN_COMMAND`, `UNKNOWN_FIELD`, `CONFIRMATION_REQUIRED`, `CONFIRMATION_MISMATCH`, `NOT_CONFIRMED`, `TOOL_FAILED`, `TOOL_MISSING`, `DOCTOR_PROBLEMS`, `INTERNAL`, `NOT_GLOBAL_INSTALL`, `REGISTRY_UNREACHABLE`, `REGISTRY_AUTH`, `INSTALL_FAILED`, `NPM_FAILED` and `NO_LATEST`. The agent-cli skill says which of them a Command may throw, and asserts codes through them.
+- A CLI's `doctor` rows read the Project file as `ctx.project`, which was always `undefined` there. `doctor` reads the file once for all its rows; a row that reads `ctx.project` while the file is unusable is skipped, since the `project` row reports it. See `DoctorCheck.run`. The agent-cli skill's example adds a `tag` row that reads it.
+
+### Changed
+
+- **Breaking:** `doctor`'s `project` row carries the code of the failed read, so a Project file its schema rejects fails `doctor` with `PROJECT_INVALID` instead of `DOCTOR_PROBLEMS` (still exit 2), the code a Command fails with on the same file. The row's message adds the error's hint.
+
 ## v0.6.0 (2026-10-20)
 
 ### Changed

package/dist/bin.js

@@ -5795,7 +5795,7 @@ var UsageError = class extends CliError {
 		this.name = "UsageError";
 	}
 };
-const INTERNAL_CODE = "INTERNAL";
+const INTERNAL = "INTERNAL";
 function errnoOf(error) {
 	return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0;
 }
@@ -5835,7 +5835,7 @@ function fieldsOf$1(error, format) {
 		};
 	}
 	return {
-		code: INTERNAL_CODE,
+		code: INTERNAL,
 		message: messageOf(error),
 		hint: bugHint(format)
 	};
@@ -7190,22 +7190,41 @@ function nodeRow(cli) {
 		}
 	};
 }
-function projectRow(projectFile) {
-	const { file } = projectFile;
+/** A row's thrown error as its problem: a `CliError` with its hint and code, anything else a bug. */
+function problemOfError(name, error) {
+	if (error instanceof CliError) return {
+		state: "problem",
+		message: `${error.message}; ${error.hint}`,
+		code: error.code
+	};
+	return {
+		state: "problem",
+		message: `the ${name} row hit a bug: ${messageOf(error)}`
+	};
+}
+function readProject(projectFile, ctx) {
+	if (projectFile === void 0) return {
+		ok: true,
+		project: void 0
+	};
+	try {
+		return {
+			ok: true,
+			project: projectOf(projectFile, ctx.cwd, ctx.fileError)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+function projectRow({ file }, read) {
 	return {
 		name: "project",
 		run: (ctx) => {
-			let project;
-			try {
-				project = projectOf(projectFile, ctx.cwd, ctx.fileError);
-			} catch (error) {
-				if (error instanceof CliError && error.code === "PROJECT_INVALID") return {
-					state: "problem",
-					message: error.message
-				};
-				throw error;
-			}
-			return ok(project === void 0 ? `none found: no ${file} at or above ${ctx.cwd}` : join(project.root, file));
+			if (!read.ok) return problemOfError("project", read.error);
+			return ok(read.project === void 0 ? `none found: no ${file} at or above ${ctx.cwd}` : join(read.project.root, file));
 		}
 	};
 }
@@ -7273,11 +7292,11 @@ function skillRow(cli) {
 	};
 }
 /** Every row `doctor` reports, in order: the fixed rows around the CLI's own and its tools'. */
-function doctorChecks(cli, launch) {
+function doctorChecks(cli, launch, read) {
 	return [
 		buildRow(cli),
 		nodeRow(cli),
-		...cli.project === void 0 ? [] : [projectRow(cli.project)],
+		...cli.project === void 0 ? [] : [projectRow(cli.project, read)],
 		...cli.doctor ?? [],
 		...toolRows(cli.tools ?? [], cli.commands),
 		installRow(cli, launch),
@@ -7310,28 +7329,29 @@ function problemOf(check, error, { signal, deadline, ms }) {
 		state: "problem",
 		message: `${check.name} did not answer within ${ms / MS_PER_SECOND} s`
 	};
-	if (error instanceof CliError) return {
-		state: "problem",
-		message: `${error.message}; ${error.hint}`,
-		code: error.code
-	};
-	return {
-		state: "problem",
-		message: `the ${check.name} row hit a bug: ${messageOf(error)}`
-	};
+	return problemOfError(check.name, error);
 }
-function withSignal(ctx, signal) {
-	return Object.create(ctx, { signal: { value: signal } });
+function rowContext(ctx, signal, read) {
+	return Object.create(ctx, {
+		signal: { value: signal },
+		project: { get: () => {
+			if (!read.ok) throw read.error;
+			return read.project;
+		} }
+	});
 }
-async function rowOf(check, ctx) {
+async function rowOf(check, ctx, read) {
 	const ms = check.deadlineMs ?? DEFAULT_DEADLINE_MS;
 	const signal = ctx.deadline(ms);
 	let finding;
 	try {
-		finding = await Promise.race([Promise.resolve().then(() => check.run(withSignal(ctx, signal))), untilAborted(signal)]);
+		finding = await Promise.race([Promise.resolve().then(() => check.run(rowContext(ctx, signal, read))), untilAborted(signal)]);
 	} catch (error) {
 		if (ctx.signal.aborted) return void 0;
-		finding = problemOf(check, error, {
+		finding = !read.ok && error === read.error ? {
+			state: "skipped",
+			message: "the Project file is unusable; the project row says why"
+		} : problemOf(check, error, {
 			signal: ctx.signal,
 			deadline: signal,
 			ms
@@ -7379,7 +7399,8 @@ function doctorCommand(cli, launch) {
 		effect: "read",
 		output: reportSchema,
 		run: async (_input, ctx) => {
-			const checked = (await Promise.all(doctorChecks(cli, launch).map((check) => rowOf(check, ctx)))).filter((row) => row !== void 0);
+			const read = readProject(cli.project, ctx);
+			const checked = (await Promise.all(doctorChecks(cli, launch, read).map((check) => rowOf(check, ctx, read)))).filter((row) => row !== void 0);
 			const rows = checked.map(({ row }) => row);
 			const report = {
 				rows,
@@ -7533,8 +7554,20 @@ var RunControl = class {
 	}
 };
 //#endregion
-//#region ../agent-cli/dist/built-ins/upgrade-notes.js
+//#region ../agent-cli/dist/built-ins/upgrades.js
+/** A skipped release's Upgrade steps, or its whole section when it lists none. */
+const upgradeSchema = union([object({
+	version: string(),
+	steps: array(string())
+}), object({
+	version: string(),
+	notes: string()
+})]);
 const RELEASE_HEADING = /^## v?(\S+)/;
+const UPGRADE_HEADING = /^### Upgrade from v\S+$/;
+const HEADING = /^#{1,6} /;
+const ITEM = /^[-*] /;
+const NOTHING_TO_DO = /^nothing to do\.?$/i;
 function releasesIn(changelog) {
 	const releases = [];
 	let current;
@@ -7549,16 +7582,33 @@ function releasesIn(changelog) {
 			if (current !== void 0) releases.push(current);
 		} else current?.lines.push(line);
 	}
-	return releases.map(({ version, lines }) => ({
+	return releases;
+}
+function listedSteps(lines) {
+	const start = lines.findIndex((line) => UPGRADE_HEADING.test(line.trimEnd()));
+	if (start === -1) return [];
+	const end = lines.findIndex((line, i) => i > start && HEADING.test(line));
+	const body = lines.slice(start + 1, end === -1 ? void 0 : end).filter((line) => line.trim() !== "");
+	const starts = body.flatMap((line, i) => ITEM.test(line) ? [i] : []);
+	return starts.map((first, i) => body.slice(first, starts[i + 1]).map((line) => line.trim()).join(" ").replace(ITEM, ""));
+}
+function upgradeOf({ version, lines }) {
+	const listed = listedSteps(lines);
+	if (listed.length === 0) return [{
 		version,
 		notes: lines.join("\n").trim()
-	}));
+	}];
+	const todo = listed.filter((step) => !NOTHING_TO_DO.test(step));
+	return todo.length === 0 ? [] : [{
+		version,
+		steps: todo
+	}];
 }
 /**
-* What changed in each release after `from` up to `to`, oldest first, from the CHANGELOG.md in
-* `packageDir`; none when the package ships no CHANGELOG.
+* What each release after `from` up to `to` asks of the operator, oldest first, from the
+* CHANGELOG.md in `packageDir`; none when the package ships no CHANGELOG.
 */
-async function upgradeNotes(packageDir, from, to) {
+async function upgradesOf(packageDir, from, to) {
 	let changelog;
 	try {
 		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
@@ -7566,7 +7616,7 @@ async function upgradeNotes(packageDir, from, to) {
 		if (isMissingFile(error)) return [];
 		throw error;
 	}
-	return releasesIn(changelog).filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0).sort((a, b) => compareVersions(a.version, b.version));
+	return releasesIn(changelog).filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0).sort((a, b) => compareVersions(a.version, b.version)).flatMap(upgradeOf);
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/update.js
@@ -7577,18 +7627,18 @@ const updateSchema = object({
 		version: string(),
 		prefix: string()
 	}).nullable(),
-	upgrades: array(object({
-		version: string(),
-		notes: string()
-	})),
+	upgrades: array(upgradeSchema),
 	next: array(string())
 });
 function nothingToInstall({ from, latest }) {
 	return standingOf(from, latest) === "current" ? `already on ${from}, the latest release: nothing to install` : `${from} is newer than the latest release ${latest}: nothing to install`;
 }
+function renderUpgrade(upgrade) {
+	return "steps" in upgrade ? [`\nupgrade steps for ${upgrade.version}:`, ...upgrade.steps.map((step) => `- ${step}`)].join("\n") : `\nchanges in ${upgrade.version}:\n${upgrade.notes}`;
+}
 function renderUpdate(cli, install, update) {
 	const { installed } = update;
-	const head = installed === null ? [nothingToInstall(update)] : [`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`, ...update.upgrades.map(({ version, notes }) => `\nchanges in ${version}:\n${notes}`)];
+	const head = installed === null ? [nothingToInstall(update)] : [`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`, ...update.upgrades.map(renderUpgrade)];
 	const next = update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${update.latest}`);
 	return (next.length === 0 ? head : [
 		...head,
@@ -7651,7 +7701,7 @@ function updateCommand(cli, install, { bin, node }) {
 					version: latest,
 					prefix
 				},
-				upgrades: await upgradeNotes(plan.packageDir, from, latest),
+				upgrades: await upgradesOf(plan.packageDir, from, latest),
 				next: await skillNext(cli, latest, ctx)
 			};
 			if (ctx.signal.aborted) {
@@ -8075,7 +8125,7 @@ const RUNTIME_EXIT_CLASSES = {
 	[STDIN_STALLED]: "caller",
 	[INTERRUPTED]: "interrupted",
 	[DEADLINE_EXCEEDED]: "wait",
-	[INTERNAL_CODE]: "bug",
+	[INTERNAL]: "bug",
 	[PERMISSION_DENIED]: "operator",
 	[DISK_FULL]: "operator",
 	[NOT_FOUND]: "caller",
@@ -9387,14 +9437,14 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.6.0";
+var version$1 = "0.8.0";
 var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "6821473",
+	"sha": "d2cc610",
 	"dirty": false,
-	"builtAt": "2026-10-20T02:08:46.888Z"
+	"builtAt": "2026-10-20T09:33:37.544Z"
 };
 //#endregion
 //#region src/steps.ts

package/package.json

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

package/template/CHANGELOG.md

@@ -1,5 +1,5 @@
 # Changelog
 
-What changed in each release of `{{packageName}}`, newest first, in the format of [Keep a Changelog 2.0](https://keepachangelog.com/en/2.0.0/). Each change lands under `## Unreleased` as it merges, grouped under `### Added`, `### Changed`, `### Fixed` or `### Removed`. A breaking change starts with `**Breaking:**` and names what breaks: a Command, a flag, a `--json` field, an exit code or the skill. A release turns `## Unreleased` into `## vX.Y.Z (YYYY-MM-DD)`.
+What changed in each release of `{{packageName}}`, newest first, in the format of [Keep a Changelog 2.0](https://keepachangelog.com/en/2.0.0/). Each change lands under `## Unreleased` as it merges, grouped under `### Added`, `### Changed`, `### Fixed` or `### Removed`. A breaking change starts with `**Breaking:**` and names what breaks: a Command, a flag, a `--json` field, an exit code or the skill. A release turns `## Unreleased` into `## vX.Y.Z (YYYY-MM-DD)`. From the second release on, a release holds `### Upgrade from v<the release below>` listing what someone upgrading must do, or `- Nothing to do.`.
 
 ## Unreleased

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

@@ -32,7 +32,7 @@ This installs the CLI. The user has installed this skill already.
 ## 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.
+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`.