@duyquangnvx/create-agent-cli 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.32.0 (2026-11-10)
+
+### Added
+
+- A Login in `defineCli({ logins })` may be a function of the run's env that returns its declaration, for a CLI whose user picks its server with a variable: `ctx.login`, its refresh, `login`, `logout` and `doctor`'s row build it from each run's `env`, and an error it throws fails the run before any request. A stored Login is kept per token endpoint and client id, so a token from one server is never sent to another. `LoginSource` and `LoginDeclarations` are exported.
+- A Grant: a Command lists in `grants` the Logins it asks a token for one action from, and `ctx.grant(name, { scope })`, typed to those names, asks the Login's server for an Approval of that scope through the device flow, taking up the one pending for the same scope. Until the person approves it fails with `APPROVAL_PENDING` (exit 75) and the rerun with `--wait 100`; a refused one fails with `APPROVAL_DENIED` and an expired one with `APPROVAL_EXPIRED` and the rerun, both exit 2. The token is given to the run only, never stored or refreshed, and the Login's Secret does not stand in for it. `--wait <seconds>` is a Standard flag of a Command with `grants`, `defineCli` throws on a name the CLI does not declare, and `ctx.grant` throws in a dry run. `GrantOptions` is exported.
+
 ## v0.31.0 (2026-11-10)
 
 ### Added

package/dist/bin.js

@@ -7198,9 +7198,9 @@ const WAIT_FLAG = standardFlag("--wait", {
 	takes: "value",
 	schema: WAIT_SECONDS
 });
-/** Whether `--wait` is a Standard flag of the Command: it is of one that declares a Login. */
+/** Whether `--wait` is a Standard flag of the Command: it is of one that declares a Login or Grant. */
 function takesWait(command) {
-	return (command.logins ?? []).length > 0;
+	return (command.logins ?? []).length > 0 || (command.grants ?? []).length > 0;
 }
 const EFFECT_FLAGS = {
 	read: [JSON_FLAG],
@@ -7829,12 +7829,37 @@ function loginRequired(names, rerun) {
 		next: [...names.map(loginStep), rerun]
 	});
 }
+function loginAsking(name) {
+	return {
+		subject: `signing in to ${name}`,
+		denied: () => approvalDenied(name),
+		expired: () => approvalExpired(name)
+	};
+}
+/** A Grant's Approval, whose expiry the rerun of the Command heals with a new code. */
+function grantAsking(name, scope, rerun) {
+	const subject = `the grant of ${scope} from ${name}`;
+	return {
+		subject,
+		denied: () => new CliError({
+			code: APPROVAL_DENIED,
+			message: `the person refused ${subject}`,
+			hint: "ask the person whether to go ahead, and run the Command again only if they agree"
+		}),
+		expired: () => new CliError({
+			code: APPROVAL_EXPIRED,
+			message: `the code for ${subject} expired before it was approved`,
+			hint: "run the Next step for a new code, and pass its link and code to the person",
+			next: [rerun]
+		})
+	};
+}
 /** The wait ran out before the person approved: the same Approval stays pending for the rerun. */
-function approvalPending(name, approval, rerun) {
+function approvalPending({ subject }, approval, rerun) {
 	const { verificationUri, userCode, verificationUriComplete } = approval;
 	return new CliError({
 		code: APPROVAL_PENDING,
-		message: `signing in to ${name} waits for the code ${userCode} to be approved at ${verificationUriComplete ?? verificationUri}`,
+		message: `${subject} waits for the code ${userCode} to be approved at ${verificationUriComplete ?? verificationUri}`,
 		hint: "the person sees only your reply: write the link and the code in it, then run the Next step, which waits for the approval",
 		details: {
 			verificationUri,
@@ -7951,7 +7976,7 @@ function mustDeclare(code, table) {
 //#region ../agent-cli/dist/define-command.js
 /** Throws when the Command's declaration breaks a rule its type cannot express; `label` names it. */
 function checkCommand(command, label, table, logins) {
-	checkLogins(command.logins ?? [], label, logins);
+	checkLogins([...command.logins ?? [], ...command.grants ?? []], label, logins);
 	checkNoStandardFlags(command, label);
 	checkForce(command, label);
 	checkArrayArgLast(label, command.args);
@@ -7999,6 +8024,14 @@ function cliErrorOf(code, init, options) {
 	}, options);
 }
 //#endregion
+//#region ../agent-cli/dist/login/declared.js
+/** The declaration of the Login `name` for a run in `env`. */
+function declaredLogin(logins, name, env) {
+	const login = logins[name];
+	if (login === void 0) throw new Error(`${name} is not a Login the CLI declares`);
+	return typeof login === "function" ? login(env) : login;
+}
+//#endregion
 //#region ../agent-cli/dist/login/store.js
 const storedLoginSchema = object({
 	accessToken: string(),
@@ -8015,16 +8048,20 @@ const approvalSchema = object({
 	interval: number$1()
 });
 const KEY_LENGTH = 16;
-function keyOf({ tokenEndpoint, clientId }) {
-	return createHash("sha256").update(`${tokenEndpoint}\n${clientId}`).digest("hex").slice(0, KEY_LENGTH);
+function keyOf(...parts) {
+	return createHash("sha256").update(parts.join("\n")).digest("hex").slice(0, KEY_LENGTH);
 }
 function loginFilesOf(userFile, login) {
-	const key = keyOf(login);
+	const key = keyOf(login.tokenEndpoint, login.clientId);
 	return {
 		stored: userFile(`login-${key}`, storedLoginSchema),
 		approval: userFile(`approval-${key}`, approvalSchema)
 	};
 }
+/** The Approval pending for a Grant of `scope`, kept apart from the Login's and every other scope's. */
+function grantApprovalOf(userFile, { tokenEndpoint, clientId }, scope) {
+	return userFile(`grant-${keyOf(tokenEndpoint, clientId, scope)}`, approvalSchema);
+}
 /** The file's value, or `undefined` once its `expiresAt` has passed, removing the file then. */
 async function readUnexpired(file, clock) {
 	const value = await file.read();
@@ -8172,11 +8209,12 @@ function tokenScopeOf(ctx) {
 }
 //#endregion
 //#region ../agent-cli/dist/login/doctor-rows.js
-function loginRow(name, login, runAs) {
+function loginRow(name, logins, runAs) {
 	return {
 		name: `login ${name}`,
 		advisory: true,
 		run: async (ctx) => {
+			const login = declaredLogin(logins, name, ctx.env);
 			const set = setSecretOf(login, tokenScopeOf(ctx).secret);
 			if (set !== void 0) return {
 				state: "ok",
@@ -8197,16 +8235,16 @@ function loginRow(name, login, runAs) {
 }
 /** One `doctor` row per Login: where its token comes from, and `login` as the fix with none. */
 function loginRows(logins, runAs) {
-	return Object.entries(logins).map(([name, login]) => loginRow(name, login, runAs));
+	return Object.keys(logins).map((name) => loginRow(name, logins, runAs));
 }
 //#endregion
 //#region ../agent-cli/dist/version.js
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "7dd915f",
+		"sha": "8907e9d",
 		"dirty": false,
-		"builtAt": "2026-11-10T03:40:31.000Z"
+		"builtAt": "2026-11-10T09:08:31.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -10050,13 +10088,6 @@ function doctorCommand(cli, launch) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/login/declared.js
-function declaredLogin(logins, name) {
-	const login = logins[name];
-	if (login === void 0) throw new Error(`${name} is not a Login the CLI declares`);
-	return login;
-}
-//#endregion
 //#region ../agent-cli/dist/login/device-flow.js
 const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 /** RFC 8628 §3.2: the interval when the server gives none. */
@@ -10086,7 +10117,7 @@ async function startApproval(login, { fetch, clock }) {
 		interval: device.interval ?? DEFAULT_INTERVAL_S
 	};
 }
-async function pollApproval(name, login, { approval, takenUp }, scope, signal) {
+async function pollApproval(asking, login, { approval, takenUp }, scope, signal) {
 	const form = {
 		grant_type: DEVICE_CODE_GRANT,
 		device_code: approval.deviceCode,
@@ -10100,23 +10131,23 @@ async function pollApproval(name, login, { approval, takenUp }, scope, signal) {
 		if (granted.success) return storedLoginOf(granted.data, scope.clock);
 		const { error } = parsedAnswer(errorSchema, body, login.tokenEndpoint);
 		if (error === "slow_down") intervalS += SLOW_DOWN_S;
-		else if (error !== "authorization_pending") throw refusal(name, login, error);
+		else if (error !== "authorization_pending") throw refusal(asking, login, error);
 	}
 }
 /** The error a token endpoint's answer other than pending or slow down ends the polling with. */
-function refusal(name, login, error) {
-	if (error === "access_denied") return approvalDenied(name);
-	if (error === "expired_token" || error === "invalid_grant") return approvalExpired(name);
+function refusal(asking, login, error) {
+	if (error === "access_denied") return asking.denied();
+	if (error === "expired_token" || error === "invalid_grant") return asking.expired();
 	return /* @__PURE__ */ new Error(`${login.tokenEndpoint} refused the device code with ${error}`);
 }
 function endsApproval(error) {
 	return error instanceof CliError && (error.code === "APPROVAL_DENIED" || error.code === "APPROVAL_EXPIRED");
 }
 /** Takes up the pending Approval, or asks for one and keeps it as a User file, and prints its code. */
-async function askedApproval(login, files, scope) {
-	const pending = await readUnexpired(files.approval, scope.clock);
+async function askedApproval(login, file, scope) {
+	const pending = await readUnexpired(file, scope.clock);
 	const approval = pending ?? await startApproval(login, scope);
-	if (pending === void 0) await files.approval.write(approval);
+	if (pending === void 0) await file.write(approval);
 	scope.progress(`open ${approval.verificationUriComplete ?? approval.verificationUri} and approve code ${approval.userCode}`);
 	return {
 		approval,
@@ -10125,28 +10156,39 @@ async function askedApproval(login, files, scope) {
 }
 /** The `APPROVAL_PENDING` of the pending Approval, or of a new one, without polling it. */
 async function pendingApproval(name, login, files, scope, rerun) {
-	const { approval } = await askedApproval(login, files, scope);
-	return approvalPending(name, approval, rerun);
+	const { approval } = await askedApproval(login, files.approval, scope);
+	return approvalPending(loginAsking(name), approval, rerun);
 }
 /**
-* Polls the pending Approval, or a new one, until the person approves, and stores the Login. A run
-* that stops first leaves the Approval for the next.
+* Polls the Approval pending in `file`, or a new one, until the person approves, removing it once
+* refused or expired. An approved one stays until what it granted is kept, so a cut-off run loses nothing.
 */
-async function signIn(name, login, files, scope, { waitS, rerun }) {
-	const asked = await askedApproval(login, files, scope);
+async function approved(asking, login, file, scope, { waitS, rerun }) {
+	const asked = await askedApproval(login, file, scope);
 	const wait = scope.deadline(waitS * MS_PER_S);
-	let stored;
+	let granted;
 	try {
-		stored = await pollApproval(name, login, asked, scope, wait);
+		granted = await pollApproval(asking, login, asked, scope, wait);
 	} catch (error) {
-		if (wait.aborted && !scope.signal.aborted) throw approvalPending(name, asked.approval, rerun);
-		if (endsApproval(error)) await files.approval.remove();
+		if (wait.aborted && !scope.signal.aborted) throw approvalPending(asking, asked.approval, rerun);
+		if (endsApproval(error)) await file.remove();
 		throw error;
 	}
+	return granted;
+}
+/** Polls the pending Approval, or a new one, until the person approves, and stores the Login. */
+async function signIn(name, login, files, scope, wait) {
+	const stored = await approved(loginAsking(name), login, files.approval, scope, wait);
 	await files.stored.write(stored);
 	await files.approval.remove();
 	return stored;
 }
+/** Polls the Approval of the Grant's scope, or a new one, until the person approves: its token. */
+async function grant(asking, login, file, scope, wait) {
+	const { accessToken } = await approved(asking, login, file, scope, wait);
+	await file.remove();
+	return accessToken;
+}
 //#endregion
 //#region ../agent-cli/dist/built-ins/login-name.js
 /** The Login a `login` or `logout` run names, or the only one; with several, the name is needed. */
@@ -10231,7 +10273,7 @@ function logoutCommand(cli, logins, names) {
 				cliName: cli.name,
 				command: "logout"
 			}, given, names);
-			const login = declaredLogin(logins, name);
+			const login = declaredLogin(logins, name, ctx.env);
 			return {
 				login: name,
 				stored: await loginFilesOf(ctx.userFile, login).stored.read() !== void 0,
@@ -10240,7 +10282,7 @@ function logoutCommand(cli, logins, names) {
 			};
 		},
 		apply: async ({ login: name, secret }, ctx) => {
-			const login = declaredLogin(logins, name);
+			const login = declaredLogin(logins, name, ctx.env);
 			const file = loginFilesOf(ctx.userFile, login).stored;
 			const stored = await file.read();
 			const kept = secret === void 0 ? {} : { secret };
@@ -10317,7 +10359,7 @@ function loginCommand(cli, logins, names) {
 				cliName: cli.name,
 				command: "login"
 			}, given, names);
-			const login = declaredLogin(logins, name);
+			const login = declaredLogin(logins, name, ctx.env);
 			const token = await currentTokenOf(login, tokenScopeOf(ctx));
 			const stored = await readStored(loginFilesOf(ctx.userFile, login).stored, ctx.clock);
 			return {
@@ -10329,7 +10371,7 @@ function loginCommand(cli, logins, names) {
 		},
 		apply: async ({ login: name, wait, found }, ctx) => {
 			if (found !== void 0) return found;
-			const login = declaredLogin(logins, name);
+			const login = declaredLogin(logins, name, ctx.env);
 			const files = loginFilesOf(ctx.userFile, login);
 			const stored = await readStored(files.stored, ctx.clock);
 			if (stored?.refreshToken !== void 0 && await refreshed(name, login, files.stored, stored.refreshToken, ctx) !== void 0) return {
@@ -12181,7 +12223,7 @@ function approvalRerun(ctx) {
 }
 async function tokensOf(names, logins, ctx, waitS) {
 	const found = await Promise.all(names.map(async (name) => {
-		const login = declaredLogin(logins, name);
+		const login = declaredLogin(logins, name, ctx.env);
 		return {
 			name,
 			token: ctx.dryRun ? await currentTokenOf(login, tokenScopeOf(ctx)) : await freshTokenOf(name, login, ctx)
@@ -12195,7 +12237,7 @@ async function tokensOf(names, logins, ctx, waitS) {
 			tokens.set(name, token);
 			continue;
 		}
-		const login = declaredLogin(logins, name);
+		const login = declaredLogin(logins, name, ctx.env);
 		const stored = await signIn(name, login, loginFilesOf(ctx.userFile, login), ctx, {
 			waitS,
 			rerun: approvalRerun(ctx)
@@ -12221,26 +12263,49 @@ async function afterRejection(error, tokens, logins, ctx) {
 	const name = rejectedName(error, tokens);
 	const token = name === void 0 ? void 0 : tokens.get(name);
 	if (name === void 0 || token === void 0) return new Error(`the Command threw ${LOGIN_REJECTED} naming no Login it declares in details.login`, { cause: error });
-	const login = declaredLogin(logins, name);
+	const login = declaredLogin(logins, name, ctx.env);
 	if (token.source.kind === "secret" && login.secret !== void 0) return secretRejected(name, login.secret, error);
 	const files = loginFilesOf(ctx.userFile, login);
 	await files.stored.remove();
 	if (ctx.dryRun) return loginRequired([name], ctx.rerun());
 	return await pendingApproval(name, login, files, ctx, approvalRerun(ctx));
 }
+/** `ctx.grant`: polls the Approval of `scope` for at most `waitS` seconds, and keeps no token. */
+function granting(ctx, grants, logins, waitS) {
+	return async (name, { scope }) => {
+		if (!grants.includes(name)) undeclaredGrant(name);
+		if (ctx.dryRun) throw new Error(`ctx.grant("${name}") in a dry run, which asks for nothing: ask in apply`);
+		const login = {
+			...declaredLogin(logins, name, ctx.env),
+			scope
+		};
+		return await grant(grantAsking(name, scope, ctx.rerun({ remove: [WAIT_FLAG.flag] })), login, grantApprovalOf(ctx.userFile, login, scope), ctx, {
+			waitS,
+			rerun: approvalRerun(ctx)
+		});
+	};
+}
 /**
 * Runs `work` with a `ctx` whose `login` gives each named Login's token, signing in first, for at
-* most `waitS` seconds, where one is missing. A `LOGIN_REJECTED` from `work` drops the stored Login.
+* most `waitS` seconds, where one is missing, and whose `grant` asks for a Grant. A
+* `LOGIN_REJECTED` from `work` drops the stored Login.
 */
-async function withLogins(ctx, names, logins, waitS, work) {
+async function withLogins(ctx, { logins: names, grants }, logins, waitS, work) {
 	const tokens = names.length === 0 ? /* @__PURE__ */ new Map() : await tokensOf(names, logins, ctx, waitS ?? 0);
-	const loggedIn = derived(ctx, { login: (name) => tokens.get(name)?.value ?? undeclaredLogin(name) });
+	const loggedIn = derived(ctx, {
+		login: (name) => tokens.get(name)?.value ?? undeclaredLogin(name),
+		grant: granting(ctx, grants, logins, waitS ?? 0)
+	});
 	try {
 		return await work(loggedIn);
 	} catch (error) {
 		throw await afterRejection(error, tokens, logins, ctx);
 	}
 }
+/** `ctx.grant` of a name the Command does not declare in `grants`, which only a cast reaches. */
+function undeclaredGrant(name) {
+	throw new Error(`ctx.grant("${name}") names a Login the Command does not declare in grants`);
+}
 /** `ctx.login` of a name the Command does not declare, which only a cast reaches. */
 function undeclaredLogin(name) {
 	throw new Error(`ctx.login("${name}") names a Login the Command does not declare`);
@@ -12300,7 +12365,10 @@ async function execute(command, input, unlogged, run) {
 		envFile,
 		fileError
 	}, unlogged.rerun());
-	return await withLogins(unlogged, command.logins ?? [], run.logins, run.flags.wait, (ctx) => executeLoggedIn(command, input, ctx, run));
+	return await withLogins(unlogged, {
+		logins: command.logins ?? [],
+		grants: command.grants ?? []
+	}, run.logins, run.flags.wait, (ctx) => executeLoggedIn(command, input, ctx, run));
 }
 async function executeLoggedIn(command, input, ctx, { flags, commandLine, started, outputs: runOutputs }) {
 	if (command.rows !== void 0) {
@@ -12540,6 +12608,7 @@ function contextOf(scope, control, { command, flags, project, deliver, latestRel
 		...portsBase,
 		secret,
 		login: undeclaredLogin,
+		grant: async (name) => undeclaredGrant(name),
 		userFile: scope.userFile,
 		fail: cliErrorOf,
 		deadline: (ms, options) => control.deadline(ms, options),
@@ -12898,7 +12967,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.31.0",
+	version: "0.32.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.31.0",
+  "version": "0.32.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.31.0",
+    "@duyquangnvx/agent-cli": "0.32.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },