@bastani/atomic 0.9.16-alpha.2 → 0.9.16-alpha.3

package/dist/builtin/workflows/src/tui/inline-form-overlay.ts

@@ -1,317 +0,0 @@
-/**
- * Orchestration for the inline workflow input form (Option C: sticky chat
- * card + custom editor).
- *
- *   `registerInlineFormRenderer(pi)`   — call once at extension init time
- *                                       to wire `pi.registerMessageRenderer`
- *                                       for our customType. Idempotent.
- *
- *   `openInlineInputsForm(pi, ctx, …)` — drive a single form. Mutates the
- *                                       chat by emitting a custom message,
- *                                       swaps in our editor, awaits user
- *                                       input, then restores the prior
- *                                       editor and resolves with the
- *                                       coerced values (or cancel).
- *
- * The card stays in chat scrollback forever (frozen view after exit).
- *
- * cross-ref:
- *  - src/tui/inline-form-store.ts  (state map)
- *  - src/tui/inline-form-card.ts   (renderer used by message renderer)
- *  - src/tui/inline-form-editor.ts (custom EditorComponent)
- */
-
-import { isStaleExtensionContextError } from "@bastani/atomic";
-import type { ExtensionAPI, PiCommandContext } from "../extension/index.js";
-import type { WorkflowInputEntry } from "../extension/render-result.js";
-import type { PiEditorComponent, PiEditorFactory } from "../extension/wiring.js";
-import type { WorkflowInputValues } from "../shared/types.js";
-import type { GraphTheme } from "./graph-theme.js";
-import { renderInlineCard } from "./inline-form-card.js";
-import { InlineFormEditor } from "./inline-form-editor.js";
-import { createForm, finalizeForm, getForm } from "./inline-form-store.js";
-import { coerceValues } from "./inputs-picker.js";
-
-const CUSTOM_TYPE = "workflows:input-form";
-
-interface FormMessageDetails {
-	formId: string;
-}
-
-/**
- * Public result type — matches the popup-version contract so callers don't
- * care which surface was used.
- */
-export type InlineFormResult =
-	| { kind: "run"; values: WorkflowInputValues }
-	| { kind: "cancel" }
-	| { kind: "unsupported" };
-
-export interface OpenInlineFormOpts {
-	workflowName: string;
-	fields: readonly WorkflowInputEntry[];
-	prefilled?: WorkflowInputValues;
-	theme: GraphTheme;
-}
-
-// ---------------------------------------------------------------------------
-// Message renderer registration
-// ---------------------------------------------------------------------------
-
-const rendererRegisteredHosts = new WeakSet<object>();
-
-/**
- * Renderer return shape (subset of pi-tui's `Component`). Defined locally so
- * the project doesn't need to import from `@earendil-works/pi-tui` (which is
- * a peer dep of pi-coding-agent that we don't link directly).
- */
-interface CardComponent {
-	render(width: number): string[];
-	invalidate?(): void;
-}
-
-type RawRenderer = (payload: unknown) => CardComponent | null | undefined;
-
-/**
- * Wire the message renderer once per live ExtensionAPI host. pi creates a new
- * extension host on `/new`, `/resume`, `/fork`, and `/reload`, while jiti may
- * keep this module cached. A process-global boolean would skip registration in
- * the replacement session and leave emitted workflow form messages without a
- * renderer.
- *
- * Theme is captured at registration. If pi's active theme changes later the
- * renderer continues with the original; acceptable since these cards are
- * mostly historical artefacts.
- */
-export function registerInlineFormRenderer(pi: ExtensionAPI, theme: GraphTheme): void {
-	if (rendererRegisteredHosts.has(pi)) return;
-	const register = pi.registerMessageRenderer;
-	if (typeof register !== "function") return;
-
-	const renderer: RawRenderer = (raw) => {
-		const message = raw as {
-			content?: string;
-			details?: { formId?: string };
-		};
-		const formId = message.details?.formId;
-		if (!formId) return undefined;
-		const state = getForm(formId);
-		if (!state) {
-			// No backing state — the session was resumed/replaced (the store is
-			// cleared on session_start) or the map was evicted. Return null so the
-			// host renders nothing: the input widget must not reappear in chat after
-			// /resume rather than showing a stale or "snapshot lost" placeholder.
-			return null;
-		}
-		return {
-			// The card is fully reactive: read fresh state on every render call,
-			// not just at construction time. pi's host re-runs render() whenever
-			// `tui.requestRender()` fires — that's our editor's mutation signal.
-			render: (width: number) =>
-				renderInlineCard({
-					width,
-					state: getForm(formId) ?? state,
-					theme,
-				}),
-			invalidate: () => {
-				/* nothing cached; renders are pure of state */
-			},
-		};
-	};
-
-	// Call through `pi` so pi's class-backed ExtensionAPI keeps its `this` binding.
-	register.call(pi, CUSTOM_TYPE, renderer);
-	rendererRegisteredHosts.add(pi);
-}
-
-// ---------------------------------------------------------------------------
-// Open / drive a form
-// ---------------------------------------------------------------------------
-
-/**
- * Open an inline form. Returns a Promise that resolves with the user's
- * coerced values on submit, `{kind:"cancel"}` on esc, or
- * `{kind:"unsupported"}` when the host cannot mount a custom editor. The
- * unsupported result lets callers fall back to another picker surface instead
- * of surfacing a host `setEditorComponent` exception to the user.
- *
- * Requirements:
- *   - `pi.sendMessage` is available to add the sticky form card
- *   - `ctx.ui.setEditorComponent` is available and accepts the richer
- *     pi custom editor surface
- *
- * On any missing or incompatible surface we resolve `unsupported` so the
- * caller can keep the existing missing-required-input path or use a supported
- * overlay picker.
- */
-export async function openInlineInputsForm(
-	pi: ExtensionAPI,
-	ctx: PiCommandContext,
-	opts: OpenInlineFormOpts,
-): Promise<InlineFormResult> {
-	const setEditor = ctx.ui?.setEditorComponent;
-	const getEditor = ctx.ui?.getEditorComponent;
-	const sendMessage = pi.sendMessage;
-	if (typeof setEditor !== "function" || typeof sendMessage !== "function") {
-		return { kind: "unsupported" };
-	}
-	if (opts.fields.length === 0) {
-		// Defensive — caller should already have gated on fields.length > 0.
-		return { kind: "run", values: coerceValues(opts.fields, {}) };
-	}
-
-	// ── Seed state ────────────────────────────────────────────────────────
-	const formId = makeFormId();
-	const prefilled = opts.prefilled ?? {};
-	const rawText: Record<string, string> = {};
-	for (const f of opts.fields) {
-		if (prefilled[f.name] !== undefined) {
-			rawText[f.name] = String(prefilled[f.name]);
-		} else if (f.default !== undefined) {
-			rawText[f.name] = String(f.default);
-		} else if (f.type === "select" && f.choices && f.choices.length > 0) {
-			rawText[f.name] = f.choices[0]!;
-		} else if (f.type === "boolean") {
-			rawText[f.name] = "false";
-		} else {
-			rawText[f.name] = "";
-		}
-	}
-	// Focus first invalid field if any.
-	const firstInvalid = opts.fields.findIndex((f) => f.required && (rawText[f.name] ?? "").trim() === "");
-	const focusedIdx = firstInvalid >= 0 ? firstInvalid : 0;
-	const state = createForm({
-		formId,
-		workflowName: opts.workflowName,
-		fields: opts.fields,
-		rawText,
-		focusedIdx,
-		submitChoiceIdx: 0,
-		caret: (rawText[opts.fields[focusedIdx]!.name] ?? "").length,
-		status: "editing",
-	});
-
-	// ── Swap in our editor and await user decision ────────────────────────
-	const previous: PiEditorFactory | undefined = typeof getEditor === "function" ? getEditor.call(ctx.ui) : undefined;
-
-	return new Promise<InlineFormResult>((resolve) => {
-		let resolved = false;
-		let activeEditor: PiEditorComponent | undefined;
-		let installedFactory: PiEditorFactory | undefined;
-		const shouldRestorePreviousEditor = (): boolean => {
-			if (typeof getEditor !== "function") return true;
-			try {
-				return getEditor.call(ctx.ui) === installedFactory;
-			} catch (err) {
-				// During `/new`, `/resume`, `/fork`, and `/reload`, pi marks the old
-				// extension command context as stale before tearing down the old editor
-				// surface. A workflow form that settles after that point must not write
-				// its captured pre-switch editor factory back into the fresh session.
-				if (isStaleExtensionContextError(err)) {
-					return false;
-				}
-				// Preserve the previous best-effort behavior for older or unusual hosts:
-				// if introspection fails for a non-stale reason, still try the restore
-				// and let the existing setEditor catch below keep the command safe.
-				return true;
-			}
-		};
-		const restorePreviousEditor = (): void => {
-			if (!shouldRestorePreviousEditor()) return;
-			try {
-				setEditor.call(ctx.ui, previous);
-			} catch {
-				// If the host rejects the previous factory as well, leave the host's
-				// current editor alone. The important part is that the workflow command
-				// resolves without rethrowing the host editor setup failure.
-			}
-		};
-		const settle = (result: InlineFormResult): void => {
-			if (resolved) return;
-			resolved = true;
-			finalizeForm(formId, result.kind === "run" ? "submit" : "cancel");
-			activeEditor?.dispose?.();
-			activeEditor = undefined;
-			// Restore the previous editor (or default if there wasn't one).
-			restorePreviousEditor();
-			resolve(result);
-		};
-
-		const factory: PiEditorFactory = (tui, _editorTheme, kb): PiEditorComponent => {
-			activeEditor = new InlineFormEditor(tui as { requestRender?: () => void }, {
-				formId,
-				theme: opts.theme,
-				// Pi injects its `KeybindingsManager` as the third factory arg; the
-				// editor uses it to route text-editing actions (delete word, line
-				// jump, etc.) through the user's resolved keybindings. Older hosts
-				// and tests pass a non-keybindings shape — the editor's
-				// `isKeybindingsLike` guard handles that gracefully.
-				keybindings: kb as ConstructorParameters<typeof InlineFormEditor>[1]["keybindings"],
-				onExit: (outcome) => {
-					if (outcome === "submit") {
-						settle({ kind: "run", values: coerceValues(opts.fields, state.rawText) });
-					} else {
-						settle({ kind: "cancel" });
-					}
-				},
-			});
-			return activeEditor;
-		};
-
-		installedFactory = factory;
-
-		try {
-			setEditor.call(ctx.ui, factory);
-		} catch {
-			activeEditor?.dispose?.();
-			activeEditor = undefined;
-			finalizeForm(formId, "cancel");
-			resolve({ kind: "unsupported" });
-			return;
-		}
-
-		try {
-			(
-				sendMessage as unknown as (
-					msg: {
-						customType: string;
-						content?: string;
-						display?: boolean;
-						details?: FormMessageDetails;
-					},
-					options?: { excludeFromContext?: boolean },
-				) => void
-			).call(
-				pi,
-				{
-					customType: CUSTOM_TYPE,
-					content: opts.workflowName,
-					display: true,
-					details: { formId },
-				},
-				{
-					// The input form is a transient UI surface, not conversation. Keep it
-					// out of LLM context so spawning the picker and exiting without
-					// running the workflow never leaks the form into the model.
-					excludeFromContext: true,
-				},
-			);
-		} catch {
-			activeEditor?.dispose?.();
-			activeEditor = undefined;
-			restorePreviousEditor();
-			finalizeForm(formId, "cancel");
-			resolve({ kind: "unsupported" });
-		}
-	});
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function makeFormId(): string {
-	// Short, monotonic-enough — no need for cryptographic uniqueness, just
-	// enough separation between concurrent forms in scrollback.
-	return `wf-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-}

package/dist/builtin/workflows/src/tui/inline-form-store.ts

@@ -1,90 +0,0 @@
-/**
- * Shared state store for inline workflow input forms.
- *
- * One entry per active or historical form, keyed by `formId` (uuid).
- * The custom message renderer (chat-history card) and the custom editor
- * (bottom-of-screen input) both read/write through this module so a single
- * keystroke updates both views via `tui.requestRender()`.
- *
- * Lifecycle:
- *   `createForm(id, …)`          → status = "editing"
- *   editor mutates fields        → status stays "editing"
- *   `finalizeForm(id, "submit")` → status = "submitted", values frozen
- *   `finalizeForm(id, "cancel")` → status = "cancelled"
- *
- * After finalize the state stays in the map for the lifetime of the session.
- * The renderer reads it to display the historical card. On a session boundary
- * (`session_start`: new/resume/fork/reload) the store is cleared via
- * {@link clearForms}, so a rehydrated `workflows:input-form` message has no
- * backing state and its renderer suppresses output (returns null) — the input
- * widget never reappears in chat after `/resume`.
- *
- * Why a global registry instead of closure capture: the message renderer is
- * registered ONCE at factory time and called many times for any number of
- * future messages. It can't close over per-invocation state. The formId in
- * `message.details` is the only stable link between a chat-history entry and
- * its mutable backing record.
- */
-
-import type { WorkflowInputEntry } from "../extension/render-result.js";
-
-export type FormStatus = "editing" | "submitted" | "cancelled";
-
-export interface InlineFormState {
-	formId: string;
-	workflowName: string;
-	fields: readonly WorkflowInputEntry[];
-	/** Raw string per field; mirrors `inputs-picker.ts` semantics. */
-	rawText: Record<string, string>;
-	focusedIdx: number;
-	/** Reserved for older form snapshots; Submit is now a single final action. */
-	submitChoiceIdx: number;
-	caret: number;
-	status: FormStatus;
-	/** Tick counter; bumped on every mutation so renderers can hash-dedupe. */
-	version: number;
-}
-
-const FORMS = new Map<string, InlineFormState>();
-
-export function createForm(init: Omit<InlineFormState, "version">): InlineFormState {
-	const state: InlineFormState = { ...init, version: 0 };
-	FORMS.set(state.formId, state);
-	return state;
-}
-
-export function getForm(formId: string): InlineFormState | undefined {
-	return FORMS.get(formId);
-}
-
-/**
- * Mutate the form in place and bump version. Returns the same state so
- * callers can chain. Mutating directly + bumping centrally keeps every code
- * path consistent — every keystroke handler closes with `touch(state)`.
- */
-export function touch(state: InlineFormState): InlineFormState {
-	state.version += 1;
-	return state;
-}
-
-export function finalizeForm(formId: string, outcome: "submit" | "cancel"): void {
-	const s = FORMS.get(formId);
-	if (!s) return;
-	s.status = outcome === "submit" ? "submitted" : "cancelled";
-	touch(s);
-}
-
-/**
- * Clear all inline form state. Called on `session_start` so a resumed or
- * replaced session never renders a stale live form, and so a rehydrated
- * `workflows:input-form` message resolves to no backing state (its renderer
- * then returns null and the host renders nothing).
- */
-export function clearForms(): void {
-	FORMS.clear();
-}
-
-/** Test helper — clear the registry between tests. */
-export function _resetForms(): void {
-	clearForms();
-}

package/dist/builtin/workflows/src/tui/inputs-overlay.ts

@@ -1,185 +0,0 @@
-/**
- * Mount adapter for the interactive argument picker. Reads like clack:
- * a single overlay mounts the picker via the real Pi `ctx.ui.custom(factory, options)`
- * primitive; user submit resolves the parent promise with the coerced
- * typed values. Escape resolves with `cancel` so the calling slash
- * command can short-circuit. When `pi.ui.custom` is unavailable the
- * promise resolves with `cancel` so the slash command can fall back to
- * the "missing required input" text path.
- *
- * The adapter handles the cursor-blink timer in addition to the standard
- * `pi.ui.custom` factory plumbing: a 530ms half-period interval (the
- * Neovim default rate, matching atomic's design TUI) drives a `cursorOn`
- * flag that's threaded into each render so single-line text fields show a
- * blinking caret instead of a static block.
- *
- * Mount mode
- * ----------
- * Uses the same bottom-pinned primitive as `ask_user_question`: hide the
- * host working-loader row for the lifetime of the blocking picker and mount
- * with `{ overlay: false }`. pi's interactive `ExtensionUiController.custom`
- * then REPLACES the editor with the mounted component
- * (`editorContainer.clear(); addChild(component)`), which puts the focused
- * picker in the bottom editor slot instead of a floating overlay. Suppressing
- * `Working…` while mounted keeps host chrome from being wedged between the
- * `/workflow …` command and the picker, avoiding the prior bottom-anchored
- * overlay regression captured in
- * `ui/workflows/Screenshot 2026-05-13 at 1.09.32 AM.png` without overlay
- * anchor/padding tricks — the host owns geometry.
- *
- * cross-ref:
- *   - src/tui/inputs-picker.ts (pure state + render)
- *   - src/tui/session-overlays.ts (sibling picker; same mount mode)
- *   - src/extension/wiring.ts (PiCustomOverlayFunction / PiOverlayOptions)
- *   - pi docs/tui.md  Mount points and return contracts
- */
-
-import type { WorkflowInputEntry } from "../extension/render-result.js";
-import type { PiCustomComponent, PiCustomOverlayFactoryTui, PiCustomOverlayFunction } from "../extension/wiring.js";
-import type { WorkflowInputValues } from "../shared/types.js";
-import type { GraphTheme } from "./graph-theme.js";
-import { coerceValues, createInputsPickerState, handleInputsPickerInput, renderInputsPicker } from "./inputs-picker.js";
-import { isInputsPickerKey } from "./inputs-picker-input.js";
-
-export interface InputsUiSurface {
-	custom?: PiCustomOverlayFunction;
-	setWorkingVisible?: (visible: boolean) => void;
-}
-
-export type InputsPickerResult = { kind: "run"; values: WorkflowInputValues } | { kind: "cancel" };
-
-export interface OpenInputsPickerOpts {
-	workflowName: string;
-	fields: WorkflowInputEntry[];
-	/** Prefilled values (e.g. from `key=value` slash args). The form
-	 *  seeds these into the form so the user doesn't re-type what they typed. */
-	prefilled?: WorkflowInputValues;
-	theme: GraphTheme;
-}
-
-/**
- * Mount the inputs picker. Resolves with the coerced typed value map on
- * confirm, or `cancel` on esc / no UI surface.
- *
- * Behaviour matrix:
- *   - `pi.ui.custom` present: mounted in the editor slot, settled by `done()`
- *   - no `pi.ui.custom` at all: resolves `cancel` immediately so the slash
- *                               command can fall back to the "missing
- *                               required input" text path
- */
-export function openInputsPicker(ui: InputsUiSurface, opts: OpenInputsPickerOpts): Promise<InputsPickerResult> {
-	return new Promise<InputsPickerResult>((resolve) => {
-		const { workflowName, fields, prefilled, theme } = opts;
-		if (fields.length === 0) {
-			// No inputs to collect — treat as immediate run with whatever the
-			// caller already prefilled (likely empty).
-			resolve({ kind: "run", values: coerceValues(fields, {}) });
-			return;
-		}
-
-		let workingHidden = false;
-		const hideWorking = (): void => {
-			ui.setWorkingVisible?.(false);
-			workingHidden = true;
-		};
-		const restoreWorking = (): void => {
-			if (!workingHidden) return;
-			workingHidden = false;
-			ui.setWorkingVisible?.(true);
-		};
-
-		hideWorking();
-
-		const custom = ui.custom;
-		if (typeof custom !== "function") {
-			restoreWorking();
-			resolve({ kind: "cancel" });
-			return;
-		}
-
-		const state = createInputsPickerState(fields, prefilled);
-		let settled = false;
-		let cursorOn = true;
-		let cursorTimer: ReturnType<typeof setInterval> | null = null;
-
-		const settleWithoutDone = (result: InputsPickerResult): void => {
-			if (settled) return;
-			settled = true;
-			if (cursorTimer) clearInterval(cursorTimer);
-			cursorTimer = null;
-			restoreWorking();
-			resolve(result);
-		};
-
-		const factory = (
-			tui: PiCustomOverlayFactoryTui,
-			_theme: unknown,
-			keys: unknown,
-			done: (r: undefined) => void,
-		): PiCustomComponent => {
-			// Start the blink as soon as the overlay mounts. We tear it down
-			// on dispose to avoid leaking timers across overlay lifecycles.
-			cursorTimer = setInterval(() => {
-				cursorOn = !cursorOn;
-				tui.requestRender?.();
-			}, 530);
-
-			const finish = (result: InputsPickerResult): void => {
-				if (settled) return;
-				settled = true;
-				if (cursorTimer) clearInterval(cursorTimer);
-				cursorTimer = null;
-				try {
-					done(undefined);
-				} finally {
-					restoreWorking();
-					resolve(result);
-				}
-			};
-
-			return {
-				render: (width: number) =>
-					renderInputsPicker({
-						width,
-						theme,
-						workflowName,
-						fields,
-						state,
-						cursorOn,
-					}),
-				handleInput: (data: string): boolean => {
-					// Pi's `KeybindingsManager` is the third factory arg — the
-					// picker uses it so user-configured text-editing actions
-					// (delete word, line jump, etc.) work the same in the
-					// inline form. Pass it through structurally; the picker guards
-					// the shape itself.
-					const kb = keys as Parameters<typeof handleInputsPickerInput>[3];
-					const consumed = isInputsPickerKey(data, state, fields, kb);
-					const action = handleInputsPickerInput(data, state, fields, kb);
-					if (action.kind === "noop") {
-						tui.requestRender?.();
-						return consumed;
-					}
-					finish(action);
-					return true;
-				},
-				invalidate: () => tui.requestRender?.(),
-				dispose: () => {
-					settleWithoutDone({ kind: "cancel" });
-				},
-			};
-		};
-
-		// overlay: false — picker replaces the editor in-place (see header
-		// comment). The host owns geometry/focus; no overlayOptions are
-		// forwarded by interactive pi today.
-		try {
-			// handlesCtrlC: the picker treats Ctrl+C as cancel (inputs-picker-input).
-			void Promise.resolve(custom(factory, { overlay: false, handlesCtrlC: true })).catch(() => {
-				settleWithoutDone({ kind: "cancel" });
-			});
-		} catch {
-			settleWithoutDone({ kind: "cancel" });
-		}
-	});
-}