@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/builtin-pi-packages/pi-crtr-extensions/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "pi-crtr-extensions",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Silas's personal pi extensions and prompt templates.",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.79.6"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "extensions/*.ts",
+      "extensions/*/index.ts"
+    ]
+  }
+}

package/dist/builtin-pi-packages/pi-mode-switch/README.md

@@ -0,0 +1,64 @@
+# pi-mode-switch
+
+Press **Alt+M** to cycle between operating modes — the way Claude's Shift+Tab
+cycles plan / accept-edits. Whenever the mode changes, the new mode's operating
+instructions are injected (invisibly) before your next message.
+
+## Modes
+
+| Mode | What it does |
+|---|---|
+| `normal` | Full tool access (default). Restrictions lifted. |
+| `spec` | Write a specification before any code. No edits. |
+| `plan` | Produce an implementation plan. Read-only, no changes. |
+
+## Usage
+
+- `Alt+M` — cycle `normal → spec → plan → normal`
+- `/mode` — same as Alt+M
+- `/mode <normal\|spec\|plan>` — jump to a specific mode
+- the agent can switch its own mode by running the bundled `bin/mode` CLI through
+  its bash tool — e.g. `bash <plugin>/bin/mode normal` after a spec/plan is
+  approved. The command prints that mode's guidance, so the text only enters
+  context at the moment of the switch (no always-on tool)
+
+The current mode renders as a badge on the **bottom-right of the input box**,
+diagonally opposite the session-name badge (top-left). Mode persists across
+`--resume`.
+
+## How it works
+
+The extension tracks the active mode and the mode whose guidance was last
+injected. On `before_agent_start` it compares the two: if they differ, it
+prepends that mode's guidance to the turn (as a hidden `mode-switch-context`
+message) and records the injection. Stay in the same mode and nothing extra is
+added. Returning to `normal` also strips stale guidance from context.
+
+The agent can also switch its own mode without a permanent tool. The bundled
+`bin/mode` CLI, run through the normal bash tool, writes the requested mode to
+`<artifact-root>/mode-switch/request.json` and prints that mode's operating
+instructions to stdout. The extension mirrors each mode's guidance to
+`mode-switch/guidance/<mode>.txt` at session start (single source of truth stays
+in the extension), watches the request file to keep the badge and session state in
+sync, and consumes each request on read so a later Alt+M isn't clobbered. The
+guidance reaches the agent through the command's own output, so it only enters
+context at the moment of the switch — no tool sits in the context window, and
+there's no coupling to any external runtime, just files.
+
+This is guidance-only — it does not hard-restrict tools. The instructions tell
+the agent not to edit in spec/plan mode; combine with a tool gate if you want
+enforcement.
+
+The input badge is drawn by wrapping whatever editor is already installed (e.g. a
+session-name badge extension) in a transparent Proxy that overrides only
+`render()`. It composes instead of replacing, so other editor decorations keep
+working.
+
+## Install
+
+```bash
+pi install /Users/silasrhyneer/Code/cli/pi-mode-switch          # user scope
+pi install -l /Users/silasrhyneer/Code/cli/pi-mode-switch       # project scope
+```
+
+Run `/reload` in pi after install, then press Alt+M.

package/dist/builtin-pi-packages/pi-mode-switch/bin/mode

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Mode-switch CLI — lets the agent change its own operating mode.
+#
+# Usage: mode <normal|spec|plan>
+#
+# Writes the requested mode to the per-cwd channel the pi mode-switch extension
+# watches (so the badge and session state stay in sync), then prints that mode's
+# operating instructions to stdout — so the guidance enters the agent's context
+# only at the moment of the switch, with no always-on tool.
+set -euo pipefail
+
+mode="${1:-}"
+case "$mode" in
+	normal | spec | plan) ;;
+	*)
+		echo "usage: mode <normal|spec|plan>" >&2
+		exit 1
+		;;
+esac
+
+# Per-node runtime dir, mirroring the extension's artifact root
+# (~/.crouter/workspaces/<cwd-with-each-slash-as-a-dash>/mode-switch/<node-id>).
+# Run from the project root so this matches the running session's directory.
+node_id="${CRTR_NODE_ID:-standalone}"
+dir="$HOME/.crouter/workspaces/$(pwd | sed 's:/:-:g')/mode-switch/$node_id"
+mkdir -p "$dir"
+
+# Signal the running extension. Atomic write via temp + rename so the watcher
+# never reads a half-written file.
+tmp="$(mktemp "$dir/request.XXXXXX")"
+printf '{"mode":"%s","token":"%s","source":"cli"}\n' "$mode" "$(date +%s)-$$-${RANDOM:-0}" >"$tmp"
+mv -f "$tmp" "$dir/request.json"
+
+# Hand the new mode's operating instructions to the agent.
+guidance="$dir/guidance/$mode.txt"
+if [ -f "$guidance" ]; then
+	cat "$guidance"
+else
+	echo "[$mode mode] requested. (No running mode-switch extension detected for this directory, so detailed guidance is unavailable.)"
+fi

package/dist/builtin-pi-packages/pi-mode-switch/extensions/index.ts

@@ -0,0 +1,422 @@
+/**
+ * Mode Switch Extension
+ *
+ * Press Alt+M to cycle between operating modes, the way Claude's Shift+Tab
+ * cycles plan / accept-edits. Modes here:
+ *
+ *   normal  → full access (default)
+ *   spec    → write a specification before any code
+ *   plan    → produce an implementation plan, no changes
+ *
+ * The only behaviour is context injection: whenever the active mode differs
+ * from the mode whose guidance was last injected, the mode's operating
+ * instructions are prepended (invisibly) to the next agent turn. Stay in the
+ * same mode across turns and nothing extra is injected.
+ *
+ * - Alt+M or /mode to cycle; /mode <name> to jump to a specific mode
+ * - The agent can switch its own mode by running the bundled `bin/mode` CLI via
+ *   its bash tool; the command prints the new mode's guidance to stdout, so that
+ *   text only enters context at the moment of the switch (no always-on tool)
+ * - The active mode is mirrored to a tiny `current` file the attach viewer
+ *   reads for its footer indicator; when a real UI exists, it still also renders
+ *   as a badge on the bottom-right of the input box by wrapping the previous
+ *   editor instead of replacing it.
+ * - State persists across session resume
+ */
+
+import { CustomEditor, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { type FSWatcher, mkdirSync, readFileSync, rmSync, watch, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { workspaceRoot } from "../../../core/artifact.js";
+
+type Mode = "normal" | "spec" | "plan";
+
+// Absolute path to the bundled mode-switch CLI (extensions/../bin/mode). The
+// extension runs from its package source dir, so we resolve it relative to this
+// file. The agent runs it through its normal bash tool, so it costs zero context
+// until the moment it's used.
+const CLI_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "mode");
+const MODE_CLI = `bash "${CLI_PATH}"`;
+
+// Per-cwd crouter artifact root: ~/.crouter/workspaces/<cwd-with-each-slash-as-a-dash>/.
+// Mirrors crouter's mangleCwd / workspaceRoot (src/core/artifact.ts). spec/plan
+// modes write their artifacts under <root>/specs and <root>/plans respectively,
+// so we make sure both dirs exist for the cwd whenever a session starts.
+function ensureArtifactDirs(cwd: string = process.cwd()): void {
+	const root = workspaceRoot(cwd);
+	try {
+		mkdirSync(join(root, "specs"), { recursive: true });
+		mkdirSync(join(root, "plans"), { recursive: true });
+		mkdirSync(join(modeSwitchDir(cwd), "guidance"), { recursive: true });
+	} catch {
+		// Best-effort: never block session start on a filesystem hiccup.
+	}
+}
+
+// Per-node channel the CLI, attach viewer, and this extension share, under the
+// same per-cwd artifact root: <root>/mode-switch/<node-id>/{request.json,current}.
+function modeSwitchDir(cwd: string = process.cwd(), nodeId: string = process.env["CRTR_NODE_ID"] ?? "standalone"): string {
+	return join(workspaceRoot(cwd), "mode-switch", nodeId);
+}
+
+// The cycle order Alt+M walks through.
+const CYCLE: Mode[] = ["normal", "spec", "plan"];
+
+interface ModeDef {
+	/** Badge label shown in the input box. */
+	label: string;
+	/** Guidance injected before the next turn when this mode becomes active. */
+	context: string;
+}
+
+const MODES: Record<Mode, ModeDef> = {
+	normal: {
+		label: "normal",
+		context: `[NORMAL MODE]
+Mode restrictions are lifted — you have full tool access again.
+
+Proceed with the work as discussed. If a spec or plan was produced earlier in
+this session, follow it. You may read, edit, write, and run commands freely. If a
+request is large enough to need a written spec or plan first, switch modes by
+running \`${MODE_CLI} spec\` (or \`plan\`); the command prints that mode's
+operating instructions to follow.`,
+	},
+	spec: {
+		label: "spec",
+		context: `[SPEC MODE]
+You are in spec mode. Your job is to turn a rough request into a clear, written
+specification BEFORE any code is written.
+
+How to operate:
+- Do NOT implement, edit, or write production code. Hold off on changes entirely.
+- Resolve open questions as you go. Whenever something is ambiguous — scope,
+  inputs and outputs, edge cases, constraints, or what "done" means — put the
+  question to the user with the \`crtr human ask\` command rather than asking
+  inline, then fold the answer into the spec. Do this before drafting for the
+  unknowns you can see up front, and again whenever a new question surfaces while
+  you write. The finished spec records decisions, not open questions.
+- Explore the codebase read-only to ground the spec in how things actually work.
+- Then write the specification to a markdown file under the project's crtr specs
+  directory: \`~/.crouter/workspaces/<cwd-with-each-slash-replaced-by-a-dash>/specs/<slug>.md\`
+  (e.g. cwd \`/Users/me/Code/app\` → \`~/.crouter/workspaces/-Users-me-Code-app/specs/\`).
+  Create the directory if it does not exist. Cover: problem statement, goals and
+  non-goals, requirements, a high-level approach, and acceptance criteria. Keep
+  it tight and reviewable.
+- Then validate the spec with a reviewer node first: spawn one with
+  \`crtr node new "Review the spec at <absolute-path>" --kind review\` — you
+  auto-subscribe to it and are woken when it finishes. Read its verdict with
+  \`crtr feed read\` and dereference the report path it points to. It flags
+  completeness gaps, contradictions, ambiguity, scope creep, and unspecified
+  failure modes on critical paths. Resolve every Issue it raises before showing
+  the spec to anyone;
+  Recommendations are advisory.
+- Finally, present the finished spec for review with
+  \`crtr human review <absolute-path-to-the-spec.md>\` and incorporate the
+  returned comments. Do not move on until the user has reviewed it. Once they
+  approve it, run \`${MODE_CLI} normal\` to lift the restrictions and begin
+  implementing — the command prints your normal-mode operating instructions.`,
+	},
+	plan: {
+		label: "plan",
+		context: `[PLAN MODE]
+You are in plan mode. Your job is to produce an actionable implementation plan —
+no changes yet.
+
+How to operate:
+- Do NOT edit production code. Read-only exploration only (writing the plan file
+  itself is allowed).
+- Resolve open questions as you go. Whenever something is ambiguous or a decision
+  needs a call, put it to the user with the \`crtr human ask\` command rather than
+  asking inline, then fold the answer into the plan. Do this before drafting for
+  the unknowns you can see up front, and again whenever a new question surfaces
+  while you write. The finished plan records decisions, not open questions.
+- Investigate the relevant code to understand how the change fits in.
+- Then write the plan to a markdown file under the project's crtr plans
+  directory: \`~/.crouter/workspaces/<cwd-with-each-slash-replaced-by-a-dash>/plans/<slug>.md\`
+  (e.g. cwd \`/Users/me/Code/app\` → \`~/.crouter/workspaces/-Users-me-Code-app/plans/\`).
+  Create the directory if it does not exist. The plan is a numbered, ordered list
+  of concrete steps: which files to touch, which functions to add or modify,
+  which tests to write, plus risks and dependencies.
+- Then validate the plan with a reviewer node first: spawn one with
+  \`crtr node new "Review the plan at <absolute-path>" --kind review\` — you
+  auto-subscribe to it and are woken when it finishes. Read its verdict with
+  \`crtr feed read\` and dereference the report path it points to. It flags
+  completeness gaps, spec misalignment, unresolved decisions, buildability
+  problems, quality smells
+  (timelines, "for now" shortcuts, magic values, fallbacks, missing type
+  contracts), and overlapping file ownership across parallel tasks. Resolve every
+  Issue before moving on; Recommendations are advisory.
+- Finally, present the finished plan for review with
+  \`crtr human review <absolute-path-to-the-plan.md>\` and incorporate the
+  returned comments. Wait for approval before moving on. Once the user approves,
+  run \`${MODE_CLI} normal\` to begin implementation — the command prints your
+  normal-mode operating instructions.`,
+	},
+};
+
+export default function modeSwitchExtension(pi: ExtensionAPI): void {
+	let currentMode: Mode = "normal";
+	// The mode whose guidance was last injected. Injection only fires when the
+	// active mode differs from this.
+	let lastInjectedMode: Mode | null = "normal";
+	// TUI handle, captured by the editor factory, so mode changes can repaint the
+	// input badge.
+	let activeTui: TUI | undefined;
+	// Watches <root>/mode-switch/request.json for agent-initiated CLI switches.
+	let modeWatcher: FSWatcher | undefined;
+	// UI toast, available only when the session has a UI.
+	let uiNotify: ((message: string, type?: "info" | "warning" | "error") => void) | undefined;
+	// Token of the most recent CLI request this instance has applied. Lets us
+	// reconcile to the request file WITHOUT deleting it: deleting was racy because
+	// /reload can leave extra extension instances behind, and a stale one could
+	// consume the request before the on-screen instance ever observed it.
+	let lastAppliedToken: string | undefined;
+
+	/** Append the mode badge to the bottom-right of the input box border. */
+	function decorateInput(
+		lines: string[],
+		width: number,
+		theme: { fg(color: string, text: string): string; bg(color: string, text: string): string },
+	): string[] {
+		if (lines.length === 0) return lines;
+		const def = MODES[currentMode];
+		const badge = theme.bg("selectedBg", theme.fg("text", ` ${def.label} `));
+		const badgeWidth = visibleWidth(badge);
+		if (badgeWidth + 2 >= width) return lines;
+		// Replace the rightmost cells of the bottom border line with the badge.
+		const last = lines.length - 1;
+		lines[last] = truncateToWidth(lines[last]!, width - badgeWidth, "") + badge;
+		return lines;
+	}
+
+	function repaint(): void {
+		activeTui?.requestRender();
+	}
+
+	function persist(): void {
+		pi.appendEntry("mode-switch", { mode: currentMode });
+	}
+
+	function persistCurrent(): void {
+		try {
+			writeFileSync(join(modeSwitchDir(), "current"), `${currentMode}\n`);
+		} catch {
+			// Best-effort: the viewer treats the file as a hint, not authority.
+		}
+	}
+
+	// Apply a mode change to state and persistence. Shared by every path: the
+	// Alt+M / command path (which adds a UI toast and injects guidance on the
+	// next turn) and the CLI path (which already handed the agent its guidance via
+	// stdout).
+	function applyMode(next: Mode): void {
+		currentMode = next;
+		repaint();
+		persist();
+		persistCurrent();
+	}
+
+	function setMode(next: Mode, ctx: ExtensionContext): void {
+		if (next === currentMode) {
+			ctx.ui.notify(`Already in ${next} mode.`, "info");
+			return;
+		}
+		applyMode(next);
+		ctx.ui.notify(
+			currentMode === "normal"
+				? "Normal mode — full access restored."
+				: `${currentMode[0].toUpperCase()}${currentMode.slice(1)} mode — guidance will be applied on your next message.`,
+		);
+	}
+
+	// The agent switches its own mode by running the bundled CLI, which writes the
+	// requested mode to <root>/mode-switch/request.json. We pick that up live via
+	// fs.watch (with a before_agent_start reconcile as a backstop) only to sync the
+	// badge and persisted state — never to inject guidance, since the CLI already
+	// printed it to the agent's bash output. The request is consumed on read so a
+	// later Alt+M can't be clobbered by a stale request.
+	function applyFromRequest(next: Mode, source: "cli" | "attach"): void {
+		if (next === currentMode) return;
+		applyMode(next);
+		if (source === "cli") lastInjectedMode = next;
+		uiNotify?.(source === "cli" ? `Mode → ${next} (agent)` : `Mode → ${next} (viewer)`, "info");
+	}
+
+	function reconcileFromCli(): void {
+		let raw: string;
+		try {
+			raw = readFileSync(join(modeSwitchDir(), "request.json"), "utf8");
+		} catch {
+			return; // no pending request
+		}
+		let parsed: { mode?: string; token?: string; source?: "cli" | "attach" };
+		try {
+			parsed = JSON.parse(raw) as { mode?: string; token?: string; source?: "cli" | "attach" };
+		} catch {
+			return; // half-written; a later watch event or turn catches the final write
+		}
+		// Apply each CLI request at most once (token-gated) and never delete it, so
+		// every live instance — including the one actually on screen — converges to the
+		// requested mode regardless of /reload leftovers. A lingering request whose
+		// token we already applied can't clobber a later Alt+M.
+		if (parsed.token && parsed.token === lastAppliedToken) return;
+		lastAppliedToken = parsed.token;
+		if (parsed.mode && (CYCLE as string[]).includes(parsed.mode)) {
+			applyFromRequest(parsed.mode as Mode, parsed.source ?? "cli");
+		}
+	}
+
+	function startModeWatcher(dir: string): void {
+		modeWatcher?.close();
+		try {
+			modeWatcher = watch(dir, (_event, filename) => {
+				if (filename && filename !== "request.json") return;
+				reconcileFromCli();
+			});
+		} catch {
+			// fs.watch unsupported here — the before_agent_start reconcile still covers it.
+		}
+	}
+
+	function cycleMode(ctx: ExtensionContext): void {
+		const idx = CYCLE.indexOf(currentMode);
+		setMode(CYCLE[(idx + 1) % CYCLE.length], ctx);
+	}
+
+	// Alt+M cycles modes.
+	pi.registerShortcut("alt+m", {
+		description: "Cycle mode (normal → spec → plan)",
+		handler: async (ctx) => cycleMode(ctx),
+	});
+
+	// /mode cycles; /mode <name> jumps to a specific mode.
+	pi.registerCommand("mode", {
+		description: "Cycle operating mode, or /mode <normal|spec|plan> to set one",
+		getArgumentCompletions: (prefix: string) => {
+			const items = CYCLE.map((m) => ({ value: m, label: m }));
+			const filtered = items.filter((i) => i.value.startsWith(prefix));
+			return filtered.length > 0 ? filtered : null;
+		},
+		handler: async (args, ctx) => {
+			const arg = args.trim().toLowerCase();
+			if (!arg) {
+				cycleMode(ctx);
+				return;
+			}
+			if ((CYCLE as string[]).includes(arg)) {
+				setMode(arg as Mode, ctx);
+			} else {
+				ctx.ui.notify(`Unknown mode "${arg}". Use: ${CYCLE.join(", ")}.`, "error");
+			}
+		},
+	});
+
+	// The core behaviour: inject the active mode's guidance before the turn, but
+	// only when the mode has changed since the last injection. We first reconcile
+	// any agent-initiated CLI switch the fs.watch may have missed.
+	pi.on("before_agent_start", async () => {
+		reconcileFromCli();
+		if (currentMode === lastInjectedMode) return;
+		lastInjectedMode = currentMode;
+		return {
+			message: {
+				customType: "mode-switch-context",
+				content: MODES[currentMode].context,
+				display: false,
+			},
+		};
+	});
+
+	// Keep only the most recent mode-guidance message and drop the older ones, so
+	// the LLM always sees the current mode's instructions (including the
+	// "restrictions lifted" note when returning to normal) and never stale
+	// guidance from a previous mode.
+	pi.on("context", async (event) => {
+		const messages = event.messages;
+		let lastIdx = -1;
+		for (let i = messages.length - 1; i >= 0; i--) {
+			if ((messages[i] as { customType?: string }).customType === "mode-switch-context") {
+				lastIdx = i;
+				break;
+			}
+		}
+		if (lastIdx === -1) return;
+		return {
+			messages: messages.filter((m, i) => {
+				return (m as { customType?: string }).customType !== "mode-switch-context" || i === lastIdx;
+			}),
+		};
+	});
+
+	// Restore persisted mode on session start / resume, and install the input
+	// badge.
+	pi.on("session_start", async (_event, ctx) => {
+		// Guarantee the per-cwd specs/ and plans/ dirs exist so spec/plan modes
+		// have somewhere to write the moment they're entered.
+		ensureArtifactDirs();
+
+		const entries = ctx.sessionManager.getEntries();
+		const last = entries
+			.filter((e: { type: string; customType?: string }) => e.type === "custom" && e.customType === "mode-switch")
+			.pop() as { data?: { mode?: Mode } } | undefined;
+
+		if (last?.data?.mode && (CYCLE as string[]).includes(last.data.mode)) {
+			currentMode = last.data.mode;
+		}
+
+		// Re-establish non-normal mode guidance on the next turn after a resume;
+		// normal mode needs no re-injection.
+		lastInjectedMode = currentMode === "normal" ? "normal" : null;
+
+		// Mirror each mode's guidance to disk so the CLI can hand the right one to the
+		// agent on stdout, clear any stale request from a previous session, write the
+		// current mode hint for the viewer, and start watching for mode requests.
+		const dir = modeSwitchDir();
+		try {
+			for (const mode of CYCLE) {
+				writeFileSync(join(dir, "guidance", `${mode}.txt`), MODES[mode].context);
+			}
+			writeFileSync(join(dir, "current"), `${currentMode}\n`);
+			rmSync(join(dir, "request.json"), { force: true });
+		} catch {
+			// Best-effort: the before_agent_start reconcile still covers switches.
+		}
+		lastAppliedToken = undefined;
+		startModeWatcher(dir);
+
+		if (!ctx.hasUI) return;
+		uiNotify = (message, type) => ctx.ui.notify(message, type);
+
+		// Wrap whatever editor is already installed (e.g. a session-name badge on
+		// the top border) so both decorations coexist. A transparent Proxy forwards
+		// every method/property to the base editor and overrides only render() to
+		// append the mode badge on the bottom-right border line.
+		const previousFactory = ctx.ui.getEditorComponent();
+		const uiTheme = ctx.ui.theme;
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+			activeTui = tui;
+			const base = previousFactory
+				? previousFactory(tui, theme, keybindings)
+				: new CustomEditor(tui, theme, keybindings);
+			return new Proxy(base, {
+				get(target, prop, receiver) {
+					if (prop === "render") {
+						return (width: number): string[] => decorateInput(target.render(width), width, uiTheme);
+					}
+					const value = Reflect.get(target, prop, target);
+					return typeof value === "function" ? value.bind(target) : value;
+				},
+			});
+		});
+		repaint();
+	});
+
+	// Stop watching the request file when the session ends.
+	pi.on("session_shutdown", async () => {
+		modeWatcher?.close();
+		modeWatcher = undefined;
+	});
+}

package/dist/builtin-pi-packages/pi-mode-switch/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "pi-mode-switch",
+  "version": "0.1.0",
+  "description": "Press Alt+M to cycle between spec, plan, and normal modes. Injects mode-specific operating guidance whenever the mode changes.",
+  "keywords": ["pi-package", "modes", "spec", "plan"],
+  "license": "MIT",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": ["./extensions"]
+  }
+}