@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-model-modes/src/footer.ts

@@ -0,0 +1,200 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedMode } from "./presets.js";
+import {
+  getActiveMode,
+  getDefaultMode,
+  resolveActiveModePlan,
+} from "./resolver.js";
+import { CYCLE_FORWARD_KEY, CYCLE_BACKWARD_KEY } from "./keybinding.js";
+
+type Theme = ExtensionContext["ui"]["theme"];
+
+/**
+ * Unique plugin-owned status slot. The visible label lives in the value
+ * (`mode: ◆ create`) so custom footers can render extension statuses directly
+ * without relying on any footer's key-prefix behavior.
+ */
+export const MODE_FOOTER_KEY = "pi-model-modes";
+
+/**
+ * Leading marker glyph per base voice. Echoes pi-catppuccin-tui's ◆ vocabulary
+ * so the mode footer reads as part of the same family as the model/git/context
+ * line rather than a foreign symbol. Glyph choice tracks voice *character*:
+ * solid for pi-family voices (default `pi` and the more-terse `pi-direct`),
+ * outline for `chill`'s softer voice, hex for `flow`'s distinct character.
+ *
+ * The raw glyphs stay plain Unicode for stable tests and fallback renderers;
+ * the pi seam applies theme-aware color so Catppuccin footers inherit the
+ * active flavor instead of hardcoded ANSI escapes.
+ */
+const BASE_VOICE_GLYPHS: Readonly<Record<string, string>> = {
+  pi: "◆",
+  "pi-direct": "◆",
+  chill: "◇",
+  flow: "⬡",
+};
+
+/** Distinct error glyph for an unresolvable mode; wins over any partial mode. */
+const UNRESOLVABLE_GLYPH = "✕";
+
+/** Fallback when no mode is active or the base is unrecognized. */
+const DEFAULT_GLYPH = "◆";
+
+/**
+ * PURE: glyph for a base voice, with a default fallback for unset / unknown
+ * bases (forward-compat for new base voices added later). Used directly by
+ * callers that know a base but not the full `ModeFooterInputs` shape (e.g. the
+ * cycle-keybinding toast, which matches the footer's leading glyph so the
+ * toast and the footer agree visually).
+ */
+export function glyphForBase(base: string | undefined): string {
+  if (base === undefined) return DEFAULT_GLYPH;
+  return BASE_VOICE_GLYPHS[base] ?? DEFAULT_GLYPH;
+}
+
+/**
+ * PURE: pick the leading footer glyph for the current state.
+ *
+ * Precedence mirrors the indicator itself: modeError wins, then unset falls
+ * back to the default glyph, then the per-base-voice map.
+ */
+export function selectModeGlyph(inputs: ModeFooterInputs): string {
+  if (inputs.modeError !== undefined) return UNRESOLVABLE_GLYPH;
+  return glyphForBase(inputs.mode?.base);
+}
+
+/** PURE inputs to the footer render (no pi coupling). */
+export interface ModeFooterInputs {
+  /** Effective preset name when the spec is a string preset. */
+  specName: string | undefined;
+  /** Resolved axes; undefined means no effective mode. */
+  mode: ResolvedMode | undefined;
+  /** Broken active/default mode; wins over a resolved mode. */
+  modeError: string | undefined;
+  /** Whether cycle keybindings are registered and the footer hint is honest. */
+  cycleHintEnabled: boolean;
+  /** Forward cycle key text, forwarded verbatim from the keybinding seam. */
+  cycleForwardKey: string;
+  /** Backward cycle key text, forwarded verbatim from the keybinding seam. */
+  cycleBackwardKey: string;
+}
+
+/** PURE styling hooks for the mode footer render. Defaults are identity. */
+export interface ModeFooterStyle {
+  label(text: string, inputs: ModeFooterInputs): string;
+  glyph(text: string, inputs: ModeFooterInputs): string;
+  value(text: string, inputs: ModeFooterInputs): string;
+  modifier(text: string, inputs: ModeFooterInputs): string;
+  separator(text: string, inputs: ModeFooterInputs): string;
+  hint(text: string, inputs: ModeFooterInputs): string;
+}
+
+const PLAIN_MODE_FOOTER_STYLE: ModeFooterStyle = {
+  label: (text) => text,
+  glyph: (text) => text,
+  value: (text) => text,
+  modifier: (text) => text,
+  separator: (text) => text,
+  hint: (text) => text,
+};
+
+/**
+ * Catppuccin-compatible styling: use semantic pi theme tokens so the selected
+ * Catppuccin flavor (or any other theme) owns the actual colors.
+ */
+export function createThemedModeFooterStyle(theme: Theme): ModeFooterStyle {
+  return {
+    label: (text) => theme.fg("muted", text),
+    glyph: (text, inputs) => {
+      if (inputs.modeError !== undefined) return theme.fg("error", text);
+      if (inputs.mode === undefined) return theme.fg("dim", text);
+      return theme.fg("accent", text);
+    },
+    value: (text, inputs) => {
+      if (inputs.modeError !== undefined) return theme.fg("error", text);
+      if (inputs.mode === undefined) return theme.fg("dim", text);
+      return theme.fg("toolTitle", text);
+    },
+    modifier: (text) => theme.fg("accent", text),
+    separator: (text) => theme.fg("dim", text),
+    hint: (text) => theme.fg("dim", text),
+  };
+}
+
+/** PURE: build the one-line footer string. Always returns a string. */
+export function formatModeFooter(
+  inputs: ModeFooterInputs,
+  style: ModeFooterStyle = PLAIN_MODE_FOOTER_STYLE,
+): string {
+  const glyph = selectModeGlyph(inputs);
+  let value: string;
+  if (inputs.modeError !== undefined) {
+    value = "unresolvable";
+  } else if (inputs.mode === undefined) {
+    value = "unset";
+  } else if (inputs.specName !== undefined) {
+    value = inputs.specName;
+  } else {
+    value = `${inputs.mode.base}/${inputs.mode.agency}/${inputs.mode.quality}/${inputs.mode.scope}`;
+  }
+  let indicator = `${style.label("mode:", inputs)} ${style.glyph(glyph, inputs)} ${style.value(value, inputs)}`;
+
+  if (inputs.modeError === undefined && inputs.mode !== undefined && inputs.mode.modifiers.length > 0) {
+    indicator += ` ${style.modifier(`+${inputs.mode.modifiers.length}`, inputs)}`;
+  }
+
+  if (!inputs.cycleHintEnabled) {
+    return indicator;
+  }
+  return `${indicator} ${style.separator("·", inputs)} ${style.hint(
+    `${inputs.cycleForwardKey}/${inputs.cycleBackwardKey} cycle`,
+    inputs,
+  )}`;
+}
+
+let cycleHintEnabled = false;
+
+/** Factory-only: enable/disable the cycle hint. */
+export function setCycleHintEnabled(b: boolean): void {
+  cycleHintEnabled = b;
+}
+
+/** TEST-ONLY: reset module-scope footer state. */
+export function resetFooterForTesting(): void {
+  cycleHintEnabled = false;
+}
+
+/**
+ * Thin pi seam. UI-only side effect: reads resolver state and pushes the
+ * formatted footer string. No prompt, cache, splice, or resolver mutation.
+ */
+export function refreshModeFooter(ctx: ExtensionContext): void {
+  if (!ctx.hasUI) {
+    return;
+  }
+
+  const spec = getActiveMode() ?? getDefaultMode();
+  const specName = typeof spec === "string" ? spec : undefined;
+  let mode: ResolvedMode | undefined;
+  let modeError: string | undefined;
+  try {
+    mode = resolveActiveModePlan().mode;
+  } catch (err) {
+    modeError = (err as Error).message;
+  }
+
+  ctx.ui.setStatus(
+    MODE_FOOTER_KEY,
+    formatModeFooter(
+      {
+        specName,
+        mode,
+        modeError,
+        cycleHintEnabled,
+        cycleForwardKey: CYCLE_FORWARD_KEY,
+        cycleBackwardKey: CYCLE_BACKWARD_KEY,
+      },
+      createThemedModeFooterStyle(ctx.ui.theme),
+    ),
+  );
+}

package/node_modules/@nklisch/pi-model-modes/src/fragments.ts

@@ -0,0 +1,178 @@
+import { fileURLToPath } from "node:url";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+
+/**
+ * Fragment loader — convention-directory discovery + stat/mtime-invalidated
+ * module-scope content cache. Pure file layer: paths in, trimmed content out.
+ * No naming, selection, or splice policy (that's resolver/assemble). Module-scope
+ * mutable state is EXPECTED (the content cache IS stateful); reset for tests.
+ *
+ * Root is package-relative (<package>/prompts/), never cwd-relative — this runs
+ * as a pi package loaded via jiti in the user's working dir. A test-only root
+ * override loads fixtures deterministically.
+ *
+ * Design: `.work/active/features/epic-mode-composition-fragment-loader.md`.
+ */
+
+/** The three convention axes. Exactly one value per axis is selected downstream. */
+export type Axis = "agency" | "quality" | "scope";
+export const AXES: readonly Axis[] = ["agency", "quality", "scope"] as const;
+
+/** One cached file: numeric mtimeMs + trimmed content. */
+interface CacheEntry {
+  mtimeMs: number;
+  content: string;
+}
+
+// --- Module-scope state (mutable by design) --------------------------------
+const PACKAGE_ROOT = fileURLToPath(new URL("../prompts/", import.meta.url));
+let rootOverride: string | undefined;
+const contentCache = new Map<string, CacheEntry>();
+
+function fragmentRoot(): string {
+  return rootOverride ?? PACKAGE_ROOT;
+}
+
+// --- Internal helpers -------------------------------------------------------
+
+/** `.md` files in `dir`, mapped to absolute paths, filename-sorted ascending. */
+function listMarkdown(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith(".md"))
+    .map((e) => join(dir, e.name))
+    .sort();
+}
+
+// --- Discovery --------------------------------------------------------------
+
+/**
+ * Absolute paths of the `.md` files in one axis dir, filename-sorted ascending.
+ * FAIL FAST: throws if the dir is missing OR empty (an axis must have ≥1 value).
+ */
+export function discoverAxis(axis: Axis): string[] {
+  const dir = join(fragmentRoot(), "axis", axis);
+  let files: string[];
+  try {
+    files = listMarkdown(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`Fragment axis dir not found: ${dir}`);
+    }
+    throw err;
+  }
+  if (files.length === 0) {
+    throw new Error(`Fragment axis '${axis}' is empty: ${dir}`);
+  }
+  return files;
+}
+
+/**
+ * Absolute paths of the `.md` files in `modifiers/`, filename-sorted ascending.
+ * FAIL FAST: throws if the dir is MISSING. An EMPTY modifiers dir returns `[]`
+ * (zero modifiers is a valid library state).
+ */
+export function discoverModifiers(): string[] {
+  const dir = join(fragmentRoot(), "modifiers");
+  try {
+    return listMarkdown(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`Fragment modifiers dir not found: ${dir}`);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Parse <root>/base.json and resolve each `overlays` entry to an absolute path,
+ * preserving manifest order (load-bearing). FAIL FAST: throws if base.json is
+ * missing/unparseable, if `overlays` is not a string[], or if any referenced
+ * overlay file does not exist (orphaned manifest entry).
+ */
+export function discoverBaseOverlays(): string[] {
+  const root = fragmentRoot();
+  const manifestPath = join(root, "base.json");
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`base.json not found: ${manifestPath}`);
+    }
+    throw new Error(`Malformed base.json (unparseable): ${manifestPath}`);
+  }
+
+  const overlays = (parsed as { overlays?: unknown } | null)?.overlays;
+  if (
+    !Array.isArray(overlays) ||
+    !overlays.every((e) => typeof e === "string")
+  ) {
+    throw new Error(
+      `Malformed base.json: 'overlays' must be a string[]: ${manifestPath}`,
+    );
+  }
+
+  const normRoot = resolve(root);
+  return (overlays as string[]).map((entry) => {
+    const abs = resolve(normRoot, entry);
+    // Path containment: an overlay must resolve INSIDE the fragment root. base.json
+    // is package data, but a `../` escape is still a defect worth a clear error
+    // rather than a silent out-of-root read.
+    if (abs !== normRoot && !abs.startsWith(normRoot + sep)) {
+      throw new Error(
+        `base.json overlay escapes the fragment root: ${abs} (entry "${entry}")`,
+      );
+    }
+    let st;
+    try {
+      st = statSync(abs);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new Error(
+          `base.json references missing overlay: ${abs} (entry "${entry}")`,
+        );
+      }
+      throw err; // permission/other I/O errors surface as-is, not mislabeled
+    }
+    if (!st.isFile()) {
+      throw new Error(
+        `base.json overlay is not a file: ${abs} (entry "${entry}")`,
+      );
+    }
+    return abs;
+  });
+}
+
+// --- Content load -----------------------------------------------------------
+
+/**
+ * Trimmed content for an absolute fragment path, through the stat/mtime cache.
+ * Stats the file every call; re-reads only when mtimeMs changed since the cached
+ * entry. FAIL FAST: throws if the path cannot be stat'd/read (missing/unreadable).
+ */
+export function loadFragment(path: string): string {
+  const st = statSync(path);
+  const hit = contentCache.get(path);
+  if (hit && hit.mtimeMs === st.mtimeMs) {
+    return hit.content;
+  }
+  const content = readFileSync(path, "utf8").trim();
+  contentCache.set(path, { mtimeMs: st.mtimeMs, content });
+  return content;
+}
+
+// --- Test-only API (mirrors cache.ts resetForTesting idiom) -----------------
+
+/** TEST-ONLY: override the fragment root (absolute). `undefined` restores the
+ *  package-relative default. */
+export function setFragmentRootForTesting(absRoot: string | undefined): void {
+  rootOverride = absRoot;
+}
+
+/** TEST-ONLY: clear the content cache AND reset the root override. */
+export function resetFragmentsForTesting(): void {
+  contentCache.clear();
+  rootOverride = undefined;
+}

package/node_modules/@nklisch/pi-model-modes/src/handler.ts

@@ -0,0 +1,113 @@
+import type {
+  BeforeAgentStartEvent,
+  BeforeAgentStartEventResult,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import { deriveIdentityLine } from "./identity.js";
+import {
+  computeCacheKey,
+  getCachedResult,
+  setCachedResult,
+} from "./cache.js";
+import type { CacheKeyInputs } from "./cache.js";
+import { resolveActiveModePlan, type ModePlan } from "./resolver.js";
+import { assembleSystemPrompt } from "./assemble.js";
+import {
+  noStylePlan,
+  resolveActiveStylePlan,
+  type StylePlan,
+} from "./style.js";
+
+export type RequiredBeforeAgentStartResult = BeforeAgentStartEventResult & {
+  systemPrompt: string;
+};
+
+let lastBaseSystemPrompt: string | undefined;
+const warnedStyleErrors = new Set<string>();
+
+export function getLastBaseSystemPrompt(): string | undefined {
+  return lastBaseSystemPrompt;
+}
+
+/** TEST-ONLY: clear all handler-owned memo and warning state. */
+export function resetHandlerForTesting(): void {
+  lastBaseSystemPrompt = undefined;
+  warnedStyleErrors.clear();
+}
+
+function resolveStyleGracefully(warn: boolean): StylePlan {
+  try {
+    return resolveActiveStylePlan();
+  } catch (cause) {
+    const message = (cause as Error).message;
+    if (warn && !warnedStyleErrors.has(message)) {
+      warnedStyleErrors.add(message);
+      console.warn(
+        `pi-model-modes: style unresolvable — degrading to no-style (${message})`,
+      );
+    }
+    return noStylePlan("unset", "unset");
+  }
+}
+
+/**
+ * PURE two-path splice shared by the live handler and inspect assembly.
+ * The explicit legacy branch preserves exact bytes only when both optional
+ * layers are absent; opting into a style uses the deterministic blank-line join.
+ */
+function spliceSystemPrompt(
+  identity: string,
+  stylePlan: StylePlan,
+  plan: ModePlan,
+  baseSystemPrompt: string,
+): string {
+  if (stylePlan.content === "" && plan.mode === undefined) {
+    return identity ? `${identity}\n${baseSystemPrompt}` : baseSystemPrompt;
+  }
+  return assembleSystemPrompt(
+    identity,
+    plan,
+    baseSystemPrompt,
+    stylePlan.content === "" ? undefined : stylePlan.content,
+  );
+}
+
+/** Assemble the current mode and style against a known clean pi base. */
+export function assembleForInspect(
+  model: Model<any> | undefined,
+  baseSystemPrompt: string,
+): string {
+  const plan = resolveActiveModePlan();
+  const stylePlan = resolveStyleGracefully(false);
+  const identity = model ? deriveIdentityLine(model) : "";
+  return spliceSystemPrompt(identity, stylePlan, plan, baseSystemPrompt);
+}
+
+/** Cache-aware `before_agent_start` transform. */
+export function handleBeforeAgentStart(
+  e: BeforeAgentStartEvent,
+  ctx: ExtensionContext,
+): RequiredBeforeAgentStartResult {
+  const model = ctx.model;
+  lastBaseSystemPrompt = e.systemPrompt;
+
+  const plan = resolveActiveModePlan();
+  const stylePlan = resolveStyleGracefully(true);
+  const inputs: CacheKeyInputs = {
+    modelName: model?.name ?? "",
+    modelId: model?.id ?? "",
+    modelProvider: model?.provider ?? "",
+    modeSignature: plan.signature,
+    styleSignature: stylePlan.signature,
+    baseSystemPrompt: e.systemPrompt,
+  };
+  const key = computeCacheKey(inputs);
+  const cached = getCachedResult(key);
+  if (cached !== undefined) return { systemPrompt: cached };
+
+  const identity = model ? deriveIdentityLine(model) : "";
+  const result = spliceSystemPrompt(identity, stylePlan, plan, e.systemPrompt);
+  setCachedResult(key, result, inputs);
+  return { systemPrompt: result };
+}

package/node_modules/@nklisch/pi-model-modes/src/identity.ts

@@ -0,0 +1,16 @@
+import type { Model } from "@earendil-works/pi-ai";
+import { providerDisplayName } from "./provider-names.js";
+
+/**
+ * Derive the identity line from a pi model object.
+ *
+ * Pure: reads `model.name` and `model.provider` only — no mutation, no I/O,
+ * no pi runtime coupling beyond the `import type`. Same model in => same
+ * string out, every call (byte-deterministic; the line-level foundation of
+ * SPEC Invariant 2).
+ *
+ * Format: `You are {model.name} from {providerDisplayName(model.provider)}.`
+ */
+export function deriveIdentityLine(model: Model<any>): string {
+  return `You are ${model.name} from ${providerDisplayName(model.provider)}.`;
+}

package/node_modules/@nklisch/pi-model-modes/src/keybinding.ts

@@ -0,0 +1,117 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  setActiveMode,
+  getActiveMode,
+  getDefaultMode,
+  resolveActiveModePlan,
+} from "./resolver.js";
+import { listPresetNames } from "./presets.js";
+import { glyphForBase, refreshModeFooter } from "./footer.js";
+
+/**
+ * Mode-cycle keybindings — the keyboard switching path. `Ctrl+Shift+U` cycles
+ * FORWARD through the sorted preset list and `Ctrl+Shift+Alt+U` cycles BACKWARD,
+ * each setting the session OVERRIDE (via the resolver seam) relative to the
+ * current EFFECTIVE mode. The package factory registers these shortcuts only
+ * when the global `cycleKeybinding` config flag is `true`; otherwise callers
+ * must opt in explicitly.
+ *
+ * The cycle math (`nextPresetName`) is a PURE helper — fully unit-testable
+ * without pi. `registerModeKeybindings` is the thin pi seam.
+ *
+ * `Key` import note: pi examples import `Key` from `@earendil-works/pi-tui`.
+ * That package is a direct dev-dependency of this plugin (added when the
+ * autocomplete seam landed), but this module still uses equivalent `KeyId`
+ * strings to keep the runtime import surface minimal.
+ *
+ * `Ctrl+M` is intentionally avoided: terminal legacy input encodes it as
+ * carriage return, so it collides with Enter.
+ */
+
+/** KeyId for forward cycle. */
+export const CYCLE_FORWARD_KEY = "ctrl+shift+u";
+/** KeyId for backward cycle. */
+export const CYCLE_BACKWARD_KEY = "ctrl+shift+alt+u";
+
+/**
+ * PURE: the next preset name when cycling through a SORTED preset list.
+ *
+ *   - empty list → `undefined` (no-op at the caller).
+ *   - `current` found at index `i` → forward `(i+1) % len`, backward
+ *     `(i-1+len) % len` (wraps at both ends).
+ *   - `current` unset or not a preset name (`indexOf` → -1) → enter the list at
+ *     `names[0]` going forward, `names[len-1]` going backward.
+ */
+export function nextPresetName(
+  names: string[],
+  current: string | undefined,
+  dir: 1 | -1,
+): string | undefined {
+  const len = names.length;
+  if (len === 0) {
+    return undefined;
+  }
+  const idx = current === undefined ? -1 : names.indexOf(current);
+  if (idx === -1) {
+    // From unset / a non-preset spec: forward → first, backward → last.
+    return dir === 1 ? names[0] : names[len - 1];
+  }
+  const next = (idx + dir + len) % len;
+  return names[next];
+}
+
+/**
+ * Register the forward/backward mode-cycle shortcuts. Each handler computes the
+ * sorted preset names, derives the current EFFECTIVE spec name
+ * (`getActiveMode() ?? getDefaultMode()`, only when it's a string preset), picks
+ * the next preset via `nextPresetName`, then `setActiveMode(next)` +
+ * `ctx.ui.notify('mode: <next>')`. An empty preset list notifies "no presets".
+ */
+export function registerModeKeybindings(pi: ExtensionAPI): void {
+  const cycle = (dir: 1 | -1) => async (ctx: ExtensionContext): Promise<void> => {
+    const names = listPresetNames();
+    if (names.length === 0) {
+      ctx.ui.notify("no presets", "info");
+      return;
+    }
+    const effective = getActiveMode() ?? getDefaultMode();
+    const current = typeof effective === "string" ? effective : undefined;
+    const next = nextPresetName(names, current, dir);
+    if (next === undefined) {
+      // Defensive: names is non-empty above, so this is unreachable.
+      ctx.ui.notify("no presets", "info");
+      return;
+    }
+    setActiveMode(next);
+    refreshModeFooter(ctx);
+    // Match the footer's leading glyph so the toast and the footer agree. The
+    // resolver is the same path `refreshModeFooter` uses; for the virtual `none`
+    // preset (or any spec without a base) `mode` is undefined and we fall back
+    // to the default glyph, exactly as the footer does for unset.
+    let base: string | undefined;
+    try {
+      base = resolveActiveModePlan().mode?.base;
+    } catch {
+      // Resolver broken — footer will show the unresolvable marker; the toast
+      // uses the default glyph rather than throwing mid-cycle.
+      base = undefined;
+    }
+    const theme = ctx.ui.theme;
+    ctx.ui.notify(
+      `${theme.fg("muted", "mode:")} ${theme.fg("accent", glyphForBase(base))} ${theme.fg("toolTitle", next)}`,
+      "info",
+    );
+  };
+
+  pi.registerShortcut(CYCLE_FORWARD_KEY, {
+    description: "Cycle to the next mode preset",
+    handler: cycle(1),
+  });
+  pi.registerShortcut(CYCLE_BACKWARD_KEY, {
+    description: "Cycle to the previous mode preset",
+    handler: cycle(-1),
+  });
+}