one-code-extension 0.4.1 → 0.6.0

package/extensions/plugins/panel/keys.ts

@@ -1,52 +1,49 @@
 /**
- * Raw-byte key decoding for the /plugins panel (pure).
+ * Key decoding for the /plugins panel (pure), named through
+ * `lib/key-input.ts` so every terminal encoding of a key decodes alike.
  *
- * Navigation bytes are always controls; any other printable input is a `text`
+ * Navigation keys are always controls; any other printable input is a `text`
  * intent the state layer routes (search box, Add Marketplace draft, or a
  * single-letter action where the active view has no text field). Unrecognized
  * escape sequences are swallowed so they never leak into a draft.
  */
 
+import { keyId, keyText } from "../../lib/key-input.ts";
+
 export type PanelKey =
 	| { kind: "up" | "down" | "pageUp" | "pageDown" | "nextTab" | "prevTab" | "enter" | "back" | "space" | "backspace" | "close" }
 	| { kind: "text"; text: string };
 
 export function decodePanelKey(data: string): PanelKey | undefined {
-	switch (data) {
-		case "\x1b[A":
-		case "\x1bOA":
+	switch (keyId(data)) {
+		case "up":
 			return { kind: "up" };
-		case "\x1b[B":
-		case "\x1bOB":
+		case "down":
 			return { kind: "down" };
-		case "\x1b[5~":
+		case "pageUp":
 			return { kind: "pageUp" };
-		case "\x1b[6~":
+		case "pageDown":
 			return { kind: "pageDown" };
-		case "\x1b[C":
-		case "\x1bOC":
-		case "\t":
+		case "right":
+		case "tab":
 			return { kind: "nextTab" };
-		case "\x1b[D":
-		case "\x1bOD":
-		case "\x1b[Z":
+		case "left":
+		case "shift+tab":
 			return { kind: "prevTab" };
-		case "\r":
-		case "\n":
+		case "enter":
 			return { kind: "enter" };
-		case "\x1b":
+		case "escape":
 			return { kind: "back" };
-		case " ":
+		case "space":
 			return { kind: "space" };
-		case "\x7f":
-		case "\b":
+		case "backspace":
+		case "ctrl+backspace":
 			return { kind: "backspace" };
-		case "\x03": // ctrl+c
+		case "ctrl+c":
 			return { kind: "close" };
 		default:
 			break;
 	}
-	if (data.startsWith("\x1b")) return undefined;
-	const text = [...data].filter((ch) => ch >= " " && ch !== "\x7f").join("");
+	const text = keyText(data);
 	return text ? { kind: "text", text } : undefined;
 }

package/extensions/plugins/panel/render.ts

@@ -7,7 +7,7 @@
  */
 
 import { formatInstallCount } from "../counts.ts";
-import { cutPlainText, panelTopRule, type RenderBlock as Block, searchBoxLines, windowBlocks } from "../../lib/tui-render.ts";
+import { cutPlainText, hintLines, panelTopRule, type RenderBlock as Block, searchBoxLines, windowBlocks } from "../../lib/tui-render.ts";
 import type { DiscoverRow, InstalledRow } from "./rows.ts";
 import { clampPanelState, type PanelState, type PanelView, resolveDetail, selectableRows, TABS, type Tab } from "./state.ts";
 
@@ -176,7 +176,7 @@ function detailLines(input: PanelRenderInput, paint: PanelPaint): { lines: strin
 		const discover = row as DiscoverRow;
 		const detail = input.discoverDetails.get(discover.id);
 		push(`${discover.name} · ${discover.marketplace}`, paint.bold);
-		if (discover.description) push(discover.description);
+		if (discover.description) for (const line of wrapNote(discover.description, width - 4)) push(line);
 		push("");
 		if (detail?.version) push(`Version: ${detail.version}`, (t) => paint.fg("dim", t));
 		if (detail?.author) push(`Author: ${detail.author}`, (t) => paint.fg("dim", t));
@@ -250,20 +250,26 @@ const FOOTERS: Record<Tab, string[]> = {
 /** Installed search hints while the `/` box is open (Esc leaves it). */
 const INSTALLED_SEARCH_FOOTER = ["Type to search · Enter/Space to toggle · Esc to leave search"];
 
+/** Footer hint lines wrapped at their separators to the panel's width (one leading space), so no key is cut off. */
+function fitFooter(lines: string[], width: number): string[] {
+	return hintLines(lines, width - 1, " ");
+}
+
 export function renderPanel(input: PanelRenderInput, paint: PanelPaint): string[] {
 	const { state, view, width, height } = input;
 	clampPanelState(state, view);
 
 	const out: string[] = [panelTopRule(paint.fg, width), tabBar(state, view, paint, width), ""];
+	// Wrapped to the width where it is set: the list counts its lines for the budget.
 	let footer: string[];
 
 	if (state.addDialog) {
 		out.push(...addDialogLines(state.addDialog.draft, paint, width));
-		footer = ["Enter to add · Esc to cancel"];
+		footer = fitFooter(["Enter to add · Esc to cancel"], width);
 	} else if (state.detail) {
 		const detail = detailLines(input, paint);
 		out.push(...detail.lines);
-		footer = [detail.footer];
+		footer = fitFooter([detail.footer], width);
 	} else {
 		let blocks: Block[];
 		switch (state.tab) {
@@ -293,7 +299,7 @@ export function renderPanel(input: PanelRenderInput, paint: PanelPaint): string[
 				break;
 			}
 		}
-		footer = state.tab === "installed" && state.installedSearching ? INSTALLED_SEARCH_FOOTER : FOOTERS[state.tab];
+		footer = fitFooter(state.tab === "installed" && state.installedSearching ? INSTALLED_SEARCH_FOOTER : FOOTERS[state.tab], width);
 		const budget = Math.max(3, height - out.length - 2 - footer.length);
 		const windowed = windowBlocks(blocks, state.cursor[state.tab], budget);
 		out.push(...windowed.lines);
@@ -310,6 +316,6 @@ export function renderPanel(input: PanelRenderInput, paint: PanelPaint): string[
 			),
 		);
 	}
-	out.push("", ...footer.map((line) => paint.fg("dim", cutPlainText(` ${line}`, width - 1))));
+	out.push("", ...footer.map((line) => paint.fg("dim", line)));
 	return out;
 }

package/extensions/plugins/shell-expand.ts

@@ -0,0 +1,107 @@
+/**
+ * Expanding a plugin command body: arguments, then each `` !`command` ``
+ * placeholder replaced with that command's output.
+ *
+ * Two rules keep a typed argument from becoming shell syntax. Placeholders
+ * are found in the body as written, before any argument goes in, and an
+ * argument substituted into a placeholder's command goes in as a
+ * single-quoted word (`template.ts`), so `$(…)`, `;` or a backtick pair in
+ * what the user typed stays text. And the command runs in the bash every
+ * other shell path uses (`lib/shell-spawn.ts`: Git Bash on Windows, never a
+ * bare `/bin/sh` or `cmd.exe`), as Claude Code runs these in its bash:
+ * Node's `shell: true` used `/bin/sh` (dash on Debian and Ubuntu) and
+ * `cmd.exe`, where `[[ ]]`, `head` and process substitution fail and the
+ * error text became the placeholder's output.
+ */
+
+import type { ChildProcess } from "node:child_process";
+import { detachedSpawnOptions, killProcessTree, waitForChildExit } from "../lib/process-tree.ts";
+import { bashSpawn, type ShellSpawn, spawnShellCommand } from "../lib/shell-spawn.ts";
+import { shellQuote } from "../lib/shell-quote.ts";
+import { splitShellPlaceholders, substituteArguments } from "./template.ts";
+
+export const SHELL_TIMEOUT_MS = 30_000;
+/** A placeholder output past this many characters stops being collected, and says so. */
+const MAX_OUTPUT_CHARS = 2 * 1024 * 1024;
+
+/**
+ * Run one placeholder command in bash and return its stdout (stderr when
+ * stdout is empty), trimmed. A failure returns its error text, as before:
+ * the placeholder shows what went wrong rather than vanishing.
+ */
+export async function runPlaceholderCommand(
+	command: string,
+	cwd: string,
+	opts: { spec?: ShellSpawn; timeoutMs?: number; maxOutputChars?: number } = {},
+): Promise<string> {
+	const spec = opts.spec ?? bashSpawn().spawn;
+	if (!spec) return `command failed: ${bashSpawn().error ?? "no bash shell found"}`;
+	let child: ChildProcess;
+	try {
+		child = spawnShellCommand(spec, command, { cwd, stdio: ["ignore", "pipe", "pipe"], ...detachedSpawnOptions() });
+	} catch (error) {
+		return `command failed: ${error instanceof Error ? error.message : String(error)}`;
+	}
+	const maxChars = opts.maxOutputChars ?? MAX_OUTPUT_CHARS;
+	let stdout = "";
+	let stderr = "";
+	const cut = { stdout: false, stderr: false };
+	const capture = (sink: "stdout" | "stderr") => (chunk: string) => {
+		const current = sink === "stdout" ? stdout : stderr;
+		if (current.length + chunk.length > maxChars) cut[sink] = true;
+		if (current.length >= maxChars) return;
+		const next = current + chunk.slice(0, maxChars - current.length);
+		if (sink === "stdout") stdout = next;
+		else stderr = next;
+	};
+	child.stdout?.setEncoding("utf8");
+	child.stderr?.setEncoding("utf8");
+	child.stdout?.on("data", capture("stdout"));
+	child.stderr?.on("data", capture("stderr"));
+	let timedOut = false;
+	const timeoutMs = opts.timeoutMs ?? SHELL_TIMEOUT_MS;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		killProcessTree(child, "SIGKILL");
+	}, timeoutMs);
+	timer.unref();
+	try {
+		await waitForChildExit(child);
+	} catch (error) {
+		return `command failed: ${error instanceof Error ? error.message : String(error)}`;
+	} finally {
+		clearTimeout(timer);
+	}
+	// The model must know an output is incomplete (a `git diff` cut mid-file).
+	const shown = stdout ? "stdout" : "stderr";
+	const text = `${(stdout || stderr).trim()}${cut[shown] ? `\n[output cut after ${maxChars} characters]` : ""}`;
+	if (timedOut) return `${text ? `${text}\n` : ""}command timed out after ${Math.round(timeoutMs / 1000)} seconds`;
+	return text;
+}
+
+/**
+ * Expand a command body: every placeholder's command runs once (with the
+ * arguments quoted in), text pieces get the arguments as typed, and an
+ * output is never scanned for arguments or placeholders again. `persist`
+ * bounds each output (a large `git diff`) before it lands in the prompt.
+ */
+export async function expandTemplate(
+	body: string,
+	args: string,
+	cwd: string,
+	opts: { persist?: (text: string, index: number) => string; run?: (command: string, cwd: string) => Promise<string> } = {},
+): Promise<string> {
+	const pieces = splitShellPlaceholders(body);
+	const commands = [...new Set(pieces.flatMap((piece) => (piece.kind === "shell" ? [substituteArguments(piece.command, args, shellQuote)] : [])))];
+	const run = opts.run ?? ((command: string, dir: string) => runPlaceholderCommand(command, dir));
+	const outputs = new Map<string, string>();
+	await Promise.all(
+		commands.map(async (command, index) => {
+			const text = await run(command, cwd);
+			outputs.set(command, opts.persist ? opts.persist(text, index) : text);
+		}),
+	);
+	return pieces
+		.map((piece) => (piece.kind === "text" ? substituteArguments(piece.text, args) : (outputs.get(substituteArguments(piece.command, args, shellQuote)) ?? "")))
+		.join("");
+}

package/extensions/plugins/template.ts

@@ -1,5 +1,5 @@
 /**
- * Claude Code command-template expansion (pure apart from the shell hook).
+ * Claude Code command-template expansion (pure; `shell-expand.ts` runs the commands).
  *
  * A command markdown file has frontmatter (`description`, `allowed-tools`,
  * `argument-hint`) and a body that may contain:
@@ -17,26 +17,43 @@ export interface CommandTemplate {
 	body: string;
 }
 
-export function substituteArguments(body: string, args: string): string {
+/**
+ * Replace `$ARGUMENTS`, `$@` and `$1`… with the invocation's arguments. With
+ * `quote`, each argument word is passed through it (a shell placeholder's
+ * command gets them as quoted words), so `$ARGUMENTS` stays one word per
+ * argument and no argument can add shell syntax.
+ */
+export function substituteArguments(body: string, args: string, quote?: (word: string) => string): string {
 	const parts = args.trim().length > 0 ? args.trim().split(/\s+/) : [];
-	return body
-		.replace(/\$ARGUMENTS\b/g, args.trim())
-		.replace(/\$@/g, args.trim())
-		.replace(/\$(\d+)/g, (_match, index) => parts[Number(index) - 1] ?? "");
+	const all = quote ? parts.map(quote).join(" ") : args.trim();
+	// One pass: a second pass would substitute inside argument text the first
+	// one inserted (an argument holding `$1`), unquoting it.
+	return body.replace(/\$ARGUMENTS\b|\$@|\$(\d+)/g, (_match, index: string | undefined) => {
+		if (index === undefined) return all;
+		const part = parts[Number(index) - 1];
+		return quote ? quote(part ?? "") : (part ?? "");
+	});
 }
 
-/** Finds each !`command` occurrence so the caller can run them. */
-export function findShellPlaceholders(body: string): string[] {
-	const found: string[] = [];
+export type TemplatePiece = { kind: "text"; text: string } | { kind: "shell"; command: string };
+
+/**
+ * A template body split into text and `` !`command` `` placeholders, found in
+ * the body as written: an argument substituted later can never become a
+ * placeholder. Until 2026-09-27 the arguments went in first, so an argument
+ * holding `` !`…` `` ran as a command of its own.
+ */
+export function splitShellPlaceholders(body: string): TemplatePiece[] {
+	const pieces: TemplatePiece[] = [];
 	const pattern = /!`([^`]+)`/g;
+	let last = 0;
 	let match = pattern.exec(body);
 	while (match) {
-		found.push(match[1]);
+		if (match.index > last) pieces.push({ kind: "text", text: body.slice(last, match.index) });
+		pieces.push({ kind: "shell", command: match[1] });
+		last = match.index + match[0].length;
 		match = pattern.exec(body);
 	}
-	return found;
-}
-
-export function replaceShellPlaceholders(body: string, outputs: Map<string, string>): string {
-	return body.replace(/!`([^`]+)`/g, (_match, command: string) => outputs.get(command) ?? "");
+	if (last < body.length) pieces.push({ kind: "text", text: body.slice(last) });
+	return pieces;
 }

package/extensions/powershell/child.ts

@@ -0,0 +1,7 @@
+/** One Code's PowerShell tool for an in-process child session (lib/child-extensions.ts): the same tool and activation, prints nothing. */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { powershellTool } from "./index.ts";
+
+export default function childPowershellExtension(pi: ExtensionAPI) {
+	powershellTool(pi, { announce: false });
+}

package/extensions/powershell/description.ts

@@ -10,9 +10,11 @@
  * (identical in the reconstructed `PowerShellTool/prompt.ts`). The
  * "Developer tools verified on this machine's PATH" list Claude Code can add
  * sits behind a remote flag that was off in the capture, so it is not
- * reproduced. One Code appends its own short note about the deferred task
- * tools and the `Start-Sleep` guard, after the captured text, the way the
- * bash tool does.
+ * reproduced. The shipped text corrects the captured working-directory
+ * sentence (`CC_CWD_SENTENCE`), drops the Glob/Grep lines
+ * (`CC_SEARCH_LINES`) and appends One
+ * Code's own short note about the deferred task tools and the `Start-Sleep`
+ * guard, after the captured text, the way the bash tool does.
  */
 
 export type PowerShellEditionName = "core" | "desktop" | "unknown";
@@ -126,14 +128,44 @@ Usage notes:
 
 /** One Code's addendum: where the harness differs from Claude Code's runtime (task tools are deferred, the sleep guard). */
 export const ONE_CODE_ADDENDUM =
-	" A background run returns a task id immediately; completion arrives as a task notification, and the output is retrievable with task_output / stoppable with task_stop (both deferred — load them with tool_search; in a one-shot print/json session the call runs to completion and returns the output directly). A foreground command that LEADS with `Start-Sleep` is blocked; to wait on a condition use the monitor tool (deferred — load it with tool_search select:monitor).";
+	" A background run returns a task id immediately; completion arrives as a task notification, and the output is retrievable with task_output / stoppable with task_stop (both deferred — load them with tool_search; in a one-shot print/json session the call runs to completion within the foreground timeout and returns the output directly). A foreground command that LEADS with `Start-Sleep` is blocked; to wait on a condition use the monitor tool (deferred — load it with tool_search select:monitor).";
 
 /** Claude Code's description for the detected edition, verbatim, without One Code's addendum. */
 export function claudeCodePowerShellDescription(edition: PowerShellEditionName): string {
 	return TEMPLATE.replace("{{EDITION}}", EDITION_SECTIONS[edition]);
 }
 
-/** The description the `powershell` tool ships: Claude Code's text plus One Code's addendum. */
+/**
+ * Claude Code's shell keeps its working directory between calls; pi's
+ * PowerShell tool spawns a fresh process per call in the session's directory,
+ * so a `Set-Location` ends with its command. A model that trusts the captured
+ * sentence would `cd` in one call and resolve relative paths against the
+ * wrong folder in the next, so the shipped text swaps it.
+ */
+export const CC_CWD_SENTENCE = "Working directory persists between commands; shell state (variables, functions) does not.";
+export const ONE_CODE_CWD_SENTENCE =
+	"Each command starts in the session's working directory; neither a directory change (`cd`, `Set-Location`) nor shell state (variables, functions) carries over to the next command.";
+
+/**
+ * Claude Code's PowerShell prompt names Glob and Grep even in its native
+ * builds, which ship neither (their Bash prompt drops the same two lines).
+ * One Code ships no search tools outside the tiny tier, so the lines would
+ * forbid the only search route left (`Get-ChildItem -Recurse`,
+ * `Select-String`); they are dropped on every tier. A tiny model still sees
+ * `find` and `grep` in its tool list.
+ */
+export const CC_SEARCH_LINES =
+	"    - File search: Use Glob (NOT Get-ChildItem -Recurse)\n    - Content search: Use Grep (NOT Select-String)\n";
+
+/** The same reason takes searching out of the file operations the tool is told to leave alone. */
+export const CC_FILE_OPERATIONS = "(reading, writing, editing, searching, finding files)";
+export const ONE_CODE_FILE_OPERATIONS = "(reading, writing, editing files)";
+
+/** The description the `powershell` tool ships: Claude Code's text with the corrections above, plus One Code's addendum. */
 export function powerShellToolDescription(edition: PowerShellEditionName): string {
-	return `${claudeCodePowerShellDescription(edition)}${ONE_CODE_ADDENDUM}`;
+	const text = claudeCodePowerShellDescription(edition)
+		.replace(CC_CWD_SENTENCE, ONE_CODE_CWD_SENTENCE)
+		.replace(CC_SEARCH_LINES, "")
+		.replace(CC_FILE_OPERATIONS, ONE_CODE_FILE_OPERATIONS);
+	return `${text}${ONE_CODE_ADDENDUM}`;
 }

package/extensions/powershell/guards.ts

@@ -64,7 +64,7 @@ export function powershellGuardReason(command: string, opts: { background: boole
 			// finds "rebase" instead of misreading the flag's value as the
 			// subcommand and missing the interactive-editor guard entirely.
 			const words = statement.trim().split(/\s+/).slice(1);
-			const { sub, rest } = gitSubcommand(words.map((value) => ({ value, hadExpansion: false })));
+			const { sub, rest } = gitSubcommand(words.map((value) => ({ value })));
 			const flags = new Set(rest.map((t) => t.value));
 			if (sub === "rebase" && (flags.has("-i") || flags.has("--interactive"))) {
 				return (

package/extensions/powershell/index.ts

@@ -1,13 +1,13 @@
 /**
  * powershell extension — Claude Code's PowerShell tool on top of pi's own
- * `powershell` built-in (docs/decisions/windows.md, findings §22).
+ * `powershell` built-in (working-docs/decisions/windows.md, findings §22).
  *
  * Registering a tool named `powershell` overrides pi's built-in (findings §2),
  * exactly as `extensions/bash` overrides `bash`, and the shared body in
  * lib/shell-tool.ts supplies the `run_in_background` orchestration for both.
  * The foreground path delegates to pi's real definition
- * (`createPowerShellToolDefinition`) so schema, cwd handling, truncation and
- * streaming stay upstream's — with One Code's own `operations`
+ * (`createPowerShellToolDefinition`) so schema, cwd handling and streaming
+ * stay upstream's (a long output is cut Claude Code's way, as for bash) — with One Code's own `operations`
  * (lib/shell-spawn.ts), because pi's local operations throw off Windows and
  * this tool is developed against a `pwsh` on this Mac. The description is
  * Claude Code's captured text (description.ts); the guards are the PowerShell
@@ -25,7 +25,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { createPowerShellToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { perCwd } from "../lib/per-cwd.ts";
-import { bashSpawn, createPowerShellOperations, POWERSHELL_UTF8_PREFIX, powerShellEdition, powerShellSpawn } from "../lib/shell-spawn.ts";
+import { bashSpawn, createPowerShellOperations, POWERSHELL_TOOL_PREFIX, powerShellEdition, powerShellSpawn } from "../lib/shell-spawn.ts";
 import { registerShellTool } from "../lib/shell-tool.ts";
 import { powerShellToolDescription } from "./description.ts";
 import { powershellGuardReason } from "./guards.ts";
@@ -40,6 +40,11 @@ const PowerShellParams = Type.Object({
 });
 
 export default function powershellExtension(pi: ExtensionAPI) {
+	powershellTool(pi, { announce: true });
+}
+
+/** The tool itself; `announce: false` is the in-process child's shape (powershell/child.ts), which prints no notices. */
+export function powershellTool(pi: ExtensionAPI, { announce }: { announce: boolean }) {
 	const spec = powerShellSpawn();
 	const operations = createPowerShellOperations(() => spec);
 	const base = createPowerShellToolDefinition(process.cwd(), { operations });
@@ -66,8 +71,8 @@ export default function powershellExtension(pi: ExtensionAPI) {
 		foreground: perCwd((cwd: string) => createPowerShellToolDefinition(cwd, { operations })),
 		guard: powershellGuardReason,
 		backgroundShell: () => spec,
-		// The foreground path prepends pi's UTF-8 prefix inside the operations; the background spawn needs it too.
-		wrapBackgroundCommand: (command) => `${POWERSHELL_UTF8_PREFIX}${command}`,
+		// The foreground path prepends the tool's prefix inside the operations; the background spawn needs it too.
+		wrapBackgroundCommand: (command) => `${POWERSHELL_TOOL_PREFIX}${command}`,
 	});
 
 	let noticesShown = false;
@@ -76,7 +81,7 @@ export default function powershellExtension(pi: ExtensionAPI) {
 		const active = pi.getActiveTools();
 		const next = withShellTools(active, current);
 		if (next.join(" ") !== active.join(" ")) pi.setActiveTools(next);
-		if (noticesShown || current.notices.length === 0) return;
+		if (!announce || noticesShown || current.notices.length === 0) return;
 		noticesShown = true;
 		for (const notice of current.notices) {
 			if (ctx?.hasUI) ctx.ui.notify(notice, "warning");
@@ -86,4 +91,6 @@ export default function powershellExtension(pi: ExtensionAPI) {
 
 	pi.on("session_start", (_event, ctx) => reconcile(ctx));
 	pi.on("model_select", () => reconcile());
+	// pi restores the selected branch's tool loadout at a /tree switch.
+	pi.on("session_tree", () => reconcile());
 }