pi-lean-dimension 0.5.0 → 0.6.0

package/node_modules/pi-lean-host/core/oauth-command.ts

@@ -788,7 +788,7 @@ async function wizardFields(
 		GRANT_ITEMS,
 	);
 	if (grant === undefined) {
-		await cancelled();
+		cancelled();
 		return undefined;
 	}
 	let redirectUri: string | undefined;
@@ -805,11 +805,12 @@ async function wizardFields(
 			)
 		)?.trim();
 		if (raw === undefined) {
-			await cancelled();
+			cancelled();
 			return undefined;
 		}
 		if (raw !== "") redirectUri = raw;
 	}
+	// ast-grep-ignore: hardcoded-url
 	const tokenUrl = (
 		await ctx.ui.input(
 			`Token endpoint URL for '${storeDomain}'`,
@@ -817,7 +818,7 @@ async function wizardFields(
 		)
 	)?.trim();
 	if (!tokenUrl) {
-		await cancelled();
+		cancelled();
 		return undefined;
 	}
 	// Store-name rule: client-id/secret are picked from provisioned secrets —
@@ -836,7 +837,7 @@ async function wizardFields(
 		names,
 	);
 	if (clientId === undefined) {
-		await cancelled();
+		cancelled();
 		return undefined;
 	}
 	const clientSecret = await ctx.ui.select(
@@ -844,7 +845,7 @@ async function wizardFields(
 		grant === "client_credentials" ? names : [OMIT_SECRET, ...names],
 	);
 	if (clientSecret === undefined) {
-		await cancelled();
+		cancelled();
 		return undefined;
 	}
 	// A public PKCE client (secret omitted) sends no client credentials —
@@ -860,7 +861,7 @@ async function wizardFields(
 					AUTH_METHOD_ITEMS,
 				)) as OAuth2TokenEndpointAuthMethod | undefined);
 	if (tokenEndpointAuthMethod === undefined) {
-		await cancelled();
+		cancelled();
 		return undefined;
 	}
 	if (grant === "client_credentials") {
@@ -874,6 +875,7 @@ async function wizardFields(
 			},
 		};
 	}
+	// ast-grep-ignore: hardcoded-url
 	const authorizeUrl = (
 		await ctx.ui.input(
 			`Authorization endpoint URL for '${storeDomain}'`,
@@ -881,7 +883,7 @@ async function wizardFields(
 		)
 	)?.trim();
 	if (!authorizeUrl) {
-		await cancelled();
+		cancelled();
 		return undefined;
 	}
 	const scopesRaw = await ctx.ui.input(
@@ -889,7 +891,7 @@ async function wizardFields(
 		"e.g. read,profile — empty to skip",
 	);
 	if (scopesRaw === undefined) {
-		await cancelled();
+		cancelled();
 		return undefined;
 	}
 	const scopes = scopesRaw

package/node_modules/pi-lean-host/core/oauth-flow.ts

@@ -316,20 +316,36 @@ async function startAuthCodeFlow(
 		// wrap) so they never have to hunt for it in the scrollback above.
 		// Retry loop: a bad paste (typo, state mismatch, exchange hiccup) just
 		// re-prompts — the pending flow (verifier + state) is unchanged, so a
-		// retry is always safe. Escape/cancel exits to the --code nudge below.
+		// retry is always safe. Escape opens the recovery input below.
 		for (;;) {
 			const pasted = await ctx.ui.input(
 				`Open this URL in YOUR browser and authorize, then paste the redirect URL (or just the code) for '${storeDomain}':\n` +
 					printableAuthorizeUrl(authorizeUrl),
 				"paste the address-bar URL after consenting",
 			);
-			// Cancelled → fall through to the --code nudge (pending flow survives).
-			if (pasted === undefined) break;
+			if (pasted === undefined) {
+				// Esc at the paste: one recovery input instead of a hard cancel.
+				// Empty Enter (or a re-typed identical URI — a prefilling client
+				// submits the default on plain Enter) → paste again; the pending flow
+				// was never touched, so resuming is free and any code already issued
+				// against this authorize URL stays valid. A different typed URI →
+				// restart the flow with it (fresh PKCE/state/authorize URL, wizard
+				// answers intact since the mint call never returned). Esc → the
+				// --code nudge, pending survives.
+				const recovery = await ctx.ui.input(
+					`Redirect URI — Enter to keep ${redirectUri} and try the paste again, or type a corrected URI (Esc to abort)`,
+					redirectUri,
+				);
+				if (recovery === undefined) break;
+				const typed = recovery.trim();
+				if (typed === "" || typed === redirectUri) continue;
+				return startAuthCodeFlow(auth, storeDomain, ctx, typed);
+			}
 			try {
 				return await completePastedCode(auth, storeDomain, pasted);
 			} catch (err) {
 				ctx.ui.notify(
-					`🔑 ${err instanceof Error ? err.message : String(err)} — paste again, or escape to cancel.`,
+					`🔑 ${err instanceof Error ? err.message : String(err)} — paste again, or escape for recovery options.`,
 					"warning",
 				);
 			}

package/node_modules/pi-lean-host/core/parse-api-guide.ts

@@ -780,9 +780,8 @@ function validateResponseShape(
 
 /**
  * Validate a `Record<string, string>` auth sub-field (headers, secretRefs,
- * secretQueryRefs, headerPrefixes). Returns the parsed record, or a ParseError
- * when `raw` is absent/null/non-object/an array, or a value fails `valueOk`
- * (default: any string; `headerPrefixes` passes a non-empty check).
+ * secretQueryRefs). Returns the parsed record, or a ParseError when `raw` is
+ * absent/null/non-object/an array or any value is not a string.
  */
 function parseStringRecord(
 	raw: unknown,
@@ -790,13 +789,12 @@ function parseStringRecord(
 	fm: string,
 	field: string,
 	expect: string,
-	valueOk: (v: unknown) => boolean = (v) => typeof v === "string",
 ): Record<string, string> | ParseApiGuideResult {
 	if (
 		raw === null ||
 		typeof raw !== "object" ||
 		Array.isArray(raw) ||
-		Object.values(raw).some((v) => !valueOk(v))
+		Object.values(raw).some((v) => typeof v !== "string")
 	) {
 		return fail(file, field, expect, describeFound(raw), {
 			snippet: snippetFor(fm, "auth"),

package/node_modules/pi-lean-host/core/transport.ts

@@ -231,7 +231,7 @@ function cacheKey(url: string, opts?: FetchOptions): string {
  * normalized by this). Defined here so the transport layer — the one place
  * that holds a raw request URL and may embed it in an error message — can
  * self-redact instead of relying on callers to remember. `helpers.ts`
- * re-exports it for the capture points it owns (result.url, urls[],
+ * uses it for the capture points it owns (result.url, urls[],
  * HelperError.url).
  */
 export function redactSecretParams(

package/node_modules/pi-lean-host/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lean-host",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "Read-only REST API client for Pi. Your agent authors and calls YAML recipes handling the tedious parts: pagination, OAuth2, rate limits, backoff. Credentials live in a local store, injected in code, never in agent context. Churn-free research + retrieval",
 	"keywords": [
 		"pi-package",

package/node_modules/pi-lean-host/tools/api-guide.ts

@@ -13,18 +13,18 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
-import { appendFooter, contentText } from "./utils.js";
+import {
+	appendFooter,
+	disambiguationMenuResult,
+	shortNameErrorResult,
+} from "./utils.js";
 import {
 	loadAllGuides,
 	findGuidesByDomain,
 	getCatalogText,
 } from "../core/guide-store.js";
 import { TODAY } from "../core/parse-api-guide.js";
-import {
-	formatGuideListings,
-	selectGuideByShortName,
-	shortNameErrorText,
-} from "../core/guide-catalog.js";
+import { selectGuideByShortName } from "../core/guide-catalog.js";
 import { authStatusLine, canonicalStoreDomain } from "../core/auth.js";
 import { INLINE_LIMIT } from "../core/response-spill.js";
 import type { ApiGuide } from "../core/api-guide-types.js";
@@ -90,28 +90,12 @@ export const apiGuideTool = defineTool({
 		if (guideSelector) {
 			const sel = selectGuideByShortName(matches, guideSelector);
 			if (!sel.ok) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: shortNameErrorText(
-								sel,
-								domain,
-								guideSelector,
-								`Call api-guide({domain: "${domain}"}) to see the menu.`,
-							),
-						},
-					],
-					details:
-						sel.reason === "no_match"
-							? { error: "no_guide_by_shortname", domain, guide: guideSelector }
-							: {
-									error: "ambiguous_shortname",
-									domain,
-									guide: guideSelector,
-									directories: sel.directories,
-								},
-				};
+				return shortNameErrorResult(
+					sel,
+					domain,
+					guideSelector,
+					`Call api-guide({domain: "${domain}"}) to see the menu.`,
+				);
 			}
 			return renderGuideDetail(sel.guide, domain);
 		}
@@ -121,7 +105,12 @@ export const apiGuideTool = defineTool({
 		}
 
 		// Multiple guides for one domain → disambiguation menu.
-		return renderDisambiguationMenu(domain, matches);
+		return disambiguationMenuResult(
+			domain,
+			matches,
+			(shortName) =>
+				`Call api-guide({domain: "${domain}", guide: "${shortName}"}) for details.`,
+		);
 	},
 
 	renderCall(args, theme, _context) {
@@ -292,31 +281,3 @@ function renderGuideDetail(
 		},
 	};
 }
-
-/**
- * Disambiguation menu for a domain claimed by more than one guide. Lists
- * each guide's shortName (+ description when present) and a truncated op-name
- * summary; the org header shows only when all matches share one organization.
- */
-function renderDisambiguationMenu(
-	domain: string,
-	matches: { guide: ApiGuide; dirName: string }[],
-): AgentToolResult<unknown> {
-	const orgs = new Set(
-		matches.map((m) => m.guide.organization).filter((o): o is string => !!o),
-	);
-	const orgName = [...orgs][0];
-	const orgPart =
-		orgs.size === 1 && orgName ? ` (organization: ${orgName})` : "";
-	const lines: string[] = [];
-	lines.push(`${matches.length} API guides for '${domain}'${orgPart}:`);
-	lines.push(formatGuideListings(matches));
-	const example = matches[0]!.guide.shortName;
-	lines.push(
-		`Call api-guide({domain: "${domain}", guide: "${example}"}) for details.`,
-	);
-	return {
-		content: [{ type: "text", text: lines.join("\n") }],
-		details: { domain, disambiguation: matches.length },
-	};
-}

package/node_modules/pi-lean-host/tools/api-learn.ts

@@ -27,7 +27,12 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
-import { appendFooter, contentText } from "./utils.js";
+import {
+	appendFooter,
+	contentText,
+	disambiguationMenuResult,
+	shortNameErrorResult,
+} from "./utils.js";
 import {
 	existsSync,
 	mkdirSync,
@@ -43,11 +48,7 @@ import {
 	parseApiGuide,
 	stampFrontmatterField,
 } from "../core/parse-api-guide.js";
-import {
-	formatGuideListings,
-	selectGuideByShortName,
-	shortNameErrorText,
-} from "../core/guide-catalog.js";
+import { selectGuideByShortName } from "../core/guide-catalog.js";
 import {
 	GUIDE_SCHEMA_VERSION,
 	type ApiGuide,
@@ -415,25 +416,6 @@ function stageFetchedRecipe(
 	};
 }
 
-/** Disambiguation menu for the N-guide fetch-recipe case (mirrors
- * api-guide's menu). */
-function renderFetchMenu(
-	domain: string,
-	matches: { guide: ApiGuide; dirName: string }[],
-): AgentToolResult<unknown> {
-	const lines: string[] = [];
-	lines.push(`${matches.length} API guides for '${domain}':`);
-	lines.push(formatGuideListings(matches));
-	const example = matches[0]!.guide.shortName;
-	lines.push(
-		`Call api-learn({domain: "${domain}", guide: "${example}"}) to fetch one guide's recipe.`,
-	);
-	return {
-		content: [{ type: "text", text: lines.join("\n") }],
-		details: { mode: "menu", domain, disambiguation: matches.length },
-	};
-}
-
 // ═══════════════════════════════════════════════════════════════════
 // Tool definition
 // ═══════════════════════════════════════════════════════════════════
@@ -541,34 +523,23 @@ export const apiLearnTool = defineTool({
 				const { guide, dirName } = matches[0]!;
 				return stageFetchedRecipe(domain, guide, dirName);
 			}
-			// N guides → disambiguation by shortName (mirrors api-guide).
+			// N guides → disambiguation by shortName (shared menu helper).
 			if (!guideSelector) {
-				return renderFetchMenu(domain, matches);
+				return disambiguationMenuResult(
+					domain,
+					matches,
+					(shortName) =>
+						`Call api-learn({domain: "${domain}", guide: "${shortName}"}) to fetch one guide's recipe.`,
+				);
 			}
 			const sel = selectGuideByShortName(matches, guideSelector);
 			if (!sel.ok) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: shortNameErrorText(
-								sel,
-								domain,
-								guideSelector,
-								`Call api-learn({domain: "${domain}"}) to see the menu.`,
-							),
-						},
-					],
-					details:
-						sel.reason === "no_match"
-							? { error: "no_guide_by_shortname", domain, guide: guideSelector }
-							: {
-									error: "ambiguous_shortname",
-									domain,
-									guide: guideSelector,
-									directories: sel.directories,
-								},
-				};
+				return shortNameErrorResult(
+					sel,
+					domain,
+					guideSelector,
+					`Call api-learn({domain: "${domain}"}) to see the menu.`,
+				);
 			}
 			return stageFetchedRecipe(domain, sel.guide, sel.dirName);
 		}

package/node_modules/pi-lean-host/tools/api-probe.ts

@@ -93,8 +93,6 @@ export interface ProbeResult {
 }
 
 export interface ProbeOptions {
-	/** Accept header (default application/json). */
-	accept?: string;
 	/** On 404, walk the apiHost version backward (vN→v1). Default true. */
 	walkVersions?: boolean;
 	/**
@@ -563,7 +561,6 @@ export async function probe(
 	opts: ProbeOptions = {},
 	ctx?: ExtensionContext,
 ): Promise<ProbeResult> {
-	const accept = opts.accept ?? "application/json";
 	const walkVersions = opts.walkVersions ?? true;
 	const domain =
 		opts.domain ?? resolveProvisionedParentDomain(hostnameOf(apiHost));
@@ -575,7 +572,6 @@ export async function probe(
 		apiHost,
 		path,
 		params,
-		accept,
 		authCtx,
 		domain,
 		versionPrefixOf(apiHost),
@@ -593,7 +589,7 @@ export async function probe(
 		return base;
 	}
 	const hit = await walkBackward(
-		{ apiHost, path, params, accept, authCtx, domain },
+		{ apiHost, path, params, authCtx, domain },
 		Number(stated),
 	);
 	return hit ?? base;
@@ -615,7 +611,6 @@ async function walkBackward(
 		apiHost: string;
 		path: string;
 		params: Record<string, unknown>;
-		accept: string;
 		authCtx: ProbeAuthCtx;
 		domain: string;
 	},
@@ -628,7 +623,6 @@ async function walkBackward(
 			withVersion(ctx.apiHost, k),
 			ctx.path,
 			ctx.params,
-			ctx.accept,
 			ctx.authCtx,
 			ctx.domain,
 			`/v${k}`,
@@ -667,7 +661,6 @@ async function fetchOne(
 	apiHost: string,
 	path: string,
 	params: Record<string, unknown>,
-	accept: string,
 	authCtx: ProbeAuthCtx,
 	domain: string,
 	prefix = "",
@@ -694,7 +687,7 @@ async function fetchOne(
 	const url = redactUrl(rawUrl);
 	const hasQuerySecret = Object.keys(authCtx.queryParams).length > 0;
 	const res = await fetchUrl(rawUrl, {
-		headers: { accept, ...authCtx.headers },
+		headers: { accept: "application/json", ...authCtx.headers },
 		fresh: true,
 		...(authCtx.hasAuthBlock
 			? {
@@ -787,8 +780,7 @@ async function fetchOne(
 			shape: null,
 			draft: "",
 			raw,
-			note:
-				"non-JSON body (set opts.accept for XML/HTML, or use a different path)",
+			note: "non-JSON body (use a different path)",
 		};
 	}
 
@@ -839,21 +831,20 @@ function buildUrl(
 	const substituted = fillPathTemplate(path, fillParams);
 	const qs = new URLSearchParams(
 		Object.fromEntries(
-			Object.entries(queryParams)
-				.filter(([k, v]) => v !== undefined && !pathTokens.has(k))
-				.map(([k, v]) => {
-					// Probe has no guide schema to declare listStyle against, so
-					// non-scalar values are a loud error — never the silent
-					// String(v) wire form (String(["a","b"]) → "a,b" is
-					// accidentally comma-correct but misdescribes repeat/bracket
-					// APIs; [object Object] is wrong everywhere).
-					if (Array.isArray(v) || (typeof v === "object" && v !== null)) {
-						throw new Error(
-							`Param "${k}" is ${Array.isArray(v) ? "an array" : "an object"} — api-probe sends scalar params only: pre-join list values as a string, or JSON.stringify DSL params`,
-						);
-					}
-					return [k, String(v)] as [string, string];
-				}),
+			Object.entries(queryParams).flatMap(([k, v]): [string, string][] => {
+				if (v === undefined || pathTokens.has(k)) return [];
+				// Probe has no guide schema to declare listStyle against, so
+				// non-scalar values are a loud error — never the silent
+				// String(v) wire form (String(["a","b"]) → "a,b" is
+				// accidentally comma-correct but misdescribes repeat/bracket
+				// APIs; [object Object] is wrong everywhere).
+				if (Array.isArray(v) || (typeof v === "object" && v !== null)) {
+					throw new Error(
+						`Param "${k}" is ${Array.isArray(v) ? "an array" : "an object"} — api-probe sends scalar params only: pre-join list values as a string, or JSON.stringify DSL params`,
+					);
+				}
+				return [[k, String(v)]];
+			}),
 		),
 	).toString();
 	return joinUrl(apiHost, substituted, qs);

package/node_modules/pi-lean-host/tools/api-scaffold.ts

@@ -27,14 +27,15 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
-import { appendFooter, contentText } from "./utils.js";
+import {
+	appendFooter,
+	contentText,
+	disambiguationMenuResult,
+	shortNameErrorResult,
+} from "./utils.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import {
-	formatGuideListings,
-	selectGuideByShortName,
-	shortNameErrorText,
-} from "../core/guide-catalog.js";
+import { selectGuideByShortName } from "../core/guide-catalog.js";
 import type { ApiGuide } from "../core/api-guide-types.js";
 import { findGuidesByDomain, getUserGuidesDir } from "../core/guide-store.js";
 import { assertSafeDomain, slug } from "../core/path-template.js";
@@ -235,45 +236,22 @@ export const apiScaffoldTool = defineTool({
 		} else if (guideSelector) {
 			const sel = selectGuideByShortName(matches, guideSelector);
 			if (!sel.ok) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: shortNameErrorText(
-								sel,
-								domain,
-								guideSelector,
-								`Call api-scaffold({domain: "${domain}", verify: true}) to see the menu.`,
-							),
-						},
-					],
-					details:
-						sel.reason === "no_match"
-							? { error: "no_guide_by_shortname", domain, guide: guideSelector }
-							: {
-									error: "ambiguous_shortname",
-									domain,
-									guide: guideSelector,
-									directories: sel.directories,
-								},
-				};
+				return shortNameErrorResult(
+					sel,
+					domain,
+					guideSelector,
+					`Call api-scaffold({domain: "${domain}", verify: true}) to see the menu.`,
+				);
 			}
 			selected = sel;
 		} else {
-			// N guides, no selector → disambiguation menu (mirrors api-learn).
-			return {
-				content: [
-					{
-						type: "text",
-						text: [
-							`${matches.length} API guides for '${domain}':`,
-							formatGuideListings(matches),
-							`Call api-scaffold({domain: "${domain}", guide: "${matches[0]!.guide.shortName}", verify: true}) to scaffold one.`,
-						].join("\n"),
-					},
-				],
-				details: { mode: "menu", domain, disambiguation: matches.length },
-			};
+			// N guides, no selector → disambiguation menu.
+			return disambiguationMenuResult(
+				domain,
+				matches,
+				(shortName) =>
+					`Call api-scaffold({domain: "${domain}", guide: "${shortName}", verify: true}) to scaffold one.`,
+			);
 		}
 
 		const { guide, dirName } = selected;

package/node_modules/pi-lean-host/tools/utils.ts

@@ -2,6 +2,12 @@ import type {
 	AgentToolResult,
 	ThemeColor,
 } from "@earendil-works/pi-coding-agent";
+import {
+	formatGuideListings,
+	selectGuideByShortName,
+	shortNameErrorText,
+} from "../core/guide-catalog.js";
+import type { ApiGuide } from "../core/api-guide-types.js";
 
 /**
  * Extract the text of the first text content block of a tool result.
@@ -15,6 +21,69 @@ export function contentText(
 	return c && c.type === "text" ? c.text : fallback;
 }
 
+/**
+ * Tool-channel error result for a failed `selectGuideByShortName` — the
+ * shared envelope (error text + structured details) behind api-guide,
+ * api-learn, and api-scaffold's `{domain, guide}` resolution. The trailing
+ * "how to see the menu" hint differs per tool, so callers pass it.
+ */
+export function shortNameErrorResult(
+	sel: Extract<ReturnType<typeof selectGuideByShortName>, { ok: false }>,
+	domain: string,
+	selector: string,
+	callToAction: string,
+): AgentToolResult<unknown> {
+	return {
+		content: [
+			{
+				type: "text",
+				text: shortNameErrorText(sel, domain, selector, callToAction),
+			},
+		],
+		details:
+			sel.reason === "no_match"
+				? { error: "no_guide_by_shortname", domain, guide: selector }
+				: {
+						error: "ambiguous_shortname",
+						domain,
+						guide: selector,
+						directories: sel.directories,
+					},
+	};
+}
+
+/**
+ * Tool-channel disambiguation menu for a domain claimed by N guides:
+ * count header (+ shared `organization:` when all matches share one),
+ * per-guide listings, and a per-tool call-to-action footer built from
+ * the first match's shortName.
+ */
+export function disambiguationMenuResult(
+	domain: string,
+	matches: { guide: ApiGuide }[],
+	callToAction: (shortName: string) => string,
+): AgentToolResult<unknown> {
+	const orgs = new Set(
+		matches.map((m) => m.guide.organization).filter((o): o is string => !!o),
+	);
+	const orgName = [...orgs][0];
+	const orgPart =
+		orgs.size === 1 && orgName ? ` (organization: ${orgName})` : "";
+	return {
+		content: [
+			{
+				type: "text",
+				text: [
+					`${matches.length} API guides for '${domain}'${orgPart}:`,
+					formatGuideListings(matches),
+					callToAction(matches[0]!.guide.shortName),
+				].join("\n"),
+			},
+		],
+		details: { mode: "menu", domain, disambiguation: matches.length },
+	};
+}
+
 /**
  * Append a dim-styled content preview to an in-progress result string,
  * with a "more chars" suffix when the content exceeds the given limit.