@duyquangnvx/create-agent-cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.4.0 (2026-10-19)
+
+### Added
+
+- The last field of a Command's `args` may be a `z.array(...)`, optionally wrapped in optional or default, which takes every remaining operand: `tool preview a b c` gives `dirs: ["a", "b", "c"]`. None gives an empty array for the schema to judge, or leaves an optional field out so its default applies. Each operand is coerced like a scalar arg of the element's type, and an issue on one names it and its position, as in `<values...> "x" (argument 3): ...`. Text help shows the field as `<name...>` (`[name...]` when optional), and `--help --json` gives it the array schema. `defineCommand` throws when an array field is not the last of `args`.
+- The ports factory receives `PortsBase`, the run's base context: `env`, `cwd`, `packageRoot`, `secret`, `spawn`, `files`, `clock` and `signal`, the same classified, cwd-resolved helpers a Command gets, so an adapter reads a secret or the package root as a Command does. Under `runCli` it sees the test's `env`, `cwd`, `clock`, `files` and `spawn`, and the `ports` option still replaces its result. It runs when a run first reads `ctx.ports`, at most once, and what it throws exits by its Exit class like a Command error; a run that never reads them, such as `doctor` or `update`, never calls it, and a `doctor` row that reads them reports the error as its problem. A factory written as `() => Ports` still type-checks; the type `PortsBase` is exported.
+- A write or destructive Command may declare `force: "<what it replaces>"`, which gives it the Standard flag `--force` with that sentence as the flag's description in help and help JSON. A Command gets `--force` from `outputs`, `force` or both; with `outputs`, `--force` still lifts `OUTPUT_EXISTS`, and `outputs` alone keeps the generic description. `ctx.force` is true only when the caller passed `--force` to a Command that has it, and `plan` sees it under `--dry-run` too. `defineCommand` throws when a read or serve Command declares `force`, or when the sentence is empty.
+- `ctx.files.read(path)` returns a file's bytes as a `Uint8Array`; `ctx.files.list(folder)` returns the names in a folder, sorted, never the Runtime's temp files; `ctx.files.remove(path)` removes a file or a folder with everything in it, and succeeds when the path does not exist; `ctx.files.mkdir(path, { exclusive? })` creates a folder and its missing parents, and with `exclusive: true` fails when the folder exists. Each resolves its path against `ctx.cwd` and fails as `write` does: `PERMISSION_DENIED` (exit 2, with the sandbox hint under a Coding agent), `DISK_FULL` (exit 2) or `NOT_FOUND` (exit 1), naming the path. The type `MkdirOptions` is exported.
+- The Runtime code `ALREADY_EXISTS` (exit 1), raised for EEXIST, such as an exclusive `mkdir` of an existing folder, naming the path, with a hint to pass another path or remove that one. `ALREADY_EXISTS`, `PERMISSION_DENIED`, `DISK_FULL` and `NOT_FOUND` are exported as constants, so a Command catches one with `error instanceof CliError && error.code === ALREADY_EXISTS`.
+
+### Changed
+
+- **Breaking:** `doctor` exits 0 when only its `install` or `registry` row is a problem (not a global install, a newer version on the registry, or the registry unreachable). Those rows still show `problem` with their fix, in text and `--json`, and the fix stays under `next`.
+- **Breaking:** the `Files` interface gains `read`, `list`, `remove` and `mkdir`, so every fake passed as `runCli`'s `files` option must implement them. The scaffolded template's fake and the skill's example implement them.
+- **Breaking:** `ctx.files.write` creates missing parent folders, so a write into a missing folder no longer fails with `NOT_FOUND`.
+- The agent-cli skill teaches every 0.4.0 feature: the ports factory reading `PortsBase`, array positionals, `force` with `ctx.force`, and `ctx.files`' `read`, `list`, `remove` and `mkdir` with a caught `ALREADY_EXISTS`. Its example `links` gains `bundle <folder> <ids...>`, which writes shortcut files into a new folder and replaces an existing one under `--force`, a `web` port that `links check` uses and whose factory reads `LINKS_TOKEN`, and reads `links.json` through `ctx.files`.
+
+### Fixed
+
+- Under a Coding agent, a `PERMISSION_DENIED` on a read (`ctx.files.read`, `list` or `exists`, an unreadable `.env`, a tool `ctx.spawn` cannot run) asks the user to allow reading the path in the sandbox, not to add it to the sandbox's write list.
+- A `$XDG_CONFIG_HOME/<cli>/.env` the Runtime cannot read makes `ctx.secret` fail with `PERMISSION_DENIED` (exit 2) naming the file, with the sandbox hint under an agent, instead of exit 70. A missing `.env` still means no secrets.
+
 ## v0.3.0 (2026-10-19)
 
 ### Added

package/dist/bin.js

@@ -5603,21 +5603,29 @@ function describe(schema) {
 		current = current.unwrap();
 		description ??= current.description;
 	}
+	const variadic = current instanceof ZodArray;
+	if (current instanceof ZodArray) current = current.element;
 	return {
 		type: typeOf(current),
 		required,
 		defaultValue,
 		description,
-		choices: current instanceof ZodEnum ? current.options.map(String) : void 0
+		choices: current instanceof ZodEnum ? current.options.map(String) : void 0,
+		variadic
 	};
 }
+function argLabel(key, { variadic, required }) {
+	if (!variadic) return `<${key}>`;
+	return required ? `<${key}...>` : `[${key}...]`;
+}
 function argField(key, schema) {
-	const label = `<${key}>`;
+	const described = describe(schema);
+	const label = argLabel(key, described);
 	return {
 		key,
 		name: key,
 		schema,
-		...describe(schema),
+		...described,
 		label,
 		usage: label
 	};
@@ -5643,6 +5651,14 @@ function fieldsOf$1(schema, toField) {
 function argFields(schema) {
 	return fieldsOf$1(schema, argField);
 }
+/** Throws when an arg that takes every remaining operand is not the last arg. */
+function checkArrayArgLast(name, args) {
+	const misplaced = argFields(args).slice(0, -1).filter((field) => field.variadic);
+	if (misplaced.length > 0) {
+		const keys = misplaced.map(({ key }) => `'${key}'`).join(", ");
+		throw new Error(`Command '${name}' declares array arg ${keys} before its last arg; only the last arg may be an array`);
+	}
+}
 function optionFields(schema) {
 	return fieldsOf$1(schema, optionField);
 }
@@ -5935,6 +5951,12 @@ function pageFooter({ items, next }) {
 	return `${items.length} shown; ${more}\n`;
 }
 //#endregion
+//#region ../agent-cli/dist/planned.js
+/** Whether `command` changes something through a Plan: a write or destructive Command. */
+function hasPlan(command) {
+	return command.effect === "write" || command.effect === "destructive";
+}
+//#endregion
 //#region ../agent-cli/dist/flags.js
 const HELP_FLAG = "--help";
 const VERSION_FLAG = "--version";
@@ -5997,10 +6019,14 @@ const RESERVED = new Map([
 	...LIST_FLAGS
 ].map((flag) => [nameOf(flag), flag]));
 /** The Standard flags of a Command with this Effect and declarations, and of a List Command. */
-function standardFlagsFor(effect, { outputs, cost }, list) {
+function standardFlagsFor(effect, { outputs, force, cost }, list) {
+	const forceFlag = force === void 0 ? FORCE_FLAG : {
+		...FORCE_FLAG,
+		description: force
+	};
 	return [
 		...EFFECT_FLAGS[effect],
-		...outputs ? [FORCE_FLAG] : [],
+		...outputs || force !== void 0 ? [forceFlag] : [],
 		...cost ? [YES_FLAG] : [],
 		...list?.standardFlags ?? []
 	];
@@ -6019,10 +6045,19 @@ function checkNoStandardFlags(command) {
 	});
 	if (lines.length > 0) throw new Error([`Command '${command.name}' declares Standard flags the Runtime adds; rename them:`, ...lines].join("\n"));
 }
+/** Throws when `force` is declared on a Command with no Plan, or says nothing. */
+function checkForce(command) {
+	const force = "force" in command ? command.force : void 0;
+	if (force === void 0) return;
+	if (!hasPlan(command)) throw new Error(`Command '${command.name}' declares force, which only a write or destructive Command may`);
+	if (force.trim() === "") throw new Error(`Command '${command.name}' declares an empty force; say what ${FORCE_FLAG.flag} replaces`);
+}
 //#endregion
 //#region ../agent-cli/dist/define.js
 function checkedCommand(command) {
 	checkNoStandardFlags(command);
+	checkForce(command);
+	checkArrayArgLast(command.name, command.args);
 	return command;
 }
 function defineCommandFor() {
@@ -6369,8 +6404,10 @@ function isAgent(env) {
 const PERMISSION_DENIED = "PERMISSION_DENIED";
 const DISK_FULL = "DISK_FULL";
 const NOT_FOUND = "NOT_FOUND";
-function permissionHint({ path, callerLine, env }) {
-	return isAgent(env) ? `your sandbox may block it: ask your user to run \`! ${callerLine}\`, or to allow ${path} in the sandbox's write list` : `check the permissions of ${path} and its folder`;
+const ALREADY_EXISTS = "ALREADY_EXISTS";
+function permissionHint({ path, access, callerLine, env }) {
+	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`}`;
 }
 /** The error a file system failure on `path` stands for; any other error comes back unchanged. */
 function classifyErrno(error, context) {
@@ -6392,6 +6429,11 @@ function classifyErrno(error, context) {
 			message: `not found: ${path}`,
 			hint: `check that ${path} and its folder exist`
 		}, { cause: error });
+		case "EEXIST": return new CliError({
+			code: ALREADY_EXISTS,
+			message: `already exists: ${path}`,
+			hint: `pass another path, or remove ${path}`
+		}, { cause: error });
 		default: return error;
 	}
 }
@@ -6740,6 +6782,7 @@ function contextSpawn(run, defaults, callerLine) {
 			if (isMissingFile(error)) throw missingError(command, error);
 			throw classifyErrno(error, {
 				path: command,
+				access: "read",
 				callerLine,
 				env: defaults.env
 			});
@@ -6778,6 +6821,7 @@ function runtimeCodes() {
 		[PERMISSION_DENIED]: "operator",
 		[DISK_FULL]: "operator",
 		[NOT_FOUND]: "caller",
+		[ALREADY_EXISTS]: "caller",
 		[TOOL_FAILED]: "operator",
 		[TOOL_MISSING]: "operator",
 		[PROJECT_INVALID]: "operator",
@@ -7219,6 +7263,7 @@ function projectRow(projectFile) {
 function installRow(cli, bin) {
 	return {
 		name: "install",
+		advisory: true,
 		run: async (ctx) => {
 			const { install } = cli;
 			if (install === void 0) return ok(`${cli.name} declares no install, so it has no \`update\``);
@@ -7238,6 +7283,7 @@ function installRow(cli, bin) {
 function registryRow(cli) {
 	return {
 		name: "registry",
+		advisory: true,
 		run: async (ctx) => {
 			const { install } = cli;
 			if (install === void 0) return ok(`${cli.name} declares no registry to compare this build with`);
@@ -7325,15 +7371,15 @@ function problemOf(check, error, { signal, deadline, ms }) {
 		message: `the ${check.name} row hit a bug: ${messageOf(error)}`
 	};
 }
+function withSignal(ctx, signal) {
+	return Object.create(ctx, { signal: { value: signal } });
+}
 async function rowOf(check, ctx) {
 	const ms = check.deadlineMs ?? DEFAULT_DEADLINE_MS;
 	const signal = ctx.deadline(ms);
 	let finding;
 	try {
-		finding = await Promise.race([Promise.resolve().then(() => check.run({
-			...ctx,
-			signal
-		})), untilAborted(signal)]);
+		finding = await Promise.race([Promise.resolve().then(() => check.run(withSignal(ctx, signal))), untilAborted(signal)]);
 	} catch (error) {
 		finding = problemOf(check, error, {
 			signal: ctx.signal,
@@ -7576,10 +7622,15 @@ function cliError(_table, code, init, options) {
 //#endregion
 //#region ../agent-cli/dist/command-spec.js
 function declaredOf(command) {
-	const planned = command.effect === "write" || command.effect === "destructive";
+	if (!hasPlan(command)) return {
+		outputs: false,
+		force: void 0,
+		cost: false
+	};
 	return {
-		outputs: planned && command.outputs !== void 0,
-		cost: planned && command.cost !== void 0
+		outputs: command.outputs !== void 0,
+		force: command.force,
+		cost: command.cost !== void 0
 	};
 }
 function commandSpec(commandLine, command) {
@@ -7641,7 +7692,7 @@ function dryRunOutcome(command, plan) {
 		].join("\n")
 	};
 }
-async function execute(command, input, ctx, { dryRun, confirm, yes, force, page, invocation, commandLine, started }) {
+async function execute(command, input, ctx, { dryRun, confirm, yes, page, invocation, commandLine, started }) {
 	await checkTools(command.tools ?? [], ctx.env);
 	if (command.rows !== void 0) return outcomeOf(await command.run({
 		...input,
@@ -7657,7 +7708,7 @@ async function execute(command, input, ctx, { dryRun, confirm, yes, force, page,
 	await checkOutputs({
 		invocation,
 		commandLine,
-		force,
+		force: ctx.force,
 		files: ctx.files
 	}, command.outputs?.(plan));
 	checkCost({
@@ -7708,6 +7759,7 @@ function realFiles() {
 		},
 		write: async (path, data) => {
 			const folder = dirname(path);
+			await mkdir(folder, { recursive: true });
 			if (!swept.has(folder)) {
 				await sweep(folder);
 				swept.add(folder);
@@ -7720,9 +7772,50 @@ function realFiles() {
 				await rm(temp, { force: true });
 				throw error;
 			}
+		},
+		read: (path) => readFile(path),
+		list: (folder) => readdir(folder),
+		remove: (path) => rm(path, {
+			recursive: true,
+			force: true
+		}),
+		mkdir: async (path, options) => {
+			if (options?.exclusive !== true) {
+				await mkdir(path, { recursive: true });
+				return;
+			}
+			await mkdir(dirname(path), { recursive: true });
+			await mkdir(path);
 		}
 	};
 }
+/**
+* `files` resolving paths against `cwd`, its failures classified by errno; `list` drops the
+* Runtime's temp files and sorts.
+*/
+function classifiedFiles(files, { cwd, env, callerLine }) {
+	async function at(access, path, work) {
+		const target = resolve(cwd, path);
+		try {
+			return await work(target);
+		} catch (error) {
+			throw classifyErrno(error, {
+				path: target,
+				access,
+				callerLine,
+				env
+			});
+		}
+	}
+	return {
+		exists: (path) => at("read", path, (target) => files.exists(target)),
+		write: (path, data) => at("write", path, (target) => files.write(target, data)),
+		read: (path) => at("read", path, (target) => files.read(target)),
+		list: (folder) => at("read", folder, async (target) => (await files.list(target)).filter((name) => !TEMP_FILE.test(name)).sort()),
+		remove: (path) => at("write", path, (target) => files.remove(target)),
+		mkdir: (path, options) => at("write", path, (target) => files.mkdir(target, options))
+	};
+}
 //#endregion
 //#region ../agent-cli/dist/package-root.js
 /**
@@ -7893,10 +7986,14 @@ function optionValue(field, raw) {
 	return field.type === "boolean" && raw === true && field.label === `--no-${field.name}` ? false : raw;
 }
 function converted(field, raw) {
+	if (Array.isArray(raw)) return raw.map((element) => converted(field, element));
 	if (field.type !== "number" || typeof raw !== "string" || raw.trim() === "") return raw;
 	const number = Number(raw);
 	return Number.isNaN(number) ? raw : number;
 }
+function variadicValue(field, values) {
+	return values.length === 0 && !field.required ? void 0 : values;
+}
 function parse(schema, values) {
 	const input = Object.fromEntries([...values].filter(([, raw]) => raw !== void 0).map(([field, raw]) => [field.key, converted(field, raw)]));
 	return schema.safeParse(input);
@@ -7908,9 +8005,15 @@ function issueLines(result, values, howToPass, reported) {
 		if (field === void 0) return [`  ${issue.message}`];
 		if (reported.includes(field)) return [];
 		const raw = values.get(field);
-		return raw === void 0 ? [`  ${field.label}: required, ${howToPass(field)}`] : [`  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`];
+		if (raw === void 0) return [`  ${field.label}: required, ${howToPass(field)}`];
+		return Array.isArray(raw) ? [operandsIssueLine(field, raw, issue, [...values.keys()].indexOf(field) + 1)] : [`  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`];
 	});
 }
+function operandsIssueLine(field, raw, issue, first) {
+	const [, element] = issue.path;
+	if (typeof element === "number") return `  ${field.label} ${JSON.stringify(raw[element])} (argument ${first + element}): ${issue.message}`;
+	return raw.length === 0 ? `  ${field.label}: ${issue.message}, pass them as arguments from ${first}` : `  ${field.label} ${JSON.stringify(raw)}: ${issue.message}`;
+}
 function unknownLine({ flag, suggestion }) {
 	return `  unknown option '${flag}'${suggestion === void 0 ? "" : ` (did you mean ${suggestion}?)`}`;
 }
@@ -7934,7 +8037,8 @@ function parseInput(spec, words, invocation) {
 	const { operands, unknownOptions, values } = tokenize(words, known);
 	if (values.get(CONFIRM_FLAG.flag) === true) throw invalidInputError(spec.commandLine, `option '${CONFIRM_FLAG.usage}' argument missing`);
 	const missing = [...optionFields, ...pageFields].filter((field) => field.type !== "boolean" && values.get(field.label) === true);
-	const argValues = new Map(argFields.map((field, index) => [field, operands[index]?.value]));
+	const argValues = new Map(argFields.map((field, index) => [field, field.variadic ? variadicValue(field, operands.slice(index).filter((operand) => !operand.afterUnknownOption).map((operand) => operand.value)) : operands[index]?.value]));
+	const extraOperands = argFields.some((field) => field.variadic) ? [] : operands.slice(argFields.length);
 	const valuesOf = (fields) => new Map(fields.map((field) => [field, missing.includes(field) ? void 0 : optionValue(field, values.get(field.label))]));
 	const optionValues = valuesOf(optionFields);
 	const pageValues = valuesOf(pageFields);
@@ -7944,7 +8048,7 @@ function parseInput(spec, words, invocation) {
 	const unknown = unknownOptionsOf(unknownOptions, candidateFlags(known));
 	const otherLines = [
 		...missing.map((field) => `  ${field.label}: missing value, pass ${field.usage}`),
-		...operands.slice(argFields.length).filter((operand) => !operand.afterUnknownOption).map((operand) => `  unexpected argument ${JSON.stringify(operand.value)}`),
+		...extraOperands.filter((operand) => !operand.afterUnknownOption).map((operand) => `  unexpected argument ${JSON.stringify(operand.value)}`),
 		...issueLines(args, argValues, (field) => `pass it as argument ${argFields.indexOf(field) + 1}`, []),
 		...issueLines(options, optionValues, (field) => `pass ${field.usage}`, missing),
 		...issueLines(page, pageValues, (field) => `pass ${field.usage}`, missing)
@@ -8059,23 +8163,30 @@ function dotenvPath(cliName, env) {
 	const config = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
 	return join(config, cliName, ".env");
 }
-function readDotenv(path) {
+function readDotenv(path, env, callerLine) {
+	let text;
 	try {
-		return parseEnv(readFileSync(path, "utf8"));
+		text = readFileSync(path, "utf8");
 	} catch (error) {
 		if (isMissingFile(error)) return {};
-		throw error;
+		throw classifyErrno(error, {
+			path,
+			access: "read",
+			callerLine,
+			env
+		});
 	}
+	return parseEnv(text);
 }
 /** Looks `name` up in the env, then in `$XDG_CONFIG_HOME/<cli>/.env`; an empty value counts as unset. */
-function secretOf(cliName, env, name) {
+function secretOf({ cliName, env, callerLine }, name) {
 	const fromEnv = env[name];
 	if (fromEnv) return {
 		value: fromEnv,
 		origin: { kind: "env" }
 	};
 	const path = dotenvPath(cliName, env);
-	const fromFile = readDotenv(path)[name];
+	const fromFile = readDotenv(path, env, callerLine)[name];
 	return fromFile ? {
 		value: fromFile,
 		origin: {
@@ -8111,6 +8222,7 @@ async function prepare(folder, cutoff, target) {
 	} catch (error) {
 		throw classifyErrno(error, {
 			path: folder,
+			access: "write",
 			callerLine: target.callerLine,
 			env: target.env
 		});
@@ -8168,35 +8280,6 @@ function styleFor(env, stdoutIsTTY) {
 }
 //#endregion
 //#region ../agent-cli/dist/run-cli.js
-/** `files` resolving paths against `cwd`, its failures classified by errno. */
-function classifiedFiles(files, base, callerLine) {
-	return {
-		exists: async (path) => {
-			const target = resolve(base.cwd, path);
-			try {
-				return await files.exists(target);
-			} catch (error) {
-				throw classifyErrno(error, {
-					path: target,
-					callerLine,
-					env: base.env
-				});
-			}
-		},
-		write: async (path, data) => {
-			const target = resolve(base.cwd, path);
-			try {
-				await files.write(target, data);
-			} catch (error) {
-				throw classifyErrno(error, {
-					path: target,
-					callerLine,
-					env: base.env
-				});
-			}
-		}
-	};
-}
 async function runCommand(routed, { base, writeStdout, signal, format: baseFormat, ports, clock, files, spawn, projectFile }) {
 	const { command, commandLine } = routed.spec;
 	const format = {
@@ -8225,7 +8308,11 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 	});
 	let delivered;
 	const callerLine = commandLineOf(invocation);
-	const classified = classifiedFiles(files, base, callerLine);
+	const classified = classifiedFiles(files, {
+		cwd: base.cwd,
+		env: base.env,
+		callerLine
+	});
 	const spill = spillTo({
 		cliName: format.cliName,
 		commandName: command.name,
@@ -8234,20 +8321,31 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 		files: classified,
 		callerLine
 	});
-	const ctx = {
-		...base,
+	const portsBase = {
+		cwd: base.cwd,
+		env: base.env,
+		packageRoot: base.packageRoot,
+		secret: base.secret,
 		signal: control.signal,
-		deadline: (ms) => control.deadline(ms),
-		runToEnd: (name, work) => control.runToEnd(name, work),
-		ports: ports(),
 		clock,
 		files: classified,
 		spawn: contextSpawn(spawn, {
 			cwd: base.cwd,
 			env: base.env,
 			signal: control.signal
-		}, callerLine),
+		}, callerLine)
+	};
+	const builtPorts = once(() => ports(portsBase));
+	const ctx = {
+		...base,
+		...portsBase,
+		deadline: (ms) => control.deadline(ms),
+		runToEnd: (name, work) => control.runToEnd(name, work),
+		get ports() {
+			return builtPorts();
+		},
 		project,
+		force: flags.force,
 		poll: (check, { intervalMs }) => poll(clock, check, intervalMs, control.signal),
 		deliver: (data) => {
 			delivered = deliveredOutcome(command, data);
@@ -8262,7 +8360,6 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 				dryRun: flags.dryRun,
 				confirm: flags.confirm,
 				yes: flags.yes,
-				force: flags.force,
 				page: flags.page,
 				invocation,
 				commandLine,
@@ -8285,6 +8382,25 @@ async function runCommand(routed, { base, writeStdout, signal, format: baseForma
 		fields: flags.fields
 	}, spill);
 }
+/** `build` runs on the first call; later calls give its value or throw its error again. */
+function once(build) {
+	let outcome;
+	return () => {
+		if (outcome === void 0) try {
+			outcome = {
+				ok: true,
+				value: build()
+			};
+		} catch (error) {
+			outcome = {
+				ok: false,
+				error
+			};
+		}
+		if (outcome.ok) return outcome.value;
+		throw outcome.error;
+	};
+}
 function portsOf(cli, replacement) {
 	if (replacement !== void 0) return () => replacement;
 	return cli.ports ?? (() => ({}));
@@ -8328,7 +8444,11 @@ async function runWithProgress(cli, argv, options, write) {
 				env: options.env,
 				packageRoot: packageRootOf(options.bin, options.cwd),
 				progress: (message) => write.stderr(`${message}\n`),
-				secret: (name) => secretOf(cli.name, options.env, name)
+				secret: (name) => secretOf({
+					cliName: cli.name,
+					env: options.env,
+					callerLine: commandLineOf(format.invocation)
+				}, name)
 			},
 			writeStdout: (text) => write.stdout(text),
 			signal: options.signal,
@@ -8378,9 +8498,9 @@ async function runProcess(cli) {
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "411548a",
+	"sha": "a7760d0",
 	"dirty": false,
-	"builtAt": "2026-10-19T08:42:00.085Z"
+	"builtAt": "2026-10-19T10:55:24.637Z"
 };
 //#endregion
 //#region src/steps.ts
@@ -8509,7 +8629,7 @@ async function writeTemplate(root, files, values) {
 }
 //#endregion
 //#region src/version.ts
-const version = "0.3.0";
+const version = "0.4.0";
 //#endregion
 //#region src/create.ts
 const { defineCommand } = agentCli();

package/package.json

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

package/template/test/cli.test.ts

@@ -14,6 +14,18 @@ function fakeFiles(existing: readonly string[] = []) {
     write: async (path, data) => {
       written.set(path, String(data));
     },
+    read: async (path) => {
+      const text = written.get(path);
+      if (text === undefined) {
+        throw Object.assign(new Error(`ENOENT: no such file, open '${path}'`), { code: "ENOENT" });
+      }
+      return new TextEncoder().encode(text);
+    },
+    list: async () => [],
+    remove: async (path) => {
+      written.delete(path);
+    },
+    mkdir: async () => {},
   };
   return { files, written };
 }