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

package/dist/builtin/workflows/src/extension/status-writer.ts

@@ -1,182 +0,0 @@
-/**
- * Status file writer — subscribes to store updates and emits an atomic
- * status JSON file for CI polling.
- *
- * Behaviour:
- * - Only active when config.statusFile === true.
- * - Default path: <projectRoot>/.atomic/workflows/status.json
- * - Atomic write via temp-file + rename (no torn reads by CI consumers).
- * - Flushes on every store update; guaranteed to flush on run terminal states
- *   (completed | failed | killed).
- * - Write errors surfaced as level:"warning" WorkflowNotice via store;
- *   duplicate errors are deduplicated so one notice per distinct error message.
- *
- * cross-ref: src/shared/types.ts WorkflowRuntimeConfig
- *            src/store.ts Store
- *            src/store-types.ts StoreSnapshot
- */
-
-import { mkdir, rename, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { CONFIG_DIR_NAME } from "@bastani/atomic";
-import type { Store } from "../shared/store.js";
-import type { StoreSnapshot } from "../shared/store-types.js";
-import type { WorkflowRuntimeConfig } from "../shared/types.js";
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const DEFAULT_STATUS_SUBPATH = join(CONFIG_DIR_NAME, "workflows", "status.json");
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface StatusWriterOpts {
-	/**
-	 * Project root used to resolve the default status file path.
-	 * Defaults to process.cwd() when absent.
-	 */
-	projectRoot?: string;
-}
-
-export interface StatusWriter {
-	/** Wait until all currently queued status writes have reached disk. */
-	flush(): Promise<void>;
-	/** Stop receiving store updates and cancel any pending flush. */
-	unsubscribe(): void;
-}
-
-// ---------------------------------------------------------------------------
-// Path resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the effective status file path.
- *
- * Priority:
- * 1. config.statusFilePath (explicit override)
- * 2. <projectRoot>/.atomic/workflows/status.json  (default)
- */
-export function resolveStatusFilePath(
-	config: Pick<WorkflowRuntimeConfig, "statusFilePath">,
-	opts: StatusWriterOpts = {},
-): string {
-	if (config.statusFilePath) return config.statusFilePath;
-	const root = opts.projectRoot ?? process.cwd();
-	return join(root, DEFAULT_STATUS_SUBPATH);
-}
-
-// ---------------------------------------------------------------------------
-// Atomic write
-// ---------------------------------------------------------------------------
-
-/**
- * Write `content` to `path` atomically using a sibling temp file + rename.
- * Creates parent directories as needed.
- */
-export async function atomicWriteJson(path: string, content: string): Promise<void> {
-	const dir = dirname(path);
-	await mkdir(dir, { recursive: true });
-	const tmpPath = `${path}.tmp`;
-	await writeFile(tmpPath, content, "utf8");
-	await rename(tmpPath, path);
-}
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-/**
- * Create a status writer that flushes StoreSnapshot to a JSON file on every
- * store update.
- *
- * Returns a no-op writer when config.statusFile is false.
- *
- * @example
- * ```ts
- * const writer = createStatusWriter(store, runtimeConfig, { projectRoot: process.cwd() });
- * // ... later on shutdown:
- * writer.unsubscribe();
- * ```
- */
-export function createStatusWriter(
-	store: Store,
-	config: WorkflowRuntimeConfig,
-	opts: StatusWriterOpts = {},
-): StatusWriter {
-	if (!config.statusFile) {
-		return { async flush() {}, unsubscribe() {} };
-	}
-
-	const filePath = resolveStatusFilePath(config, opts);
-
-	// Track last error message to deduplicate warning notices and avoid
-	// re-entrant infinite loops when writes keep failing.
-	let lastErrorMessage: string | null = null;
-
-	let active = true;
-	let writing = false;
-	let pendingContent: string | null = null;
-	let drainPromise: Promise<void> | null = null;
-
-	function recordWriteError(err: unknown): void {
-		const msg = err instanceof Error ? err.message : String(err);
-		// Deduplicate: only record one notice per distinct error message.
-		if (msg === lastErrorMessage) return;
-		lastErrorMessage = msg;
-		store.recordNotice({
-			id: `status-writer-error-${Date.now()}`,
-			level: "warning",
-			message: `atomic-workflows: status file write failed (${filePath}): ${msg}`,
-			createdAt: Date.now(),
-		});
-	}
-
-	async function drainWrites(): Promise<void> {
-		if (writing) return;
-		writing = true;
-		try {
-			while (active && pendingContent !== null) {
-				const content = pendingContent;
-				pendingContent = null;
-				try {
-					await atomicWriteJson(filePath, content);
-					// Clear error dedup on successful write.
-					lastErrorMessage = null;
-				} catch (err: unknown) {
-					recordWriteError(err);
-				}
-			}
-		} finally {
-			writing = false;
-		}
-	}
-
-	function ensureDrain(): Promise<void> {
-		drainPromise ??= drainWrites().finally(() => {
-			drainPromise = null;
-			if (active && pendingContent !== null) void ensureDrain();
-		});
-		return drainPromise;
-	}
-
-	const unsubscribeStore = store.subscribe((snap: StoreSnapshot) => {
-		pendingContent = JSON.stringify(snap, null, 2);
-		void ensureDrain();
-	});
-
-	return {
-		async flush() {
-			while (active && (pendingContent !== null || drainPromise !== null)) {
-				await ensureDrain();
-			}
-		},
-		unsubscribe() {
-			active = false;
-			pendingContent = null;
-			unsubscribeStore();
-		},
-	};
-}

package/dist/builtin/workflows/src/extension/ui-surface.ts

@@ -1,387 +0,0 @@
-import type { ChatMessageRenderOptions } from "@bastani/atomic";
-
-// ---------------------------------------------------------------------------
-// UI adapter — maps pi ctx.ui dialog surface to WorkflowUIAdapter
-// ---------------------------------------------------------------------------
-
-/**
- * Subset of pi's ExtensionUIDialogOptions consumed by the adapter.
- * Structurally matched against @bastani/atomic
- * ExtensionUIDialogOptions.
- */
-export interface PiUIDialogOptions {
-	/** AbortSignal to programmatically dismiss the dialog. */
-	signal?: AbortSignal;
-	/** Timeout in milliseconds. */
-	timeout?: number;
-}
-
-/**
- * Structural subset of pi-tui's `OverlayOptions` that this extension
- * consumes when mounting overlays via `ctx.ui.custom(factory, options)`.
- * Mirrors @earendil-works/pi-tui dist/tui.d.ts `OverlayOptions`.
- *
- * Only the fields actually forwarded by this extension are typed. Pi may
- * accept additional fields in the future; values pass through verbatim.
- */
-export interface PiOverlayOptions {
-	/** Overlay width — number = columns, "N%" = percent of terminal columns. */
-	width?: number | string;
-	/** Minimum overlay width in columns. */
-	minWidth?: number;
-	/** Overlay maximum height — number = rows, "N%" = percent of terminal rows. */
-	maxHeight?: number | string;
-	/** Anchor edge / corner. Pi-tui accepts named anchors like "center". */
-	anchor?: string;
-	/** Horizontal offset (columns) applied after anchor resolution. */
-	offsetX?: number;
-	/** Vertical offset (rows) applied after anchor resolution. */
-	offsetY?: number;
-	/** Explicit overlay top row (0-indexed) — overrides anchor vertical. */
-	row?: number;
-	/** Explicit overlay left column (0-indexed) — overrides anchor horizontal. */
-	col?: number;
-	/** Margin inset, scalar or per-edge object. */
-	margin?: number | { top?: number; right?: number; bottom?: number; left?: number };
-	/** Responsive visibility predicate. */
-	visible?: boolean | ((terminal: { rows: number; columns: number }) => boolean);
-	/** When `true`, overlay does not capture focus. */
-	nonCapturing?: boolean;
-}
-
-export interface PiCustomComponent {
-	render(width: number): string[];
-	/** Return true when input was consumed; false lets fullscreen viewport input fall through. */
-	handleInput?: (data: string) => boolean;
-	invalidate?: () => void;
-	dispose?: () => void;
-}
-
-/**
- * Handle exposed by pi's TUI for controlling a live overlay. Mirrors the
- * shape from @earendil-works/pi-tui `OverlayHandle` — `setHidden(true)`
- * temporarily hides the overlay (cheap to flip on/off, used for a
- * show/hide toggle), `hide()` permanently dismisses it.
- */
-export interface PiOverlayHandle {
-	hide(): void;
-	setHidden(hidden: boolean): void;
-	isHidden(): boolean;
-	focus(): void;
-	unfocus(): void;
-	isFocused(): boolean;
-}
-
-/**
- * Options accepted by Pi/pi's real `ctx.ui.custom(factory, options)`
- * overlay primitive. Aligned with the shape documented in
- * `@bastani/atomic docs/tui.md` and
- * `@earendil-works/pi-tui dist/tui.d.ts`.
- *
- * Host-compatibility note: pi's interactive
- * `ExtensionUiController.custom` hardcodes the overlay geometry when
- * `overlay: true` to `{ anchor: "bottom-center", width: "100%",
- * maxHeight: "100%", margin: 0 }`, and does NOT forward this object's
- * `overlayOptions` field. Consumers MUST NOT rely on `overlayOptions`
- * for actual placement in interactive pi mode — the field is
- * retained for forward-compatibility (future hosts and the test seam
- * may consume it).
- *
- * Workflow pickers (`session-overlays.ts`, `inputs-overlay.ts`) mount
- * with `overlay: false`, which causes the host to REPLACE the editor
- * with the picker inline at the editor's natural position — see
- * those files for rationale and `ui/workflows/Screenshot 2026-05-13
- * at 1.11.49 AM.png` for the target spacing.
- *
- * `onHandle` is honoured today only by the full-screen graph overlay
- * (`overlay-adapter.ts`); inline pickers leave it unset and dismiss
- * via the factory `done()` callback.
- */
-export interface PiHostCustomUiState {
-	blockingInlineCustomUiDepth: number;
-	blockingInlineCustomUiActive: boolean;
-	blockingInlineCustomUiFocusDeferred?: boolean;
-}
-
-export type PiHostCustomUiStateListener = (state: PiHostCustomUiState) => void;
-
-export interface PiCustomOverlayOptions {
-	/**
-	 * `true` mounts a floating popup; `false` mounts a focused
-	 * full-screen pi-tui pane that takes keyboard focus and renders in
-	 * place of the editor until the factory's `done()` callback fires.
-	 */
-	overlay: boolean;
-	/** Keep host inline custom UI pending in the background while this overlay is visible. */
-	deferInlineCustomUiFocus?: boolean;
-	/**
-	 * Declare that this component binds Ctrl+C itself, so the host forwards the
-	 * first press instead of closing the component. Required by every workflow
-	 * surface whose hint row offers `ctrl+c Skip`, `ctrl+c Close`, or cancel.
-	 */
-	handlesCtrlC?: boolean;
-	/** Declare that this component claims internal UI actions such as jump-to-bottom. */
-	handlesInternalUiAction?: boolean;
-	/**
-	 * Geometry / anchoring intended for pi-tui's `resolveOverlayLayout`.
-	 * NOT forwarded by current pi interactive `custom()` — see
-	 * the host-compatibility note above. Treat as advisory metadata
-	 * until the host wires it through.
-	 */
-	overlayOptions?: PiOverlayOptions;
-	/**
-	 * Optional callback invoked with the OverlayHandle once pi-tui
-	 * mounts the overlay. Use to drive show/hide toggles without
-	 * re-mounting. Only the full-screen graph overlay path consumes
-	 * this today; inline pickers leave it unset and dismiss via the
-	 * factory `done()` callback.
-	 */
-	onHandle?: (handle: PiOverlayHandle) => void;
-}
-
-/**
- * Surface of the Pi `TUI` instance exposed to overlay factories. The
- * `terminal` accessor is optional because some host implementations and test
- * mocks do not surface it; consumers must handle `undefined`. `mode` identifies
- * whether the host renderer already owns fullscreen terminal modes, so local
- * fallback controls do not disable that baseline.
- */
-export interface PiCustomOverlayFactoryTui {
-	readonly mode?: "regular" | "fullscreen";
-	requestRender?: () => void;
-	terminal?: {
-		rows?: number;
-		columns?: number;
-		setAutowrap?: (enabled: boolean) => void;
-	};
-	setFocus?: (target: unknown) => void;
-	start?: () => void;
-	stop?: () => void;
-	[key: string]: unknown;
-}
-
-export type PiTheme = unknown;
-export type PiKeybindings = unknown;
-
-export type PiCustomOverlayFactory<T = unknown> = (
-	tui: PiCustomOverlayFactoryTui,
-	theme: PiTheme,
-	keybindings: PiKeybindings,
-	done: (result: T) => void,
-) => PiCustomComponent | Promise<PiCustomComponent>;
-
-export type PiCustomOverlayFunction = (
-	factory: PiCustomOverlayFactory,
-	options: PiCustomOverlayOptions,
-) => Promise<unknown> | unknown;
-
-export interface PiHostInputFormField {
-	name: string;
-	type: "string" | "text" | "number" | "integer" | "boolean" | "select";
-	description?: string;
-	required?: boolean;
-	choices?: string[];
-	placeholder?: string;
-	initialValue: string;
-}
-
-export interface PiHostInputFormRequest {
-	title: string;
-	fields: PiHostInputFormField[];
-	/** Optional panel heading label rendered on the form border. */
-	heading?: string;
-	/** Optional submit button label. */
-	submitLabel?: string;
-}
-
-export type PiHostInputFormFunction = (request: PiHostInputFormRequest) => Promise<Record<string, string> | undefined>;
-
-/**
- * JSON-safe session-selector row for the host-native session picker
- * capability. Structural mirror of @bastani/atomic `HostSessionPickerRow` —
- * `SessionInfo` with `created`/`modified` flattened to epoch millis.
- */
-export interface PiHostSessionPickerRow {
-	path: string;
-	id: string;
-	cwd: string;
-	/** Creation time in epoch milliseconds. */
-	createdAt: number;
-	/** Last-modified time in epoch milliseconds. */
-	modifiedAt: number;
-	messageCount: number;
-	firstMessage: string;
-	/** Generated resume summary. Absent when never generated, or stale against the latest message. */
-	summary?: string;
-	allMessagesText?: string;
-	name?: string;
-	/** Optional semantic color for synthetic selector rows. */
-	messageColor?: "success" | "warning" | "accent" | "error";
-}
-
-/** Request accepted by the host-native session picker capability. */
-export interface PiHostSessionPickerRequest {
-	/** Rows shown in the first frame; push later rows via the handle's `update()`. */
-	sessions: PiHostSessionPickerRow[];
-	/** Show the rename keybinding hint in the picker header. Defaults to false. */
-	showRenameHint?: boolean;
-	/**
-	 * Invoked after the user confirms a Ctrl+D delete on a row. The host never
-	 * removes the row itself; reply with `update()` (row removed) or `error()`.
-	 */
-	onDelete?: (path: string) => void | Promise<void>;
-}
-
-/** Live control surface for an open host-native session picker. */
-export interface PiHostSessionPickerHandle {
-	/** Resolves with the selected row's `path`, or `undefined` on cancel/close. */
-	result: Promise<string | undefined>;
-	/** Replace the picker rows; host-side navigation/search state is preserved. */
-	update(sessions: PiHostSessionPickerRow[]): void;
-	/** Surface a transient error message in the picker header. */
-	error(message: string): void;
-	/** Close the picker; `result` resolves `undefined`. Idempotent. */
-	close(): void;
-}
-
-/**
- * Host-native session-list picker capability (`ctx.ui.hostSessionPicker`).
- * Every interactive Atomic host implements it with one identical API: the
- * terminal host mounts the real `SessionSelectorComponent` natively —
- * directly (no IPC) in non-isolated mode, over the engine session-picker
- * protocol channel in isolated mode — so picker navigation and search are
- * zero-IPC and only open/update/select/delete/cancel cross a process
- * boundary. Absent only on non-interactive surfaces (headless RPC, print)
- * and mismatched hosts; callers fail with an actionable error there rather
- * than degrade. The workflow resume picker REQUIRES this capability.
- */
-export type PiHostSessionPickerFunction = (request: PiHostSessionPickerRequest) => PiHostSessionPickerHandle;
-
-/**
- * Structural shape of pi's custom editor component. Interactive mode
- * currently installs extension editors through `InteractiveMode.setEditorComponent`,
- * which expects the richer `CustomEditor` surface and configures these methods
- * before mounting. Keep the extra methods optional for lightweight tests and
- * non-interactive shims, but real custom editors should implement them.
- *
- * The resize-handler contract (`setTopBorder` / `getTopBorderAvailableWidth`)
- * is invoked unconditionally by `InteractiveMode`'s `process.stdout` "resize"
- * listener — any custom editor mounted via `setEditorComponent` MUST provide
- * them or the host throws `TypeError` on the first terminal resize.
- */
-export interface PiEditorComponent {
-	focused?: boolean;
-	getText(): string;
-	setText(text: string): void;
-	handleInput(data: string): void;
-	render(width: number): string[];
-	invalidate?(): void;
-	dispose?(): void;
-	onSubmit?: (text: string) => void | Promise<void>;
-	onChange?: (text: string) => void;
-	onAutocompleteCancel?: () => void;
-	onAutocompleteUpdate?: () => void;
-	setUseTerminalCursor?(useTerminalCursor: boolean): void;
-	getUseTerminalCursor?(): boolean;
-	setAutocompleteMaxVisible?(maxVisible: number): void;
-	getAutocompleteMaxVisible?(): number;
-	setMaxHeight?(maxHeight: number | undefined): void;
-	setHistoryStorage?(storage: object): void;
-	setActionKeys?(action: string, keys: readonly string[]): void;
-	setCustomKeyHandler?(key: string, handler: () => void): void;
-	removeCustomKeyHandler?(key: string): void;
-	clearCustomKeyHandlers?(): void;
-	setAutocompleteProvider?(provider: object): void;
-	addToHistory?(text: string): void;
-	insertTextAtCursor?(text: string): void;
-	getExpandedText?(): string;
-	setPaddingX?(padding: number): void;
-	setTopBorder?(content: unknown): void;
-	getTopBorderAvailableWidth?(terminalWidth: number): number;
-}
-
-export type PiEditorFactory = (
-	tui: { requestRender?: () => void },
-	theme: unknown,
-	keybindings: unknown,
-) => PiEditorComponent;
-
-/**
- * Structural type for the pi UI dialog surface.
- * Matches @bastani/atomic ExtensionUIContext dialog methods.
- * All fields optional — presence is checked at runtime before building adapter.
- */
-export interface PiUISurface {
-	/** Show a text input dialog. Returns undefined when user dismisses. */
-	input?: (title: string, placeholder?: string, opts?: PiUIDialogOptions) => Promise<string | undefined>;
-	/** Show a confirmation dialog. */
-	confirm?: (title: string, message: string, opts?: PiUIDialogOptions) => Promise<boolean>;
-	/** Show a selector and return the user's choice. Returns undefined when user dismisses. */
-	select?: (title: string, options: string[], opts?: PiUIDialogOptions) => Promise<string | undefined>;
-	/** Show a multi-line editor. Returns undefined when user dismisses. */
-	editor?: (title: string, prefill?: string) => Promise<string | undefined>;
-	notify?: (message: string, type?: "info" | "warning" | "error") => void;
-	onTerminalInput?: (handler: unknown) => () => void;
-	setStatus?: (key: string, text: string | undefined) => void;
-	setWorkingMessage?: (message?: string) => void;
-	setWorkingVisible?: (visible: boolean) => void;
-	setWorkingIndicator?: (options?: unknown) => void;
-	setHiddenThinkingLabel?: (label?: string) => void;
-	/** Set a live widget above or below the editor. */
-	setWidget?: (
-		key: string,
-		factory:
-			| string[]
-			| ((tui: unknown, theme: unknown) => { render(width: number): string[]; dispose?(): void })
-			| undefined,
-		opts?: { placement?: string },
-	) => void;
-	setFooter?: (factory: unknown) => void;
-	setHeader?: (factory: unknown) => void;
-	setTitle?: (title: string) => void;
-	/** Show a custom component or overlay. */
-	custom?: PiCustomOverlayFunction;
-	/** Host-native session-list picker (all interactive hosts; absent headless). */
-	hostSessionPicker?: PiHostSessionPickerFunction;
-	/** Host-native inline input form (all current interactive Atomic hosts). */
-	hostInputForm?: PiHostInputFormFunction;
-	/** Get host-owned inline custom UI focus state, if exposed by the host. */
-	getHostCustomUiState?: () => PiHostCustomUiState;
-	/** Observe host-owned inline custom UI focus state changes, if exposed by the host. */
-	onHostCustomUiStateChange?: (listener: PiHostCustomUiStateListener) => () => void;
-	/** Move focus to a mounted host-owned inline custom UI, if one is pending. */
-	focusHostInlineCustomUi?: () => boolean;
-	pasteToEditor?: (text: string) => void;
-	setEditorText?: (text: string) => void;
-	getEditorText?: () => string;
-	addAutocompleteProvider?: (factory: unknown) => void;
-	/**
-	 * Install a custom editor (replaces the bottom input bar) until cleared
-	 * with `setEditorComponent(undefined)`. Used by the inline workflow
-	 * input form to capture per-field keystrokes.
-	 * cross-ref: docs/extensions.md §Custom Editor (pi-coding-agent).
-	 */
-	setEditorComponent?: (factory: PiEditorFactory | undefined) => void;
-	/** Return the currently-installed editor factory, or undefined for the default. */
-	getEditorComponent?: () => PiEditorFactory | undefined;
-	/** Current resolved Pi theme and theme helpers, forwarded to stage extensions. */
-	theme?: unknown;
-	getAllThemes?: () => Array<{ name: string; path: string | undefined }>;
-	getTheme?: (name: string) => unknown;
-	setTheme?: (theme: string | unknown) => { success: boolean; error?: string };
-	getToolsExpanded?: () => boolean;
-	setToolsExpanded?: (expanded: boolean) => void;
-	getChatRenderSettings?: () => Partial<Omit<ChatMessageRenderOptions, "ui" | "cwd">> | undefined;
-}
-
-/**
- * Runtime surface that includes the optional UI dialog surface.
- * Used by command/overlay code (graph mounts and picker overlays) to interact with `pi.ui.custom`, `pi.ui.confirm`,
- * etc. Workflow-level HIL routing — `ctx.ui.input/confirm/select/editor`
- * inside a workflow body — stays in the store-backed background adapter.
- * In-stage `ask_user_question` uses this surface to bind the live pi UI into
- * SDK stage sessions.
- */
-export interface UIWiringSurface {
-	ui?: PiUISurface;
-}