@openlines/opl-pi-sht 0.1.14

package/extensions/opl-modes/menus.ts

@@ -0,0 +1,60 @@
+/** Shared select-menu dialog: bordered title + SelectList + help footer. */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, Text, Spacer, SelectList, type SelectItem } from "@earendil-works/pi-tui";
+
+export interface SelectMenuOptions {
+  /** Render the title bold (default true). */
+  bold?: boolean;
+  /** Dim suffix appended after the title, e.g. a warning hint. */
+  dimSuffix?: string;
+}
+
+/** Show a bordered select menu and resolve with the chosen item's value, or null when cancelled. */
+export function showSelectMenu(
+  ctx: ExtensionContext,
+  title: string,
+  items: SelectItem[],
+  opts: SelectMenuOptions = {},
+): Promise<string | null> {
+  const { bold = true, dimSuffix } = opts;
+
+  return ctx.ui.custom<string | null>((tui, theme, kb, done) => {
+    const border = new DynamicBorder((s: string) => theme.fg("border", s));
+    const titleText = theme.fg("text", bold ? theme.bold(title) : title) + (dimSuffix ? theme.fg("dim", dimSuffix) : "");
+    const titleLine = new Text(titleText, 1, 0);
+
+    const selectList = new SelectList(items, Math.min(items.length, 10), {
+      selectedPrefix: (t) => theme.fg("accent", t),
+      selectedText: (t) => theme.fg("accent", t),
+      description: (t) => theme.fg("muted", t),
+      scrollInfo: (t) => theme.fg("dim", t),
+      noMatch: (t) => theme.fg("warning", t),
+    });
+    selectList.onSelect = (item) => done(item.value);
+    selectList.onCancel = () => done(null);
+
+    const help = new Text(theme.fg("dim", "↑↓") + theme.fg("muted", " navigate ") + theme.fg("dim", "enter") + theme.fg("muted", " select ") + theme.fg("dim", "esc") + theme.fg("muted", " cancel"), 1, 0);
+
+    const container = new Container();
+    container.addChild(border);
+    container.addChild(new Spacer());
+    container.addChild(titleLine);
+    container.addChild(new Spacer());
+    container.addChild(selectList);
+    container.addChild(new Spacer());
+    container.addChild(help);
+    container.addChild(border);
+
+    return {
+      render(width: number) { return container.render(width); },
+      invalidate() { container.invalidate(); },
+      handleInput(data: string) {
+        if (kb.matches(data, "app.tools.expand")) { ctx.ui.setToolsExpanded(!ctx.ui.getToolsExpanded()); return; }
+        selectList.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+}

package/extensions/opl-modes/state.ts

@@ -0,0 +1,152 @@
+/** OFF/CHAT/PLAN/EXECUTE unified state machine with session persistence via appendEntry blob. */
+
+import { ENTRY_TYPE, getModeDefinition } from "./config.js";
+import type { AgentMode, AgentModeBlob, ModeAppearanceConfig } from "./types.js";
+
+/** Mutable state — shared within the extension module. */
+const state: {
+  mode: AgentMode;
+  activePlanFile: string | null;
+  refining: boolean;
+  refineCount: number;
+} = {
+  mode: "off",
+  activePlanFile: null,
+  refining: false,
+  refineCount: 0,
+};
+
+// Publish unified global and legacy globals at module load.
+(globalThis as Record<string, unknown>).__agentMode = { mode: "off" };
+(globalThis as Record<string, unknown>).__planMode = { mode: "off" };
+(globalThis as Record<string, unknown>).__chatMode = { mode: "off" };
+
+/** Derive and sync all globalThis snapshots from unified state. */
+function syncGlobalThis(): void {
+  const m = state.mode;
+  // Unified global for the mode-switcher footer segment
+  (globalThis as Record<string, unknown>).__agentMode = {
+    mode: m,
+    appearance: getModeDefinition(m)?.appearance,
+  } satisfies { mode: AgentMode; appearance?: ModeAppearanceConfig };
+  // Legacy globals for backward compat with chat-input and footer segments
+  (globalThis as Record<string, unknown>).__planMode = { mode: m === "chat" ? "off" : m };
+  (globalThis as Record<string, unknown>).__chatMode = { mode: m === "chat" ? "chat" : "off" };
+  const requestRender = (globalThis as Record<string, unknown>).__footerRequestRender;
+  if (typeof requestRender === "function") requestRender();
+}
+
+export function getMode(): AgentMode { return state.mode; }
+export function getActivePlanFile(): string | null { return state.activePlanFile; }
+export function getRefining(): boolean { return state.refining; }
+
+export function setRefining(value: boolean): void {
+  state.refining = value;
+  syncGlobalThis();
+}
+
+export function getRefineCount(): number { return state.refineCount; }
+export function incrementRefineCount(): void { state.refineCount++; }
+export function resetRefineCount(): void { state.refineCount = 0; }
+
+export function setActivePlanFile(
+  file: string | null,
+  pi: { appendEntry: (type: string, data?: unknown) => void },
+): void {
+  state.activePlanFile = file;
+  syncGlobalThis();
+  persist(pi);
+}
+
+export function enterPlanWithFile(
+  file: string | null,
+  pi: { appendEntry: (type: string, data?: unknown) => void },
+): void {
+  state.mode = "plan";
+  state.activePlanFile = file;
+  state.refining = false;
+  syncGlobalThis();
+  persist(pi);
+}
+
+export function transition(
+  newMode: AgentMode,
+  pi: { appendEntry: (type: string, data?: unknown) => void },
+): void {
+  if (newMode === "plan") state.activePlanFile = null;
+  state.mode = newMode;
+  state.refining = false;
+  state.refineCount = 0;
+  syncGlobalThis();
+  persist(pi);
+}
+
+function persist(pi: { appendEntry: (type: string, data?: unknown) => void }): void {
+  pi.appendEntry(ENTRY_TYPE, {
+    mode: state.mode,
+    activePlanFile: state.activePlanFile,
+  } satisfies AgentModeBlob);
+}
+
+/**
+ * Restore state from the most recent relevant session entry on the current branch.
+ * Checks for native mode-switcher entries first; falls back to legacy plan-mode/chat-mode entries
+ * so sessions saved by the old extensions are restored correctly.
+ */
+export function restore(
+  entries: Array<{ type: string; customType?: string; data?: unknown }>,
+): boolean {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== "custom") continue;
+
+    if (entry.customType === ENTRY_TYPE) {
+      const data = entry.data as AgentModeBlob | undefined;
+      if (data?.mode) {
+        state.mode = data.mode;
+        state.activePlanFile = data.activePlanFile ?? null;
+        state.refining = false;
+        syncGlobalThis();
+        return true;
+      }
+    }
+  }
+
+  // Backward compat: restore from legacy entries written by the old extensions.
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== "custom") continue;
+
+    if (entry.customType === "plan-mode") {
+      const data = entry.data as { mode?: string; activePlanFile?: string | null } | undefined;
+      if (data?.mode === "plan" || data?.mode === "execute") {
+        state.mode = data.mode as AgentMode;
+        state.activePlanFile = data.activePlanFile ?? null;
+        state.refining = false;
+        syncGlobalThis();
+        return true;
+      }
+    }
+
+    if (entry.customType === "chat-mode") {
+      const data = entry.data as { mode?: string } | undefined;
+      if (data?.mode === "chat") {
+        state.mode = "chat";
+        state.activePlanFile = null;
+        state.refining = false;
+        syncGlobalThis();
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+export function resetState(): void {
+  state.mode = "off";
+  state.activePlanFile = null;
+  state.refining = false;
+  state.refineCount = 0;
+  syncGlobalThis();
+}

package/extensions/opl-modes/types.ts

@@ -0,0 +1,164 @@
+/** Shared types for the opl-modes extension. */
+
+/** Mode identifier — now extensible via config. Built-in: off, chat, plan, execute. */
+export type AgentMode = string;
+
+/** Persisted blob — plan file is the source of truth for steps. */
+export interface AgentModeBlob {
+  mode: AgentMode;
+  activePlanFile: string | null;
+}
+
+export interface PlanFileSummary {
+  name: string;
+  title: string;
+}
+
+/** Model reference — provider + model id, resolved via ctx.modelRegistry.find(provider, id). */
+export interface ModeModelConfig {
+  provider: string;
+  id: string;
+}
+
+// ─── User Config ─────────────────────────────────────────────────────────────
+
+export interface CleanupUserConfig {
+  cleanupOnComplete?: boolean;
+}
+
+export interface UiUserConfig {
+  hideNotify?: boolean;
+  hideWidget?: boolean;
+}
+
+export interface ShortcutsUserConfig {
+  cycleMode?: string;
+}
+
+export interface ChatLabelUserConfig {
+  notify?: string;
+  notifyType?: string;
+  widget?: string;
+  widgetColor?: string;
+}
+
+export interface PlanLabelUserConfig {
+  notify?: string;
+  notifyType?: string;
+  notifyWithTitle?: string;
+  notifyLoaded?: string;
+  widget?: string;
+  widgetWithTitle?: string;
+  widgetColor?: string;
+}
+
+export interface ExecuteLabelUserConfig {
+  notify?: string;
+  notifyWithTitle?: string;
+  notifyType?: string;
+  widget?: string;
+  widgetWithTitle?: string;
+  widgetColor?: string;
+}
+
+export interface OffLabelUserConfig {
+  notify?: string;
+  notifyType?: string;
+}
+
+/** Visual identity for a custom mode, consumed by mode-aware renderers. */
+export interface ModeAppearanceConfig {
+  prefix?: string;
+  prefixColor?: string;
+  borderColor?: string;
+  modeColor?: string;
+}
+
+/** Label configuration for a single mode. */
+export interface ModeLabelConfig {
+  notify?: string;
+  notifyType?: string;
+  notifyWithTitle?: string;
+  notifyLoaded?: string;
+  widget?: string;
+  widgetWithTitle?: string;
+  widgetColor?: string;
+}
+
+/** Legacy hardcoded labels — kept for backward compat. Prefer `modes` in user config. */
+export interface LabelsUserConfig {
+  chat?: ChatLabelUserConfig;
+  plan?: PlanLabelUserConfig;
+  execute?: ExecuteLabelUserConfig;
+  off?: OffLabelUserConfig;
+}
+
+/** Complete definition for a single mode. */
+export interface ModeDefinition {
+  /** System prompt injected when this mode is active. */
+  prompt: string | (() => string);
+  /** Tool names available in this mode. Omit to inherit all tools. */
+  tools?: string[];
+  /** Bash command patterns considered safe (allowed). Compiled RegExp at runtime. */
+  safePatterns?: RegExp[];
+  /** Bash command patterns considered destructive (blocked). Compiled RegExp at runtime. */
+  destructivePatterns?: RegExp[];
+  /** UI labels for this mode. */
+  labels?: ModeLabelConfig;
+  /** Custom-mode appearance published to opl-input and opl-footer. */
+  appearance?: ModeAppearanceConfig;
+  /** Whether plan_complete tool should be available. Default: false */
+  allowPlanComplete?: boolean;
+  /** Whether plan execution can be started from this mode (mode-picker "Execute:" items and /execute). Default: true. The plan-mode action menu is always available regardless of this flag. */
+  allowExecute?: boolean;
+  /** Whether to show this mode in the picker menu and cycling shortcut. Default: true */
+  visible?: boolean;
+  /** Whether this mode can be entered via the picker or cycle shortcut. Default: true. Unlike `visible`, disabling does not remove the mode — it can still be reached programmatically (e.g. execute mode via plan selection). */
+  enabled?: boolean;
+  /** Model to switch to when this mode is entered. Omit to leave the current model untouched. */
+  model?: ModeModelConfig;
+}
+
+/** User-facing mode definition — patterns are raw strings, compiled to RegExp internally. */
+export interface UserModeDefinition {
+  prompt?: string;
+  tools?: string[];
+  safePatterns?: string[];
+  destructivePatterns?: string[];
+  labels?: ModeLabelConfig;
+  appearance?: ModeAppearanceConfig;
+  allowPlanComplete?: boolean;
+  /** Set to false to block starting plan execution while this mode is active (hides picker "Execute:" items and blocks /execute). Default: true. */
+  allowExecute?: boolean;
+  visible?: boolean;
+  /** Set to false to disable this mode from the picker menu and cycle shortcut. Default: true. */
+  enabled?: boolean;
+  /** Model to switch to when this mode is entered. Omit to leave the current model untouched. */
+  model?: ModeModelConfig;
+}
+/** Partial mode definition for user config — all fields optional, patterns as raw strings. */
+export type PartialModeDefinition = UserModeDefinition;
+
+export interface BashPatternsUserConfig {
+  safePatterns?: string[];
+  destructivePatterns?: string[];
+}
+
+export interface ModeSwitcherUserConfig {
+  cleanup?: CleanupUserConfig;
+  ui?: UiUserConfig;
+  shortcuts?: ShortcutsUserConfig;
+  /** @deprecated Use `modes` registry instead. Kept for backward compat. */
+  labels?: LabelsUserConfig;
+  bashPatterns?: BashPatternsUserConfig;
+  /** Replace-only: provide a list of tool names to replace the default CHAT mode tool set. Omit to keep defaults. */
+  chatAllowedTools?: string[];
+  /** Replace-only: provide a list of tool names to replace the default PLAN mode tool set. Omit to keep defaults. */
+  planAllowedTools?: string[];
+  /** User-defined modes that extend or override built-in modes. */
+  modes?: Record<string, PartialModeDefinition>;
+  /** Tool names withheld from the active set at rest and enabled on demand via the load_tools loader. Protected/core tools are ignored. */
+  lazyTools?: string[];
+  /** Default notify text template for custom modes that don't set their own `labels.notify`. Use {Name} as a placeholder for the mode name (capitalized). Default: "✓ {Name} mode ON". */
+  defaultNotifyTemplate?: string;
+}

package/extensions/opl-modes/utils.ts

@@ -0,0 +1,138 @@
+/** Pure utilities: isSafeCommand, extractPlanText, plan file I/O, color helpers */
+
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync, readdirSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { SAFE_COMMAND_PATTERNS, DESTRUCTIVE_PATTERNS, PLAN_DIR, PLAN_FILE_PREFIX } from "./config.js";
+import type { PlanFileSummary } from "./types.js";
+
+/** Check if command matches safe patterns and not destructive patterns. */
+export function isSafeCommand(command: string): boolean {
+  return SAFE_COMMAND_PATTERNS.some((p) => p.test(command))
+    && !DESTRUCTIVE_PATTERNS.some((p) => p.test(command));
+}
+
+const PLAN_ACTION_VERB = /^\s*\d+\.\s+(?:\*{1,2})?(?:add|creat|updat|fix|remov|refactor|implement|modif|chang|edit|writ|build|run|install|configur|set\s+up|delet|mov|renam|inject|migrat|replac|extract|test|deploy|integrat|convert)/i;
+
+/** Heuristic: does text look like a plan? (numbered steps, checkboxes, structured). */
+export function isPlanLike(text: string): boolean {
+  const lines = text.split('\n');
+  const numberedSteps = lines.filter(l => /^\s*\d+\.\s/.test(l));
+  if (numberedSteps.length >= 3 && text.length > 200 && lines.some(l => PLAN_ACTION_VERB.test(l))) return true;
+  const checkboxes = lines.filter(l => /^\s*- \[[ xX]\]/.test(l));
+  if (checkboxes.length >= 3 && text.length > 150) return true;
+  return false;
+}
+
+/** Extract the raw text under the "Plan:" header from a message. Falls back to entire message if plan-like. Returns null if no plan found. */
+export function extractPlanText(message: string): string | null {
+  const planMatch = message.match(/^\s*(?:#{1,6}\s*)?(?:\*{1,2})?Plan:(?:\*{1,2})?[^\n]*$/im);
+  if (planMatch) {
+    const afterPlan = message.slice(planMatch.index! + planMatch[0].length);
+    return afterPlan.trim();
+  }
+  // Fallback: if message looks like a plan, use entire message
+  if (isPlanLike(message)) return message.trim();
+  return null;
+}
+
+// ─── Plan File I/O ────────────────────────────────────────────────────────────
+
+/** Ensure .pi/plans/ exists, return its absolute path. */
+export function ensurePlanDir(): string {
+  const dir = join(process.cwd(), PLAN_DIR);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Derive display title from filename.
+ *  For named plans (e.g. plan-add-auth.md) → "Add Auth".
+ *  For timestamp plans (e.g. plan-2026-05-10-14-30.md) → "May 10, 2026 14:30". */
+export function titleFromFilename(filename: string): string {
+  const stem = filename.replace(/^plan-/ , "").replace(/\.md$/, "");
+
+  // Detect timestamp pattern: YYYY-MM-DD-HH-MM
+  const tsMatch = stem.match(/^(\d{4})-(\d{2})-(\d{2})-(\d{2})-(\d{2})$/);
+  if (tsMatch) {
+    const [, y, m, d, h, min] = tsMatch;
+    const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+    const month = months[parseInt(m, 10) - 1] ?? m;
+    return `${month} ${parseInt(d, 10)}, ${y} ${h}:${min}`;
+  }
+
+  // Named plan: hyphens → spaces, title-case
+  return stem.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/** Sanitize a plan name — reject path traversal and invalid characters. Returns null if invalid. */
+export function sanitizePlanName(name: string): string | null {
+  const trimmed = name.trim();
+  if (!trimmed) return null;
+  if (trimmed.includes("/") || trimmed.includes("\\") || trimmed.includes("..")) return null;
+  if (!/^[\w\s.-]+$/.test(trimmed)) return null;
+  return trimmed.replace(/\s+/g, "-");
+}
+
+/** List available plan files in .pi/plans/ with titles from # Plan: heading. */
+export function listPlanFiles(): PlanFileSummary[] {
+  const dir = join(process.cwd(), PLAN_DIR);
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir)
+    .filter((f) => f.startsWith(PLAN_FILE_PREFIX) && f.endsWith(".md"))
+    .sort();
+
+  return files.map((filename) => {
+    const content = readFileSync(join(dir, filename), "utf-8");
+    const titleMatch = content.match(/^# Plan:\s*(.+)$/m);
+    const title = titleMatch ? titleMatch[1].trim() : titleFromFilename(filename);
+    return { name: filename, title };
+  });
+}
+
+/** Extract text content from an LLM message (string or array of content blocks). */
+export function extractTextFromMessage(message: Record<string, unknown>): string | null {
+  const content = message.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((block: unknown): block is { type: string; text?: string } =>
+        typeof block === "object" && block !== null && "type" in block && (block as { type: string }).type === "text",
+      )
+      .map((block) => block.text ?? "")
+      .join("\n");
+  }
+  return null;
+}
+
+// ─── Color Utilities ────────────────────────────────────────────────────────
+
+/** Check if a color string is a hex color (e.g. "#ff6600"). */
+export function isHexColor(color: string): boolean {
+  return color.startsWith("#");
+}
+
+/** Convert hex color string to ANSI truecolor escape. */
+function hexToAnsi(hex: string): string {
+  const h = hex.replace("#", "");
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) return "";
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+/** Apply a color to text — supports pi theme tokens and hex values. */
+export function applyLabelColor(theme: Theme, color: string, text: string): string {
+  if (isHexColor(color)) {
+    const ansi = hexToAnsi(color);
+    if (!ansi) return text;
+    return `${ansi}${text}\x1b[39m`;
+  }
+  try {
+    return theme.fg(color as ThemeColor, text);
+  } catch {
+    return text;
+  }
+}

package/extensions/opl-questionnaire/README.md

@@ -0,0 +1,26 @@
+# opl-questionnaire
+
+Adds a model-callable interactive questionnaire for discrete choices, preferences, and confirmations.
+
+## Commands, flags, and shortcuts
+
+- Tool: `questionnaire`.
+- `↑`/`↓`: move through options; `1`-`9`/`0`: select options 1-10; `Enter`: select or submit.
+- Multi-question UI: `Tab`/`Shift+Tab` or `←`/`→` changes tabs; `Esc` cancels or exits custom-answer editing.
+
+## Extension features
+
+- Renders one question as a compact option list and multiple questions as tabs with a final Submit tab.
+- Questions require an `id`, prompt, options, and optional label or free-text `allowOther` response.
+- Rejects duplicate IDs and questions that cannot be answered; returns `(no response)` for an empty custom answer.
+- Returns structured answers containing question ID, selected value and label, custom-text flag, and option index where applicable.
+- Blocks submission until every multi-question prompt has an answer.
+- Returns a clear error in headless sessions so the model can use plain-text questions instead.
+
+## Configuration
+
+No external configuration file. Availability follows Pi's active tool set: the shipped `opl-modes` chat and plan lists include `questionnaire`; custom modes must list it explicitly.
+
+## Architecture
+
+`index.ts` registers the tool, validates input, renders the custom TUI, and formats results. `types.ts` contains the TypeBox parameter schema and shared question/answer types.