pi-one-ui 0.1.1 → 0.2.0

package/extensions/app/config/store.ts

@@ -0,0 +1,290 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  fchmodSync,
+  fsyncSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type ConfigRecord = Record<string, unknown>;
+
+export type ConfigStorePaths = {
+  canonical: string;
+  legacyUnified: string;
+  legacyShell: string;
+  legacyRenderer: string;
+};
+
+/**
+ * Returns canonical and legacy configuration locations for an agent directory.
+ */
+export function configPaths(agentDir = getAgentDir()): ConfigStorePaths {
+  return {
+    canonical: join(agentDir, "pi-one-ui.json"),
+    legacyUnified: join(agentDir, "pi-mine-ui.json"),
+    legacyShell: join(agentDir, "zentui.json"),
+    legacyRenderer: join(agentDir, "claude-code-style.json"),
+  };
+}
+
+export const defaultConfigPaths = configPaths();
+export const configPath = defaultConfigPaths.canonical;
+
+export type ConfigFileState =
+  | { kind: "missing"; record: ConfigRecord; writePath: string }
+  | { kind: "valid"; record: ConfigRecord; writePath: string; mode: number }
+  | { kind: "corrupt"; error: unknown };
+
+/**
+ * Extracts a Node filesystem error code without depending on an error class.
+ */
+function errorCode(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error
+    ? String(error.code)
+    : undefined;
+}
+
+/**
+ * Reads one config file, resolving symlink targets without replacing the link.
+ */
+export function readConfigFileState(path: string): ConfigFileState {
+  let writePath = path;
+  try {
+    const pathStat = lstatSync(path);
+    if (pathStat.isSymbolicLink()) writePath = realpathSync(path);
+    const targetStat = statSync(writePath);
+    const parsed = JSON.parse(readFileSync(writePath, "utf8"));
+    return parsed !== null &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed)
+      ? {
+          kind: "valid",
+          record: parsed as ConfigRecord,
+          writePath,
+          mode: targetStat.mode & 0o7777,
+        }
+      : {
+          kind: "corrupt",
+          error: new Error("top-level value must be a JSON object"),
+        };
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      try {
+        lstatSync(path);
+      } catch (pathError) {
+        if (errorCode(pathError) === "ENOENT")
+          return { kind: "missing", record: {}, writePath: path };
+      }
+    }
+    return { kind: "corrupt", error };
+  }
+}
+
+/**
+ * Writes JSON through a temporary file and atomic rename.
+ */
+export function writeConfigAtomically(
+  path: string,
+  record: ConfigRecord,
+  mode?: number,
+): void {
+  const tempPath = join(
+    dirname(path),
+    `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  let file: number | undefined;
+  try {
+    file = openSync(tempPath, "wx", mode ?? 0o666);
+    if (mode !== undefined) fchmodSync(file, mode);
+    writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    fsyncSync(file);
+    closeSync(file);
+    file = undefined;
+    renameSync(tempPath, path);
+  } catch (error) {
+    if (file !== undefined) {
+      try {
+        closeSync(file);
+      } catch {}
+    }
+    try {
+      unlinkSync(tempPath);
+    } catch (cleanupError) {
+      if (errorCode(cleanupError) !== "ENOENT") {
+        // Preserve the persistence failure; the best-effort cleanup error is secondary.
+      }
+    }
+    throw error;
+  }
+}
+
+/**
+ * Builds a stable read error while preserving the underlying failure detail.
+ */
+function configReadError(path: string, error: unknown): Error {
+  const detail = error instanceof Error ? ` (${error.message})` : "";
+  return new Error(
+    `Unable to read pi-one-ui config because ${path} is corrupt or unreadable${detail}`,
+  );
+}
+
+/**
+ * Builds the compatibility error used when a config write is unsafe.
+ */
+function configWriteError(path: string, label: string, error: unknown): Error {
+  const detail = error instanceof Error ? ` (${error.message})` : "";
+  return new Error(
+    `Refusing to save ${label} config because ${path} is corrupt or unreadable; fix or remove it first.${detail}`,
+  );
+}
+
+type SelectedConfig = {
+  record: ConfigRecord;
+  writePath: string;
+  mode?: number;
+  materialize: boolean;
+};
+
+/**
+ * Reads an optional config source and turns corruption into an explicit error.
+ */
+function optionalConfig(
+  path: string,
+): { record: ConfigRecord; writePath: string; mode: number } | undefined {
+  const state = readConfigFileState(path);
+  if (state.kind === "missing") return undefined;
+  if (state.kind === "corrupt") throw configReadError(path, state.error);
+  return state;
+}
+
+/**
+ * Selects the active source and the destination used by a later update.
+ */
+function selectUnifiedConfig(paths: ConfigStorePaths): SelectedConfig {
+  const canonical = optionalConfig(paths.canonical);
+  if (canonical) return { ...canonical, materialize: false };
+
+  const legacyUnified = optionalConfig(paths.legacyUnified);
+  if (legacyUnified)
+    return {
+      ...legacyUnified,
+      writePath: paths.canonical,
+      materialize: true,
+    };
+
+  const shell = optionalConfig(paths.legacyShell);
+  const renderer = optionalConfig(paths.legacyRenderer);
+  if (!shell && !renderer) {
+    return {
+      record: {},
+      writePath: paths.canonical,
+      materialize: false,
+    };
+  }
+
+  return {
+    record: {
+      ...(shell?.record ?? {}),
+      version: 1,
+      renderer: renderer?.record ?? {},
+    },
+    writePath: paths.canonical,
+    mode: shell?.mode ?? renderer?.mode,
+    materialize: true,
+  };
+}
+
+/**
+ * Read the one raw unified record used by all configuration domains.
+ * Legacy sources are best-effort materialized through the same atomic writer;
+ * the in-memory record remains usable if the agent directory is read-only.
+ */
+export function readUnifiedConfigRecord(
+  paths: ConfigStorePaths = defaultConfigPaths,
+): ConfigRecord {
+  const selected = selectUnifiedConfig(paths);
+  if (selected.materialize) {
+    try {
+      writeConfigAtomically(selected.writePath, selected.record, selected.mode);
+    } catch {
+      // Keep using the selected legacy record in memory when migration cannot be written.
+    }
+  }
+  return selected.record;
+}
+
+/**
+ * Mutates one explicitly selected file while preserving its safety semantics.
+ */
+export function mutateConfigFile(
+  path: string,
+  mutate: (record: ConfigRecord) => void,
+  label = "pi-one-ui",
+): ConfigRecord {
+  const state = readConfigFileState(path);
+  if (state.kind === "corrupt")
+    throw configWriteError(path, label, state.error);
+
+  mutate(state.record);
+  writeConfigAtomically(
+    state.writePath,
+    state.record,
+    state.kind === "valid" ? state.mode : undefined,
+  );
+  return state.record;
+}
+
+export type ConfigStoreListener = (record: ConfigRecord) => void;
+
+/**
+ * Process-wide raw configuration store. Domain config modules own parsing and
+ * selectors; this module owns source selection, migration and persistence.
+ */
+export class ConfigStore {
+  readonly paths: ConfigStorePaths;
+  private readonly listeners = new Set<ConfigStoreListener>();
+
+  /**
+   * Creates a store for canonical and legacy paths.
+   */
+  constructor(paths: ConfigStorePaths = defaultConfigPaths) {
+    this.paths = paths;
+  }
+
+  /**
+   * Reads the current canonical or legacy-backed raw configuration record.
+   */
+  read(): ConfigRecord {
+    return readUnifiedConfigRecord(this.paths);
+  }
+
+  /**
+   * Mutates and atomically persists the active raw configuration record.
+   */
+  update(mutate: (record: ConfigRecord) => void): ConfigRecord {
+    const selected = selectUnifiedConfig(this.paths);
+    mutate(selected.record);
+    writeConfigAtomically(selected.writePath, selected.record, selected.mode);
+    for (const listener of this.listeners) listener(selected.record);
+    return selected.record;
+  }
+
+  /**
+   * Subscribes to successful updates and returns an idempotent unsubscribe function.
+   */
+  subscribe(listener: ConfigStoreListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+}
+
+export const configStore = new ConfigStore();

package/extensions/app/host/pi-extension-port.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type PiExtensionPort = Pick<
+  ExtensionAPI,
+  | "appendEntry"
+  | "on"
+  | "registerCommand"
+  | "registerEntryRenderer"
+  | "registerMarkdownTransformer"
+  | "registerMessageRenderer"
+>;
+
+/**
+ * Binds the host extension API once so modules do not pass the raw object around.
+ */
+export function createPiExtensionPort(pi: ExtensionAPI): PiExtensionPort {
+  return {
+    appendEntry: pi.appendEntry.bind(pi),
+    on: pi.on.bind(pi) as PiExtensionPort["on"],
+    registerCommand: pi.registerCommand.bind(pi),
+    registerEntryRenderer: pi.registerEntryRenderer.bind(pi),
+    registerMarkdownTransformer: pi.registerMarkdownTransformer.bind(pi),
+    registerMessageRenderer: pi.registerMessageRenderer.bind(pi),
+  };
+}

package/extensions/app/host/pi-ui-port.ts

@@ -0,0 +1,52 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type PiUi = ExtensionContext["ui"];
+
+export type PiUiPort = Pick<
+  PiUi,
+  | "custom"
+  | "getEditorComponent"
+  | "getToolsExpanded"
+  | "notify"
+  | "onTerminalInput"
+  | "setEditorComponent"
+  | "setFooter"
+  | "setHeader"
+  | "setStatus"
+  | "setToolsExpanded"
+  | "setWidget"
+  | "setWorkingIndicator"
+  | "setWorkingMessage"
+  | "setWorkingVisible"
+> & {
+  readonly theme: PiUi["theme"];
+  requestRender(force?: boolean): void;
+};
+
+/**
+ * Adapts a session UI context to the narrow port consumed by layouts.
+ */
+export function createPiUiPort(
+  ctx: ExtensionContext,
+  requestRender: (force?: boolean) => void = () => {},
+): PiUiPort {
+  const ui = ctx.ui;
+  return {
+    custom: (...args) => ui.custom(...args),
+    getEditorComponent: () => ui.getEditorComponent(),
+    getToolsExpanded: () => ui.getToolsExpanded(),
+    notify: (...args) => ui.notify(...args),
+    onTerminalInput: (handler) => ui.onTerminalInput(handler),
+    setEditorComponent: (factory) => ui.setEditorComponent(factory),
+    setFooter: (factory) => ui.setFooter(factory),
+    setHeader: (factory) => ui.setHeader(factory),
+    setStatus: (key, text) => ui.setStatus(key, text),
+    setToolsExpanded: (expanded) => ui.setToolsExpanded(expanded),
+    setWidget: ui.setWidget.bind(ui) as PiUiPort["setWidget"],
+    setWorkingIndicator: (options) => ui.setWorkingIndicator(options),
+    setWorkingMessage: (message) => ui.setWorkingMessage(message),
+    setWorkingVisible: (visible) => ui.setWorkingVisible(visible),
+    theme: ui.theme,
+    requestRender,
+  };
+}

package/extensions/app/host/tui-capabilities.ts

@@ -0,0 +1,27 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type TuiCapabilities = Readonly<{
+  interactive: boolean;
+  customUi: boolean;
+  editorFactory: boolean;
+  footer: boolean;
+  header: boolean;
+  workingIndicator: boolean;
+  overlays: boolean;
+}>;
+
+/**
+ * Detects which interactive UI seams are available in the current host context.
+ */
+export function detectTuiCapabilities(ctx: ExtensionContext): TuiCapabilities {
+  const ui = ctx.ui as Partial<ExtensionContext["ui"]>;
+  return {
+    interactive: ctx.mode === "tui" && ctx.hasUI,
+    customUi: typeof ui.custom === "function",
+    editorFactory: typeof ui.setEditorComponent === "function",
+    footer: typeof ui.setFooter === "function",
+    header: typeof ui.setHeader === "function",
+    workingIndicator: typeof ui.setWorkingIndicator === "function",
+    overlays: typeof ui.custom === "function",
+  };
+}

package/extensions/app/overlay/input-router.ts

@@ -0,0 +1,63 @@
+export type InputRouteResult = { consume?: boolean; data?: string } | undefined;
+export type InputRoute = (data: string) => InputRouteResult;
+
+type RegisteredRoute = {
+  priority: number;
+  order: number;
+  route: InputRoute;
+};
+
+/**
+ * Routes raw terminal input by descending priority and stops at a consumer.
+ */
+export class InputRouter {
+  private nextOrder = 0;
+  private readonly routes: RegisteredRoute[] = [];
+
+  /**
+   * Registers an input route.
+   *
+   * @param route Handler that may consume one input packet.
+   * @param priority Higher-priority routes receive input first.
+   * @returns A function that removes the route.
+   */
+  register(route: InputRoute, priority = 0): () => void {
+    const entry: RegisteredRoute = {
+      priority,
+      order: this.nextOrder++,
+      route,
+    };
+    this.routes.push(entry);
+    this.routes.sort(
+      (left, right) =>
+        right.priority - left.priority || left.order - right.order,
+    );
+    return () => {
+      const index = this.routes.indexOf(entry);
+      if (index >= 0) this.routes.splice(index, 1);
+    };
+  }
+
+  /**
+   * Routes one input packet until a registered handler consumes it.
+   *
+   * @param data Raw terminal input packet.
+   * @returns The consuming route result, if any.
+   */
+  dispatch(data: string): InputRouteResult {
+    for (const entry of [...this.routes]) {
+      const result = entry.route(data);
+      if (result?.consume) return result;
+    }
+    return undefined;
+  }
+
+  /**
+   * Removes all registered routes, normally during runtime teardown.
+   */
+  clear(): void {
+    this.routes.length = 0;
+  }
+}
+
+export const inputRouter = new InputRouter();

package/extensions/app/overlay/overlay-manager.ts

@@ -0,0 +1,39 @@
+export type OverlayTask<T> = () => Promise<T>;
+
+/**
+ * Tracks plugin-owned overlay activity across settings and context dialogs.
+ */
+export class OverlayManager {
+  private activeCount = 0;
+
+  /**
+   * Runs one asynchronous overlay task and balances its active count.
+   *
+   * @param task Function that opens and waits for the overlay.
+   * @returns The value produced when the overlay closes.
+   */
+  async run<T>(task: OverlayTask<T>): Promise<T> {
+    this.activeCount += 1;
+    try {
+      return await task();
+    } finally {
+      this.activeCount = Math.max(0, this.activeCount - 1);
+    }
+  }
+
+  /**
+   * Reports whether at least one plugin-owned overlay is active.
+   */
+  hasActive(): boolean {
+    return this.activeCount > 0;
+  }
+
+  /**
+   * Returns the current plugin-owned overlay depth.
+   */
+  depth(): number {
+    return this.activeCount;
+  }
+}
+
+export const overlayManager = new OverlayManager();

package/extensions/{shell → app/overlay}/selector-border.ts

@@ -3,16 +3,16 @@ import {
   SettingsSelectorComponent,
   type Theme,
 } from "@earendil-works/pi-coding-agent";
-import type { ZentuiConfig } from "../app/config/shell.ts";
+import type { ZentuiConfig } from "../config/shell.ts";
 import {
   installPrototypePatch,
   removePrototypePatch,
-} from "./prototype-patch-registry.ts";
+} from "../ownership/prototype-patch-registry.ts";
 import {
   EDITOR_BORDER_STYLE,
   renderChromeBorder,
   renderEditorBorder,
-} from "./style.ts";
+} from "../../shared/style.ts";
 
 type PatchableSelectorPrototype = {
   render: (width: number) => string[];

package/extensions/app/overlay/selector-controller.ts

@@ -0,0 +1,104 @@
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  hasUnsupportedComponentStyle,
+  type PolishedTuiConfig,
+} from "../config/shell.ts";
+import { installSelectorBorderStyle } from "./selector-border.ts";
+
+/**
+ * Provides the shared configuration and host state consumed by selector styling.
+ */
+export type SelectorControllerContext = {
+  readonly getConfig: () => PolishedTuiConfig;
+};
+
+/**
+ * Owns selector border patch installation and restoration for the Overlay layer.
+ */
+export class SelectorController {
+  private readonly context: SelectorControllerContext;
+  private activeTheme: Theme | undefined;
+  private cleanupPatch: () => void = () => {};
+  private installed = false;
+
+  /**
+   * Creates a selector controller backed by the canonical configuration.
+   *
+   * @param context Configuration selector used by the patch.
+   */
+  constructor(context: SelectorControllerContext) {
+    this.context = context;
+  }
+
+  /**
+   * Starts selector ownership for an interactive TUI session.
+   *
+   * @param ctx Active Pi extension context.
+   */
+  startSession(ctx: ExtensionContext): void {
+    if (!this.isTuiContext(ctx)) return;
+    this.activeTheme = ctx.ui.theme;
+    this.reconcile();
+  }
+
+  /**
+   * Reconciles selector border ownership with the latest configuration.
+   */
+  reconcile(): void {
+    const config = this.context.getConfig();
+    const enabled =
+      config.components.selectorBorders.enabled &&
+      config.components.selectorBorders.style === "zentui" &&
+      !hasUnsupportedComponentStyle(config, "selectorBorders");
+    if (enabled) this.install();
+    else this.uninstall();
+  }
+
+  /**
+   * Restores selector prototypes and clears session-local state.
+   */
+  cleanup(): void {
+    this.uninstall();
+    this.activeTheme = undefined;
+  }
+
+  /**
+   * Installs the selector prototype patch once.
+   */
+  private install(): void {
+    if (this.installed || !this.activeTheme) return;
+    try {
+      this.cleanupPatch = installSelectorBorderStyle(
+        () => this.activeTheme,
+        this.context.getConfig,
+      );
+      this.installed = true;
+    } catch {
+      this.cleanupPatch = () => {};
+      this.installed = false;
+    }
+  }
+
+  /**
+   * Removes the selector prototype patch when owned by this controller.
+   */
+  private uninstall(): void {
+    try {
+      this.cleanupPatch();
+    } finally {
+      this.cleanupPatch = () => {};
+      this.installed = false;
+    }
+  }
+
+  /**
+   * Reports whether a context exposes an interactive TUI.
+   *
+   * @param ctx Candidate Pi extension context.
+   * @returns Whether selector styling may be installed.
+   */
+  private isTuiContext(ctx: ExtensionContext): boolean {
+    const mode = (ctx as ExtensionContext & { mode?: string }).mode;
+    return ctx.hasUI && (mode === undefined || mode === "tui");
+  }
+}

package/extensions/app/ownership/layout-registry.ts

@@ -0,0 +1,65 @@
+export const LAYOUT_OWNERSHIP = {
+  header: "header",
+  context: "context",
+  workingLine: "working-line",
+  editor: "editor",
+  footer: "footer",
+  overlay: "overlay",
+  input: "overlay",
+} as const;
+
+export type LayoutId = keyof typeof LAYOUT_OWNERSHIP;
+export type LayoutOwner = (typeof LAYOUT_OWNERSHIP)[LayoutId];
+
+type Claim = {
+  owner: LayoutOwner;
+  token: object;
+};
+
+/**
+ * Tracks ownership of host UI seams. A layout can be claimed once and its
+ * release callback is safe to call repeatedly or after another owner wins.
+ */
+export class LayoutRegistry {
+  private readonly claims = new Map<LayoutId, Claim>();
+
+  /**
+   * Claims one layout for a runtime token.
+   *
+   * @returns A release function that only removes this token's claim.
+   */
+  claim(layout: LayoutId, token: object): () => void {
+    const owner = LAYOUT_OWNERSHIP[layout];
+    const current = this.claims.get(layout);
+    if (current && current.token !== token) {
+      throw new Error(
+        `UI layout ${layout} is already owned by ${current.owner}`,
+      );
+    }
+    this.claims.set(layout, { owner, token });
+    return () => {
+      if (this.claims.get(layout)?.token === token) this.claims.delete(layout);
+    };
+  }
+
+  /**
+   * Returns the canonical owner assigned to a claimed layout.
+   */
+  ownerOf(layout: LayoutId): LayoutOwner | undefined {
+    return this.claims.get(layout)?.owner;
+  }
+
+  /**
+   * Reports whether a runtime token currently claims the layout.
+   */
+  isClaimed(layout: LayoutId): boolean {
+    return this.claims.has(layout);
+  }
+
+  /**
+   * Releases all claims, normally during runtime disposal.
+   */
+  clear(): void {
+    this.claims.clear();
+  }
+}