@bastani/atomic 0.7.17 → 0.8.0

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

@@ -0,0 +1,326 @@
+/**
+ * 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 type {
+  ExtensionAPI,
+  PiCommandContext,
+} from "../extension/index.js";
+import type {
+  PiEditorComponent,
+  PiEditorFactory,
+} from "../extension/wiring.js";
+import type { WorkflowInputEntry } from "../extension/render-result.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: Record<string, unknown> }
+  | { kind: "cancel" }
+  | { kind: "unsupported" };
+
+export interface OpenInlineFormOpts {
+  workflowName: string;
+  description?: string;
+  fields: readonly WorkflowInputEntry[];
+  prefilled?: Record<string, unknown>;
+  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) => string | CardComponent | 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) {
+      // Process restart / map evicted — tombstone the entry.
+      return `▎ ${message.content ?? "workflow form"}  ·  (snapshot lost)`;
+    }
+    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 */
+      },
+    };
+  };
+
+  // The project's local `ExtensionAPI` types `registerMessageRenderer` as
+  // returning a plain string. The real pi runtime also accepts a Component
+  // (see docs/extensions.md §Custom UI). Cast through `unknown` so the call
+  // typechecks against both shapes. Call through `pi` so pi's
+  // class-backed ExtensionAPI keeps its `this` binding.
+  (register as unknown as (event: string, r: RawRenderer) => void).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,
+    description: opts.description,
+    fields: opts.fields,
+    rawText,
+    focusedIdx,
+    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 (
+          err instanceof Error &&
+          err.message.includes("This extension ctx is stale")
+        ) {
+          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;
+        },
+      ) => void).call(pi, {
+        customType: CUSTOM_TYPE,
+        content: opts.workflowName,
+        display: true,
+        details: { formId },
+      });
+    } 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

@@ -0,0 +1,78 @@
+/**
+ * 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 forever (module-lifetime). The
+ * renderer reads it to display the historical card. If the process restarts,
+ * the map is empty and the renderer falls back to a "form (snapshot lost)"
+ * placeholder — acceptable because frozen cards are decorative, not
+ * functional.
+ *
+ * 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;
+  description?: string;
+  fields: readonly WorkflowInputEntry[];
+  /** Raw string per field; mirrors `inputs-picker.ts` semantics. */
+  rawText: Record<string, string>;
+  focusedIdx: 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);
+}
+
+/** Test helper — clear the registry between tests. */
+export function _resetForms(): void {
+  FORMS.clear();
+}

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

@@ -0,0 +1,163 @@
+/**
+ * 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 `{ overlay: false }`. pi's interactive
+ * `ExtensionUiController.custom` REPLACES the editor with the mounted
+ * component (`editorContainer.clear(); addChild(component)`), so the
+ * picker renders **inline** at the editor's natural position in the
+ * chat layout. This avoids the bottom-anchored overlay regression
+ * captured in `ui/workflows/Screenshot 2026-05-13 at 1.09.32 AM.png`
+ * (host `Working…` / widget rows wedged between command and picker)
+ * without any overlay 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 {
+  PiCustomComponent,
+  PiCustomOverlayFactoryTui,
+  PiCustomOverlayFunction,
+} from "../extension/wiring.js";
+import type { WorkflowInputEntry } from "../extension/render-result.js";
+import type { GraphTheme } from "./graph-theme.js";
+import {
+  coerceValues,
+  createInputsPickerState,
+  handleInputsPickerInput,
+  renderInputsPicker,
+} from "./inputs-picker.js";
+
+export interface InputsUiSurface {
+  custom?: PiCustomOverlayFunction;
+}
+
+export type InputsPickerResult =
+  | { kind: "run"; values: Record<string, unknown> }
+  | { kind: "cancel" };
+
+export interface OpenInputsPickerOpts {
+  workflowName: string;
+  description?: 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?: Record<string, unknown>;
+  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 as an overlay, 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, description, fields, prefilled, theme } = opts;
+    const custom = ui.custom;
+    if (typeof custom !== "function") {
+      resolve({ kind: "cancel" });
+      return;
+    }
+    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;
+    }
+
+    const state = createInputsPickerState(fields, prefilled);
+    let settled = false;
+    let cursorOn = true;
+    let cursorTimer: ReturnType<typeof setInterval> | null = null;
+
+    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;
+        done(undefined);
+        resolve(result);
+      };
+
+      return {
+        render: (width: number) =>
+          renderInputsPicker({
+            width,
+            theme,
+            workflowName,
+            description,
+            fields,
+            state,
+            cursorOn,
+          }),
+        handleInput: (data: string) => {
+          // 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
+          // fallback overlay as in the inline form. Pass it through
+          // structurally; the picker guards the shape itself.
+          const kb = keys as Parameters<typeof handleInputsPickerInput>[3];
+          const action = handleInputsPickerInput(data, state, fields, kb);
+          if (action.kind === "noop") {
+            tui.requestRender?.();
+            return;
+          }
+          finish(action);
+        },
+        invalidate: () => tui.requestRender?.(),
+        dispose: () => {
+          if (cursorTimer) clearInterval(cursorTimer);
+          cursorTimer = null;
+          if (!settled) {
+            settled = true;
+            resolve({ 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.
+    void custom(factory, { overlay: false });
+  });
+}