@pi-archimedes/core 2.10.3 → 2.11.0

package/src/pi-support.ts

@@ -0,0 +1,190 @@
+// ── Runtime pi-version support guard ─────────────────────────────────────────
+//
+// A published `peerDependencies` range protects nobody. `pi install` installs
+// extensions with peers omitted (`--legacy-peer-deps` /
+// `--config.auto-install-peers=false` / `--omit=peer`), and at runtime the
+// extension loader aliases every host specifier to pi's own copy, so a range is
+// never installed, never solved, and never parsed. The only mechanism that can
+// reach a user running an older host is a comparison against the `VERSION` the
+// running pi exports, at the moment the package registers itself (ADR 0026).
+//
+// Two rules the shape of this module follows from:
+//
+// 1. **Warn and still register.** A package that refuses to load makes `/plugins`
+//    report an enabled package that loaded nothing — strictly worse than a
+//    warning. Nothing here can prevent registration; `reportPiSupport` only
+//    records.
+// 2. **Silent by construction.** No console write on either path. A stray write
+//    smears the fullscreen frame and is discarded by a subagent child, so the
+//    warning goes into a registry that `meta` prints once, through the
+//    notification surface, and to `diag()` for anyone reading the log file.
+//
+// Reload-stability: pi builds a fresh jiti/module registry on every extension
+// load, so a module-level `let warned = false` re-arms on `/reload` and the
+// aggregated notice would be printed again. Both pieces of state therefore live
+// on `globalThis` under `Symbol.for(...)`, the same device `profiler.ts` uses.
+//
+// The `Symbol.for` keys and the plain-object entry shape are a contract, not an
+// implementation detail: `packages/diff` is a standalone package with no
+// dependency on core (AGENTS.md), so it keeps a sibling copy of this logic and
+// reports into the same registry through the same keys. Keep the two in step —
+// `pi-support.test.ts` here and `packages/diff/src/pi-support.test.ts` pin both
+// ends of it.
+
+import { VERSION } from "@earendil-works/pi-coding-agent";
+import { diag } from "./log.js";
+
+/** Result of measuring the running pi against one package's floor. */
+export interface PiSupport {
+  ok: boolean;
+  /** The version the host reports (`VERSION` as exported by pi). */
+  actual: string;
+  /** The floor the package asked for. */
+  min: string;
+}
+
+/** One below-floor report. Plain data: `diff` writes this same shape itself. */
+export interface PiSupportWarning {
+  pkg: string;
+  min: string;
+  actual: string;
+}
+
+const WARNINGS_KEY = Symbol.for("archimedes:piSupportWarnings");
+const NOTICED_KEY = Symbol.for("archimedes:piSupportNoticed");
+
+type Registry = Record<string, PiSupportWarning>;
+
+// Type-safe globalThis access (the pattern `profiler.ts` also uses).
+function getGlobal<T>(key: symbol): T | undefined {
+  return (globalThis as Record<symbol, unknown>)[key] as T | undefined;
+}
+function setGlobal<T>(key: symbol, value: T): void {
+  (globalThis as Record<symbol, unknown>)[key] = value;
+}
+
+function registry(): Registry {
+  return getGlobal<Registry>(WARNINGS_KEY) ?? {};
+}
+
+/**
+ * Numeric three-component comparison: -1 when `a` is older, 1 when newer, 0
+ * when equal. Leading `v` and absent components are tolerated (`"1.0"` is
+ * `"1.0.0"`), and a component that is not numeric counts as 0 rather than NaN —
+ * NaN compares false against everything, which would make a floor
+ * simultaneously satisfied and violated.
+ *
+ * This is the suite's only comparator on the core side of the dependency
+ * islands; `packages/diff` keeps a copy because it does not depend on core.
+ */
+export function compareVersions(a: string, b: string): number {
+  const part = (v: string, i: number): number => {
+    const n = Number(v.replace(/^v/, "").split(".")[i] ?? "0");
+    return Number.isFinite(n) ? n : 0;
+  };
+  for (let i = 0; i < 3; i++) {
+    const left = part(a, i);
+    const right = part(b, i);
+    if (left > right) return 1;
+    if (left < right) return -1;
+  }
+  return 0;
+}
+
+/** Measure the running pi against `min`. Inclusive: a host at the floor is ok. */
+export function checkPiSupport(min: string): PiSupport {
+  const actual = typeof VERSION === "string" ? VERSION : "";
+  return { ok: compareVersions(actual, min) >= 0, actual, min };
+}
+
+/**
+ * Record a below-floor warning for `meta` to print, aggregated, once.
+ *
+ * Never throws and never writes to the console: this runs at the top of a
+ * package's `register()`, where the only acceptable failure mode is "nothing
+ * happened, carry on registering". Idempotent per package, so a `/reload` or a
+ * `/new` (both re-run registration) does not multiply the entry.
+ */
+export function reportPiSupport(pkg: string, min: string): void {
+  try {
+    const support = checkPiSupport(min);
+    if (support.ok) return;
+    const current = registry();
+    if (pkg in current) return;
+    current[pkg] = { pkg, min, actual: support.actual };
+    setGlobal(WARNINGS_KEY, current);
+    // The log file is the only other place this can go: a standalone install
+    // has no aggregator, and a subagent child discards stdout.
+    diag(pkg, `pi ${support.actual} is below this package's floor (>=${min}); loaded anyway`);
+  } catch {
+    // A guard that can throw is a guard that can break registration.
+  }
+}
+
+/** Every warning recorded so far, in report order (mainly for `meta` and tests). */
+export function piSupportWarnings(): PiSupportWarning[] {
+  try {
+    return Object.values(registry());
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Is this registry entry something this module can actually report?
+ *
+ * The registry is shared memory: `packages/diff` writes it without importing
+ * here, and a standalone `diff` and an installed suite are installed and
+ * versioned separately, so an entry may predate or postdate this shape. A
+ * sentence built from missing fields reads "pi undefined is older than
+ * undefined (>=undefined) need.", which is worse than saying nothing — so an
+ * unrecognisable entry is left out of the notice and named in the log instead.
+ */
+function isReportable(entry: unknown): entry is PiSupportWarning {
+  const w = entry as Partial<PiSupportWarning> | null | undefined;
+  return (
+    typeof w === "object" &&
+    w !== null &&
+    typeof w.pkg === "string" &&
+    typeof w.min === "string" &&
+    typeof w.actual === "string"
+  );
+}
+
+/**
+ * The one aggregated message, or `undefined` when there is nothing to say or it
+ * has already been handed out.
+ *
+ * Reading it spends it: a second call returns `undefined`, which is how `meta`
+ * prints one line per session rather than one per package, and how a `/reload`
+ * (fresh modules, same `globalThis`) stays quiet — the pi version cannot change
+ * without restarting the process, so repeating the notice would be noise. An
+ * empty registry does not spend anything, so a floor raised later in the
+ * process is still heard.
+ */
+export function takePiSupportNotice(): string | undefined {
+  try {
+    const entries = Object.entries(registry());
+    const warnings = entries.filter(([, entry]) => isReportable(entry)).map(([, entry]) => entry);
+    const unreadable = entries.length - warnings.length;
+    if (unreadable > 0) {
+      // Loud in the log, silent on screen: a dropped warning must never be a
+      // silent one, and a shape this module cannot read is a drift bug someone
+      // needs to be able to find.
+      diag(
+        "core",
+        `pi-support registry held ${unreadable} entr${unreadable === 1 ? "y" : "ies"} outside the agreed shape; left out of the host-version notice`,
+      );
+    }
+    if (warnings.length === 0) return undefined;
+    if (getGlobal<boolean>(NOTICED_KEY)) return undefined;
+    setGlobal(NOTICED_KEY, true);
+    const floors = warnings.map((w) => `${w.pkg} (>=${w.min})`).join(", ");
+    return [
+      `pi-archimedes: pi ${warnings[0]!.actual} is older than ${floors} need.`,
+      "Everything still loaded; update pi if something behaves oddly.",
+    ].join("\n");
+  } catch {
+    return undefined;
+  }
+}

package/src/profiler.ts

@@ -1,4 +1,6 @@
-/** Lightweight startup profiler — prints per-package timings when PI_TIMING=1. */
+/** Lightweight startup profiler — records per-package timings when PI_TIMING=1. */
+
+import { diag } from "./log.js";
 
 const ENABLED = process.env.PI_TIMING === "1";
 
@@ -32,18 +34,25 @@ export function reset(): void {
   globalThis[TIMINGS_KEY] = { baseline: Date.now(), entries: [] };
 }
 
-/** Print accumulated timings to stderr. Call once at session_shutdown or on demand. */
+/**
+ * Append accumulated timings to the diagnostics log. Call once at
+ * session_shutdown or on demand.
+ *
+ * `PI_TIMING=1` decides *what* is measured; `PI_ARCHIMEDES_LOG` decides where
+ * it lands. Both are required to see anything, because timings are a developer
+ * diagnostic and the console is off-limits: on fullscreen screen a stray write
+ * smears the viewport, and in a subagent child it is discarded before anyone
+ * reads it.
+ */
 export function print(): void {
   if (!ENABLED) return;
   const state = getState();
   if (state.entries.length === 0) return;
 
   let prevMs = 0;
-  console.error("");
   for (const entry of state.entries) {
     const delta = entry.ms - prevMs;
     prevMs = entry.ms;
-    console.error(`  archimedes: ${entry.label}: +${delta}ms (${entry.ms}ms cumulative)`);
+    diag("core", `archimedes: ${entry.label}: +${delta}ms (${entry.ms}ms cumulative)`);
   }
-  console.error("".padEnd(60, "-"));
 }

package/src/screen-mode-discipline.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect } from "vitest";
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ── The rule (ADR 0027) ─────────────────────────────────────────────────────
+//
+// Screen mode is mutable mid-session: `switchTuiMode()` stops the running TUI,
+// builds a new one, re-mounts every child and rebinds extension input
+// listeners. A stored `tui` therefore keeps a *stopped* renderer — every write
+// is accepted, nothing throws, and the component silently renders into a
+// renderer nobody draws from. So: never store a renderer; ask the one you were
+// just handed. This test is the mechanical half of that rule.
+//
+// The `\w*tui\w*` widening (not `\btui\b`) is load-bearing: the shape this
+// guard was written for is `let uiTui: TUI | undefined` in
+// `packages/ui/src/index.ts`, where `ui` glues straight onto `Tui`, so a
+// word-anchored pattern matches nothing of the kind. That declaration is gone
+// (Task 8 deleted the startup un-patch that read it), but the pattern stays
+// widened — the `catches every shape` test below is what proves the widening
+// still has something to catch. The patterns are also case-insensitive for the
+// same reason: a name like `uiTui` has a capital T.
+//
+// Module-scope declarations accept an `export` prefix and an optional type
+// annotation, because those are how the binding is really written: `export let
+// sharedTui: TUI` and `const appTui: TUI = tui` hoard a renderer just as much
+// as `let sharedTui = tui` does, and a pattern that requires the declaration
+// keyword at column 0 followed immediately by `=` sees neither. A `const` with
+// no type annotation is only caught when its initializer is a renderer, which
+// is what keeps the `tuiMode` *setting* — a screen-mode string whose name also
+// contains "tui" — out of the net.
+
+interface ViolationRule {
+  /** What shape of renderer hoarding this catches. */
+  readonly label: string;
+  readonly pattern: RegExp;
+}
+
+const RULES: readonly ViolationRule[] = [
+  { label: "class field holding a renderer", pattern: /(private|public|readonly)\s+\w*tui\w*\s*[:=]/i },
+  { label: "renderer assigned to an instance property", pattern: /\bthis\.\w*tui\w*\s*=/i },
+  { label: "module-scope mutable renderer binding", pattern: /^(export\s+)?(let|var)\s+\w*tui\w*\b/im },
+  { label: "module-scope const typed as a renderer", pattern: /^(export\s+)?const\s+\w*tui\w*\s*:\s*TUI\b/im },
+  { label: "module-scope binding initialised from a renderer", pattern: /^(export\s+)?(let|var|const)\s+\w+\s*=\s*\w*tui\w*\s*[;,]?\s*$/im },
+];
+
+/**
+ * Known violations, each with the one-line reason that keeps it, and the
+ * removal point. Matched on the exact trimmed line so a *new* violation in the
+ * same file still fails the guard.
+ *
+ * Empty as of Task 8: the last entry was the `let uiTui` whose only reader was
+ * the startup `addChild` un-patch, and both went together. Keep the shape of
+ * this list even while it is empty — an exemption without a reason and a
+ * removal point is how the guard quietly widens.
+ */
+interface AllowEntry {
+  readonly file: string;
+  readonly line: string;
+  readonly reason: string;
+}
+
+const ALLOW_LIST: readonly AllowEntry[] = [];
+
+// ── Walking the tree ────────────────────────────────────────────────────────
+
+/** Repo root, resolved from this file (`packages/core/src` → repo root). */
+const REPO_ROOT = fileURLToPath(new URL("../../../", import.meta.url));
+
+// Every `packages/<name>/src` directory, plus `meta/src`.
+function sourceDirs(): string[] {
+  const dirs: string[] = [];
+  for (const entry of readdirSync(join(REPO_ROOT, "packages"), { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const src = join(REPO_ROOT, "packages", entry.name, "src");
+    if (existsSync(src)) dirs.push(src);
+  }
+  const metaSrc = join(REPO_ROOT, "meta", "src");
+  if (existsSync(metaSrc)) dirs.push(metaSrc);
+  return dirs;
+}
+
+/** Source files under those trees, excluding tests (which fake renderers). */
+function collectSourceFiles(): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== "node_modules") walk(full);
+      } else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) {
+        out.push(relative(REPO_ROOT, full).split(/[\\/]/).join("/"));
+      }
+    }
+  };
+  for (const dir of sourceDirs()) walk(dir);
+  return out.sort();
+}
+
+interface Hit {
+  file: string;
+  line: number;
+  rule: string;
+  text: string;
+}
+
+function findViolations(files: readonly string[]): Hit[] {
+  const hits: Hit[] = [];
+  for (const file of files) {
+    const lines = readFileSync(join(REPO_ROOT, file), "utf8").split("\n");
+    lines.forEach((text, i) => {
+      for (const rule of RULES) {
+        // Fresh lastIndex-free test: these patterns have no /g.
+        if (rule.pattern.test(text)) {
+          hits.push({ file, line: i + 1, rule: rule.label, text: text.trim() });
+        }
+      }
+    });
+  }
+  return hits;
+}
+
+function isAllowed(hit: Hit): boolean {
+  return ALLOW_LIST.some((e) => e.file === hit.file && e.line === hit.text);
+}
+
+const FILES = collectSourceFiles();
+const VIOLATIONS = findViolations(FILES).filter((h) => !isAllowed(h));
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("screen-mode discipline: never store a renderer", () => {
+  it("walks the whole suite, not an empty file set", () => {
+    expect(existsSync(join(REPO_ROOT, "pnpm-workspace.yaml"))).toBe(true);
+    expect(FILES.length).toBeGreaterThan(50);
+    // The three trees the guard is supposed to cover.
+    for (const expected of [
+      "packages/core/src/screen-mode.ts",
+      "packages/ui/src/index.ts",
+      "meta/src/index.ts",
+    ]) {
+      expect(FILES).toContain(expected);
+    }
+  });
+
+  it("reports no renderer hoarding outside the allow-list", () => {
+    expect(
+      VIOLATIONS.map((v) => `${v.file}:${v.line} [${v.rule}] ${v.text}`),
+    ).toEqual([]);
+  });
+
+  it("catches every shape the rule forbids (patterns are not dead)", () => {
+    const offenders = [
+      "private tui: TUI | undefined;",
+      "readonly viewportTui = tui;",
+      "this.tui = tui;",
+      "this.altTui = next;",
+      "let sharedTui: TUI | undefined;",
+      "var cachedTui = tui;",
+      "const appTui = tui;",
+      // Re-exported bindings are the same hoarding with `export` in front —
+      // a pattern anchored on `^(let|var|const)` walks straight past them.
+      "export let sharedTui: TUI | undefined;",
+      "export var cachedTui = tui;",
+      "export const appTui = tui;",
+      "export let cachedTui;",
+      // A type annotation between the name and the initializer is how a
+      // renderer binding is actually written in TypeScript, so the shape the
+      // guard most needs to see must not be the shape it skips.
+      "const appTui: TUI = tui;",
+      "export const appTui: TUI = tui;",
+      "let currentTui: TUI = tui;",
+    ];
+    for (const line of offenders) {
+      expect(RULES.some((r) => r.pattern.test(line)), `expected a rule to reject: ${line}`).toBe(true);
+    }
+
+    // And leaves honest code alone: renderers received as parameters, locals
+    // inside a function, unrelated names that merely contain "tui", and the
+    // tuiMode *setting* (a screen-mode string, not a renderer) at module
+    // scope — widening the declaration patterns must not swallow it.
+    const fine = [
+      "  const factory = (tui: TUI, theme: Theme) => {",
+      "  const tuiMode = settings.tuiMode;",
+      "  return screenMode(tui);",
+      "    const tui = getRenderer();",
+      "export function screenMode(tui: object): ScreenMode {",
+      "const tuiMode = settings.tuiMode;",
+      "export const tuiModes = [\"regular\", \"fullscreen\"] as const;",
+      "const tuiMode: TuiMode = readMode();",
+    ];
+    for (const line of fine) {
+      expect(RULES.some((r) => r.pattern.test(line)), `expected no rule to reject: ${line}`).toBe(false);
+    }
+  });
+
+  it("keeps the allow-list as small as the work that removes it", () => {
+    // The list is empty: every renderer hoard the guard was written to excuse
+    // was deleted with the startup patch that needed it (Task 8). An entry
+    // reappearing is allowed only with a reason naming the task that removes
+    // it, so this assertion is the rule, not a snapshot.
+    expect(
+      ALLOW_LIST.map((e) => `${e.file}: ${e.line}`),
+    ).toEqual([]);
+    for (const entry of ALLOW_LIST) {
+      const actual = readFileSync(join(REPO_ROOT, entry.file), "utf8").split("\n");
+      expect(
+        actual.some((l) => l.trim() === entry.line),
+        `allow-list entry no longer matches ${entry.file}: ${entry.line}`,
+      ).toBe(true);
+      expect(entry.reason).toMatch(/Task \d+/);
+    }
+  });
+});

package/src/screen-mode.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { screenMode, screenCapabilities } from "./screen-mode.js";
+
+// The renderer identity check is pi-tui's (`isViewportTUI` reads a symbol
+// marker on the instance). A viewport TUI cannot be fabricated in a test —
+// `VIEWPORT_TUI` is not exported — which is why `screenCapabilities()` takes
+// the mode rather than the renderer: the capability table stays testable, and
+// `screenMode()` keeps a single, one-line delegation to pi.
+
+describe("screenMode", () => {
+  it("reports regular screen for a renderer without the viewport marker", () => {
+    expect(screenMode({})).toBe("regular");
+  });
+
+  it("reports regular screen for a renderer-shaped object that is not a viewport TUI", () => {
+    expect(screenMode({ terminal: { rows: 24 }, children: [] })).toBe("regular");
+  });
+});
+
+describe("screenCapabilities", () => {
+  it("forbids scrollback writes and requires frame fitting on fullscreen screen", () => {
+    expect(screenCapabilities("fullscreen")).toEqual({
+      transcriptWrite: false,
+      frameBounded: true,
+    });
+  });
+
+  it("allows scrollback writes and no frame fitting on regular screen", () => {
+    expect(screenCapabilities("regular")).toEqual({
+      transcriptWrite: true,
+      frameBounded: false,
+    });
+  });
+
+  it("exposes exactly the two capabilities that differ between screens", () => {
+    expect(Object.keys(screenCapabilities("regular")).sort()).toEqual([
+      "frameBounded",
+      "transcriptWrite",
+    ]);
+  });
+
+  it("resolves the two capabilities inversely for every mode", () => {
+    for (const mode of ["regular", "fullscreen"] as const) {
+      const caps = screenCapabilities(mode);
+      expect(caps.transcriptWrite).not.toBe(caps.frameBounded);
+    }
+  });
+});

package/src/screen-mode.ts

@@ -0,0 +1,45 @@
+import { isViewportTUI } from "@earendil-works/pi-tui";
+
+// ── Screen mode (ADR 0027) ──────────────────────────────────────────────────
+//
+// Pi 1.0.0 made fullscreen screen the default `tuiMode`: components render
+// into a clipped, height-allocated, wheel-routed viewport instead of terminal
+// scrollback. Screen mode is also mutable mid-session — `switchTuiMode()`
+// stops the running TUI, builds a new one and re-mounts every child — so the
+// only trustworthy answer is the renderer instance currently in hand. Nothing
+// here holds on to one.
+
+export type ScreenMode = "regular" | "fullscreen";
+
+/**
+ * Which screen the given renderer draws into.
+ *
+ * Ask the renderer we were just handed. Never store the result or the `tui`:
+ * a retained renderer is a stopped renderer after a `tuiMode` switch, and it
+ * accepts every write without throwing.
+ */
+export function screenMode(tui: object): ScreenMode {
+  return isViewportTUI(tui as never) ? "fullscreen" : "regular";
+}
+
+export interface ScreenCapabilities {
+  /** May append into terminal scrollback. Off on fullscreen screen. */
+  transcriptWrite: boolean;
+  /** Must fit an allocated, wheel-routed viewport. On fullscreen screen. */
+  frameBounded: boolean;
+}
+
+/**
+ * The policy a screen mode implies. Takes the mode, not the renderer, so the
+ * table is unit-testable: pi-tui does not export the viewport marker, so a
+ * test cannot fabricate a viewport TUI to ask.
+ *
+ * These two are the only capabilities that differ between the screens today —
+ * add one here when a second real difference shows up, never ad hoc in a
+ * component.
+ */
+export function screenCapabilities(mode: ScreenMode): ScreenCapabilities {
+  return mode === "fullscreen"
+    ? { transcriptWrite: false, frameBounded: true }
+    : { transcriptWrite: true, frameBounded: false };
+}