pi-minimalist 0.1.0

package/src/config-file.ts

@@ -0,0 +1,277 @@
+/**
+ * Reading and writing the `minimalist` key in Pi's settings.json.
+ *
+ * WHY settings.json AND NOT OUR OWN FILE
+ * --------------------------------------
+ * The old `pi-minimalist.json` was a second config file the user had to know
+ * about, and it hardcoded `~/.pi/agent`, so anyone setting
+ * `PI_CODING_AGENT_DIR` silently wrote their preference somewhere it would never
+ * be read back. settings.json is where a Pi user already looks, it is what
+ * `pi-env` reads, and Pi tolerates unknown top-level keys (the published
+ * `pi-powerline-footer` extension does exactly this with its `powerline` key).
+ *
+ * SCOPE
+ *   defaults  <  global agent settings.json (PI_CODING_AGENT_DIR if set).
+ *   Project-local `minimalist` blocks are deliberately ignored.
+ *
+ * FAILURE POLICY
+ * This file is hand-edited by a human, so a syntax error must never take the UI
+ * down: every read failure falls back to defaults, and a malformed value is
+ * ignored field by field so one bad line cannot disable the rest.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  BASIC_KEYS,
+  DEFAULT_BASIC,
+  DEFAULTS,
+  DEFAULT_TOKENS,
+  GLYPH_PRESETS,
+  SETTINGS_KEY,
+  type BasicSettings,
+  type Glyphs,
+  type Settings,
+  type Tokens,
+} from "./config.ts";
+
+/**
+ * Pi's config directory.
+ *
+ * Two lines copied from Pi's `getAgentDir()` on purpose: importing it pulls in
+ * the package's whole module graph (~17MB), which would make `./run-tests.sh
+ * --unit` depend on a full Pi install. `test/integration.test.ts` asserts this
+ * copy agrees with Pi's real implementation, so it cannot drift unnoticed.
+ */
+export function agentDir(env = process.env): string {
+  return env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+}
+
+export function globalSettingsPath(env = process.env): string {
+  return join(agentDir(env), "settings.json");
+}
+
+/** Legacy state file written by the removed `/quiet` command. */
+export function legacyQuietPath(env = process.env): string {
+  return join(agentDir(env), "pi-minimalist.json");
+}
+
+type Json = Record<string, unknown>;
+
+function isRecord(value: unknown): value is Json {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------------------
+// JSON comments
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove `//` and block comments that are outside string literals.
+ *
+ * Pi bundles `strip-json-comments` but does not re-export it to extensions, so
+ * this is a small character scanner. The only real subtlety is that `//` inside a
+ * JSON string (a URL, a Windows path) must NOT start a comment.
+ */
+export function stripJsonComments(text: string): string {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  let comment: "line" | "block" | undefined;
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    const next = text[i + 1];
+
+    if (comment === "line") {
+      if (char === "\n") {
+        comment = undefined;
+        out += char;
+      }
+      continue;
+    }
+    if (comment === "block") {
+      if (char === "*" && next === "/") {
+        comment = undefined;
+        i++;
+      }
+      continue;
+    }
+    if (inString) {
+      out += char;
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      out += char;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      comment = "line";
+      i++;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      comment = "block";
+      i++;
+      continue;
+    }
+    out += char;
+  }
+  return out;
+}
+
+/** True when a file carries comments, so writing it back would destroy them. */
+export function hasComments(text: string): boolean {
+  return stripJsonComments(text).length !== text.length;
+}
+
+// ---------------------------------------------------------------------------
+// Reading
+// ---------------------------------------------------------------------------
+
+/** Parse a settings file. Any failure yields `{}` — never throws. */
+function readSettingsFile(path: string): Json {
+  try {
+    if (!existsSync(path)) return {};
+    // Pi supports comments in settings.json, so tolerate them when READING.
+    const parsed = JSON.parse(stripJsonComments(readFileSync(path, "utf8")));
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Take only well-typed fields from raw JSON.
+ *
+ * Field-by-field so one bad value cannot poison the rest, which matters because
+ * this is hand-edited input.
+ */
+function coerce(raw: unknown, into: Settings): Settings {
+  if (!isRecord(raw)) return into;
+  const out = { ...into };
+
+  for (const key of BASIC_KEYS) {
+    if (typeof DEFAULT_BASIC[key] === "boolean" && typeof raw[key] === "boolean") {
+      // BASIC_KEYS also contains the enum below; the runtime default narrows the
+      // assignable values more honestly than a second maintained key list.
+      (out as Record<string, unknown>)[key] = raw[key];
+    }
+  }
+  if (raw.activitySummary === "elapsed" || raw.activitySummary === "tools") {
+    out.activitySummary = raw.activitySummary;
+  }
+  if (Array.isArray(raw.excludeTools)) {
+    out.excludeTools = raw.excludeTools.filter((name): name is string => typeof name === "string");
+  }
+  if (raw.glyphStyle === "unicode" || raw.glyphStyle === "ascii") {
+    out.glyphStyle = raw.glyphStyle;
+  }
+  if (isRecord(raw.glyphs)) {
+    out.glyphs = pickStrings(raw.glyphs, Object.keys(GLYPH_PRESETS.unicode) as (keyof Glyphs)[]);
+  }
+  if (isRecord(raw.tokens)) {
+    // A token NAME cannot be validated here: the set of valid names is Pi's theme
+    // palette, which this file deliberately does not import. An unknown name
+    // throws inside theme.fg/bg at paint time, and core then falls back to its
+    // verbose card — visibly wrong, rather than silently mispainted. The cast is
+    // therefore the honest boundary of what this function can check.
+    out.tokens = pickStrings(raw.tokens, Object.keys(DEFAULT_TOKENS) as (keyof Tokens)[]) as Partial<Tokens>;
+  }
+  if (typeof raw.maxDetailChars === "number" && raw.maxDetailChars > 0) {
+    out.maxDetailChars = Math.floor(raw.maxDetailChars);
+  }
+  return out;
+}
+
+/** Copy only the string-valued keys we recognize. */
+function pickStrings<K extends string>(raw: Json, keys: K[]): Partial<Record<K, string>> {
+  const out: Partial<Record<K, string>> = {};
+  for (const key of keys) {
+    if (typeof raw[key] === "string") out[key] = raw[key] as string;
+  }
+  return out;
+}
+
+/** Read only the global agent settings, never project-local preferences. */
+export function loadSettings(env = process.env): Settings {
+  const global = readSettingsFile(globalSettingsPath(env));
+  return coerce(global[SETTINGS_KEY], DEFAULTS);
+}
+
+/**
+ * One-time migration of the old `/quiet` preference.
+ *
+ * Returns a value only when settings.json has no `groupToolRuns` yet, so an
+ * explicit new setting always wins and a stale legacy file cannot resurrect a
+ * preference the user has since changed.
+ */
+export function migratedQuiet(env = process.env): boolean | undefined {
+  const existing = readSettingsFile(globalSettingsPath(env))[SETTINGS_KEY];
+  if (isRecord(existing) && typeof existing.groupToolRuns === "boolean") return undefined;
+  try {
+    const legacy = JSON.parse(readFileSync(legacyQuietPath(env), "utf8"));
+    return isRecord(legacy) && legacy.quiet === true ? true : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+
+export type SaveResult =
+  | { ok: true }
+  | { ok: false; reason: "comments" | "unparsable" | "write"; detail?: string };
+
+/**
+ * Persist only the supplied editor-managed settings into the global agent file.
+ * A normal edit passes one key; Restore defaults intentionally passes all.
+ * Hand-written `glyphs`/`tokens`/`excludeTools` values survive untouched.
+ *
+ * REFUSES to write a file containing comments. `JSON.stringify` would silently
+ * delete them, and quietly destroying an annotated config is far worse than
+ * asking the user to edit one line by hand.
+ */
+export function saveBasicSettings(settings: Partial<BasicSettings>, env = process.env): SaveResult {
+  const path = globalSettingsPath(env);
+
+  let raw = "";
+  try {
+    if (existsSync(path)) raw = readFileSync(path, "utf8");
+  } catch (error) {
+    return { ok: false, reason: "write", detail: String(error) };
+  }
+  if (raw && hasComments(raw)) return { ok: false, reason: "comments", detail: path };
+
+  let root: unknown;
+  try {
+    root = raw.trim() ? JSON.parse(raw) : {};
+  } catch (error) {
+    return { ok: false, reason: "unparsable", detail: String(error) };
+  }
+  if (!isRecord(root)) return { ok: false, reason: "unparsable", detail: path };
+
+  if (root[SETTINGS_KEY] !== undefined && !isRecord(root[SETTINGS_KEY])) {
+    return { ok: false, reason: "unparsable", detail: path };
+  }
+  const existing = isRecord(root[SETTINGS_KEY]) ? root[SETTINGS_KEY] : {};
+  const merged: Json = { ...existing };
+  for (const key of BASIC_KEYS) {
+    if (settings[key] !== undefined) merged[key] = settings[key];
+  }
+
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({ ...root, [SETTINGS_KEY]: merged }, null, 2)}\n`);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, reason: "write", detail: String(error) };
+  }
+}

package/src/config-ui.ts

@@ -0,0 +1,208 @@
+/** `/minimalist` (also `/minimalist config`) — Pi's SettingsList with live, conditional rows. */
+
+import { truncateToWidth, type AutocompleteItem, type Component, type SettingItem, type SettingsList, type SettingsListTheme } from "@earendil-works/pi-tui";
+import {
+  BASIC_KEYS,
+  DEFAULT_BASIC,
+  type BasicKey,
+  type BasicSettings,
+  type Config,
+  type Settings,
+} from "./config.ts";
+
+type Field = {
+  key: BasicKey;
+  label: string;
+  description: string;
+  /** Hidden until prose folding is on. */
+  activityOption?: boolean;
+};
+
+/** Label and hover description for every basic setting, in display order. */
+export const FIELDS: Field[] = [
+  {
+    key: "compactToolRows",
+    label: "Compact tool rows",
+    description: "Show each tool call as one line instead of Pi's full card. Off restores Pi's native rendering.",
+  },
+  {
+    key: "groupToolRuns",
+    label: "Combine consecutive tool calls",
+    description: "Replace consecutive finished tool calls with a single count, e.g. 'read ×2, edit ×1'.",
+  },
+  {
+    key: "foldIntermediateActivity",
+    label: "Collapse earlier activity",
+    description: "Keep the latest assistant reply visible; replace earlier text, thinking, and tool calls with one summary.",
+  },
+  {
+    key: "foldActivityOnFinalAnswer",
+    label: "  Collapse when final answer starts",
+    description: "Keep work visible until OpenAI starts its final answer, then collapse the earlier activity.",
+    activityOption: true,
+  },
+  {
+    key: "activitySummary",
+    label: "  Activity summary",
+    description: "Show either elapsed work time or the tools used in place of folded activity.",
+    activityOption: true,
+  },
+  {
+    key: "gutter",
+    label: "Left border",
+    description: "Show a coloured bar to the left of each row, making tool calls easier to spot.",
+  },
+  {
+    key: "timer",
+    label: "Elapsed timer",
+    description: "Show how long a running tool has taken, updated once per second.",
+  },
+  {
+    key: "thinkingAsToolCall",
+    label: "Compact thinking rows",
+    description: "Show collapsed thinking as a compact tool-style row. Off restores Pi's native thinking rendering.",
+  },
+  {
+    key: "keepActiveToolsExpanded",
+    label: "Keep running tools out of groups",
+    description: "Never fold a tool that is still running, so you can watch its progress.",
+  },
+  {
+    key: "keepActiveThinkingExpanded",
+    label: "Show thinking while generating",
+    description: "Show the full thinking block as it arrives, instead of a one-line preview.",
+  },
+  {
+    key: "glyphStyle",
+    label: "Symbols",
+    description: "Use ordinary Unicode symbols, or switch to ASCII if some symbols are missing or misaligned. A Nerd Font is not required.",
+  },
+];
+
+type InputComponent = Component & { handleInput(data: string): void };
+type SettingsListConstructor = new (...args: ConstructorParameters<typeof SettingsList>) => SettingsList;
+type BasicValue = BasicSettings[BasicKey];
+
+/** Conditional rows plus their display values. */
+export function items(settings: Settings): SettingItem[] {
+  return FIELDS.filter((field) => !field.activityOption || settings.foldIntermediateActivity).map(
+    ({ key, label, description }) => {
+      const value = settings[key];
+      return {
+        id: key,
+        label,
+        description,
+        currentValue: displayValue(value),
+        values: key === "activitySummary" ? ["elapsed time", "tools used"] : key === "glyphStyle" ? ["Unicode", "ASCII"] : ["on", "off"],
+      };
+    },
+  );
+}
+
+export type ConfigScreenDeps = {
+  SettingsList: SettingsListConstructor;
+  theme: SettingsListTheme;
+  config: Config;
+  onChange: (key: BasicKey, value: BasicValue) => void;
+  onReset: () => void;
+  onClose: () => void;
+};
+
+/** Build a live screen; toggling prose folding immediately adds/removes its two child rows. */
+export function createConfigScreen(deps: ConfigScreenDeps): InputComponent {
+  const { SettingsList, theme, config, onChange, onReset, onClose } = deps;
+  let list: SettingsList;
+
+  const build = () => {
+    const rows = [
+      ...items(config.all()),
+      {
+        id: "restoreDefaults",
+        label: "Restore defaults",
+        description: "Reset the settings in this editor, including Symbols. Custom glyphs, colours, and excluded tools are kept.",
+        currentValue: "Enter to restore",
+        values: ["Restore"],
+      },
+    ];
+    return new SettingsList(
+      rows,
+      rows.length,
+      theme,
+      (id, displayValue) => {
+        if (id === "restoreDefaults") {
+          for (const key of BASIC_KEYS) config.set(key, DEFAULT_BASIC[key]);
+          onReset();
+          list = build();
+          list.selectItem(id);
+          return;
+        }
+        if (!isBasicKey(id)) return;
+        if (id === "activitySummary") {
+          const value = displayValue === "tools used" ? "tools" : "elapsed";
+          config.set(id, value);
+          onChange(id, value);
+        } else if (id === "glyphStyle") {
+          const value = displayValue === "ASCII" ? "ascii" : "unicode";
+          config.set(id, value);
+          onChange(id, value);
+        } else {
+          const value = displayValue === "on";
+          config.set(id, value);
+          onChange(id, value);
+        }
+        if (id === "foldIntermediateActivity") {
+          list = build();
+          list.selectItem(id);
+        }
+      },
+      onClose,
+    );
+  };
+
+  list = build();
+  return {
+    render: (width) => [
+      ...list.render(width),
+      truncateToWidth(theme.hint("  Changes apply live · Ctrl+O reveals tool output"), width),
+    ],
+    handleInput: (data) => list.handleInput(data),
+    handleMouse: (event) => list.handleMouse?.(event),
+    invalidate: () => list.invalidate?.(),
+  };
+}
+
+function isBasicKey(id: string): id is BasicKey {
+  return (BASIC_KEYS as string[]).includes(id);
+}
+
+function displayValue(value: BasicValue): string {
+  if (value === "elapsed") return "elapsed time";
+  if (value === "tools") return "tools used";
+  if (value === "unicode") return "Unicode";
+  if (value === "ascii") return "ASCII";
+  return value ? "on" : "off";
+}
+
+/** Argument completions for `/minimalist ...`. */
+export function argumentCompletions(prefix: string): AutocompleteItem[] | null {
+  const items: AutocompleteItem[] = [
+    { value: "config", label: "config", description: "Open the settings editor" },
+    { value: "status", label: "status", description: "Show current settings" },
+  ];
+  const filtered = items.filter((item) => item.value.startsWith(prefix));
+  return filtered.length > 0 ? filtered : null;
+}
+
+/** One-line-per-visible-setting summary for `/minimalist status`. */
+export function summary(settings: Settings): string {
+  const visible = FIELDS.filter((field) => !field.activityOption || settings.foldIntermediateActivity);
+  const width = Math.max(...visible.map((field) => field.label.length));
+  return [
+    ...visible.map(({ key, label }) => {
+      return `  ${label.padEnd(width)}  ${displayValue(settings[key])}`;
+    }),
+    "",
+    "  /minimalist          change these",
+    "  settings.json        custom glyphs, colours, excluded tools",
+  ].join("\n");
+}