@black942026/pi-ask-user 0.0.0-stage → 0.1.0

package/src/adapters/pi.ts

@@ -0,0 +1,238 @@
+import type { ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, isKeyRepeat, matchesKey, type KeyId, type OverlayHandle } from "@earendil-works/pi-tui";
+import {
+	DEFAULT_OVERLAY_TOGGLE_KEY,
+	isAllowedOverlayToggleSpec,
+	resolveAskUserConfig,
+	toUiPreferences,
+	type AskUserConfigOverrides,
+} from "../config.ts";
+import { createAskUserHost, type CreateAskUserHostOptions } from "../route.ts";
+import type {
+	AskUIInput,
+	AskUIOutcome,
+	AskUserDisplayMode,
+	AskUserHost,
+	AskUserMode,
+	CustomUIRenderer,
+} from "../types.ts";
+import { AskUserComponent, type AskUserTheme, type CustomUIResult } from "../ui/custom.ts";
+import { createNativeRunner } from "../ui/native.ts";
+
+export interface PiHostOptions {
+	/**
+	 * Explicit UI route: `custom` | `native`. The single highest precedence. When
+	 * omitted, the route is probed from the implementations this context really
+	 * supports, or read from the user config file. An invalid value is reported as
+	 * `invalid_config`.
+	 */
+	mode?: AskUserMode;
+	/** Explicit display mode; overrides the config file and the request. */
+	displayMode?: AskUserDisplayMode;
+	/** Explicit overlay toggle key; `null` disables it. Overrides the config file. */
+	overlayToggleKey?: string | null;
+	/** Explicit timeout (ms) per question; overrides the config file and the request. */
+	timeoutPerQuestionMs?: number;
+	/**
+	 * Path to the user config file, or `false` to skip reading it. Defaults to
+	 * `~/.pi/ask-user/config.json`. There are no environment variables.
+	 */
+	configFile?: string | false;
+}
+
+/**
+ * Build the default host adapter for a running Pi extension, from an available
+ * `ExtensionContext`.
+ *
+ * The Pi lifecycle only exposes the context during a tool call / command
+ * handler, so the capability probe happens here, at host creation — not at
+ * extension registration, which can capture only the explicit options.
+ *
+ * The user config file is read here too, once per host, and resolved as
+ * `explicit option > file > built-in`. An invalid file does not throw: it makes
+ * the host unusable (`invalid_config`), so every call is refused actionably and
+ * nothing falls back to another route.
+ *
+ * Both implementations are bound wherever they can really run:
+ *
+ *  - `customUI`      — only in `tui` mode with a callable `ctx.ui.custom()`.
+ *  - `nativeDialogs` — only when `ctx.hasUI` and `ctx.ui.input` is callable,
+ *    i.e. native input dialogs shown one question at a time. RPC reports
+ *    `hasUI: true`, so a nonresponsive RPC client is *not* pre-judged: the
+ *    attempt is made and the shared deadline turns silence into an actionable
+ *    `timeout`.
+ *
+ * The route is then resolved once (explicit `mode`, else the probe with `custom`
+ * preferred, else unsupported) and stored on the host. JSON/print have no
+ * dialog-capable UI, so with no explicit mode the result is `no_available_ui`,
+ * and an explicit `custom`/`native` there is `configured_unavailable` — neither
+ * silently becomes a different route. The model can never influence any of this:
+ * it comes from this adapter, not from tool parameters.
+ */
+export function createPiHost(ctx: ExtensionContext, options: PiHostOptions = {}): AskUserHost {
+	const programmatic: AskUserConfigOverrides = {};
+	if (options.mode !== undefined) programmatic.mode = options.mode;
+	if (options.displayMode !== undefined) programmatic.displayMode = options.displayMode;
+	if ("overlayToggleKey" in options) programmatic.overlayToggleKey = options.overlayToggleKey;
+	if (options.timeoutPerQuestionMs !== undefined) programmatic.timeoutPerQuestionMs = options.timeoutPerQuestionMs;
+
+	const resolved = resolveAskUserConfig(programmatic, { configFile: options.configFile });
+	const config = resolved.config;
+
+	const hostOptions: CreateAskUserHostOptions = { name: "pi" };
+	if (config.mode !== undefined) hostOptions.mode = config.mode;
+	hostOptions.preferences = toUiPreferences(config);
+	if (resolved.error !== undefined) hostOptions.configError = resolved.error.message;
+
+	const overlayToggleKey =
+		config.overlayToggleKey === undefined ? DEFAULT_OVERLAY_TOGGLE_KEY : config.overlayToggleKey;
+	if (ctx.mode === "tui" && typeof ctx.ui?.custom === "function") {
+		hostOptions.customUI = createPiCustomRenderer(ctx.ui, { overlayToggleKey });
+	}
+	if (ctx.hasUI && typeof ctx.ui?.input === "function") {
+		hostOptions.nativeDialogs = createNativeRunner(ctx.ui);
+	}
+	return createAskUserHost(hostOptions);
+}
+
+export interface PiCustomRendererOptions {
+	/**
+	 * The overlay show/hide key, or `null` to disable it. When omitted, the
+	 * built-in default (`alt+o`) applies. Ignored on the native route and for
+	 * inline display, which register no listener.
+	 */
+	overlayToggleKey?: string | null;
+}
+
+/**
+ * Custom renderer backed by `ctx.ui.custom()`. TUI mode only.
+ *
+ * For an overlay it also installs the show/hide shortcut: the overlay handle
+ * (`onHandle` → `OverlayHandle.setHidden`) plus a raw `ctx.ui.onTerminalInput`
+ * listener, so the *same* key restores the overlay even while it is hidden
+ * (hidden overlays receive no component input). The listener is removed and the
+ * handle dropped in `finally`, on every exit path. Hiding neither resolves the
+ * interaction nor pauses its deadline: aborts and timeouts still complete while
+ * hidden, and `Esc` still cancels.
+ */
+export function createPiCustomRenderer(ui: ExtensionUIContext, options: PiCustomRendererOptions = {}): CustomUIRenderer {
+	const rawToggle = options.overlayToggleKey;
+	const candidate = rawToggle === null ? undefined : (rawToggle ?? DEFAULT_OVERLAY_TOGGLE_KEY);
+	// Defensive guard: the config layer rejects reserved/conflicting keys with an
+	// actionable error, so a validated chord always arrives here. A direct caller
+	// that bypasses it gets the toggle disabled rather than a listener that could
+	// shadow Esc or steal typing — never a silent substitution of another key.
+	const toggleSpec = candidate !== undefined && isAllowedOverlayToggleSpec(candidate) ? candidate : undefined;
+	return {
+		async render(input: AskUIInput): Promise<AskUIOutcome> {
+			const { request, deadline, signal } = input;
+			const overlay = request.displayMode !== "inline";
+			const toggle = overlay ? toggleSpec : undefined;
+
+			let handle: OverlayHandle | undefined;
+			let unsubscribe: (() => void) | undefined;
+			let component: AskUserComponent | undefined;
+			let abortHandler: (() => void) | undefined;
+			let cleanedUp = false;
+			let announced = false;
+
+			// Idempotent: safe to call from the abort path, `finally`, and repeatedly.
+			const cleanup = (): void => {
+				if (cleanedUp) return;
+				cleanedUp = true;
+				if (abortHandler && signal) {
+					signal.removeEventListener("abort", abortHandler);
+					abortHandler = undefined;
+				}
+				unsubscribe?.();
+				unsubscribe = undefined;
+				handle = undefined;
+				component = undefined;
+			};
+			// On abort/timeout the core settles independently of `ui.custom`; remove
+			// the raw listener and drop the handle immediately so keys can no longer
+			// be captured even if the custom UI never resolves.
+			const onAbort = (): void => {
+				try {
+					component?.abort();
+				} catch {
+					// Settling the component must not mask the abort.
+				}
+				cleanup();
+			};
+
+			try {
+				if (signal?.aborted) {
+					// Already cancelled before any UI: install no side effects.
+					onAbort();
+					return { kind: "abort" };
+				}
+				if (signal) {
+					abortHandler = onAbort;
+					signal.addEventListener("abort", onAbort, { once: true });
+				}
+
+				if (toggle !== undefined && typeof ui.onTerminalInput === "function") {
+					unsubscribe = ui.onTerminalInput((data) => {
+						if (!handle || !matchesKey(data, toggle as KeyId)) return undefined;
+						// Kitty's progressive protocol reports press, repeat and release
+						// separately. Toggle only on the initial press; consume repeat and
+						// release so they cannot reach the component behind the overlay.
+						if (isKeyRepeat(data) || isKeyRelease(data)) return { consume: true };
+						const nextHidden = !handle.isHidden();
+						handle.setHidden(nextHidden);
+						if (nextHidden && !announced) {
+							announced = true;
+							ui.notify?.(`ask_user hidden — press ${toggle} to reopen`, "info");
+						}
+						return { consume: true };
+					});
+				}
+
+				input.onUpdate?.("Waiting for user input…");
+				const result = await ui.custom<CustomUIResult>(
+					(tui, theme, _keybindings, done) => {
+						component = new AskUserComponent({
+							request,
+							deadline,
+							theme: theme as unknown as AskUserTheme,
+							tui,
+							done,
+							overlayToggleKey: toggle,
+						});
+						if (signal?.aborted) queueMicrotask(() => component?.abort());
+						return component;
+					},
+					{
+						overlay,
+						overlayOptions: {
+							anchor: "center",
+							// Keep the dialog readable on very wide terminals; Pi clamps
+							// this fixed width to the available columns on smaller ones.
+							width: 96,
+							minWidth: 64,
+							maxHeight: "85%",
+							margin: 1,
+						},
+						// Only an overlay has a handle to hide/show.
+						...(
+							overlay
+								? {
+										onHandle: (overlayHandle: OverlayHandle) => {
+											handle = overlayHandle;
+										},
+									}
+								: {}
+						),
+					},
+				);
+				if (!result) {
+					return { kind: "error", message: "custom UI returned no result (the host failed to render the custom component)." };
+				}
+				return result;
+			} finally {
+				cleanup();
+			}
+		},
+	};
+}

package/src/answers.ts

@@ -0,0 +1,84 @@
+import type { AskUserAnswer, NormalizedQuestion } from "./types.ts";
+
+/**
+ * A draft answer as manipulated by a UI before being finalized. Selections are
+ * option indices; free text is kept verbatim while editing.
+ */
+export interface DraftAnswer {
+	selections: number[];
+	freeText: string;
+	usedDefault: boolean;
+}
+
+export function emptyDraft(): DraftAnswer {
+	return { selections: [], freeText: "", usedDefault: false };
+}
+
+/** A draft is empty when it carries neither a selection nor any free text. */
+export function draftIsEmpty(draft: DraftAnswer): boolean {
+	return draft.selections.length === 0 && draft.freeText.trim() === "";
+}
+
+/**
+ * Materialize the question default as a draft, or `undefined` when the question
+ * has no default. A default that matches an option label selects that option;
+ * otherwise it is treated as free text (which is what `input` questions want).
+ */
+export function draftFromDefault(question: NormalizedQuestion): DraftAnswer | undefined {
+	if (!question.hasDefault || question.default === undefined) return undefined;
+	if (question.kind !== "input") {
+		const idx = question.options.findIndex((option) => option.label === question.default!.trim());
+		if (idx >= 0) {
+			return { selections: [idx], freeText: "", usedDefault: true };
+		}
+	}
+	return { selections: [], freeText: question.default, usedDefault: true };
+}
+
+/** Finalize a draft into an answer. Assumes the draft is non-empty. */
+export function toAnswer(question: NormalizedQuestion, draft: DraftAnswer): AskUserAnswer {
+	const selections = draft.selections
+		.filter((idx) => idx >= 0 && idx < question.options.length)
+		.map((idx) => question.options[idx]!.label);
+	const freeText = draft.freeText.trim();
+	const answer: AskUserAnswer = {
+		index: question.index,
+		id: question.id,
+		title: question.title,
+		kind: question.kind,
+		selections,
+		usedDefault: draft.usedDefault,
+	};
+	if (freeText !== "") answer.freeText = freeText;
+	return answer;
+}
+
+export interface FinalizeResult {
+	answers: AskUserAnswer[];
+	/** Indices (0-based question indices) still unanswered and without a default. */
+	unanswered: number[];
+}
+
+/**
+ * Apply defaults to empty drafts and finalize the questionnaire. Questions that
+ * are still empty and have no default are reported in `unanswered`; they are
+ * omitted from `answers`.
+ */
+export function finalizeAnswers(questions: NormalizedQuestion[], drafts: DraftAnswer[]): FinalizeResult {
+	const answers: AskUserAnswer[] = [];
+	const unanswered: number[] = [];
+	questions.forEach((question, index) => {
+		const draft = drafts[index] ?? emptyDraft();
+		if (draftIsEmpty(draft)) {
+			const fallback = draftFromDefault(question);
+			if (fallback) {
+				answers.push(toAnswer(question, fallback));
+			} else {
+				unanswered.push(index);
+			}
+			return;
+		}
+		answers.push(toAnswer(question, draft));
+	});
+	return { answers, unanswered };
+}

package/src/ask.ts

@@ -0,0 +1,103 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createPiHost } from "./adapters/pi.ts";
+import { askUser } from "./core.ts";
+import type {
+	AskUserDisplayMode,
+	AskUserEventSink,
+	AskUserHost,
+	AskUserMode,
+	AskUserResult,
+} from "./types.ts";
+
+/** Options for {@link createAskUser}. */
+export interface CreateAskUserOptions {
+	/**
+	 * Explicit UI route for the bound host (`custom` | `native`); highest
+	 * precedence. A route the environment cannot run is refused, never
+	 * substituted.
+	 */
+	mode?: AskUserMode;
+	/** Explicit display mode; overrides the config file and the request. */
+	displayMode?: AskUserDisplayMode;
+	/** Explicit overlay toggle key; `null` disables it. Overrides the config file. */
+	overlayToggleKey?: string | null;
+	/** Explicit timeout (ms) per question; overrides the config file and the request. */
+	timeoutPerQuestionMs?: number;
+	/** Path to the user config file, or `false` to skip reading it. */
+	configFile?: string | false;
+	/**
+	 * Optional observer for the interactive wait. A direct caller has no Pi event
+	 * bus, so nothing is emitted unless this is supplied — there is no fabricated
+	 * bus access. Pass a sink to receive `waitStarted`/`waitEnded` around each UI
+	 * attempt.
+	 */
+	events?: AskUserEventSink;
+}
+
+/**
+ * Options accepted when reusing an already-built {@link AskUserHost}. The config
+ * knobs were resolved into the host at its creation, so only call-scoped
+ * observers apply here.
+ */
+export interface CreateAskUserFromHostOptions {
+	/** Optional observer for the interactive wait (see {@link CreateAskUserOptions.events}). */
+	events?: AskUserEventSink;
+}
+
+/**
+ * A host-bound, directly callable asker for other extensions — not the model.
+ *
+ * Availability is readable **before** any UI is shown:
+ *
+ *  - `isAvailable` — `true` when the bound host has a ready interactive route;
+ *  - `notAvailableReason` — why it has none, or `undefined` when it has one.
+ *
+ * This reports the host's structural/configured capability; it is not a promise
+ * that a render will succeed.
+ *
+ * Calling it resolves to an {@link AskUserResult} for the caller and never
+ * forwards anything to the model; there is no plain-text fallback.
+ */
+export interface AskUser {
+	(request: unknown): Promise<AskUserResult>;
+	readonly isAvailable: boolean;
+	readonly notAvailableReason: string | undefined;
+	/** The host this asker is bound to. */
+	readonly host: AskUserHost;
+}
+
+function isAskUserHost(value: ExtensionContext | AskUserHost): value is AskUserHost {
+	return typeof value === "object" && value !== null && "support" in value;
+}
+
+/**
+ * Bind a directly callable `ask` to a host.
+ *
+ * Pass a Pi `ExtensionContext` (optionally with explicit options) to probe the
+ * environment and read the user config once, or pass a pre-built
+ * {@link AskUserHost} to reuse one. The result exposes `isAvailable` /
+ * `notAvailableReason` up front, so callers can decide before showing any UI.
+ *
+ * A direct call has no Pi event bus: pass `events` to observe the interactive
+ * wait, or accept that no runtime events are emitted.
+ */
+export function createAskUser(ctx: ExtensionContext, options?: CreateAskUserOptions): AskUser;
+export function createAskUser(host: AskUserHost, options?: CreateAskUserFromHostOptions): AskUser;
+export function createAskUser(
+	source: ExtensionContext | AskUserHost,
+	options: CreateAskUserOptions | CreateAskUserFromHostOptions = {},
+): AskUser {
+	const host = isAskUserHost(source)
+		? source
+		: createPiHost(source, options as CreateAskUserOptions);
+	const support = host.support;
+	const events = options.events;
+	const ask = ((request: unknown) =>
+		askUser(request, events ? { host, events } : { host })) as AskUser;
+	Object.defineProperties(ask, {
+		isAvailable: { value: support.status === "available", enumerable: true },
+		notAvailableReason: { value: support.status === "available" ? undefined : support.reason, enumerable: true },
+		host: { value: host, enumerable: true },
+	});
+	return ask;
+}