@duyquangnvx/create-agent-cli 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.27.0 (2026-11-08)
+
+### Added
+
+- A Secret declared `optional: true` is one the Command runs without, such as a token that overrides a saved login: it is read as any Secret is, `ctx.secret` types it `Secret | undefined`, and its absence fails nothing. Help JSON lists it with `"optional": true`, and `doctor` names it only when set; a name needed by any Command or by `defineCli({ secrets })` stays needed there.
+- Each Command's text help lists its Secrets under `Secrets:`, each with where to get it.
+
 ## v0.26.0 (2026-11-06)
 
 ### Added

package/dist/bin.js

@@ -7033,8 +7033,11 @@ function secretOf({ envFile, env, fileError }, name) {
 		}
 	} : void 0;
 }
+function isNeeded({ optional }) {
+	return optional !== true;
+}
 function missingIn(scope, secrets) {
-	return secrets.filter(({ name }) => secretOf(scope, name) === void 0);
+	return secrets.filter((secret) => isNeeded(secret) && secretOf(scope, secret.name) === void 0);
 }
 function getItFrom({ get }) {
 	return `(get it from ${get})`;
@@ -7057,10 +7060,14 @@ function checkSecrets(secrets, scope, rerun) {
 function originOf({ origin }) {
 	return origin.kind === "env" ? "the environment" : origin.path;
 }
-/** The `doctor` row over every distinct Secret the CLI and its Commands declare; none without any. */
+/**
+* The `doctor` row over every distinct Secret the CLI and its Commands declare; none without any. A
+* name needed anywhere counts as needed, and an unset optional one goes unmentioned.
+*/
 function secretRows(secrets, commands) {
 	const declared = declaredIn(secrets, commands, (command) => command.secrets);
 	if (declared.length === 0) return [];
+	const needed = new Map(declaredIn(secrets.filter(isNeeded), commands, (command) => command.secrets?.filter(isNeeded)).map((declaration) => [declaration.name, declaration]));
 	return [{
 		name: "secrets",
 		run: ({ env, envFile, fileError }) => {
@@ -7072,14 +7079,18 @@ function secretRows(secrets, commands) {
 					fileError
 				}, declaration.name)
 			}));
-			const missing = read.filter(({ secret }) => secret === void 0);
+			const missing = read.flatMap(({ declaration, secret }) => {
+				const neededAs = needed.get(declaration.name);
+				return secret === void 0 && neededAs !== void 0 ? [neededAs] : [];
+			});
 			if (missing.length > 0) return {
 				state: "problem",
-				message: `${missing.map(({ declaration }) => `${declaration.name} is not set ${getItFrom(declaration)}`).join(", ")}; add ${missing.length === 1 ? "it" : "them"} to ${envFile} or the environment`
+				message: `${missing.map((declaration) => `${declaration.name} is not set ${getItFrom(declaration)}`).join(", ")}; add ${missing.length === 1 ? "it" : "them"} to ${envFile} or the environment`
 			};
+			const found = read.flatMap(({ declaration, secret }) => secret === void 0 ? [] : [`${declaration.name} from ${originOf(secret)}`]);
 			return {
 				state: "ok",
-				message: read.flatMap(({ declaration, secret }) => secret === void 0 ? [] : [`${declaration.name} from ${originOf(secret)}`]).join(", ")
+				message: found.length > 0 ? found.join(", ") : "no Secret is set, and none is needed"
 			};
 		}
 	}];
@@ -7089,9 +7100,9 @@ function secretRows(secrets, commands) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "ed7073b",
+		"sha": "8ba1668",
 		"dirty": false,
-		"builtAt": "2026-11-06T05:43:19.000Z"
+		"builtAt": "2026-11-08T16:12:26.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -10085,6 +10096,9 @@ function argRow(field) {
 function optionRow(field) {
 	return fieldRow(field, defaultsOf(field));
 }
+function secretRow(declaration) {
+	return [isNeeded(declaration) ? declaration.name : `${declaration.name} (optional)`, `get it from ${declaration.get}`];
+}
 function flagRow({ usage, description }) {
 	return [usage, description];
 }
@@ -10095,6 +10109,7 @@ function commandLines(spec, style, { examples }) {
 		...examples ? examplesSection(spec.examples, style) : [],
 		...section("Arguments", spec.args.map(argRow), style),
 		...section("Options", spec.options.map(optionRow), style),
+		...section("Secrets", (spec.command.secrets ?? []).map(secretRow), style),
 		...spec.help === void 0 ? [] : ["", spec.help],
 		"",
 		`${style.bold("Effect:")} ${spec.effect} (${EFFECT_NOTES[spec.effect]})`,
@@ -11240,15 +11255,17 @@ function portsBaseOf(scope, signal) {
 }
 function contextOf(portsBase, control, parts) {
 	const { ports, project, force, dryRun, secrets = [], rerun, deliver, notice } = parts;
-	const declared = new Set(secrets.map(({ name }) => name));
+	const declared = new Map(secrets.map((declaration) => [declaration.name, declaration]));
+	function secret(name) {
+		const declaration = declared.get(name);
+		if (declaration === void 0) throw new Error(`ctx.secret("${name}") names a Secret the Command does not declare`);
+		const found = portsBase.secret(name);
+		if (found === void 0 && isNeeded(declaration)) throw new Error(`ctx.secret("${name}") found no value`);
+		return found;
+	}
 	return {
 		...portsBase,
-		secret: (name) => {
-			if (!declared.has(name)) throw new Error(`ctx.secret("${name}") names a Secret the Command does not declare`);
-			const secret = portsBase.secret(name);
-			if (secret === void 0) throw new Error(`ctx.secret("${name}") found no value`);
-			return secret;
-		},
+		secret,
 		fail: cliErrorOf,
 		deadline: (ms, options) => control.deadline(ms, options),
 		runToEnd: (name, work) => control.runToEnd(name, work),
@@ -11614,7 +11631,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.26.0",
+	version: "0.27.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.26.0",
+  "version": "0.27.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.26.0",
+    "@duyquangnvx/agent-cli": "0.27.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },