@duyquangnvx/create-agent-cli 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.30.0 (2026-11-09)
+
+### Added
+
+- A Side task learns how its run ended: `SideTaskRun` has `ended`, a promise of `RunEnd`, `{ exitCode, errors: [{ code, message }] }` with no errors on success, as the caller sees it, the Runtime's codes such as `INTERRUPTED` included. `RunEnd` and `RunEndError` are exported.
+- `defineCli({ skill })` of a Global install takes `add`, the whole line that installs the skill from its Skill Hub, so the Hub sees who installed it. `setup` then copies no skill and ends with `run: <add>`, its `--json` `skill` being `{ add }`, on every run; `update` leaves the Skill copy alone, its `skill` being `null`; and `doctor`'s `skill` row passes on any one home copy and gives `add` as the fix when there is none. `defineCli` throws on an empty or multi-line `add`, and on `add` beside any install but a Global install. Users whose copy came from the package move to the Hub when they run `setup` again, so a CLI that adds `add` asks them to.
+
+### Changed
+
+- **Breaking:** `defineCli({ sideTask })` also runs for a Command whose input is rejected, such as a missing arg or an unknown option after its name, with `dryRun` false, so a usage count also counts those runs.
+
+### Upgrade from v0.29.0
+
+- A Side task that must not count a run whose input was rejected awaits `ended` and skips that run by its error code, such as `INVALID_INPUT`.
+
 ## v0.29.0 (2026-11-09)
 
 ### Added

package/dist/bin.js

@@ -5972,10 +5972,19 @@ function bugHint(format) {
 	const rerun = `rerun with ${debugVariable(format.cliName)}=1 to see the stack trace`;
 	return bugs === void 0 ? rerun : `${rerun}, then report it at ${bugs}`;
 }
+/** The code and message the caller sees for one error a run failed with. */
+function runEndErrorOf(error) {
+	return error instanceof CliError ? {
+		code: error.code,
+		message: error.message
+	} : {
+		code: INTERNAL,
+		message: messageOf(error)
+	};
+}
 function fieldsOf$1({ error, exitClass }, format) {
 	if (!(error instanceof CliError)) return {
-		code: INTERNAL,
-		message: messageOf(error),
+		...runEndErrorOf(error),
 		hint: bugHint(format)
 	};
 	const { code, message, hint, details, retryAt, next } = error;
@@ -7734,9 +7743,9 @@ function cliErrorOf(code, init, options) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "0478338",
+		"sha": "3c4069a",
 		"dirty": false,
-		"builtAt": "2026-11-09T05:16:34.000Z"
+		"builtAt": "2026-11-09T06:02:49.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -8398,12 +8407,19 @@ const homeSyncSchema = object({
 	written: array(string()),
 	removed: array(string())
 });
+function copiedFromPackage(skill) {
+	return skill !== void 0 && skill.add === void 0;
+}
+/** The home Skill copies `setup` and `update` write: none when the skill comes from its Skill Hub. */
+async function syncedCopiesOf(cli, ctx) {
+	return copiedFromPackage(cli.skill) ? homeCopiesOf(ctx.files, cli.name, ctx.env) : [];
+}
 /**
 * Makes each home Skill copy match the folder in the package at `packageDir`. Null when the CLI
-* declares no skill, or that package ships none, which must not empty a copy.
+* declares no skill, its Skill Hub installs it, or that package ships none, which must not empty a copy.
 */
 async function syncHome(cli, packageDir, ctx) {
-	if (cli.skill === void 0) return null;
+	if (!copiedFromPackage(cli.skill)) return null;
 	const source = join(packageDir, cli.skill.folder);
 	if ((await filesIn(ctx.files, source)).length === 0) return null;
 	const copies = await homeCopiesOf(ctx.files, cli.name, ctx.env);
@@ -8463,14 +8479,27 @@ async function findingOf$1(cli, folder, install, ctx) {
 		fix: `${install.runAs} setup`
 	};
 }
-/** A skill the package ships, which `setup` and `update` copy under home. */
-function homeSkill(cli, { folder }, install) {
+async function hubFindingOf(cli, add, ctx) {
+	const paths = await homeCopiesOf(ctx.files, cli.name, ctx.env);
+	const copies = await Promise.all(paths.map((path) => homeCopyAt(ctx.files, path)));
+	const found = copies.filter((copy) => copy.state !== "missing");
+	return found.length === 0 ? {
+		state: "problem",
+		message: copies.map(describeCopy).join("; "),
+		fix: add
+	} : {
+		state: "ok",
+		message: found.map((copy) => copy.path).join("; ")
+	};
+}
+/** A skill the package ships, which `setup` and `update` copy under home unless its Skill Hub installs it. */
+function homeSkill(cli, { folder, add }, install) {
 	return {
 		builtIns: {},
 		rows: [{
 			name: "skill",
 			advisory: true,
-			run: (ctx) => findingOf$1(cli, folder, install, ctx)
+			run: (ctx) => add === void 0 ? findingOf$1(cli, folder, install, ctx) : hubFindingOf(cli, add, ctx)
 		}]
 	};
 }
@@ -8543,7 +8572,7 @@ const setupSchema = object({
 	version: string(),
 	prefix: string(),
 	installed: boolean(),
-	skill: homeSyncSchema.nullable(),
+	skill: union([homeSyncSchema, object({ add: string() })]).nullable(),
 	upgrades: array(upgradeSchema),
 	docs: string().nullable()
 });
@@ -8603,13 +8632,23 @@ function withSetupLine(error, install) {
 		next: [wholeLine(setupLineOf(install))]
 	}, { cause: error });
 }
+function renderNext(name, docs, skill) {
+	const read = docs === null ? [] : [`docs ${docs}`];
+	if (skill === null || !("add" in skill)) return docs === null ? read : [...read, `Read that folder before using ${name}.`];
+	const then = docs === null ? "" : `, then read that folder before using ${name}`;
+	return [
+		...read,
+		`Install the ${name} skill from its Skill Hub${then}.`,
+		`run: ${skill.add}`
+	];
+}
 function renderSetup(cli, install, setup) {
-	const { version, prefix, docs } = setup;
+	const { version, prefix, docs, skill } = setup;
 	return [
 		setup.installed ? `installed ${install.package}@${version} with the npm under ${prefix}` : `${install.package}@${version} is already installed under ${prefix}`,
-		...renderHomeSync(cli.name, setup.skill),
+		...skill !== null && "copies" in skill ? renderHomeSync(cli.name, skill) : [],
 		...setup.upgrades.map(renderUpgrade),
-		...docs === null ? [] : [`docs ${docs}`, `Read that folder before using ${cli.name}.`]
+		...renderNext(cli.name, docs, skill)
 	].join("\n");
 }
 /** The built-in `setup`, which runs from any copy, such as npx's, so it never asks to be the global one. */
@@ -8645,7 +8684,7 @@ function setupCommand(cli, install, launch) {
 				latest: await latestVersion(npm),
 				prefix,
 				packageDir,
-				copies: cli.skill === void 0 ? [] : await homeCopiesOf(ctx.files, cli.name, ctx.env)
+				copies: await syncedCopiesOf(cli, ctx)
 			};
 		},
 		apply: async (plan, ctx) => {
@@ -8664,16 +8703,25 @@ function setupCommand(cli, install, launch) {
 				version: installs || from === null ? latest : from,
 				prefix,
 				installed: installs,
-				skill,
+				skill: cli.skill?.add === void 0 ? skill : { add: cli.skill.add },
 				upgrades: installs && from !== null ? await upgradesOf(ctx.files, packageDir, from, latest) : [],
 				docs: cli.docs === void 0 ? null : join(packageDir, cli.docs)
 			};
 			ctx.deliver(setup);
-			if (ctx.signal.aborted) throw new CliError({
-				code: INTERRUPTED,
-				message: `interrupted, but ${plan.package}@${setup.version} and its skill are already in place`,
-				hint: "nothing to run again"
-			});
+			if (ctx.signal.aborted) {
+				const add = cli.skill?.add;
+				if (add === void 0) throw new CliError({
+					code: INTERRUPTED,
+					message: `interrupted, but ${plan.package}@${setup.version} and its skill are already in place`,
+					hint: "nothing to run again"
+				});
+				throw runtimeError({
+					code: INTERRUPTED,
+					message: `interrupted, but ${plan.package}@${setup.version} is already installed`,
+					hint: "run the Next step to install its skill from its Skill Hub",
+					next: [wholeLine(add)]
+				});
+			}
 			await assertOnPath(cli, prefix, launch, ctx);
 			return setup;
 		},
@@ -8734,7 +8782,7 @@ function updateCommand(cli, install, launch) {
 				latest: await latestVersion(npm),
 				prefix: copy.prefix,
 				packageDir: copy.packageDir,
-				copies: cli.skill === void 0 ? [] : await homeCopiesOf(ctx.files, cli.name, ctx.env)
+				copies: await syncedCopiesOf(cli, ctx)
 			};
 		},
 		apply: async (plan, ctx) => {
@@ -9635,6 +9683,11 @@ function checkTree(commands, path, table) {
 }
 function checkSkill({ name, skill, install }) {
 	if (skill?.agents !== void 0 && install?.mode === "global") throw new Error(`${name} declares an Agents section on a Global install, which has no repo to write it to`);
+	const add = skill?.add;
+	if (add === void 0) return;
+	if (add.trim() === "") throw new Error(`${name} declares an empty Skill Hub install line`);
+	if (/[\r\n]/.test(add)) throw new Error(`${name} declares a Skill Hub install line holding a line break`);
+	if (install?.mode !== "global") throw new Error(`${name} declares a Skill Hub install line, which only a Global install uses: any other's Skill copy goes in the project`);
 }
 function checkDocs({ name, docs }) {
 	if (docs === void 0) return;
@@ -9732,17 +9785,25 @@ function agentCli(values = {}) {
 /** How long a run waits for its Side task once its output is written. */
 const SIDE_TASK_WAIT_MS = 1e3;
 const noSideTask = async () => {};
+const NO_SIDE_TASK = {
+	end: () => {},
+	finish: noSideTask
+};
 function waitOver() {
 	return new DOMException(`the side task ran past its ${SIDE_TASK_WAIT_MS} ms wait`, "TimeoutError");
 }
 function startSideTask(sideTask, runWith, { clock, failed }) {
-	if (sideTask === void 0) return noSideTask;
+	if (sideTask === void 0) return NO_SIDE_TASK;
+	let end = () => {};
+	const ended = new Promise((resolve) => {
+		end = resolve;
+	});
 	const controller = new AbortController();
 	const { signal } = controller;
-	const running = (async () => sideTask(runWith(signal)))().catch((error) => {
+	const running = (async () => sideTask(runWith(signal, ended)))().catch((error) => {
 		if (!(signal.aborted && error === signal.reason)) failed(error);
 	});
-	return async () => {
+	const finish = async () => {
 		const waited = new AbortController();
 		const capped = new Promise((resolve) => after(clock, SIDE_TASK_WAIT_MS, waited.signal, () => {
 			const over = waitOver();
@@ -9753,6 +9814,10 @@ function startSideTask(sideTask, runWith, { clock, failed }) {
 		await Promise.race([running, capped]);
 		waited.abort();
 	};
+	return {
+		end,
+		finish
+	};
 }
 //#endregion
 //#region ../agent-cli/dist/command-line/suggest.js
@@ -10492,11 +10557,24 @@ function errorText({ leaves }, format) {
 	const { usageHelp, json } = format;
 	return usageHelp !== void 0 && !json && leaves.some((leaf) => leaf.error instanceof UsageError) ? `${text}\n${usageHelp}` : text;
 }
+function endOf(failure) {
+	return {
+		exitCode: failure.exitCode,
+		errors: failure.leaves.map((leaf) => runEndErrorOf(leaf.error))
+	};
+}
+const SUCCEEDED = {
+	exitCode: SUCCESS_EXIT_CODE,
+	errors: []
+};
 function failedResult(failure, format) {
 	return {
-		stdout: "",
-		stderr: errorText(failure, format),
-		exitCode: failure.exitCode
+		result: {
+			stdout: "",
+			stderr: errorText(failure, format),
+			exitCode: failure.exitCode
+		},
+		end: endOf(failure)
 	};
 }
 function stdoutOf({ value, render }, format, spill) {
@@ -10511,10 +10589,13 @@ function startedOutput(outcome, format, spill) {
 	}, spill);
 }
 /** A serve Command stopped, or ended itself, after it started: that is how it is meant to end. */
-const STOPPED_RESULT = {
-	stdout: "",
-	stderr: "",
-	exitCode: SUCCESS_EXIT_CODE
+const STOPPED = {
+	result: {
+		stdout: "",
+		stderr: "",
+		exitCode: SUCCESS_EXIT_CODE
+	},
+	end: SUCCEEDED
 };
 async function errorResult(error, format) {
 	return failedResult(await failureOf(error, format), format);
@@ -10522,9 +10603,12 @@ async function errorResult(error, format) {
 async function commandResult(settled, format, spill) {
 	if (settled.ok) try {
 		return {
-			stdout: await stdoutOf(settled.outcome, format, spill),
-			stderr: "",
-			exitCode: SUCCESS_EXIT_CODE
+			result: {
+				stdout: await stdoutOf(settled.outcome, format, spill),
+				stderr: "",
+				exitCode: SUCCESS_EXIT_CODE
+			},
+			end: SUCCEEDED
 		};
 	} catch (spillError) {
 		return errorResult(spillError, format);
@@ -10538,16 +10622,26 @@ async function commandResult(settled, format, spill) {
 	} catch (rejected) {
 		return failedResult(withLeaves(failure, rejected, format), format);
 	}
-	const result = failedResult(failure, format);
+	const { result, end } = failedResult(failure, format);
 	try {
 		return {
-			...result,
-			stdout: await stdoutOf(outcome, format, spill)
+			result: {
+				...result,
+				stdout: await stdoutOf(outcome, format, spill)
+			},
+			end
 		};
 	} catch (spillError) {
+		const lost = withLeaves(failure, spillError, format);
 		return {
-			...result,
-			stderr: errorText(withLeaves(failure, spillError, format), format)
+			result: {
+				...result,
+				stderr: errorText(lost, format)
+			},
+			end: {
+				...endOf(lost),
+				exitCode: result.exitCode
+			}
 		};
 	}
 }
@@ -11490,12 +11584,34 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		json: routed.json,
 		invocation
 	};
-	const failed = async (error, finishSideTask) => {
-		control.close();
+	const sideTaskOf = (dryRun) => startSideTask(builtIn ? void 0 : cli.sideTask?.bind(cli), (sideSignal, ended) => {
+		const sideBase = scope.portsBase(sideSignal);
+		const sidePorts = once(() => scope.ports(sideBase));
 		return {
-			result: await errorResult(error, format),
-			finishSideTask
+			...sideBase,
+			command: routed.spec.path,
+			dryRun,
+			ended,
+			get ports() {
+				return sidePorts();
+			}
 		};
+	}, {
+		clock,
+		failed: (error) => {
+			if (isDebug(baseFormat)) progress(`side task failed: ${traceOf(error)}`);
+		}
+	});
+	const ran = ({ result, end }, sideTask) => {
+		sideTask.end(end);
+		return {
+			result,
+			finishSideTask: sideTask.finish
+		};
+	};
+	const failed = (error) => {
+		control.close();
+		return errorResult(error, format);
 	};
 	let parsed;
 	try {
@@ -11508,27 +11624,11 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			});
 		});
 	} catch (error) {
-		return failed(error, noSideTask);
+		return ran(await failed(error), sideTaskOf(false));
 	}
 	const { input, flags } = parsed;
 	resumed = command.deadline?.resume(input, rerunOf);
-	const finishSideTask = startSideTask(builtIn ? void 0 : cli.sideTask?.bind(cli), (sideSignal) => {
-		const sideBase = scope.portsBase(sideSignal);
-		const sidePorts = once(() => scope.ports(sideBase));
-		return {
-			...sideBase,
-			command: routed.spec.path,
-			dryRun: flags.dryRun,
-			get ports() {
-				return sidePorts();
-			}
-		};
-	}, {
-		clock,
-		failed: (error) => {
-			if (isDebug(baseFormat)) progress(`side task failed: ${traceOf(error)}`);
-		}
-	});
+	const sideTask = sideTaskOf(flags.dryRun);
 	let project;
 	try {
 		project = builtIn || cli.project === void 0 ? void 0 : projectOf(cli.project, cwd, {
@@ -11536,7 +11636,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			rerun
 		});
 	} catch (error) {
-		return failed(error, finishSideTask);
+		return ran(await failed(error), sideTask);
 	}
 	let delivered;
 	const ctx = contextOf(scope, control, {
@@ -11572,32 +11672,23 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			},
 			outputs
 		})));
-		if (served) return {
-			result: STOPPED_RESULT,
-			finishSideTask
-		};
+		if (served) return ran(STOPPED, sideTask);
 		settled = {
 			ok: true,
 			outcome
 		};
 	} catch (error) {
-		if (served && control.signal.aborted) return {
-			result: STOPPED_RESULT,
-			finishSideTask
-		};
+		if (served && control.signal.aborted) return ran(STOPPED, sideTask);
 		settled = {
 			ok: false,
 			error,
 			delivered
 		};
 	}
-	return {
-		result: await commandResult(settled, {
-			...format,
-			fields: flags.fields
-		}, spill),
-		finishSideTask
-	};
+	return ran(await commandResult(settled, {
+		...format,
+		fields: flags.fields
+	}, spill), sideTask);
 }
 async function noticesOf(cli, launch, ctx) {
 	await installOf(cli).notice(launch, ctx);
@@ -11685,10 +11776,10 @@ async function routeAndRun(cli, argv, options, write, stopNotice) {
 			...format,
 			json: routed.json
 		}));
-		case "usage error": return ranAlone(errorResult(routed.error, {
+		case "usage error": return ranAlone((await errorResult(routed.error, {
 			...misused(routed.node),
 			json: routed.json
-		}));
+		})).result);
 		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)));
 	}
 }
@@ -11751,7 +11842,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.29.0",
+	version: "0.30.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.29.0",
+  "version": "0.30.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.29.0",
+    "@duyquangnvx/agent-cli": "0.30.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },