pi-crew 0.6.4 → 0.7.2

package/src/extension/team-tool/handle-settings.ts

@@ -4,6 +4,11 @@ import { configPatchFromConfig } from "../team-tool/config-patch.ts";
 import { result } from "../team-tool/context.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { suggestConfigKey } from "../../config/suggestions.ts";
+import {
+	formatThemesListing,
+	discoverPiThemes,
+	setPiTheme,
+} from "../../ui/theme-discovery.ts";
 
 // ---------------------------------------------------------------------------
 // Effective defaults — values used when config key is not set
@@ -244,6 +249,8 @@ const USAGE = [
 	"  json                  Show full effective config as JSON",
 	"  schema                Show all known config keys (schema reference)",
 	"  paths                 Show config file paths (user + project)",
+	"  themes                Browse theme gallery (Pi UI themes)",
+	"  theme <name>          Switch the Pi UI theme (applies live, no restart)",
 	"  get <key>             Get a specific config value",
 	"  set <key> <value>     Set a config value",
 	"  unset <key>           Remove a config value",
@@ -319,6 +326,56 @@ export function handleSettings(params: { config?: Record<string, unknown> }, ctx
 		return result(lines.join("\n"), { ...OK, path: loaded.path } as never);
 	}
 
+	// team-settings themes — browse the theme gallery
+	if (args === "themes" || args === "theme-gallery") {
+		return result(formatThemesListing(), { ...OK } as never);
+	}
+
+	// team-settings theme <name> — switch the Pi UI theme
+	if (args === "theme" || args.startsWith("theme ")) {
+		const name = args === "theme" ? "" : args.slice(6).trim();
+		if (!name) {
+			const available = discoverPiThemes().map((t) => t.name).join(", ");
+			return result(
+				`Usage: team-settings theme <name>\n\nAvailable Pi themes: ${available}\n\nBrowse all: team-settings themes`,
+				{ ...ERR },
+				true,
+			);
+		}
+		const available = discoverPiThemes();
+		const exists = available.some((t) => t.name === name);
+		if (!exists) {
+			const hint = available.map((t) => t.name).join(", ");
+			return result(
+				`Unknown Pi theme: ${name}\n\nAvailable: ${hint}\n\nCustom themes live in ~/.pi/agent/themes/<name>.json`,
+				{ ...ERR },
+				true,
+			);
+		}
+		try {
+			const savedTo = setPiTheme(name);
+			return result(
+				[
+					`✓ Pi theme set to '${name}'`,
+					`  Written to: ${savedTo}`,
+					`  Applied live — no restart needed.`,
+				].join("\n"),
+				{ ...OK, theme: name } as never,
+			);
+		} catch (error) {
+			return result(error instanceof Error ? error.message : String(error), { ...ERR }, true);
+		}
+	}
+
+	// team-settings shiki <name> — removed (Shiki highlighting dropped)
+	if (args === "shiki" || args === "shiki-theme" || args.startsWith("shiki ") || args.startsWith("shiki-theme ")) {
+		return result(
+			`Shiki syntax highlighting has been removed from pi-crew.\nUse 'team-settings theme <name>' to switch the Pi UI theme, which drives code-block colors.`,
+			{ ...ERR },
+			true,
+		);
+	}
+
 	// team-settings scope [user|project]
 	if (args === "scope" || args.startsWith("scope ")) {
 		const scopeArg = args === "scope" ? "" : args.slice(6).trim();

package/src/extension/team-tool/inspect.ts

@@ -1,7 +1,7 @@
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { readEvents } from "../../state/event-log.ts";
 import { loadRunManifestById } from "../../state/state-store.ts";
-import { aggregateUsage, formatUsage } from "../../state/usage.ts";
+import { aggregateUsage, formatUsage, formatCostReport } from "../../state/usage.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { locateRunCwd } from "../team-tool.ts";
 import { result, type TeamContext } from "./context.ts";
@@ -41,6 +41,9 @@ export function handleSummary(params: TeamToolParamsValue, ctx: TeamContext): Pi
 		`Workflow: ${loaded.manifest.workflow ?? "(none)"}`,
 		`Goal: ${loaded.manifest.goal}`,
 		`Usage: ${formatUsage(usage)}`,
+		"",
+		formatCostReport(loaded.tasks),
+		"",
 		"Tasks:",
 		...loaded.tasks.map((task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`),
 	];

package/src/extension/team-tool/plan.ts

@@ -4,6 +4,7 @@ import { validateWorkflowForTeam } from "../../workflows/validate-workflow.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
+import { composeSingleAgentPrompt } from "../../runtime/single-agent-compose.ts";
 
 export function handlePlan(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	const teamName = params.team ?? "default";
@@ -14,6 +15,12 @@ export function handlePlan(params: TeamToolParamsValue, ctx: TeamContext): PiTea
 	if (!workflow) return result(`Workflow '${workflowName}' not found.`, { action: "plan", status: "error" }, true);
 	const errors = validateWorkflowForTeam(workflow, team);
 	if (errors.length > 0) return result([`Workflow '${workflow.name}' is not valid for team '${team.name}':`, ...errors.map((error) => `- ${error}`)].join("\n"), { action: "plan", status: "error" }, true);
-	const lines = [`Team plan: ${team.name}`, `Workflow: ${workflow.name}`, `Goal: ${params.goal ?? params.task ?? "(not provided)"}`, "", "Steps:", ...workflow.steps.map((step, index) => `${index + 1}. ${step.id} [${step.role}]${step.dependsOn?.length ? ` after ${step.dependsOn.join(", ")}` : ""}`)];
+	const goal = params.goal ?? params.task ?? "(not provided)";
+	// ROADMAP T2.2: single-agent composition mode (cliff hedge).
+	if (params.singleAgent) {
+		const composed = composeSingleAgentPrompt(workflow, goal);
+		return result([`Single-agent plan for ${team.name} / ${workflow.name} (${composed.stepCount} phases composed into one sequential prompt):`, "", composed.prompt, "", "This prompt can be handed to a single agent to execute the entire workflow sequentially — pi-crew's cliff-resilient mode (survives single-agent domination)."].join("\n"), { action: "plan", status: "ok" });
+	}
+	const lines = [`Team plan: ${team.name}`, `Workflow: ${workflow.name}`, `Goal: ${goal}`, "", "Steps:", ...workflow.steps.map((step, index) => `${index + 1}. ${step.id} [${step.role}]${step.dependsOn?.length ? ` after ${step.dependsOn.join(", ")}` : ""}`)];
 	return result(lines.join("\n"), { action: "plan", status: "ok" });
 }

package/src/runtime/intercom-bridge.ts

@@ -51,6 +51,10 @@ const MAX_QUEUE_SIZE = 100;
 export class IntercomQueue {
 	private pending = new Map<string, PendingMessage>();
 	private queue: IntercomMessage[] = [];
+	/** Monotonic sequence counter — guarantees unique IDs even when many
+	 * messages enqueue within the same millisecond (avoids Date.now()
+	 * collision + weak Math.random birthday-paradox flakes under load). */
+	private seq = 0;
 
 	/**
 	 * Enqueue a message and return a promise that resolves when the
@@ -63,7 +67,7 @@ export class IntercomQueue {
 			if (firstKey) this.evict(firstKey, "queue_full");
 		}
 
-		const id = `icm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+		const id = `icm-${Date.now().toString(36)}-${(this.seq++).toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 
 		return new Promise<IntercomResponse>((resolve) => {
 			const entry: PendingMessage = { message, id, resolve };

package/src/runtime/replace.ts

@@ -0,0 +1,555 @@
+/**
+ * Cascading text replacement engine ported from pi-diff.
+ *
+ * Tries exact → escape-normalized → line-trimmed → block-anchor →
+ * whitespace-normalized → trimmed-boundary matching to be lenient when
+ * AI agents provide slightly-wrong oldText (indentation drift, whitespace
+ * differences, escaped characters).
+ *
+ * When an LLM calls an edit tool with oldString + newString, the oldString
+ * often doesn't match exactly due to:
+ *   - Whitespace differences (indentation, trailing spaces)
+ *   - Escape sequences (LLMs escaping \n, \t, quotes in tool call params)
+ *   - Minor formatting drift (tabs vs spaces, trimmed lines)
+ *
+ * This module provides a cascade of replacer strategies, each progressively
+ * more lenient. The first strategy that finds exactly one match wins.
+ * If multiple candidates exist for a fuzzy strategy, we reject (safety first).
+ *
+ * Design inspired by OpenCode's edit tool (anomalyco/opencode) and
+ * Cline's diff-apply evals, but restructured for independent use.
+ *
+ * Standalone module: no pi-diff or pi-specific dependencies.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ReplaceResult {
+	/** The resulting content after replacement (unchanged if no match). */
+	content: string;
+	/** Whether a replacement was made. */
+	changed: boolean;
+	/** Name of the replacer strategy that matched, or "none". */
+	strategy: string;
+	/** Number of occurrences replaced (only when changed=true). */
+	count: number;
+}
+
+/**
+ * A replacer yields candidate substrings from `content` that match `find`.
+ * Each yielded string is an actual substring of `content` that the caller
+ * should replace. Yields nothing when no match is found.
+ */
+type Replacer = (content: string, find: string) => Generator<string, void, undefined>;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function countOccurrences(content: string, substring: string): number {
+	if (substring.length === 0) return 0;
+	let count = 0;
+	let pos = 0;
+	while (true) {
+		pos = content.indexOf(substring, pos);
+		if (pos === -1) break;
+		count++;
+		pos += substring.length;
+	}
+	return count;
+}
+
+/** Levenshtein distance for block anchor similarity comparison. */
+function levenshtein(a: string, b: string): number {
+	if (a === "" || b === "") return Math.max(a.length, b.length);
+	const matrix = Array.from({ length: a.length + 1 }, (_, i) =>
+		Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+	);
+	for (let i = 1; i <= a.length; i++) {
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+		}
+	}
+	return matrix[a.length][b.length];
+}
+
+// ---------------------------------------------------------------------------
+// Replacers (in priority order)
+// ---------------------------------------------------------------------------
+
+/**
+ * 1. Simple exact match.
+ */
+const SimpleReplacer: Replacer = function* (content, find) {
+	if (content.includes(find)) yield find;
+};
+
+/**
+ * 2. Escape-normalized match — unescapes common escape sequences
+ * in the find string before matching. Handles LLMs that escape
+ * tool call parameters (\\n, \\t, \\", etc.).
+ *
+ * Runs early (after Simple) so unescaped content flows through
+ * line-level strategies (LineTrimmed, BlockAnchor) correctly.
+ * Inspired by OpenCode's EscapeNormalizedReplacer.
+ */
+const EscapeNormalizedReplacer: Replacer = function* (content, find) {
+	const unescapeStr = (str: string): string => {
+		return str.replace(/\\([nrt'"`\\$])/g, (_match: string, char: string) => {
+			switch (char) {
+				case "n":
+					return "\n";
+				case "t":
+					return "\t";
+				case "r":
+					return "\r";
+				case "'":
+					return "'";
+				case '"':
+					return '"';
+				case "`":
+					return "`";
+				case "\\":
+					return "\\";
+				case "$":
+					return "$";
+				default:
+					return char;
+			}
+		});
+	};
+
+	const unescaped = unescapeStr(find);
+	if (unescaped === find) return; // nothing was escaped, skip
+	if (unescaped.length === 0) return;
+
+	// Yield the unescaped string if found directly in content
+	if (content.includes(unescaped)) {
+		yield unescaped;
+		return;
+	}
+
+	// Fallback: find matching blocks in content
+	const contentLines = content.split("\n");
+	const findLines = unescaped.split("\n");
+	for (let i = 0; i <= contentLines.length - findLines.length; i++) {
+		const block = contentLines.slice(i, i + findLines.length).join("\n");
+		if (block === unescaped || block.trim() === unescaped.trim()) {
+			yield block;
+			return;
+		}
+	}
+};
+
+/**
+ * 3. Line-trimmed match — compares lines after trimming whitespace.
+ * Handles cases where indentation or trailing whitespace differs.
+ */
+const LineTrimmedReplacer: Replacer = function* (content, find) {
+	const contentLines = content.split("\n");
+	const findLines = find.split("\n");
+
+	// Remove trailing empty line from find if present
+	if (findLines.length > 1 && findLines[findLines.length - 1] === "") {
+		findLines.pop();
+	}
+
+	if (findLines.length > contentLines.length) return;
+
+	for (let i = 0; i <= contentLines.length - findLines.length; i++) {
+		let matches = true;
+		for (let j = 0; j < findLines.length; j++) {
+			if (contentLines[i + j].trim() !== findLines[j].trim()) {
+				matches = false;
+				break;
+			}
+		}
+		if (matches) {
+			// Compute the actual substring in the original content
+			let startPos = 0;
+			for (let k = 0; k < i; k++) {
+				startPos += contentLines[k].length + 1;
+			}
+			let endPos = startPos;
+			for (let k = 0; k < findLines.length; k++) {
+				endPos += contentLines[i + k].length;
+				if (k < findLines.length - 1) endPos += 1;
+			}
+			yield content.slice(startPos, endPos);
+		}
+	}
+};
+
+/**
+ * 4. Block anchor match — uses first and last lines as anchors,
+ * then compares middle lines with Levenshtein similarity.
+ * Requires at least 3 lines in the find string.
+ *
+ * Dual threshold: single candidates get a lower bar (anchors alone
+ * are strong evidence), multiple candidates need higher similarity
+ * to disambiguate. Inspired by OpenCode's BlockAnchorReplacer.
+ */
+const BlockAnchorReplacer: Replacer = function* (content, find) {
+	const contentLines = content.split("\n");
+	const findLines = find.split("\n");
+
+	// Need at least 3 lines for meaningful anchor matching
+	if (findLines.length < 3) return;
+
+	if (findLines[findLines.length - 1] === "") findLines.pop();
+	if (findLines.length < 3) return;
+
+	const firstAnchor = findLines[0].trim();
+	const lastAnchor = findLines[findLines.length - 1].trim();
+	const searchBlockSize = findLines.length;
+
+	const SINGLE_CANDIDATE_THRESHOLD = 0.25;
+	const MULTIPLE_CANDIDATES_THRESHOLD = 0.4;
+
+	// Collect candidate positions where both anchors match
+	const candidates: Array<{ startLine: number; endLine: number }> = [];
+	for (let i = 0; i < contentLines.length; i++) {
+		if (contentLines[i].trim() !== firstAnchor) continue;
+		// Look for matching last line after this first line
+		for (let j = i + 2; j < contentLines.length; j++) {
+			if (contentLines[j].trim() === lastAnchor) {
+				candidates.push({ startLine: i, endLine: j });
+				break;
+			}
+		}
+	}
+
+	if (candidates.length === 0) return;
+
+	// Score each candidate by Levenshtein similarity
+	// Single candidate: relaxed threshold (anchors provide strong signal)
+	// Multiple candidates: require higher similarity to disambiguate
+	const isSingleCandidate = candidates.length === 1;
+	const threshold = isSingleCandidate ? SINGLE_CANDIDATE_THRESHOLD : MULTIPLE_CANDIDATES_THRESHOLD;
+
+	if (isSingleCandidate) {
+		const { startLine, endLine } = candidates[0];
+		const actualBlockSize = endLine - startLine + 1;
+		const middleCount = Math.min(searchBlockSize - 2, actualBlockSize - 2);
+		let similarity = 0;
+		if (middleCount > 0) {
+			for (let j = 1; j <= middleCount; j++) {
+				const originalLine = contentLines[startLine + j].trim();
+				const searchLine = findLines[j].trim();
+				const maxLen = Math.max(originalLine.length, searchLine.length);
+				if (maxLen === 0) continue;
+				const distance = levenshtein(originalLine, searchLine);
+				similarity += 1 - distance / maxLen;
+			}
+			similarity /= middleCount;
+		} else {
+			// No middle lines — anchors alone suffice
+			similarity = 1;
+		}
+		if (similarity >= threshold) {
+			let startPos = 0;
+			for (let k = 0; k < startLine; k++) startPos += contentLines[k].length + 1;
+			let endPos = startPos;
+			for (let k = startLine; k <= endLine; k++) {
+				endPos += contentLines[k].length;
+				if (k < endLine) endPos += 1;
+			}
+			yield content.slice(startPos, endPos);
+		}
+		return;
+	}
+
+	// Multiple candidates: pick best match above higher threshold
+	let bestMatch: { startLine: number; endLine: number } | null = null;
+	let bestSimilarity = -1;
+	for (const candidate of candidates) {
+		const { startLine, endLine } = candidate;
+		const actualBlockSize = endLine - startLine + 1;
+		const middleCount = Math.min(searchBlockSize - 2, actualBlockSize - 2);
+		let similarity = 0;
+		if (middleCount > 0) {
+			for (let j = 1; j <= middleCount; j++) {
+				const originalLine = contentLines[startLine + j].trim();
+				const searchLine = findLines[j].trim();
+				const maxLen = Math.max(originalLine.length, searchLine.length);
+				if (maxLen === 0) continue;
+				const distance = levenshtein(originalLine, searchLine);
+				similarity += 1 - distance / maxLen;
+			}
+			similarity /= middleCount;
+		} else {
+			similarity = 1;
+		}
+		if (similarity > bestSimilarity) {
+			bestSimilarity = similarity;
+			bestMatch = candidate;
+		}
+	}
+	if (!bestMatch || bestSimilarity < threshold) return;
+
+	// Yield the actual content substring
+	const { startLine, endLine } = bestMatch;
+	let startPos = 0;
+	for (let k = 0; k < startLine; k++) {
+		startPos += contentLines[k].length + 1;
+	}
+	let endPos = startPos;
+	for (let k = startLine; k <= endLine; k++) {
+		endPos += contentLines[k].length;
+		if (k < endLine) endPos += 1;
+	}
+	yield content.slice(startPos, endPos);
+};
+
+/**
+ * 5. Whitespace-normalized match — collapses all whitespace runs
+ * to single spaces and trims. Handles any whitespace differences.
+ */
+const WhitespaceNormalizedReplacer: Replacer = function* (content, find) {
+	const normalize = (text: string) => text.replace(/\s+/g, " ").trim();
+	const normalizedFind = normalize(find);
+
+	if (normalizedFind.length === 0) return;
+	const contentLines = content.split("\n");
+	const findLines = find.split("\n");
+
+	// Single-line: find by normalized line content
+	if (findLines.length <= 1 || (findLines.length === 2 && findLines[1] === "")) {
+		for (let i = 0; i < contentLines.length; i++) {
+			if (normalize(contentLines[i]) === normalizedFind) {
+				yield contentLines[i];
+			}
+		}
+		return;
+	}
+
+	// Multi-line: find blocks where normalized content matches
+	const effectiveFindLines = findLines[findLines.length - 1] === "" ? findLines.slice(0, -1) : findLines;
+	for (let i = 0; i <= contentLines.length - effectiveFindLines.length; i++) {
+		const block = contentLines.slice(i, i + effectiveFindLines.length);
+		if (normalize(block.join("\n")) === normalizedFind) {
+			yield block.join("\n");
+		}
+	}
+};
+
+/**
+ * 6. Indentation-flexible match — strips common leading indentation
+ * before comparing. Handles blocks that shifted indent level.
+ * NOTE: Excluded from the REPLACERS cascade — LineTrimmedReplacer's
+ * per-line trim() is a superset. Kept here as documentation artifact.
+ */
+const IndentationFlexibleReplacer: Replacer = function* (content, find) {
+	const removeIndent = (text: string): string => {
+		const lines = text.split("\n");
+		const nonEmpty = lines.filter((l) => l.trim().length > 0);
+		if (nonEmpty.length === 0) return text;
+		const minIndent = Math.min(
+			...nonEmpty.map((l) => {
+				const m = l.match(/^(\s*)/);
+				return m ? m[1].length : 0;
+			}),
+		);
+		return lines.map((l) => (l.trim().length === 0 ? l : l.slice(minIndent))).join("\n");
+	};
+
+	const normalizedFind = removeIndent(find);
+	if (normalizedFind.length === 0) return;
+
+	const contentLines = content.split("\n");
+	const findLines = find.split("\n");
+	const effectiveFindLines = findLines[findLines.length - 1] === "" ? findLines.slice(0, -1) : findLines;
+
+	for (let i = 0; i <= contentLines.length - effectiveFindLines.length; i++) {
+		const block = contentLines.slice(i, i + effectiveFindLines.length).join("\n");
+		if (removeIndent(block) === normalizedFind) {
+			yield block;
+		}
+	}
+};
+
+/**
+ * 7. Trimmed-boundary match — trims leading/trailing whitespace
+ * from the find string before matching. Handles accidental
+ * whitespace at boundaries.
+ */
+const TrimmedBoundaryReplacer: Replacer = function* (content, find) {
+	const trimmed = find.trim();
+	if (trimmed === find || trimmed.length === 0) return;
+
+	if (content.includes(trimmed)) {
+		yield trimmed;
+		return;
+	}
+
+	// Fallback: find blocks where the trimmed version matches
+	const contentLines = content.split("\n");
+	const findLines = find.split("\n");
+	for (let i = 0; i <= contentLines.length - findLines.length; i++) {
+		const block = contentLines.slice(i, i + findLines.length).join("\n");
+		if (block.trim() === trimmed) {
+			yield block;
+			return;
+		}
+	}
+};
+
+/**
+ * 8. Multi-occurrence replacer — yields ALL exact matches.
+ * NOTE: Excluded from the REPLACERS cascade because replaceAll is
+ * handled directly in the public `replace()` fast path for exact
+ * matches. Fuzzy-strategy replaceAll would be unsafe (ambiguous).
+ * Kept here as documentation artifact.
+ */
+const MultiOccurrenceReplacer: Replacer = function* (content, find) {
+	if (find.length === 0) return;
+
+	let pos = 0;
+	while (true) {
+		const idx = content.indexOf(find, pos);
+		if (idx === -1) break;
+		yield find;
+		pos = idx + find.length;
+	}
+};
+
+/**
+ * 9. Context-aware match — uses first and last lines as context
+ * anchors, then checks trimmed-line similarity (50%) for middle
+ * lines. Simpler than BlockAnchor (no Levenshtein).
+ * NOTE: Excluded from the REPLACERS cascade — BlockAnchorReplacer's
+ * Levenshtein-based scoring subsumes this. Kept as documentation.
+ */
+const ContextAwareReplacer: Replacer = function* (_content, _find) {
+	// Reference implementation in OpenCode:
+	// https://github.com/anomalyco/opencode/blob/dev/packages/opencode/src/tool/edit.ts
+};
+
+// ---------------------------------------------------------------------------
+// All replacers in priority order (active members)
+// ---------------------------------------------------------------------------
+
+const REPLACERS: Replacer[] = [
+	SimpleReplacer,
+	EscapeNormalizedReplacer,
+	LineTrimmedReplacer,
+	BlockAnchorReplacer,
+	WhitespaceNormalizedReplacer,
+	TrimmedBoundaryReplacer,
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Replace oldString with newString in content using a cascade of matching
+ * strategies. Tries exact match first, then progressively relaxes matching
+ * rules. If no strategy finds a match, returns unchanged content.
+ *
+ * Safety: if a fuzzy strategy finds multiple candidates, it is skipped
+ * (we never auto-pick among ambiguous matches). Only exact matches
+ * (SimpleReplacer) are allowed to match multiple occurrences, and only
+ * when replaceAll=true.
+ *
+ * @param content - The full file content to edit.
+ * @param oldString - The text to find and replace.
+ * @param newString - The replacement text.
+ * @param options.replaceAll - When true, replace ALL non-overlapping
+ *   occurrences. Only safe for exact matches (simple replacer).
+ * @returns ReplaceResult with the new content and match strategy info.
+ */
+export function replace(
+	content: string,
+	oldString: string,
+	newString: string,
+	options?: { replaceAll?: boolean },
+): ReplaceResult {
+	if (oldString.length === 0) {
+		return { content, changed: false, strategy: "none", count: 0 };
+	}
+	if (oldString === newString) {
+		return { content, changed: false, strategy: "none", count: 0 };
+	}
+
+	const replaceAll = options?.replaceAll ?? false;
+
+	// Fast path: simple exact match with replaceAll
+	if (replaceAll && content.includes(oldString)) {
+		const result = content.replaceAll(oldString, newString);
+		if (result !== content) {
+			const count = countOccurrences(content, oldString);
+			return { content: result, changed: true, strategy: "simple-replaceAll", count };
+		}
+	}
+
+	// Fast path: single exact match
+	if (!replaceAll) {
+		const idx = content.indexOf(oldString);
+		if (idx !== -1) {
+			const lastIdx = content.lastIndexOf(oldString);
+			if (idx === lastIdx) {
+				// Exactly one occurrence
+				const result = content.slice(0, idx) + newString + content.slice(idx + oldString.length);
+				return { content: result, changed: true, strategy: "simple", count: 1 };
+			}
+			// Multiple occurrences — fall through to fuzzy strategies
+			// (we never auto-pick among duplicates)
+		}
+	}
+
+	// Run through each replacer strategy in priority order
+	for (const replacer of REPLACERS) {
+		// Skip SimpleReplacer — already handled above
+		if (replacer === SimpleReplacer) continue;
+
+		const candidates: string[] = [];
+		for (const candidate of replacer(content, oldString)) {
+			candidates.push(candidate);
+		}
+
+		if (candidates.length === 0) continue;
+
+		if (replaceAll) {
+			// For replaceAll, use all candidates
+			let result = content;
+			let totalCount = 0;
+			for (const candidate of candidates) {
+				const count = countOccurrences(result, candidate);
+				if (count > 0) {
+					result = result.replaceAll(candidate, newString);
+					totalCount += count;
+				}
+			}
+			if (totalCount > 0) {
+				const strategyName = replacer.name
+					.replace("Replacer", "")
+					.replace(/([a-z])([A-Z])/g, "$1-$2")
+					.toLowerCase();
+				return { content: result, changed: true, strategy: `${strategyName}-replaceAll`, count: totalCount };
+			}
+			continue;
+		}
+
+		// Single replacement: must have exactly one candidate
+		if (candidates.length === 1) {
+			const candidate = candidates[0];
+			const idx = content.indexOf(candidate);
+			if (idx !== -1) {
+				const result = content.slice(0, idx) + newString + content.slice(idx + candidate.length);
+				const strategyName = replacer.name
+					.replace("Replacer", "")
+					.replace(/([a-z])([A-Z])/g, "$1-$2")
+					.toLowerCase();
+				return { content: result, changed: true, strategy: strategyName, count: 1 };
+			}
+		}
+		// Multiple candidates — skip this strategy (safety first)
+	}
+
+	// No match found
+	return { content, changed: false, strategy: "none", count: 0 };
+}