@pi-archimedes/core 2.0.1 → 2.2.0

package/README.md

@@ -0,0 +1,51 @@
+# @pi-archimedes/core
+
+The visual foundation and shared infrastructure for pi-archimedes.
+
+Core is what you see first — the animated splash screen, the framed editor, and styled thinking blocks. It is also the invisible glue: an event bus that lets packages talk to each other, shared text and color utilities, and a settings system. Install it standalone for polished chrome, or let the meta package include it automatically.
+
+## What you get
+
+- **Animated splash screen** — configurable reveal animations (9 styles) that set the tone when Pi starts
+- **Framed editor** — custom editor component with double-press quit guard
+- **Styled thinking blocks** — configurable label text, color, and muted theme option; optional code block unindenting
+- **Event bus** — shared pub/sub channel that lets packages communicate (subagent costs → footer, subagent questions → ask, etc.)
+- **Shared utilities** — text truncation/width calculation, color helpers, config loading, settings I/O, and startup profiling
+
+## Install
+
+```bash
+pi install npm:@pi-archimedes/core
+```
+
+Or install full meta package:
+
+```bash
+pi install npm:pi-archimedes
+```
+
+## Usage
+
+Core works automatically when Pi starts. It sets the session header, editor frame, and thinking block renderer automatically. There are no manual commands or tools to call.
+
+For configuration:
+- When using the meta package, run `/archimedes` to access the settings panel.
+- For standalone installs, edit `archimedes.core` in `~/.pi/agent/settings.json`.
+
+## Settings
+
+Core reads configuration from the `archimedes.core` namespace in `~/.pi/agent/settings.json`.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `mutedTheme` | bool | `false` | Use subdued colors for thinking blocks |
+| `codeUnindent` | bool | `true` | Remove common indentation from code blocks inside thinking sections |
+| `labelText` | string | `Thinking...` | Custom prefix shown before thinking blocks |
+| `labelColor` | string | `255,215,0` | RGB color for the thinking label |
+| `animationStyle` | string | `vertical-up` | Splash animation style (9 options) |
+
+## Integration
+
+Core is auto-included by the `pi-archimedes` meta package. All other archimedes packages depend on `@pi-archimedes/core` for the event bus, chrome elements, and utilities. Standalone installation provides the visual chrome and bus without the other archimedes features.
+
+← Back to [pi-archimedes](../../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/core",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -16,6 +16,7 @@
     "./chrome": "./src/chrome.ts",
     "./text": "./src/text.ts",
     "./color": "./src/color.ts",
+    "./overlay": "./src/overlay.ts",
     "./config": "./src/config.ts",
     "./settings-io": "./src/settings-io.ts",
     "./profiler": "./src/profiler.ts"

package/src/config.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("./settings-io.js", () => ({
+  loadConfig: vi.fn(),
+  saveConfig: vi.fn(),
+}));
+
+const { loadCoreConfig, saveCoreConfig, DEFAULT_CORE_CONFIG, ANIMATION_STYLES } =
+  await import("./config.js");
+const { loadConfig, saveConfig } = await import("./settings-io.js");
+
+describe("loadCoreConfig", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("uses correct namespace", () => {
+    vi.mocked(loadConfig).mockReturnValue(DEFAULT_CORE_CONFIG);
+    loadCoreConfig();
+    expect(loadConfig).toHaveBeenCalledWith("archimedes.core", DEFAULT_CORE_CONFIG);
+  });
+
+  it("returns default config when no settings exist", () => {
+    vi.mocked(loadConfig).mockReturnValue(DEFAULT_CORE_CONFIG);
+    const result = loadCoreConfig();
+    expect(result).toEqual({
+      mutedTheme: false,
+      codeUnindent: true,
+      labelText: "Thinking...",
+      labelColor: "255,215,0",
+      animationStyle: "vertical-up",
+    });
+  });
+
+  it("passes through merged config from settings-io", () => {
+    const merged = { ...DEFAULT_CORE_CONFIG, mutedTheme: true };
+    vi.mocked(loadConfig).mockReturnValue(merged);
+    const result = loadCoreConfig();
+    expect(result).toEqual(merged);
+  });
+});
+
+describe("saveCoreConfig", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("saves with correct namespace", () => {
+    saveCoreConfig(DEFAULT_CORE_CONFIG);
+    expect(saveConfig).toHaveBeenCalledWith("archimedes.core", DEFAULT_CORE_CONFIG);
+  });
+
+  it("passes config through unchanged", () => {
+    const config = { ...DEFAULT_CORE_CONFIG, mutedTheme: true };
+    saveCoreConfig(config);
+    expect(saveConfig).toHaveBeenCalledWith("archimedes.core", config);
+  });
+});
+
+describe("DEFAULT_CORE_CONFIG", () => {
+  it("has the expected shape", () => {
+    expect(DEFAULT_CORE_CONFIG).toEqual({
+      mutedTheme: false,
+      codeUnindent: true,
+      labelText: "Thinking...",
+      labelColor: "255,215,0",
+      animationStyle: "vertical-up",
+    });
+  });
+});
+
+describe("ANIMATION_STYLES", () => {
+  it("contains all expected styles", () => {
+    expect(ANIMATION_STYLES).toEqual([
+      "diagonal",
+      "top-right",
+      "bottom-left",
+      "bottom-right",
+      "center-out",
+      "wave",
+      "horizontal",
+      "vertical",
+      "vertical-up",
+    ]);
+  });
+});

package/src/overlay.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect } from "vitest";
+import {
+  visibleWidth,
+  padEnd,
+  wrapText,
+  hardTruncate,
+  renderHeader,
+  renderFooter,
+  wrapWithBorder,
+  borderContentWidth,
+  OVERLAY_CHROME,
+  type OverlayTheme,
+} from "./overlay.js";
+
+// Mock theme: fg returns its text argument untouched.
+const mockTheme: OverlayTheme = {
+  fg: (_color: string, text: string) => text,
+};
+
+// Mock theme that records the color token passed to fg.
+function recordingTheme() {
+  let lastColor: string | null = null;
+  const theme: OverlayTheme = {
+    fg: (color: string, text: string) => {
+      lastColor = color;
+      return text;
+    },
+  };
+  return { theme, lastColor: () => lastColor };
+}
+
+// ── visibleWidth ─────────────────────────────────────────────────────────────
+
+describe("visibleWidth", () => {
+  it("counts a plain string", () => {
+    expect(visibleWidth("hello")).toBe(5);
+  });
+
+  it("ignores ANSI SGR codes", () => {
+    expect(visibleWidth("\x1b[31mred\x1b[0m")).toBe(3);
+  });
+
+  it("returns 0 for empty string", () => {
+    expect(visibleWidth("")).toBe(0);
+  });
+});
+
+// ── padEnd ───────────────────────────────────────────────────────────────────
+
+describe("padEnd", () => {
+  it("pads to width", () => {
+    expect(padEnd("hi", 5)).toBe("hi   ");
+  });
+
+  it("returns input unchanged when visible width >= target", () => {
+    expect(padEnd("hello", 5)).toBe("hello");
+    expect(padEnd("toolong", 5)).toBe("toolong");
+  });
+
+  it("returns '' for width <= 0", () => {
+    expect(padEnd("text", 0)).toBe("");
+    expect(padEnd("text", -3)).toBe("");
+  });
+});
+
+// ── wrapText ─────────────────────────────────────────────────────────────────
+
+describe("wrapText", () => {
+  it("wraps a long line to width", () => {
+    expect(wrapText("aaa bbb ccc ddd", 8)).toEqual(["aaa bbb ", "ccc ddd"]);
+  });
+
+  it("wraps long words to width", () => {
+    expect(wrapText("hello world", 5)).toEqual(["hello", " ", "world"]);
+  });
+
+  it("preserves empty paragraphs as blank lines", () => {
+    expect(wrapText("one\n\ntwo", 10)).toEqual(["one", "", "two"]);
+  });
+
+  it("returns [] for width <= 0", () => {
+    expect(wrapText("anything", 0)).toEqual([]);
+  });
+});
+
+// ── hardTruncate ─────────────────────────────────────────────────────────────
+
+describe("hardTruncate", () => {
+  it("leaves short strings alone", () => {
+    expect(hardTruncate("short", 10)).toBe("short");
+  });
+
+  it("truncates at the visible-width boundary", () => {
+    expect(hardTruncate("hello world", 5)).toBe("hello");
+  });
+
+  it("truncates an ANSI-colored string and appends a reset", () => {
+    const result = hardTruncate("\x1b[31mhello world\x1b[0m", 5);
+    expect(result).toBe("\x1b[31mhello\x1b[0m");
+    expect(result).toContain("\x1b[0m");
+  });
+});
+
+// ── renderHeader / renderFooter ──────────────────────────────────────────────
+
+describe("renderHeader", () => {
+  it("pads to width and renders with the accent token", () => {
+    const { theme, lastColor } = recordingTheme();
+    const out = renderHeader(" Title ", 10, theme);
+    expect(out).toBe(" Title    ");
+    expect(lastColor()).toBe("accent");
+  });
+});
+
+describe("renderFooter", () => {
+  it("pads to width and renders with the dim token", () => {
+    const { theme, lastColor } = recordingTheme();
+    const out = renderFooter(" hint ", 10, theme);
+    expect(out).toBe(" hint     ");
+    expect(lastColor()).toBe("dim");
+  });
+});
+
+// ── wrapWithBorder / borderContentWidth ──────────────────────────────────────
+
+describe("borderContentWidth", () => {
+  it("derives content width from outer width", () => {
+    expect(borderContentWidth(84)).toBe(80);
+  });
+
+  it("floors at 1 for tiny widths", () => {
+    expect(borderContentWidth(0)).toBe(1);
+    expect(borderContentWidth(2)).toBe(1);
+  });
+});
+
+describe("wrapWithBorder", () => {
+  const W = 84;
+
+  it("emits border rows with the correct shape", () => {
+    const out = wrapWithBorder(["a", "b"], W, mockTheme);
+    expect(out[0]).toBe("┌" + "─".repeat(W - 2) + "┐");
+    expect(out[out.length - 1]).toBe("└" + "─".repeat(W - 2) + "┘");
+    expect(out[1]).toBe("│ a" + " ".repeat(W - 4) + "│");
+    expect(out[2]).toBe("│ b" + " ".repeat(W - 4) + "│");
+  });
+
+  it("emits exactly lines.length + 2 rows", () => {
+    const out = wrapWithBorder(["a", "b", "c"], W, mockTheme);
+    expect(out.length).toBe(5);
+  });
+
+  it("pads every row to exactly the outer width", () => {
+    const out = wrapWithBorder(["x", "shorter", "y"], W, mockTheme);
+    for (const line of out) {
+      expect(visibleWidth(line)).toBe(W);
+    }
+  });
+
+  it("hard-truncates content wider than the content width, without overflowing", () => {
+    const long = "z".repeat(W + 10); // wider than the 80-col content area
+    const out = wrapWithBorder([long], W, mockTheme);
+    expect(out.length).toBe(3);
+    for (const line of out) {
+      expect(visibleWidth(line)).toBe(W);
+    }
+    expect(out[1]).toBe("│ " + "z".repeat(W - 4) + " │");
+  });
+});
+
+// ── OVERLAY_CHROME ───────────────────────────────────────────────────────────
+
+describe("OVERLAY_CHROME", () => {
+  it("matches the /agents overlay options", () => {
+    expect(OVERLAY_CHROME).toEqual({
+      anchor: "center",
+      width: 84,
+      maxHeight: "80%",
+    });
+  });
+});

package/src/overlay.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared overlay chrome — border wrapping, text width math, header/footer
+ * rendering. Used by the /agents manager (subagent) and the /archimedes
+ * settings overlay (meta) so both screens look identical.
+ */
+
+/** Minimal structural theme — anything with `fg` satisfies it (the real pi-coding-agent Theme, agent-manager's local interface, or a test mock). */
+export interface OverlayTheme {
+  fg(token: string, text: string): string;
+}
+
+export function wrapText(text: string, width: number): string[] {
+  if (width <= 0) return [];
+  const lines: string[] = [];
+  const paragraphs = text.split("\n");
+  for (const para of paragraphs) {
+    if (para.length === 0) {
+      lines.push("");
+      continue;
+    }
+    const words = para.split(/(\s+)/).filter(Boolean);
+    let current = "";
+    for (const word of words) {
+      const test = current === "" ? word : current + word;
+      if (test.length > width && current.length > 0) {
+        lines.push(current);
+        current = word;
+      } else {
+        current = test;
+      }
+    }
+    if (current) lines.push(current);
+  }
+  return lines;
+}
+
+export function padEnd(text: string, width: number): string {
+  if (width <= 0) return "";
+  const vw = visibleWidth(text);
+  if (vw >= width) return text;
+  return text + " ".repeat(width - vw);
+}
+
+export function visibleWidth(text: string): number {
+  // Strip ANSI escape sequences for width calculation
+  return text.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+export function renderHeader(text: string, width: number, theme: OverlayTheme): string {
+  return theme.fg("accent", padEnd(text, width));
+}
+
+export function renderFooter(text: string, width: number, theme: OverlayTheme): string {
+  return theme.fg("dim", padEnd(text, width));
+}
+
+/** Content width available inside wrapWithBorder at a given outer width.
+ *  inner = max(1, width - 2); content = max(1, inner - 2). */
+export function borderContentWidth(width: number): number {
+  const innerWidth = Math.max(1, width - 2);
+  return Math.max(1, innerWidth - 2);
+}
+
+/** Shared overlay options so /agents and /archimedes never drift. */
+export const OVERLAY_CHROME = { anchor: "center", width: 84, maxHeight: "80%" } as const;
+
+// ── Border wrapper ────────────────────────────────────────────────────────────
+
+/** Hard-truncate by visible width — no "..." suffix. Strips ANSI, truncates, rebuilds. */
+export function hardTruncate(text: string, maxVisible: number): string {
+  if (visibleWidth(text) <= maxVisible) return text;
+  // Walk the string, skipping ANSI escape sequences, and stop after
+  // maxVisible visible characters; copy SGR codes through so styling survives,
+  // and append a reset at the end so styling doesn't bleed.
+  let result = "";
+  let plainPos = 0;
+  let i = 0;
+  let copiedSgr = false;
+  while (i < text.length && plainPos < maxVisible) {
+    if (text[i] === "\x1b" && text[i + 1] === "[") {
+      // Copy the escape sequence
+      let j = i;
+      while (j < text.length && text[j] !== "m") j++;
+      result += text.slice(i, j + 1);
+      copiedSgr = true;
+      i = j + 1;
+    } else {
+      result += text[i];
+      plainPos++;
+      i++;
+    }
+  }
+  // Ensure styling doesn't bleed: append reset if we copied SGR and result doesn't end with one
+  if (copiedSgr && !/\x1b\[0?m$/.test(result)) {
+    result += "\x1b[0m";
+  }
+  return result;
+}
+
+export function wrapWithBorder(lines: string[], width: number, theme: OverlayTheme): string[] {
+  const innerWidth = Math.max(1, width - 2);
+  const contentWidth = Math.max(1, innerWidth - 2); // minus 1 space padding each side
+  const left = theme.fg("dim", "│");
+  const right = theme.fg("dim", "│");
+  const top = theme.fg("dim", `┌${"─".repeat(innerWidth)}┐`);
+  const bottom = theme.fg("dim", `└${"─".repeat(innerWidth)}┘`);
+  const result: string[] = [top];
+  for (const line of lines) {
+    const clamped = hardTruncate(line, contentWidth);
+    const padded = " " + padEnd(clamped, contentWidth) + " ";
+    result.push(left + padded + right);
+  }
+  result.push(bottom);
+  return result;
+}

package/src/settings-io.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ── hoisted: must use require() since vi.hoisted runs before imports ────────
+
+const { tempDir, fs, join, tmpdir, randomUUID } = vi.hoisted(() => {
+  const fs = require("node:fs");
+  const { join } = require("node:path");
+  const { tmpdir } = require("node:os");
+  const { randomUUID } = require("node:crypto");
+  const dir = join(tmpdir(), `settings-io-test-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return { tempDir: dir, fs, join, tmpdir, randomUUID };
+});
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => tempDir,
+}));
+
+// Import after mocks are set up
+const { loadConfig, saveConfig } = await import("./settings-io.js");
+
+describe("loadConfig", () => {
+  beforeEach(() => {
+    // Clean up settings file before each test
+    const settingsPath = join(tempDir, "settings.json");
+    if (fs.existsSync(settingsPath)) {
+      fs.unlinkSync(settingsPath);
+    }
+  });
+
+  afterEach(() => {
+    // Clean up temp dir artifacts
+    const settingsPath = join(tempDir, "settings.json");
+    const tmpPath = settingsPath + ".tmp";
+    try { fs.unlinkSync(settingsPath); } catch { /* ignore */ }
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+  });
+
+  it("returns defaults when settings missing", () => {
+    const result = loadConfig("test.ns", { foo: "bar", count: 42 });
+    expect(result).toEqual({ foo: "bar", count: 42 });
+  });
+
+  it("merges settings over defaults", () => {
+    const settingsPath = join(tempDir, "settings.json");
+    fs.writeFileSync(
+      settingsPath,
+      JSON.stringify({ "test.ns": { foo: "overridden" } }),
+      "utf-8",
+    );
+    const result = loadConfig("test.ns", { foo: "bar", count: 42 });
+    expect(result).toEqual({ foo: "overridden", count: 42 });
+  });
+
+  it("returns defaults on corrupt JSON", () => {
+    const settingsPath = join(tempDir, "settings.json");
+    fs.writeFileSync(settingsPath, "{ invalid json }", "utf-8");
+    const result = loadConfig("test.ns", { foo: "bar", count: 42 });
+    expect(result).toEqual({ foo: "bar", count: 42 });
+  });
+});
+
+describe("saveConfig", () => {
+  beforeEach(() => {
+    const settingsPath = join(tempDir, "settings.json");
+    if (fs.existsSync(settingsPath)) {
+      fs.unlinkSync(settingsPath);
+    }
+  });
+
+  afterEach(() => {
+    const settingsPath = join(tempDir, "settings.json");
+    const tmpPath = settingsPath + ".tmp";
+    try { fs.unlinkSync(settingsPath); } catch { /* ignore */ }
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+  });
+
+  it("writes atomically (tmp + rename)", () => {
+    saveConfig("test.ns", { foo: "bar" });
+    const settingsPath = join(tempDir, "settings.json");
+    expect(fs.existsSync(settingsPath)).toBe(true);
+    const tmpPath = settingsPath + ".tmp";
+    expect(fs.existsSync(tmpPath)).toBe(false);
+    const data = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    expect(data["test.ns"]).toEqual({ foo: "bar" });
+  });
+
+  it("persists data for subsequent loads", () => {
+    saveConfig("test.ns", { foo: "bar", count: 42 });
+    const result = loadConfig("test.ns", { foo: "default", count: 0 });
+    expect(result).toEqual({ foo: "bar", count: 42 });
+  });
+
+  it("writes data correctly on success path", () => {
+    saveConfig("test.ns", { foo: "bar" });
+    const settingsPath = join(tempDir, "settings.json");
+    expect(fs.existsSync(settingsPath)).toBe(true);
+    const data = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    expect(data["test.ns"]).toEqual({ foo: "bar" });
+    // No .tmp file should remain after successful rename
+    expect(fs.existsSync(settingsPath + ".tmp")).toBe(false);
+  });
+});