@pi-archimedes/diff 2.10.4 → 2.11.1

package/src/index.ts

@@ -5,14 +5,16 @@
  */
 
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import type { SettingItem } from "@earendil-works/pi-tui";
+import type { Component, SettingItem } from "@earendil-works/pi-tui";
 
 import { setConfigGetter as setShikiConfig } from "./shiki.js";
 import { setConfigGetter as setRenderConfig } from "./render/index.js";
 import { DiffComponent } from "./diff-component.js";
 import type { DiffBg, DiffColors } from "./ansi/index.js";
 import { resetDiffColors } from "./ansi/index.js";
-import { registerWriteTool, registerEditTool } from "./tools/index.js";
+import { installWriteTool, installEditTool } from "./tools/index.js";
+import { diag } from "./log.js";
+import { reportPiSupport } from "./pi-support.js";
 
 // ---------------------------------------------------------------------------
 // Re-exports
@@ -81,33 +83,58 @@ export function getDiffSettingsItems(overrideConfig?: DiffConfig): SettingItem[]
 // Extension entry point
 // ---------------------------------------------------------------------------
 
-// Load SDK dependencies at module evaluation time (top-level await) so they are
-// ready before any session_start event fires. If these imports fail the
-// extension will skip diff tool registration gracefully.
-let _sdk: { createWriteTool: any; createEditTool: any } | null = null;
-let _TextComponent: any = null;
+// `Text` is the component the `write` row reuses across repaints. It is loaded
+// at module evaluation time (top-level await) so it is ready before any
+// `session_start`; a failure here means the rows are skipped rather than
+// half-installed.
+let _TextComponent:
+	| (new (text?: string, paddingX?: number, paddingY?: number) => Component)
+	| null = null;
 
 try {
-	const [sdk, tui] = await Promise.all([
-		import("@earendil-works/pi-coding-agent"),
-		import("@earendil-works/pi-tui"),
-	]);
-	_sdk = {
-		createWriteTool: sdk.createWriteTool,
-		createEditTool: sdk.createEditTool,
-	};
+	const tui = await import("@earendil-works/pi-tui");
 	_TextComponent = tui.Text;
 } catch (error) {
-	console.error(
-		`[diff] failed to load Pi SDK: ${error instanceof Error ? error.message : String(error)}`,
+	// A missing SDK means the diff tool is not registered at all, which is a
+	// developer-facing structural failure — the log file, never the console, and
+	// with the stack: this error is swallowed, so nothing else ever prints it.
+	// (Inlined rather than imported: `describeError` lives in core, which a
+	// standalone install does not have — see `pi-support.ts`.)
+	diag(
+		"diff",
+		`[diff] failed to load Pi SDK: ${error instanceof Error ? error.stack ?? error.message : String(error)}`,
 	);
 }
 
+/**
+ * Install the diff-drawing `edit` and `write` rows.
+ *
+ * Idempotent per `pi` handle, and it has to be: pi keeps a LIST of resolvers and
+ * of event handlers per extension, so registering twice on the same extension
+ * stacks a duplicate. It is keyed to the handle rather than to this module
+ * because the two lifetimes differ — pi caches the compiled extension MODULE
+ * across sessions while every session replacement (`/new`, `/fork`, `/resume`)
+ * builds a fresh extension and hands registration a new handle. A module-wide
+ * flag would then install for the first session only, and every session after
+ * it would get pi's native `edit`/`write` rows and none of the result details
+ * the rows read. The theme and config readers are per-session, so those are
+ * refreshed on every call.
+ */
+const _installedExtensions = new WeakSet<object>();
+
 export function registerDiffTools(
 	pi: ExtensionAPI,
 	_getTheme: () => Theme,
 	readConfig: () => DiffConfig,
 ): void {
+	// Floor check first, before anything can fail: pi 1.x APIs this package now
+	// relies on are not guaranteed below 1.2.0, and a peer range cannot warn
+	// anyone because pi never installs or solves peers (ADR 0026). Warn and
+	// carry on — a `diff` that declined to load would make /plugins report an
+	// enabled package that registered nothing. Idempotent per package, and this
+	// runs again on every session_start.
+	reportPiSupport("diff", "1.2.0");
+
 	_readConfig = readConfig;
 
 	// Reset theme-derived colors so they are re-derived from the current theme
@@ -117,19 +144,33 @@ export function registerDiffTools(
 	setShikiConfig(() => getConfig());
 	setRenderConfig(() => getConfig());
 
-	if (!_sdk?.createWriteTool || !_sdk?.createEditTool || !_TextComponent) {
-		console.warn("[diff] SDK not available, skipping diff tool registration");
+	// Already installed on this extension: re-registering would stack a duplicate
+	// resolver and handler set. A different handle is a different extension, so
+	// it installs even when this module instance is a reused one.
+	if (_installedExtensions.has(pi)) return;
+
+	if (!_TextComponent) {
+		diag("diff", "[diff] SDK not available, skipping diff tool registration");
 		return;
 	}
 
 	const cwd = process.cwd();
 	const home = process.env.HOME ?? "";
 
-	// Register write tool override
-	registerWriteTool(pi, cwd, home, _sdk.createWriteTool, _TextComponent);
+	// Capability check, not a version wish: without renderer resolution there is
+	// nothing to install, and pi's own rows stand in. The floor check above is
+	// what tells the user why.
+	if (typeof pi.registerToolRenderer !== "function" || typeof pi.on !== "function") {
+		diag("diff", "[diff] pi has no registerToolRenderer(), skipping diff tool installation");
+		return;
+	}
 
-	// Register edit tool override
-	registerEditTool(pi, cwd, home, _sdk.createEditTool);
+	// The rows are chosen by pi's renderer resolution, and the result details
+	// each row reads arrive through `tool_result` (ADR 0029). Neither registers a
+	// tool, so pi's own `edit` and `write` stay in place.
+	installEditTool(pi, cwd, home);
+	installWriteTool(pi, cwd, home, _TextComponent);
+	_installedExtensions.add(pi);
 }
 
 // ── Default export (for standalone pi.extensions loading) ─────────────────

package/src/log.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { diag } from "./log.js";
+
+// Same contract as `@pi-archimedes/core/log` — see `packages/core/src/log.test.ts`.
+// Kept in sync deliberately: this package is standalone, so the sink is a
+// sibling implementation, and a contract test is what keeps them siblings
+// rather than drift.
+const SANDBOX = mkdtempSync(join(tmpdir(), `archimedes-diff-log-${randomUUID()}-`));
+const ENV = "PI_ARCHIMEDES_LOG";
+const previous = process.env[ENV];
+
+afterEach(() => {
+  if (previous === undefined) delete process.env[ENV];
+  else process.env[ENV] = previous;
+});
+
+describe("diff diag — the diagnostics sink", () => {
+  it("writes nothing when the env var is unset", () => {
+    const target = join(SANDBOX, "unset.log");
+    process.env[ENV] = target;
+    diag("diff", "enabled");
+
+    delete process.env[ENV];
+    expect(() => diag("diff", "a message")).not.toThrow();
+    expect(readFileSync(target, "utf8").trimEnd().split("\n")).toHaveLength(1);
+  });
+
+  it("appends a timestamped, scoped line", () => {
+    const target = join(SANDBOX, "write.log");
+    process.env[ENV] = target;
+
+    diag("diff", "SDK not available");
+
+    const lines = readFileSync(target, "utf8").trimEnd().split("\n");
+    expect(lines).toHaveLength(1);
+    const match = /^\[(\d{4}-\d{2}-\d{2}T[\d:.]+Z?)\] \[(.+?)\] (.*)$/.exec(lines[0]!);
+    expect(match, `unexpected line shape: ${lines[0]}`).not.toBeNull();
+    expect(match![2]).toBe("diff");
+    expect(match![3]).toBe("SDK not available");
+  });
+
+  it("appends across calls", () => {
+    const target = join(SANDBOX, "append.log");
+    process.env[ENV] = target;
+
+    diag("diff", "one");
+    diag("diff", "two");
+
+    expect(readFileSync(target, "utf8").trimEnd().split("\n")).toHaveLength(2);
+  });
+
+  it("never throws on an unwritable target, and creates no directories", () => {
+    const missing = join(SANDBOX, "nope", "log.txt");
+    process.env[ENV] = missing;
+    expect(() => diag("diff", "ENOENT")).not.toThrow();
+    expect(existsSync(join(SANDBOX, "nope"))).toBe(false);
+
+    const dir = join(SANDBOX, "directory");
+    mkdirSync(dir, { recursive: true });
+    process.env[ENV] = dir;
+    expect(() => diag("diff", "EISDIR")).not.toThrow();
+  });
+});

package/src/log.ts

@@ -0,0 +1,34 @@
+import { appendFileSync } from "node:fs";
+
+// ── Diagnostics sink (sibling of `@pi-archimedes/core/log`) ─────────────────
+//
+// Nothing in this package writes to the console: on fullscreen screen a stray
+// write lands inside the differential frame and smears the viewport, and inside
+// a subagent child it is discarded anyway (`subagent/src/stream.ts` drops every
+// non-JSON stdout line). Diagnostics therefore go to `$PI_ARCHIMEDES_LOG`, and
+// messages the user must see go to the notification surface.
+//
+// Why a copy rather than the import: `diff` is standalone, and `pi-support.ts`
+// is the one place that states what that costs and why it is worth it. The
+// canonical implementation is `packages/core/src/log.ts`; keep the two in step
+// (pinned here by `log.test.ts`, which mirrors `core/src/log.test.ts`).
+
+/**
+ * Append one diagnostic line to `$PI_ARCHIMEDES_LOG`.
+ *
+ * No-op when the variable is unset or empty. Never throws: losing a log line is
+ * always cheaper than failing a render or a tool call, which is what these
+ * calls sit next to.
+ *
+ * @param scope the package the line came from (`"diff"`)
+ * @param message the diagnostic text
+ */
+export function diag(scope: string, message: string): void {
+  const file = process.env.PI_ARCHIMEDES_LOG;
+  if (!file) return;
+  try {
+    appendFileSync(file, `[${new Date().toISOString()}] [${scope}] ${message}\n`);
+  } catch {
+    // Logging must never be the reason something failed.
+  }
+}

package/src/pi-support.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ── What this file pins ─────────────────────────────────────────────────────
+//
+// `diff` carries its own copy of the pi-version guard because it is a standalone
+// package with no dependency on `@pi-archimedes/core` (see the header of
+// `pi-support.ts`). A copy is only safe if it is pinned twice: once here, and
+// once in `packages/core/src/pi-support.test.ts`. The two ends of the contract
+// that matters — the `Symbol.for` key and the entry shape — are asserted in both
+// files, so the copies cannot drift apart silently and leave `diff`'s warning
+// out of the suite's aggregated notice.
+
+const host = vi.hoisted(() => ({ version: "1.2.0" }));
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  get VERSION() {
+    return host.version;
+  },
+}));
+
+import { reportPiSupport, piSupportWarnings } from "./pi-support.js";
+
+const WARNINGS_KEY = Symbol.for("archimedes:piSupportWarnings");
+const globals = globalThis as Record<symbol, unknown>;
+
+function wipeRegistry(): void {
+  delete globals[WARNINGS_KEY];
+}
+
+beforeEach(() => {
+  wipeRegistry();
+  host.version = "1.2.0";
+});
+
+afterEach(() => {
+  wipeRegistry();
+});
+
+describe("diff's pi-support guard", () => {
+  it("says nothing on a supported host, at the floor or above", () => {
+    host.version = "1.2.0";
+    reportPiSupport("diff", "1.2.0");
+    host.version = "1.10.0";
+    reportPiSupport("diff", "1.2.0");
+    expect(piSupportWarnings()).toEqual([]);
+  });
+
+  it("records the package, the floor and the running version below the floor", () => {
+    host.version = "0.99.2";
+    reportPiSupport("diff", "1.2.0");
+    expect(piSupportWarnings()).toEqual([{ pkg: "diff", min: "1.2.0", actual: "0.99.2" }]);
+  });
+
+  it("orders by number, not by string (1.10.0 is not older than 1.2.0)", () => {
+    host.version = "1.10.0";
+    reportPiSupport("diff", "1.2.0");
+    expect(piSupportWarnings()).toEqual([]);
+  });
+
+  it("is idempotent per package — session_start re-registers on /new and /reload", () => {
+    host.version = "0.99.2";
+    reportPiSupport("diff", "1.2.0");
+    reportPiSupport("diff", "1.2.0");
+    expect(piSupportWarnings()).toHaveLength(1);
+  });
+
+  it("never throws, whatever the host reports as its version", () => {
+    // A guard that can throw can break registration, which is the one thing it
+    // must never do.
+    host.version = "nonsense";
+    expect(() => reportPiSupport("diff", "1.2.0")).not.toThrow();
+    delete (host as { version?: string }).version;
+    expect(() => reportPiSupport("diff", "1.2.0")).not.toThrow();
+  });
+
+  it("writes nothing to the console, on either path", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    host.version = "1.2.0";
+    reportPiSupport("diff", "1.2.0");
+    host.version = "0.99.2";
+    reportPiSupport("diff", "1.2.0");
+
+    expect(log).not.toHaveBeenCalled();
+    expect(warn).not.toHaveBeenCalled();
+    expect(error).not.toHaveBeenCalled();
+    log.mockRestore();
+    warn.mockRestore();
+    error.mockRestore();
+  });
+});
+
+describe("the registry contract with @pi-archimedes/core", () => {
+  it("writes into the same Symbol.for key and entry shape core reads", () => {
+    host.version = "0.99.2";
+    reportPiSupport("diff", "1.2.0");
+    const registry = globals[WARNINGS_KEY] as Record<string, { pkg: string; min: string; actual: string }>;
+    expect(registry).toBeTypeOf("object");
+    // The exact shape `core/pi-support.ts` builds its aggregated notice from —
+    // if this changes, meta stops naming `diff` and no test would notice
+    // without this assertion.
+    expect(registry["diff"]).toEqual({ pkg: "diff", min: "1.2.0", actual: "0.99.2" });
+  });
+
+  it("leaves entries written by another package alone (co-existence, not ownership)", () => {
+    globals[WARNINGS_KEY] = { ui: { pkg: "ui", min: "1.2.0", actual: "0.99.2" } };
+    host.version = "0.99.2";
+    reportPiSupport("diff", "1.2.0");
+    expect(piSupportWarnings().map((w) => w.pkg)).toEqual(["ui", "diff"]);
+  });
+});

package/src/pi-support.ts

@@ -0,0 +1,98 @@
+import { VERSION } from "@earendil-works/pi-coding-agent";
+import { diag } from "./log.js";
+
+// ── pi-version support guard (sibling of `@pi-archimedes/core/pi-support`) ───
+//
+// `diff` is a standalone, independently installable package: it declares no
+// dependency on `@pi-archimedes/core` (AGENTS.md, README), so anything it needs
+// from the suite it carries itself. That trade now has exactly three entries —
+// the xterm colour table in `ansi/colors.ts`, the diagnostics sink in `log.ts`,
+// and this version guard. This file is the one place that states the reason, so
+// the other two point here rather than each repeating it; the reason is simply
+// that `pi install @pi-archimedes/diff` must keep working with nothing else
+// from the suite present.
+//
+// Why the check exists at all: a `peerDependencies` range reaches nobody. `pi
+// install` omits peers, and the loader aliases host specifiers to pi's own
+// copies, so the only thing that can tell a user their pi is older than this
+// package was built for is a comparison against the `VERSION` the running host
+// exports (ADR 0026). The answer is a warning, never a refusal — a `diff` that
+// declined to load would make `/plugins` report an enabled package that
+// registered nothing.
+//
+// How the warning is seen: this writes into the same `globalThis` registry core
+// owns, under the same `Symbol.for` key and the same plain-object entry shape.
+// A symbol-keyed global is the only shared memory a standalone package and the
+// suite have, and it means an installed suite still aggregates `diff` into its
+// one notice while a standalone `diff` leaves the entry for `piSupportWarnings()`
+// and the log file. `pi-support.test.ts` here and
+// `packages/core/src/pi-support.test.ts` pin both ends of that contract; keep
+// the two copies in step.
+
+/** Below-floor report. Shape shared with `core/pi-support.ts` — do not drift. */
+export interface PiSupportWarning {
+  pkg: string;
+  min: string;
+  actual: string;
+}
+
+/** The key `@pi-archimedes/core/pi-support` reads to build its notice. */
+const WARNINGS_KEY = Symbol.for("archimedes:piSupportWarnings");
+
+type Registry = Record<string, PiSupportWarning>;
+
+function registry(): Registry {
+  const existing = (globalThis as Record<symbol, unknown>)[WARNINGS_KEY];
+  return (existing as Registry | undefined) ?? {};
+}
+
+/**
+ * Numeric three-component comparison, copied from
+ * `packages/core/src/pi-support.ts`: -1 / 0 / 1, leading `v` and missing
+ * components tolerated, a non-numeric component counting as 0 rather than NaN.
+ * Numeric, not lexical, because `1.10.0` must outrank `1.2.0`.
+ */
+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;
+}
+
+/**
+ * Record a below-floor warning. Idempotent per package, silent by construction
+ * (no console write on either path), and never throws — this runs at the top of
+ * registration, where the only acceptable failure mode is "nothing happened,
+ * carry on registering".
+ */
+export function reportPiSupport(pkg: string, min: string): void {
+  try {
+    const actual = typeof VERSION === "string" ? VERSION : "";
+    if (compareVersions(actual, min) >= 0) return;
+    const current = registry();
+    if (pkg in current) return;
+    current[pkg] = { pkg, min, actual };
+    (globalThis as Record<symbol, unknown>)[WARNINGS_KEY] = current;
+    // A standalone install has no aggregator, so the log file is the only other
+    // place this can go.
+    diag(pkg, `pi ${actual} is below this package's floor (>=${min}); loaded anyway`);
+  } catch {
+    // A guard that can throw is a guard that can break registration.
+  }
+}
+
+/** Recorded warnings, in report order — the standalone view of the registry. */
+export function piSupportWarnings(): PiSupportWarning[] {
+  try {
+    return Object.values(registry());
+  } catch {
+    return [];
+  }
+}

package/src/register-diff-tools.test.ts

@@ -0,0 +1,81 @@
+/**
+ * The `registerDiffTools` install guard (ADR 0029).
+ *
+ * pi keeps a LIST of resolvers and of event handlers per extension, so a second
+ * registration on the SAME extension would stack a duplicate. But a session
+ * replacement (`/new`, `/fork`, `/resume`) reuses pi's cached extension MODULE
+ * while creating a FRESH extension — meta's own comment records exactly that —
+ * so installation has to be keyed to the `pi` handle it is registering on, not
+ * to the module. A module-wide flag hands every session after the first pi's
+ * native `edit`/`write` rows and no result details at all.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { registerDiffTools } from "./index.js";
+
+/** A `pi` handle that records what this registration asked for. */
+function fakePi() {
+  const renderers: ((name: string, next: () => unknown) => unknown)[] = [];
+  const events: string[] = [];
+  return {
+    pi: {
+      registerTool: vi.fn(),
+      registerToolRenderer: (r: (name: string, next: () => unknown) => unknown) => {
+        renderers.push(r);
+      },
+      on: (event: string) => {
+        events.push(event);
+        return () => {};
+      },
+    },
+    renderers,
+    events,
+  };
+}
+
+const themeGetter = () => ({}) as never;
+const configGetter = () => ({
+  diffTheme: "github-dark",
+  diffSplitMinWidth: 150,
+  diffSplitMinCodeWidth: 60,
+});
+
+describe("registerDiffTools install scope", () => {
+  it("does not stack a second set of renderers on the same pi handle", () => {
+    const a = fakePi();
+    // Two `session_start`s on one extension (the case the guard exists for).
+    registerDiffTools(a.pi as never, themeGetter, configGetter);
+    registerDiffTools(a.pi as never, themeGetter, configGetter);
+
+    expect(a.renderers).toHaveLength(2); // edit + write, once each
+    expect(a.events.filter((e) => e === "tool_result")).toHaveLength(2);
+    expect(a.events.filter((e) => e === "tool_call")).toHaveLength(1);
+  });
+
+  it("installs again for a fresh pi handle sharing the cached module", () => {
+    const first = fakePi();
+    registerDiffTools(first.pi as never, themeGetter, configGetter);
+
+    // A session replacement: same imported module, brand new extension.
+    const second = fakePi();
+    registerDiffTools(second.pi as never, themeGetter, configGetter);
+
+    expect(second.renderers).toHaveLength(2);
+    expect(second.events.filter((e) => e === "tool_result")).toHaveLength(2);
+    expect(second.events.filter((e) => e === "tool_call")).toHaveLength(1);
+
+    // The renderers the new extension was handed actually resolve, so the rows
+    // are the Archimedes ones rather than pi's natives.
+    const native = Object.freeze({ native: true });
+    for (const name of ["edit", "write"]) {
+      const resolved = second.renderers.map((r) => r(name, () => native));
+      const mine = resolved.filter((x) => x !== native);
+      expect(mine).toHaveLength(1);
+      expect(typeof (mine[0] as { renderCall?: unknown }).renderCall).toBe("function");
+      expect(typeof (mine[0] as { renderResult?: unknown }).renderResult).toBe("function");
+      // Tools this extension does not own fall through to the next resolver.
+      const other = second.renderers.map((r) => r("read", () => native));
+      expect(other.every((x) => x === native)).toBe(true);
+    }
+  });
+});