@duyquangnvx/create-agent-cli 0.13.0 → 0.13.1

package/CHANGELOG.md

@@ -4,6 +4,12 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.13.1 (2026-10-23)
+
+### Changed
+
+- The hints of `INTERRUPTED`, `DEADLINE_EXCEEDED`, `DISK_FULL`, `PERMISSION_DENIED` on Windows, `PROJECT_INVALID`, `TOOL_MISSING`, the npm errors of `update` and `doctor`, and a `doctor` row's fix now name the command line to run again, in backticks like the install and login lines they name, instead of "run the command again". `INTERRUPTED` adds that a run stopped on purpose needs no rerun, and a `ctx.timeout` hint says the call may have been billed, so ask the user before running it again.
+
 ## v0.13.0 (2026-10-23)
 
 ### Changed

package/dist/bin.js

@@ -6480,11 +6480,11 @@ function isCommand(node) {
 //#endregion
 //#region ../agent-cli/dist/project.js
 const PROJECT_INVALID = "PROJECT_INVALID";
-function invalid(path, problem, options) {
+function invalid(path, problem, callerLine, options) {
 	return new CliError({
 		code: PROJECT_INVALID,
 		message: `the Project file ${path} is invalid: ${problem}`,
-		hint: `fix ${path}, then run the command again`
+		hint: `fix ${path}, then run \`${callerLine}\` again`
 	}, options);
 }
 function readText(path, fileError) {
@@ -6498,30 +6498,30 @@ function readText(path, fileError) {
 		});
 	}
 }
-function parsed(path, text, schema) {
+function parsed(path, text, schema, callerLine) {
 	let json;
 	try {
 		json = JSON.parse(text);
 	} catch (error) {
-		throw invalid(path, messageOf(error), { cause: error });
+		throw invalid(path, messageOf(error), callerLine, { cause: error });
 	}
 	const result = schema.safeParse(json);
-	if (!result.success) throw invalid(path, prettifyError(result.error));
+	if (!result.success) throw invalid(path, prettifyError(result.error), callerLine);
 	return result.data;
 }
-function projectFrom(projectFile, folder, fileError) {
+function projectFrom(projectFile, folder, scope) {
 	const path = join(folder, projectFile.file);
-	const text = readText(path, fileError);
+	const text = readText(path, scope.fileError);
 	if (text !== void 0) return {
 		root: folder,
-		settings: parsed(path, text, projectFile.schema)
+		settings: parsed(path, text, projectFile.schema, scope.callerLine)
 	};
 	const parent = dirname(folder);
-	return parent === folder ? void 0 : projectFrom(projectFile, parent, fileError);
+	return parent === folder ? void 0 : projectFrom(projectFile, parent, scope);
 }
 /** The nearest Project file at or above `cwd`, parsed by its schema; undefined when there is none. */
-function projectOf(projectFile, cwd, fileError) {
-	return projectFrom(projectFile, resolve(cwd), fileError);
+function projectOf(projectFile, cwd, scope) {
+	return projectFrom(projectFile, resolve(cwd), scope);
 }
 //#endregion
 //#region ../agent-cli/dist/tools.js
@@ -6554,7 +6554,7 @@ async function findTool(name, env) {
 	for (const file of candidates) if (await isExecutable(file)) return file;
 }
 /** Fails with `TOOL_MISSING`, naming every missing tool at once, unless all are on `PATH`. */
-async function checkTools(tools, env) {
+async function checkTools(tools, env, callerLine) {
 	const found = await Promise.all(tools.map((tool) => findTool(tool.name, env)));
 	const missing = tools.filter((_tool, index) => found[index] === void 0);
 	if (missing.length === 0) return;
@@ -6562,7 +6562,7 @@ async function checkTools(tools, env) {
 	throw new CliError({
 		code: TOOL_MISSING,
 		message: `${missing.length === 1 ? "a tool it runs is" : "tools it runs are"} not on PATH: ${names}`,
-		hint: `install ${missing.length === 1 ? "it" : "them"}, then run the same command again: ${missing.map(({ install }) => install).join("; ")}`
+		hint: `install ${missing.map(({ name, install }) => `${name} (\`${install}\`)`).join(", ")}, then run \`${callerLine}\` again`
 	});
 }
 function toolsIn(node) {
@@ -6795,15 +6795,15 @@ function failedError(command, { exitCode, stderr }) {
 		hint: `the output of ${command} above says why it failed`
 	});
 }
-function missingError(command, cause) {
+function missingError(command, callerLine, cause) {
 	return new CliError({
 		code: TOOL_MISSING,
 		message: `${command} could not be started: it is not on PATH`,
-		hint: `install ${command}, then run the same command again`
+		hint: `install ${command}, then run \`${callerLine}\` again`
 	}, { cause });
 }
-function startError(command, error, fileError) {
-	if (isMissingFile(error)) return missingError(command, error);
+function startError(command, error, { fileError, callerLine }) {
+	if (isMissingFile(error)) return missingError(command, callerLine, error);
 	return fileError(error, {
 		path: command,
 		access: "read"
@@ -6833,8 +6833,7 @@ function reportingLines(onLine, onError) {
 		}
 	};
 }
-/** `ctx.spawn`: `spawn` bound to the run, its start failures classified by errno. */
-function contextSpawn(run, defaults, fileError) {
+function contextSpawn(run, defaults, scope) {
 	return async (command, args = [], options = {}) => {
 		let callerFailure;
 		const caller = (error) => {
@@ -6850,7 +6849,7 @@ function contextSpawn(run, defaults, fileError) {
 				stdin: reporting(options.stdin, caller)
 			});
 		} catch (error) {
-			throw callerFailure?.error === error ? error : startError(command, error, fileError);
+			throw callerFailure?.error === error ? error : startError(command, error, scope);
 		}
 		if (options.check === true && result.exitCode !== 0) throw failedError(command, result);
 		return result;
@@ -6927,6 +6926,7 @@ const NO_LATEST = "NO_LATEST";
 function npmContext(cli, registry, ctx, node, cwd) {
 	return {
 		cliName: cli.name,
+		callerLine: ctx.commandLine(),
 		registry,
 		cwd,
 		env: ctx.env,
@@ -6966,8 +6966,8 @@ function globalRegistry(install) {
 		package: name,
 		label: registry,
 		flags: registryFlags(install),
-		unreachableHint: "check the network or VPN, then run it again",
-		loginHint: `log in to ${registry} (npm login --registry=${registry}) or set its token in ~/.npmrc, then run it again`,
+		unreachableHint: "check the network or VPN",
+		loginHint: `log in to ${registry} (\`npm login --registry=${registry}\`) or set its token in ~/.npmrc`,
 		missingHint: `check that ${name} is published on ${registry}`
 	};
 }
@@ -7021,26 +7021,27 @@ function failureOf(call, answer, ctx) {
 	const { label: registry, package: name, loginHint, unreachableHint } = ctx.registry;
 	const code = NPM_CODE.exec(answer.stderr)?.[1];
 	const output = tail$1(answer.stderr);
+	const rerun = `run \`${ctx.callerLine}\` again`;
 	if (code !== void 0 && NETWORK_CODES.has(code)) return new CliError({
 		code: REGISTRY_UNREACHABLE,
 		message: `npm could not reach ${registry} (${code})${output}`,
-		hint: unreachableHint
+		hint: `${unreachableHint}, then ${rerun}`
 	});
 	if (code !== void 0 && AUTH_CODES.has(code)) return new CliError({
 		code: REGISTRY_AUTH,
 		message: `${registry} refused npm's credentials (${code})${output}`,
-		hint: loginHint
+		hint: `${loginHint}, then ${rerun}`
 	});
 	if (call === "view" && code === "E404") return noLatest(ctx, `npm found no ${name}@latest on ${registry}: no version of it is published there`);
 	if (call === "install") return new CliError({
 		code: INSTALL_FAILED,
 		message: `npm could not install ${name}${code === void 0 ? "" : ` (${code})`}${output}`,
-		hint: `fix what npm reports, then run it again, or install it yourself: ${installCommandLine(ctx.registry)}`
+		hint: `fix what npm reports, then ${rerun}, or install it yourself: \`${installCommandLine(ctx.registry)}\``
 	});
 	return new CliError({
 		code: NPM_FAILED,
 		message: `npm ${call} failed with exit code ${answer.exitCode}${output}`,
-		hint: "fix what npm reports, then run it again"
+		hint: `fix what npm reports, then ${rerun}`
 	});
 }
 function noLatest(ctx, message) {
@@ -7328,8 +7329,8 @@ function registryOf({ package: name }, root) {
 		package: name,
 		label: `the registry npm uses for ${name}`,
 		flags: [],
-		unreachableHint: scope === void 0 ? "check the network or VPN, then run it again" : `check the network or VPN and the ${scope}:registry that ${npmrc} sets, then run it again`,
-		loginHint: `log in to it (npm login${scope === void 0 ? "" : ` --scope=${scope}`}) or set its token in ${npmrc}, then run it again`,
+		unreachableHint: scope === void 0 ? "check the network or VPN" : `check the network or VPN and the ${scope}:registry that ${npmrc} sets`,
+		loginHint: `log in to it (\`npm login${scope === void 0 ? "" : ` --scope=${scope}`}\`) or set its token in ${npmrc}`,
 		missingHint: scope === void 0 ? `check that ${name} is published on the registry ${npmrc} names` : `check that ${name} is published, and that ${npmrc} maps ${scope} to its registry: ${scope}:registry=<url>`
 	};
 }
@@ -7475,7 +7476,10 @@ function readProject(projectFile, ctx) {
 	try {
 		return {
 			ok: true,
-			project: projectOf(projectFile, ctx.cwd, ctx.fileError)
+			project: projectOf(projectFile, ctx.cwd, {
+				fileError: ctx.fileError,
+				callerLine: ctx.commandLine()
+			})
 		};
 	} catch (error) {
 		return {
@@ -7676,11 +7680,11 @@ function render({ rows, next }, style) {
 		return `${check.padEnd(width)}${label}${" ".repeat(stateWidth - state.length)}${message}`;
 	}), ...next.map((fix) => `${"next".padEnd(width)}${fix}`)].join("\n");
 }
-function failure(cliName, problems) {
+function failure(cliName, callerLine, problems) {
 	const errors = problems.map(({ check, message, fix, code }) => new CliError({
 		code: code ?? "DOCTOR_PROBLEMS",
 		message: `${cliName} doctor found a problem in ${check}: ${message}`,
-		hint: fix === void 0 ? "the row says what is wrong" : `run ${fix}, then run doctor again`
+		hint: fix === void 0 ? "the row says what is wrong" : `run \`${fix}\`, then run \`${callerLine}\` again`
 	}));
 	return new AggregateError(errors);
 }
@@ -7713,7 +7717,7 @@ function doctorCommand(cli, launch) {
 			const problems = checked.filter(({ row, advisory }) => row.state === "problem" && !advisory).map(({ row }) => row);
 			if (problems.length > 0) {
 				ctx.deliver(report);
-				throw failure(cli.name, problems);
+				throw failure(cli.name, ctx.commandLine(), problems);
 			}
 			return report;
 		},
@@ -7727,14 +7731,16 @@ const DEADLINE_EXCEEDED = "DEADLINE_EXCEEDED";
 /** How long an interrupted Command may take to settle before the run ends without it. */
 const GRACE_MS = 3e3;
 const GRACE_OVER = Symbol("grace over");
-function interruptedError() {
+function interruptedError(callerLine) {
 	return new CliError({
 		code: INTERRUPTED,
 		message: "interrupted before it finished",
-		hint: "run the command again"
+		hint: `to finish it, run \`${callerLine}\` again, unless it was stopped on purpose; if a tool timeout stopped it, give it longer`
 	});
 }
-const WAIT_HINT = "run it again later, when the service it waits on may answer faster";
+function waitHint(callerLine, bound) {
+	return bound === "timeout" ? `the call may have been billed: ask your user before running \`${callerLine}\` again` : `run \`${callerLine}\` again later, when the service it waits on may answer faster`;
+}
 function deadlineError(commandLine, ms, hint, bound = "deadline") {
 	return new CliError({
 		code: DEADLINE_EXCEEDED,
@@ -7747,8 +7753,9 @@ var RunControl = class {
 	signal;
 	#controller = new AbortController();
 	#commandLine;
+	#callerLine;
 	#outer;
-	#onOuterAbort = () => this.#controller.abort(interruptedError());
+	#onOuterAbort = () => this.#controller.abort(interruptedError(this.#callerLine));
 	/** Each running must-finish step, tracked until it settles, with its name. */
 	#steps = /* @__PURE__ */ new Map();
 	#progress;
@@ -7761,8 +7768,9 @@ var RunControl = class {
 	#graceOver = new Promise((resolve) => {
 		this.#endGrace = resolve;
 	});
-	constructor({ commandLine, outer, clock, progress, runDeadline }) {
+	constructor({ commandLine, callerLine, outer, clock, progress, runDeadline }) {
 		this.#commandLine = commandLine;
+		this.#callerLine = callerLine;
 		this.#outer = outer;
 		this.#clock = clock;
 		this.#progress = progress;
@@ -7784,7 +7792,7 @@ var RunControl = class {
 	#abortsAfter(ms, bound) {
 		const controller = new AbortController();
 		after(this.#clock, ms, this.#disposed.signal, () => {
-			const reason = deadlineError(this.#commandLine, ms, WAIT_HINT, bound);
+			const reason = deadlineError(this.#commandLine, ms, waitHint(this.#callerLine, bound), bound);
 			this.#abortReasons.add(reason);
 			controller.abort(reason);
 		});
@@ -8098,7 +8106,7 @@ const NOT_FOUND = "NOT_FOUND";
 const ALREADY_EXISTS = "ALREADY_EXISTS";
 const NOT_A_FILE = "NOT_A_FILE";
 function permissionHint({ path, access, callerLine, env, platform }) {
-	if (platform === "win32") return `a program may hold ${path} open: close it, then run the same command again`;
+	if (platform === "win32") return `a program may hold ${path} open: close it, then run \`${callerLine}\` again`;
 	if (!isAgent(env)) return `check the permissions of ${path} and its folder`;
 	return `your sandbox may block it: ask your user to run \`! ${callerLine}\`, or ${access === "read" ? `to allow reading ${path} in the sandbox` : `to allow ${path} in the sandbox's write list`}`;
 }
@@ -8123,7 +8131,7 @@ function classifyErrno(error, context) {
 		case "EDQUOT": return new CliError({
 			code: DISK_FULL,
 			message: `no space left on the disk holding ${path}`,
-			hint: "free space on that disk, then run the same command again"
+			hint: `free space on that disk, then run \`${context.callerLine}\` again`
 		}, { cause: error });
 		case "ENOENT":
 		case "ENOTDIR":
@@ -9046,7 +9054,7 @@ function dryRunOutcome(command, plan) {
 	};
 }
 async function execute(command, input, ctx, { dryRun, confirm, yes, page, invocation, commandLine, started, files, guardOutputs }) {
-	await checkTools(command.tools ?? [], ctx.env);
+	await checkTools(command.tools ?? [], ctx.env, ctx.commandLine());
 	if (command.rows !== void 0) return outcomeOf(await command.run({
 		...input,
 		...page
@@ -9401,7 +9409,7 @@ function portsOf(cli, replacement) {
 	return cli.ports ?? (() => ({}));
 }
 function portsBaseOf(scope, signal) {
-	const { cli, options, packageRoot, progress, fileError, clock, files } = scope;
+	const { cli, options, packageRoot, progress, fileError, callerLine, clock, files } = scope;
 	const { cwd, env } = options;
 	const envFile = envFileOf(cli.name, env);
 	return {
@@ -9426,7 +9434,10 @@ function portsBaseOf(scope, signal) {
 			cwd,
 			env,
 			signal
-		}, fileError)
+		}, {
+			fileError,
+			callerLine
+		})
 	};
 }
 function contextOf(portsBase, control, parts) {
@@ -9462,8 +9473,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		flags: knownFlags(routed.spec),
 		stdinArg: stdinArgOf(routed)
 	};
+	const typedLine = (change) => commandLineOf(invocation, change);
+	const rerunLine = typedLine();
 	const fileError = fileErrorOf({
-		callerLine: commandLineOf(invocation),
+		callerLine: rerunLine,
 		env,
 		platform
 	});
@@ -9473,20 +9486,20 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		json: routed.json,
 		invocation
 	};
-	const typedLine = (change) => commandLineOf(invocation, change);
-	const callerLine = commandLineOf({
+	const pipedLine = commandLineOf({
 		...invocation,
 		stdinArg: void 0
 	});
 	let resumeHint;
 	const control = new RunControl({
 		commandLine,
+		callerLine: rerunLine,
 		outer: options.signal,
 		clock,
 		progress,
 		runDeadline: command.deadline === void 0 ? void 0 : {
 			ms: command.deadline.ms,
-			hint: () => resumeHint ?? stdinNeverEndedHint(callerLine)
+			hint: () => resumeHint ?? stdinNeverEndedHint(pipedLine)
 		}
 	});
 	const failed = (error, finishSideTask) => {
@@ -9503,7 +9516,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 			if (isTerminal(stdin)) progress(readingLine(field.name, platform));
 			return readStdin(stdin, control.signal, {
 				clock,
-				stalled: () => stdinStalled(callerLine)
+				stalled: () => stdinStalled(pipedLine)
 			});
 		});
 	} catch (error) {
@@ -9521,6 +9534,7 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 		packageRoot,
 		progress,
 		fileError,
+		callerLine: rerunLine,
 		clock,
 		files: outputs.files
 	};
@@ -9544,7 +9558,10 @@ async function runCommand(cli, routed, options, write, baseFormat) {
 	});
 	let project;
 	try {
-		project = builtIn || cli.project === void 0 ? void 0 : projectOf(cli.project, cwd, fileError);
+		project = builtIn || cli.project === void 0 ? void 0 : projectOf(cli.project, cwd, {
+			fileError,
+			callerLine: rerunLine
+		});
 	} catch (error) {
 		return failed(error, finishSideTask);
 	}
@@ -9759,14 +9776,14 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.13.0";
+var version$1 = "0.13.1";
 var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "1c3a29e",
+	"sha": "7b1baa9",
 	"dirty": false,
-	"builtAt": "2026-10-23T05:43:49.000Z"
+	"builtAt": "2026-10-23T13:03:05.000Z"
 };
 //#endregion
 //#region src/steps.ts

package/package.json

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