@kontextmind/kxm 0.7.40 → 0.7.44

package/packages/core/tui/src/adapters/pi.ts

@@ -0,0 +1,73 @@
+/**
+ * Pi TUI adapter.
+ *
+ * A Pi extension opens a surface with `ctx.ui.custom((tui, theme, keybindings,
+ * done) => component)`. This binds the kit's panel to that shape: the host's
+ * theme supplies colours, the host's renderer is asked to repaint after every
+ * key, and closing the panel hands back the owner's last published value.
+ *
+ * Nothing here knows what a roster, a route, or a gate is. The registry does,
+ * which is why the same adapter serves every KXM surface.
+ */
+
+import { KxmTuiPanelComponent } from "../tui/panelComponent.ts";
+import type { KxmTuiRegistry } from "../services/registry.ts";
+import { createKxmTuiThemeFromPi, type PiThemeLike } from "../tui/theme.ts";
+
+/** The renderer handle Pi passes to a custom component. */
+export interface KxmTuiCustomTui {
+  requestRender(): void;
+}
+
+/** The component shape Pi's `ctx.ui.custom` consumes. */
+export interface KxmTuiCustomComponent {
+  render(width: number): string[];
+  handleInput(data: string): void;
+  invalidate(): void;
+}
+
+export interface KxmTuiPiPanelOptions {
+  readonly registry: KxmTuiRegistry;
+  readonly tui: KxmTuiCustomTui;
+  readonly theme: PiThemeLike;
+  readonly title: string;
+  readonly breadcrumb?: string;
+  readonly helpLines?: readonly string[];
+  readonly width?: () => number;
+  /** Called once when the operator leaves the panel. */
+  readonly done?: (closed: true) => void;
+}
+
+/**
+ * Build the object to return from `ctx.ui.custom`.
+ *
+ * The panel is disposed on close, so a reopened surface must be built again
+ * rather than reused: Pi drops a custom component when it is closed.
+ */
+export function createKxmTuiPiPanel(options: KxmTuiPiPanelOptions): KxmTuiCustomComponent {
+  let closed = false;
+  const panel = new KxmTuiPanelComponent({
+    registry: options.registry,
+    theme: createKxmTuiThemeFromPi(options.theme),
+    title: options.title,
+    ...(options.breadcrumb === undefined ? {} : { breadcrumb: options.breadcrumb }),
+    ...(options.helpLines === undefined ? {} : { helpLines: options.helpLines }),
+    requestRender: () => options.tui.requestRender(),
+    onQuit: () => {
+      if (closed) return;
+      closed = true;
+      panel.dispose();
+      options.done?.(true);
+    },
+    ...(options.width === undefined ? {} : { getWidth: options.width }),
+  });
+  return {
+    render: (width) => panel.render(width),
+    handleInput: (data) => {
+      if (closed) return;
+      panel.handleInput(data);
+      options.tui.requestRender();
+    },
+    invalidate: () => panel.invalidate(),
+  };
+}

package/packages/core/tui/src/adapters/terminal.ts

@@ -0,0 +1,106 @@
+/**
+ * Standalone driver for a KXM panel surface.
+ *
+ * `kxm dash` already owns its hub and SSE loop, so the kit does not duplicate
+ * it. This is the small alternative for a local, file-backed surface — a config
+ * or roster panel that repaints when an owner republishes and stops when the
+ * operator leaves.
+ *
+ * A non-TTY caller gets one plain-text frame and exit code zero, which keeps
+ * `--dry-run`, CI smoke, and piped output honest instead of pretending to be an
+ * interactive session.
+ */
+
+import { ProcessTerminal, TuiAltScreen, stripTerminalSequences, type Terminal } from "@earendil-works/pi-tui";
+import { KxmTuiPanelComponent } from "../tui/panelComponent.ts";
+import { initialKxmTuiPanelState } from "../tui/panel.ts";
+import { renderKxmTuiPanel } from "../tui/render.ts";
+import type { KxmTuiRegistry } from "../services/registry.ts";
+import { createDefaultKxmTuiTheme, createPlainKxmTuiTheme, type KxmTuiTheme } from "../tui/theme.ts";
+
+export interface RunKxmTuiPanelInput {
+  readonly registry: KxmTuiRegistry;
+  readonly title: string;
+  readonly breadcrumb?: string;
+  readonly helpLines?: readonly string[];
+  readonly stdout: (text: string) => void;
+  readonly terminal?: Terminal;
+  readonly isTty?: boolean;
+  readonly theme?: KxmTuiTheme;
+  readonly abort?: AbortSignal;
+  /** Repaint interval for surfaces whose owners can change outside this process. */
+  readonly pollMs?: number;
+  readonly now?: () => number;
+}
+
+/** Draw one frame without a terminal. Used by `--dry-run` and CI smoke. */
+export function renderKxmTuiPanelFrame(input: {
+  registry: KxmTuiRegistry;
+  title: string;
+  theme?: KxmTuiTheme;
+  width?: number;
+  nowMs?: number;
+  footer?: string;
+}): string {
+  const theme = input.theme ?? createPlainKxmTuiTheme();
+  const lines = renderKxmTuiPanel(
+    input.registry.getSections(),
+    initialKxmTuiPanelState(input.registry.getSections()),
+    theme,
+    { title: input.title, footer: input.footer ?? "non-interactive frame", nowMs: input.nowMs ?? Date.now() },
+    input.width ?? 100,
+  );
+  return `${lines.map((line) => stripTerminalSequences(line)).join("\n")}\n`;
+}
+
+/** Run a panel until it quits, the caller aborts, or one frame is enough. */
+export async function runKxmTuiPanel(input: RunKxmTuiPanelInput): Promise<number> {
+  const theme = input.theme ?? createDefaultKxmTuiTheme();
+  const tty = input.isTty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!tty) {
+    input.stdout(renderKxmTuiPanelFrame({
+      registry: input.registry,
+      title: input.title,
+      theme,
+      ...(input.now === undefined ? {} : { nowMs: input.now() }),
+      ...(input.breadcrumb ? { footer: input.breadcrumb } : {}),
+    }));
+    return 0;
+  }
+
+  const terminal = input.terminal ?? new ProcessTerminal();
+  const tui = new TuiAltScreen(terminal, false, undefined, { mouse: true });
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let stopped = false;
+  let finished: () => void = () => undefined;
+  const done = new Promise<void>((resolve) => {
+    finished = resolve;
+  });
+  const stop = (): void => {
+    if (stopped) return;
+    stopped = true;
+    if (timer) clearInterval(timer);
+    input.abort?.removeEventListener("abort", stop);
+    panel.dispose();
+    tui.stop();
+    finished();
+  };
+  const panel = new KxmTuiPanelComponent({
+    registry: input.registry,
+    theme,
+    title: input.title,
+    ...(input.breadcrumb ? { breadcrumb: input.breadcrumb } : {}),
+    ...(input.helpLines ? { helpLines: input.helpLines } : {}),
+    requestRender: () => tui.requestRender(),
+    onQuit: stop,
+    getWidth: () => terminal.columns,
+  });
+  input.abort?.addEventListener("abort", stop, { once: true });
+  tui.setLayoutRoot(panel.root);
+  tui.setFocus(panel);
+  tui.start();
+  timer = setInterval(() => panel.refresh(), input.pollMs ?? 2_000);
+  timer.unref?.();
+  await done;
+  return stopped && input.abort?.aborted ? 130 : 0;
+}

package/packages/core/tui/src/exports/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Public surface of `@kontextmind/tui`.
+ *
+ * One declarative surface model, one renderer, one input decoder, one
+ * contribution registry, and thin host adapters, so `kxm dash`, the
+ * configuration surfaces, and any host adapter draw the same controls and fail
+ * the same way.
+ *
+ * Layers:
+ * - `types/`    the published-surface contract and its validation
+ * - `tui/`      pure controls: input decoding, layout, theme, reducer, renderer
+ * - `services/` the registry that routes every write to its owner
+ * - `adapters/` host bindings: a standalone terminal session and the Pi TUI
+ * - `exports/`  what leaves the package; anything unexported may be reshaped
+ *
+ * Import discipline: this entry is Pi-bound because the components render with
+ * `@earendil-works/pi-tui`. It is never re-exported from
+ * `@kontextmind/kxm/core`, whose closure must stay free of Pi and commander.
+ */
+
+export * from "../types/surface.ts";
+export * from "../tui/keys.ts";
+export * from "../tui/layout.ts";
+export * from "../tui/theme.ts";
+export * from "../tui/panel.ts";
+export * from "../tui/render.ts";
+export * from "../tui/panelComponent.ts";
+export * from "../services/registry.ts";
+export * from "../adapters/terminal.ts";
+export * from "../adapters/pi.ts";

package/packages/core/tui/src/services/registry.ts

@@ -0,0 +1,274 @@
+/**
+ * Surface registry: who owns which part of a KXM terminal surface.
+ *
+ * A panel is published, not centralised. Each owner (project, roster, routes,
+ * gates, roles, workflow, config) contributes its own sections and performs its
+ * own writes; the registry only routes requests and re-reads what changed. That
+ * keeps one rule true everywhere in KXM: the panel never becomes a second
+ * source of truth for configuration, and never writes a file by itself.
+ *
+ * There is no local echo. `invoke()` calls the owner and then re-reads its
+ * sections, so a rejected write comes back as the old value plus the owner's
+ * reason on `statusText`. A value the panel shows is a value that is on disk.
+ *
+ * Owners are addressed by name. A handler for an unregistered source, an
+ * unknown section, or an unknown action is refused rather than guessed, and a
+ * handler that throws never aborts the panel: the failure becomes a notice.
+ */
+
+import {
+  KXM_TUI_LIMITS,
+  assertKxmTuiSurface,
+  validateKxmTuiSurface,
+  type KxmTuiInvocation,
+  type KxmTuiIssue,
+  type KxmTuiSectionView,
+} from "../types/surface.ts";
+
+export interface KxmTuiActionInput {
+  readonly sectionId: string;
+  readonly fieldId: string;
+  readonly action: string;
+  readonly value?: string;
+  /** Owner-scoped state the handler needs to resolve the current surface. */
+  readonly state?: unknown;
+}
+
+export interface KxmTuiContribution<TState = unknown> {
+  /** Addressable owner id, e.g. `kxm/roster`. It is audited, never display-only. */
+  readonly source: string;
+  /**
+   * Read at publish time, not cached: an owner may have just written a file,
+   * refreshed a catalog, or lost authentication, and the panel must show that.
+   */
+  readonly listSections: (state?: TState) => readonly KxmTuiSectionView[];
+  readonly handlers: Readonly<Record<string, (input: KxmTuiActionInput) => void | Promise<void>>>;
+  /** Turn an owner failure into a legible line. Defaults to `error.message`. */
+  readonly describeError?: (error: unknown, action: string) => string;
+  /**
+   * Whether a write must be re-read through `listSections` after the handler
+   * resolves. Always true here; declared so an owner cannot promise otherwise.
+   */
+  readonly republishAfterWrite?: true;
+}
+
+export interface KxmTuiRegistryEvent {
+  readonly reason: "publish" | "invoke" | "refused" | "failed";
+  readonly source?: string;
+  readonly message?: string;
+}
+
+export interface KxmTuiInvokeResult {
+  readonly ok: boolean;
+  /** Why the request was refused or failed, already fit for one line. */
+  readonly message?: string;
+  /** Contract violations that made the owner's published surface unusable. */
+  readonly issues?: readonly KxmTuiIssue[];
+}
+
+export interface KxmTuiRegistry {
+  /** Register an owner. Re-registering the same source replaces it. */
+  register(contribution: KxmTuiContribution): void;
+  unregister(source: string): void;
+  /** The merged surface, ordered by `order` then source, safe to render. */
+  getSections(): readonly KxmTuiSectionView[];
+  /** Sections as published, including any that failed validation. */
+  getIssues(): readonly KxmTuiIssue[];
+  invoke(invocation: KxmTuiInvocation): Promise<KxmTuiInvokeResult>;
+  subscribe(listener: (event: KxmTuiRegistryEvent) => void): () => void;
+  /** Monotonic token identifying the current session of this registry. */
+  getGeneration(): number;
+  /** A source is only present when it registered; used to gate tabs. */
+  hasSource(source: string): boolean;
+  listSources(): string[];
+  dispose(): void;
+}
+
+function describe(error: unknown): string {
+  if (error instanceof Error && error.message) return error.message.split(/\r?\n/u)[0]!.slice(0, KXM_TUI_LIMITS.detailMax);
+  return String(error).split(/\r?\n/u)[0]!.slice(0, KXM_TUI_LIMITS.detailMax);
+}
+
+function normalizeSource(source: string): string {
+  if (!/^[A-Za-z0-9@][A-Za-z0-9@/._:-]*$/u.test(source) || source.length > KXM_TUI_LIMITS.sourceMax) {
+    throw new Error(`invalid kxm tui surface source: ${source.slice(0, 64)}`);
+  }
+  return source;
+}
+
+/**
+ * Create a registry.
+ *
+ * `onInternalError` receives faults that cannot be shown as a field notice (a
+ * malformed published surface, a listener that threw). It must never rethrow
+ * into the panel: a broken owner dims a section, it does not crash the UI.
+ */
+export function createKxmTuiRegistry(options: {
+  onInternalError?: (error: unknown, context: string) => void;
+} = {}): KxmTuiRegistry {
+  const contributions = new Map<string, KxmTuiContribution>();
+  const notices = new Map<string, string>();
+  const listeners = new Set<(event: KxmTuiRegistryEvent) => void>();
+  /** Per-owner cache so one repaint does not re-read every file on disk. */
+  const published = new Map<string, readonly KxmTuiSectionView[]>();
+  const issues = new Map<string, readonly KxmTuiIssue[]>();
+  let generation = 0;
+  let disposed = false;
+  let epoch = 0;
+
+  const report = (error: unknown, context: string): void => {
+    if (options.onInternalError) options.onInternalError(error, context);
+  };
+
+  const emit = (event: KxmTuiRegistryEvent): void => {
+    for (const listener of Array.from(listeners)) {
+      try {
+        listener(event);
+      } catch (error) {
+        report(error, "listener");
+      }
+    }
+  };
+
+  function readOwner(source: string, force: boolean): readonly KxmTuiSectionView[] {
+    if (!force) {
+      const cached = published.get(source);
+      if (cached) return cached;
+    }
+    const contribution = contributions.get(source);
+    if (!contribution) {
+      published.set(source, []);
+      return [];
+    }
+    let sections: readonly KxmTuiSectionView[];
+    try {
+      const raw = contribution.listSections();
+      const ownerIssues = validateKxmTuiSurface(raw);
+      if (ownerIssues.length > 0) {
+        issues.set(source, ownerIssues);
+        // Keep the surface drawable anyway: the panel is where someone repairs a
+        // bad file, so a broken section still has to render with its notice.
+        sections = raw
+          .filter((section): section is KxmTuiSectionView => Boolean(section) && typeof section === "object")
+          .map((section) => ({
+            ...section,
+            notice: section.notice ?? `published surface was refused: ${ownerIssues[0]!.code} at ${ownerIssues[0]!.path}`,
+            noticeLevel: "error" as const,
+          }));
+      } else {
+        issues.delete(source);
+        sections = raw;
+      }
+    } catch (error) {
+      issues.set(source, [{ path: source, code: "list_sections_failed", message: describe(error) }]);
+      report(error, `listSections:${source}`);
+      sections = [{ source, id: "error", title: source, order: 900, notice: describe(error), noticeLevel: "error", fields: [] }];
+    }
+    const pending = notices.get(source);
+    const withNotice = pending !== undefined && sections.length > 0
+      ? sections.map((section, index) => (index === 0 ? { ...section, notice: pending, noticeLevel: "error" as const } : section))
+      : sections;
+    published.set(source, withNotice);
+    return withNotice;
+  }
+
+  function merged(): readonly KxmTuiSectionView[] {
+    const all: KxmTuiSectionView[] = [];
+    for (const source of contributions.keys()) all.push(...readOwner(source, false));
+    return all.slice().sort((a, b) => a.order - b.order || a.source.localeCompare(b.source) || a.title.localeCompare(b.title));
+  }
+
+  return {
+    register(contribution) {
+      if (disposed) throw new Error("kxm tui registry is disposed");
+      const source = normalizeSource(contribution.source);
+      notices.delete(source);
+      published.delete(source);
+      issues.delete(source);
+      contributions.set(source, { ...contribution, source });
+      emit({ reason: "publish", source });
+    },
+    unregister(source) {
+      contributions.delete(source);
+      published.delete(source);
+      issues.delete(source);
+      notices.delete(source);
+      emit({ reason: "publish", source });
+    },
+    getSections() {
+      return merged();
+    },
+    getIssues() {
+      return [...issues.values()].flat();
+    },
+    async invoke(invocation) {
+      if (disposed) return { ok: false, message: "kxm tui registry is disposed" };
+      const contribution = contributions.get(invocation.source);
+      if (!contribution) {
+        emit({ reason: "refused", source: invocation.source, message: "unknown owner" });
+        return { ok: false, message: `${invocation.source} does not own a surface here` };
+      }
+      const handler = contribution.handlers[invocation.action];
+      if (!handler) {
+        const message = `${invocation.source} does not accept "${invocation.action}"`;
+        emit({ reason: "refused", source: invocation.source, message });
+        return { ok: false, message };
+      }
+      const currentEpoch = epoch;
+      try {
+        await handler({
+          sectionId: invocation.sectionId,
+          fieldId: invocation.fieldId,
+          action: invocation.action,
+          ...(invocation.value === undefined ? {} : { value: invocation.value }),
+        });
+      } catch (error) {
+        const failure = contribution.describeError?.(error, invocation.action) ?? describe(error);
+        notices.set(invocation.source, failure);
+        emit({ reason: "failed", source: invocation.source, message: failure });
+        // Republish so the panel shows the on-disk value plus the reason.
+        readOwner(invocation.source, true);
+        generation += 1;
+        return { ok: false, message: failure };
+      }
+      if (currentEpoch !== epoch) {
+        // A stale reply after a reset must not resurrect an old surface.
+        readOwner(invocation.source, true);
+        return { ok: false, message: "stale write result was discarded" };
+      }
+      notices.delete(invocation.source);
+      readOwner(invocation.source, true);
+      generation += 1;
+      emit({ reason: "publish", source: invocation.source });
+      return { ok: true };
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    getGeneration() {
+      return generation;
+    },
+    hasSource(source) {
+      return contributions.has(source);
+    },
+    listSources() {
+      return [...contributions.keys()];
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      epoch += 1;
+      listeners.clear();
+      contributions.clear();
+      published.clear();
+      issues.clear();
+      notices.clear();
+    },
+  };
+}
+
+/** Validate a contributed surface up front, for owners that publish constants. */
+export function checkedKxmTuiSections(sections: readonly KxmTuiSectionView[]): KxmTuiSectionView[] {
+  return assertKxmTuiSurface(sections);
+}

package/packages/core/tui/src/tui/keys.ts

@@ -0,0 +1,130 @@
+/**
+ * Keyboard input helpers for KXM terminal surfaces.
+ *
+ * The panel reducer must be testable without a terminal, so decoding lives here
+ * as pure functions instead of being scattered through `handleInput`. Paste and
+ * bracketed input arrive as one buffer, so every entry point is bounded and
+ * control bytes are dropped before they can reach a field value.
+ */
+
+import { decodeKittyPrintable, parseKey } from "@earendil-works/pi-tui";
+
+export type KxmTuiInputKind =
+  | "up"
+  | "down"
+  | "left"
+  | "right"
+  | "home"
+  | "end"
+  | "pageUp"
+  | "pageDown"
+  | "enter"
+  | "escape"
+  | "tab"
+  | "backspace"
+  | "delete"
+  | "ctrlC"
+  | "text"
+  | "ignored";
+
+export interface KxmTuiInput {
+  readonly kind: KxmTuiInputKind;
+  /** Printable payload for `kind: "text"`. */
+  readonly text?: string;
+}
+
+/** Printable maximum for one committed value; longer input is truncated. */
+export const KXM_TUI_INPUT_MAX_LENGTH = 4096;
+
+const CONTROL_BYTES = /[\u0000-\u0008\u000a-\u001f\u007f\u0080-\u009f]/u;
+
+const NAMED_KEYS: Readonly<Record<string, KxmTuiInputKind>> = Object.freeze({
+  up: "up",
+  down: "down",
+  left: "left",
+  right: "right",
+  home: "home",
+  end: "end",
+  pageup: "pageUp",
+  pagedown: "pageDown",
+  enter: "enter",
+  return: "enter",
+  escape: "escape",
+  esc: "escape",
+  tab: "tab",
+  backspace: "backspace",
+  delete: "delete",
+});
+
+const CONTROL_BYTES_GLOBAL = /[\u0000-\u0008\u000a-\u001f\u007f\u0080-\u009f]/gu;
+
+/** Strip control bytes, collapse newlines, and bound the result. */
+export function normalizeInputText(value: string): string {
+  return value.replace(CONTROL_BYTES_GLOBAL, " ").replace(/ {2,}/gu, " ").trim().slice(0, KXM_TUI_INPUT_MAX_LENGTH);
+}
+
+/** True when the buffer carries no printable text (pure escape/control input). */
+export function isControlInput(data: string): boolean {
+  for (let index = 0; index < data.length; index += 1) {
+    const code = data.charCodeAt(index);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+/**
+ * Decode one input event.
+ *
+ * Named keys resolve through the Pi key parser, which handles Kitty,
+ * modifyOtherKeys, and legacy SS3/CSI forms. A multi-character buffer that is
+ * not a key sequence is treated as pasted text.
+ */
+export function decodeKxmTuiInput(data: string | undefined): KxmTuiInput {
+  if (typeof data !== "string" || data.length === 0) return { kind: "ignored" };
+  const named = parseKey(data);
+  if (named === "ctrl+c") return { kind: "ctrlC" };
+  if (named) {
+    const kind = NAMED_KEYS[named.toLowerCase()];
+    if (kind) return { kind };
+    if (named === "space") return { kind: "text", text: " " };
+    // A single printable character comes back as its own key id. Everything
+    // else (f1, shift+tab, dead keys) is refused rather than mistaken for text.
+    if (Array.from(named).length === 1 && !CONTROL_BYTES.test(named)) {
+      return { kind: "text", text: named };
+    }
+    return { kind: "ignored" };
+  }
+  const kitty = decodeKittyPrintable(data);
+  if (kitty) {
+    const text = normalizeInputText(kitty);
+    return text ? { kind: "text", text } : { kind: "ignored" };
+  }
+  // An unrecognized escape sequence is a key we do not model, never text. A
+  // paste can legitimately carry newlines and other control bytes, so it is
+  // normalised rather than rejected.
+  if (data.startsWith("\u001b")) return { kind: "ignored" };
+  const pasted = normalizeInputText(data);
+  return pasted ? { kind: "text", text: pasted } : { kind: "ignored" };
+}
+
+/** Delete the last character; surrogate pairs go together. */
+export function deleteBackward(text: string): string {
+  const units = Array.from(text);
+  units.pop();
+  return units.join("");
+}
+
+/** Insert at an index and return the new text plus the advanced caret. */
+export function insertAt(
+  text: string,
+  caret: number,
+  insert: string,
+  maxLength = KXM_TUI_INPUT_MAX_LENGTH,
+): { text: string; caret: number } {
+  const units = Array.from(text);
+  const at = Math.max(0, Math.min(caret, units.length));
+  const added = Array.from(insert);
+  const merged = [...units.slice(0, at), ...added, ...units.slice(at)].join("");
+  const next = merged.length > maxLength ? merged.slice(0, maxLength) : merged;
+  return { text: next, caret: Math.min(next.length, at + added.length) };
+}