@duyquangnvx/create-agent-cli 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.33.0 (2026-11-10)
+
+### Changed
+
+- **Breaking:** `ctx.login(name)` returns `Promise<string>`, and the Runtime finds a Login when the Command first asks for it, once per run, no longer before `plan`, `run` or `start`: write `await ctx.login(name)`. A Command that lists a Login and returns before it asks runs on a machine not signed in, and one that asks with none stored fails with `APPROVAL_PENDING` from that call, or with `LOGIN_REQUIRED` in a dry run, which names that Login alone; of Logins asked for at once, only the first one missing starts an Approval. Ask before any effect a rerun must not repeat.
+
+### Fixed
+
+- A Login's device or token endpoint that answers with a body that is not JSON, or with JSON that is no OAuth answer, such as a proxy or a password page in front of the server, fails the run with the new Runtime code `NOT_OAUTH` (exit 3), naming the endpoint and its status in the message and in `details` (`login`, `endpoint`, `status`), where it failed with `INTERNAL` (exit 70). `runtimeCodes.NOT_OAUTH` is exported.
+
+### Upgrade from v0.32.0
+
+- Every call of `ctx.login(name)` becomes `await ctx.login(name)`: a call left without it still type-checks inside a template literal, and sends `[object Promise]` as the token.
+- A Command with an effect before its first `ctx.login` asks first, since the rerun after an Approval starts the Command over.
+
 ## v0.32.0 (2026-11-10)
 
 ### Added

package/dist/bin.js

@@ -7815,6 +7815,7 @@ const APPROVAL_PENDING = "APPROVAL_PENDING";
 const APPROVAL_DENIED = "APPROVAL_DENIED";
 const APPROVAL_EXPIRED = "APPROVAL_EXPIRED";
 const LOGIN_REJECTED = "LOGIN_REJECTED";
+const NOT_OAUTH = "NOT_OAUTH";
 function loginStep(name) {
 	return ["login", name];
 }
@@ -7831,6 +7832,7 @@ function loginRequired(names, rerun) {
 }
 function loginAsking(name) {
 	return {
+		login: name,
 		subject: `signing in to ${name}`,
 		denied: () => approvalDenied(name),
 		expired: () => approvalExpired(name)
@@ -7840,6 +7842,7 @@ function loginAsking(name) {
 function grantAsking(name, scope, rerun) {
 	const subject = `the grant of ${scope} from ${name}`;
 	return {
+		login: name,
 		subject,
 		denied: () => new CliError({
 			code: APPROVAL_DENIED,
@@ -7897,6 +7900,19 @@ function approvalExpired(name) {
 		next: [loginStep(name)]
 	});
 }
+/** An endpoint of a Login that answered as something other than its OAuth server. */
+function notOAuth({ login, url: endpoint }, status, cause) {
+	return new CliError({
+		code: NOT_OAUTH,
+		message: `${endpoint} answered ${status}, which is no OAuth answer`,
+		hint: `${endpoint} does not reach the OAuth server the Login ${login} declares: a proxy or a password page may stand in front of it, or the CLI points at the wrong server; ask whoever runs ${new URL(endpoint).origin} for the URL that reaches it`,
+		details: {
+			login,
+			endpoint,
+			status
+		}
+	}, { cause });
+}
 //#endregion
 //#region ../agent-cli/dist/runtime-codes.js
 const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
@@ -7940,7 +7956,8 @@ const anyCommandErrors = {
 	[APPROVAL_PENDING]: { class: "wait" },
 	[APPROVAL_DENIED]: { class: "operator" },
 	[APPROVAL_EXPIRED]: { class: "operator" },
-	[LOGIN_REJECTED]: { class: "operator" }
+	[LOGIN_REJECTED]: { class: "operator" },
+	[NOT_OAUTH]: { class: "source" }
 };
 /**
 * The Runtime codes only some Commands reach: each Command that throws one, Built-in or the CLI's
@@ -8087,9 +8104,12 @@ const errorSchema = object({ error: string() });
 function isoAfter(clock, seconds) {
 	return new Date(clock.now() + seconds * MS_PER_S).toISOString();
 }
-/** POSTs `form` to an OAuth endpoint and parses its JSON answer, whatever its status. */
-async function postForm(fetch, url, form, { ignoreStop } = {}) {
-	const response = await fetch(url, {
+/**
+* POSTs `form` to an OAuth endpoint and parses its JSON answer, whatever its status. A body that
+* is not JSON fails with `NOT_OAUTH`.
+*/
+async function postForm(fetch, endpoint, form, { ignoreStop } = {}) {
+	const response = await fetch(endpoint.url, {
 		method: "POST",
 		once: false,
 		...ignoreStop === void 0 ? {} : { ignoreStop },
@@ -8097,15 +8117,21 @@ async function postForm(fetch, url, form, { ignoreStop } = {}) {
 		body: new URLSearchParams(form)
 	});
 	const text = await response.text();
+	const { status } = response;
 	try {
-		return JSON.parse(text);
+		return {
+			endpoint,
+			status,
+			body: JSON.parse(text)
+		};
 	} catch (error) {
-		throw new Error(`${url} answered ${response.status} with a body that is not JSON`, { cause: error });
+		throw notOAuth(endpoint, status, error);
 	}
 }
-function parsedAnswer(schema, body, url) {
+/** The answer's body as `schema` has it, or a `NOT_OAUTH` for one of another shape. */
+function parsedAnswer(schema, { endpoint, status, body }) {
 	const parsed = schema.safeParse(body);
-	if (!parsed.success) throw new Error(`${url} answered ${JSON.stringify(body)}, not an OAuth answer`);
+	if (!parsed.success) throw notOAuth(endpoint, status);
 	return parsed.data;
 }
 function storedLoginOf({ access_token, refresh_token, expires_in }, clock) {
@@ -8131,8 +8157,12 @@ async function refreshed(name, login, file, refreshToken, ctx) {
 		client_id: login.clientId
 	};
 	return await ctx.runToEnd(`refreshing the Login ${name}`, async () => {
-		const body = await postForm(ctx.fetch, login.tokenEndpoint, form, { ignoreStop: true });
-		const granted = tokenSchema.safeParse(body);
+		const endpoint = {
+			login: name,
+			url: login.tokenEndpoint
+		};
+		const answer = await postForm(ctx.fetch, endpoint, form, { ignoreStop: true });
+		const granted = tokenSchema.safeParse(answer.body);
 		if (granted.success) {
 			const stored = {
 				refreshToken,
@@ -8141,7 +8171,7 @@ async function refreshed(name, login, file, refreshToken, ctx) {
 			await file.write(stored);
 			return stored;
 		}
-		const { error } = parsedAnswer(errorSchema, body, login.tokenEndpoint);
+		const { error } = parsedAnswer(errorSchema, answer);
 		if (error !== "invalid_grant") throw new Error(`${login.tokenEndpoint} refused the refresh of ${name} with ${error}`);
 		await file.remove();
 	});
@@ -8242,9 +8272,9 @@ function loginRows(logins, runAs) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "8907e9d",
+		"sha": "3716c19",
 		"dirty": false,
-		"builtAt": "2026-11-10T09:08:31.000Z"
+		"builtAt": "2026-11-10T16:12:55.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -10102,12 +10132,18 @@ const deviceSchema = object({
 	expires_in: number$1(),
 	interval: number$1().optional()
 });
-async function startApproval(login, { fetch, clock }) {
+async function startApproval(name, login, { fetch, clock }) {
 	const form = {
 		client_id: login.clientId,
 		...login.scope === void 0 ? {} : { scope: login.scope }
 	};
-	const device = parsedAnswer(deviceSchema, await postForm(fetch, login.deviceEndpoint, form), login.deviceEndpoint);
+	const answer = await postForm(fetch, {
+		login: name,
+		url: login.deviceEndpoint
+	}, form);
+	const refused = errorSchema.safeParse(answer.body);
+	if (refused.success) throw new Error(`${login.deviceEndpoint} refused the device request with ${refused.data.error}`);
+	const device = parsedAnswer(deviceSchema, answer);
 	return {
 		deviceCode: device.device_code,
 		userCode: device.user_code,
@@ -10123,13 +10159,17 @@ async function pollApproval(asking, login, { approval, takenUp }, scope, signal)
 		device_code: approval.deviceCode,
 		client_id: login.clientId
 	};
+	const endpoint = {
+		login: asking.login,
+		url: login.tokenEndpoint
+	};
 	let intervalS = approval.interval;
 	for (let first = true;; first = false) {
 		if (!(first && takenUp)) await scope.clock.sleep(intervalS * MS_PER_S, signal);
-		const body = await postForm(scope.fetch, login.tokenEndpoint, form);
-		const granted = tokenSchema.safeParse(body);
+		const answer = await postForm(scope.fetch, endpoint, form);
+		const granted = tokenSchema.safeParse(answer.body);
 		if (granted.success) return storedLoginOf(granted.data, scope.clock);
-		const { error } = parsedAnswer(errorSchema, body, login.tokenEndpoint);
+		const { error } = parsedAnswer(errorSchema, answer);
 		if (error === "slow_down") intervalS += SLOW_DOWN_S;
 		else if (error !== "authorization_pending") throw refusal(asking, login, error);
 	}
@@ -10144,9 +10184,9 @@ 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, file, scope) {
+async function askedApproval(name, login, file, scope) {
 	const pending = await readUnexpired(file, scope.clock);
-	const approval = pending ?? await startApproval(login, scope);
+	const approval = pending ?? await startApproval(name, login, scope);
 	if (pending === void 0) await file.write(approval);
 	scope.progress(`open ${approval.verificationUriComplete ?? approval.verificationUri} and approve code ${approval.userCode}`);
 	return {
@@ -10156,7 +10196,7 @@ async function askedApproval(login, file, 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.approval, scope);
+	const { approval } = await askedApproval(name, login, files.approval, scope);
 	return approvalPending(loginAsking(name), approval, rerun);
 }
 /**
@@ -10164,7 +10204,7 @@ async function pendingApproval(name, login, files, scope, rerun) {
 * refused or expired. An approved one stays until what it granted is kept, so a cut-off run loses nothing.
 */
 async function approved(asking, login, file, scope, { waitS, rerun }) {
-	const asked = await askedApproval(login, file, scope);
+	const asked = await askedApproval(asking.login, login, file, scope);
 	const wait = scope.deadline(waitS * MS_PER_S);
 	let granted;
 	try {
@@ -12221,48 +12261,60 @@ function approvalRerun(ctx) {
 		add: [WAIT_FLAG.flag, String(100)]
 	});
 }
-async function tokensOf(names, logins, ctx, waitS) {
-	const found = await Promise.all(names.map(async (name) => {
-		const login = declaredLogin(logins, name, ctx.env);
-		return {
-			name,
-			token: ctx.dryRun ? await currentTokenOf(login, tokenScopeOf(ctx)) : await freshTokenOf(name, login, ctx)
-		};
+/** The token of the Login `name`, signing in first, for at most `waitS` seconds, when none is found. */
+async function tokenOf(name, logins, ctx, waitS) {
+	const login = declaredLogin(logins, name, ctx.env);
+	const found = ctx.dryRun ? await currentTokenOf(login, tokenScopeOf(ctx)) : await freshTokenOf(name, login, ctx);
+	if (found === void 0 && ctx.dryRun) throw loginRequired([name], ctx.rerun());
+	const token = found ?? storedToken(await signIn(name, login, loginFilesOf(ctx.userFile, login), ctx, {
+		waitS,
+		rerun: approvalRerun(ctx)
 	}));
-	const missing = found.flatMap(({ name, token }) => token === void 0 ? [name] : []);
-	if (missing.length > 0 && ctx.dryRun) throw loginRequired(missing, ctx.rerun());
-	const tokens = /* @__PURE__ */ new Map();
-	for (const { name, token } of found) {
-		if (token !== void 0) {
-			tokens.set(name, token);
-			continue;
-		}
-		const login = declaredLogin(logins, name, ctx.env);
-		const stored = await signIn(name, login, loginFilesOf(ctx.userFile, login), ctx, {
-			waitS,
-			rerun: approvalRerun(ctx)
-		});
-		tokens.set(name, storedToken(stored));
-	}
 	ctx.signal.throwIfAborted();
-	return tokens;
+	return token;
+}
+/**
+* `ctx.login`, which finds each Login once, when first asked, and the tokens it gave. A Login it
+* fails to find fails every Login asked for after it the same way.
+*/
+function loggingIn(ctx, names, logins, waitS) {
+	const asked = /* @__PURE__ */ new Map();
+	const given = /* @__PURE__ */ new Map();
+	let turn = Promise.resolve();
+	const find = async (name, earlier) => {
+		await earlier;
+		const token = await tokenOf(name, logins, ctx, waitS);
+		given.set(name, token);
+		return token;
+	};
+	const login = async (name) => {
+		if (!names.includes(name)) undeclaredLogin(name);
+		const asking = asked.get(name) ?? find(name, turn);
+		asked.set(name, asking);
+		turn = asking;
+		return (await asking).value;
+	};
+	return {
+		login,
+		given
+	};
 }
 /** The Login a `LOGIN_REJECTED` names in `details.login`, or the Command's only one. */
-function rejectedName(rejected, tokens) {
+function rejectedName(rejected, names) {
 	const { details } = rejected;
 	if (typeof details === "object" && details !== null && "login" in details) return typeof details.login === "string" ? details.login : void 0;
-	const [only, ...rest] = tokens.keys();
+	const [only, ...rest] = names;
 	return rest.length === 0 ? only : void 0;
 }
 /**
 * What a run whose Command threw `error` fails with: a `LOGIN_REJECTED` of a stored Login drops
 * it for a new Approval, one of a Secret's token fails as the operator's to fix.
 */
-async function afterRejection(error, tokens, logins, ctx) {
+async function afterRejection(error, { names, given }, logins, ctx) {
 	if (!(error instanceof CliError && error.code === "LOGIN_REJECTED")) return error;
-	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 name = rejectedName(error, names);
+	const token = name === void 0 ? void 0 : given.get(name);
+	if (name === void 0 || token === void 0) return new Error(`the Command threw ${LOGIN_REJECTED} naming no Login ctx.login gave it in details.login`, { cause: error });
 	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);
@@ -12286,20 +12338,23 @@ function granting(ctx, grants, logins, waitS) {
 	};
 }
 /**
-* 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, and whose `grant` asks for a Grant. A
+* Runs `work` with a `ctx` whose `login` finds a named Login's token when first asked, signing in
+* first, for at most `waitS` seconds, where it is missing, and whose `grant` asks for a Grant. A
 * `LOGIN_REJECTED` from `work` drops the stored Login.
 */
 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 { login, given } = loggingIn(ctx, names, logins, waitS ?? 0);
 	const loggedIn = derived(ctx, {
-		login: (name) => tokens.get(name)?.value ?? undeclaredLogin(name),
+		login,
 		grant: granting(ctx, grants, logins, waitS ?? 0)
 	});
 	try {
 		return await work(loggedIn);
 	} catch (error) {
-		throw await afterRejection(error, tokens, logins, ctx);
+		throw await afterRejection(error, {
+			names,
+			given
+		}, logins, ctx);
 	}
 }
 /** `ctx.grant` of a name the Command does not declare in `grants`, which only a cast reaches. */
@@ -12607,7 +12662,7 @@ function contextOf(scope, control, { command, flags, project, deliver, latestRel
 	return {
 		...portsBase,
 		secret,
-		login: undeclaredLogin,
+		login: async (name) => undeclaredLogin(name),
 		grant: async (name) => undeclaredGrant(name),
 		userFile: scope.userFile,
 		fail: cliErrorOf,
@@ -12967,7 +13022,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.32.0",
+	version: "0.33.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.32.0",
+  "version": "0.33.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.32.0",
+    "@duyquangnvx/agent-cli": "0.33.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },