@zihanw/pi-forge 0.2.0 → 0.3.0

package/src/sillytavern-importer.ts

@@ -1,12 +1,16 @@
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
-import type { PromptStack, PromptStackItem } from "./types.ts";
+import type { PromptRegexRule, PromptStack, PromptStackItem } from "./types.ts";
 
 // ── SillyTavern preset raw types ──────────────────────────────────────────
 
 interface StPreset {
 	prompts?: StPromptDef[];
 	prompt_order?: StPromptOrderEntry[];
+	extensions?: {
+		regex_scripts?: unknown[];
+		[key: string]: unknown;
+	};
 	names_behavior?: number;
 	preset_name?: string;
 	name?: string;
@@ -39,6 +43,57 @@ interface StConversionItem {
 	orderIndex: number;
 }
 
+interface StRegexScript {
+	script_name?: string;
+	scriptName?: string;
+	name?: string;
+	disabled?: boolean;
+	promptOnly?: boolean;
+	markdownOnly?: boolean;
+	findRegex?: string;
+	replaceString?: string;
+	trimStrings?: unknown;
+	substituteRegex?: unknown;
+	placement?: unknown;
+	minDepth?: unknown;
+	maxDepth?: unknown;
+	runOnEdit?: unknown;
+	[key: string]: unknown;
+}
+
+type RegexScriptMode = "prompt-only" | "markdown-only" | "prompt+markdown" | "unspecified" | "disabled";
+
+interface RegexScriptReportEntry {
+	name: string;
+	mode: RegexScriptMode;
+	enabled: boolean;
+	promptOnly: boolean;
+	markdownOnly: boolean;
+	findRegex?: string;
+	replaceString?: string;
+	trimStrings?: string[];
+	placement?: number[];
+	substituteRegex?: number;
+	minDepth?: number;
+	maxDepth?: number;
+	convertedRuleId?: string;
+	conversionNote?: string;
+	conversionWarnings: string[];
+}
+
+interface RegexScriptReport {
+	total: number;
+	enabled: number;
+	disabled: number;
+	promptOnly: number;
+	markdownOnly: number;
+	mixed: number;
+	unspecified: number;
+	converted: number;
+	scripts: RegexScriptReportEntry[];
+	rules: PromptRegexRule[];
+}
+
 // ── Marker identifiers ─────────────────────────────────────────────────────
 
 const MARKER_CHAT_HISTORY = "chatHistory";
@@ -52,6 +107,15 @@ const MARKER_SKIP = new Set([
 	"dialogueExamples",
 ]);
 
+const ST_REGEX_PLACEMENT_LABELS: Record<number, string> = {
+	0: "MD Display",
+	1: "User Input",
+	2: "AI Output",
+	3: "Slash Commands",
+	5: "World Info",
+	6: "Reasoning",
+};
+
 // ── ST macros that pi-forge handles natively ───────────────────────────────
 
 const NATIVE_MACROS = new Set([
@@ -61,6 +125,16 @@ const NATIVE_MACROS = new Set([
 	"cwd",
 	"date",
 	"time",
+	"setvar",
+	"setturnvar",
+	"setsessionvar",
+	"getvar",
+	"var",
+	"getturnvar",
+	"getsessionvar",
+	"clearvar",
+	"clearturnvar",
+	"clearsessionvar",
 ]);
 
 const MACRO_DISPLAY_NAMES: Record<string, string> = {
@@ -85,8 +159,6 @@ const MACRO_DISPLAY_NAMES: Record<string, string> = {
 // ── ST macros that need manual migration ───────────────────────────────────
 
 const MACRO_NEEDS_MIGRATION: Record<string, string> = {
-	"setvar": "pi-forge {{setvar::name::value}} / {{setsessionvar::name::value}} — scoping differs",
-	"getvar": "pi-forge {{getvar::name}} — lookup order: turn → session → static",
 	"addvar": "use pi-forge {{getvar::name}} + math, or setvar with computed value",
 	"getglobalvar": "use pi-forge session variables via {{getsessionvar::name}}",
 	"setglobalvar": "use pi-forge {{setsessionvar::name::value}}",
@@ -119,6 +191,19 @@ const MACRO_NEEDS_MIGRATION: Record<string, string> = {
 	"anchorafter": "ST extension injection point — no pi-forge equivalent",
 };
 
+const NATIVE_MACRO_NOTES: Record<string, string> = {
+	setvar: "handled as a turn variable by default, with {{setvar::session::name::value}} for session scope",
+	setturnvar: "handled as a turn variable",
+	setsessionvar: "handled as a session variable",
+	getvar: "handled with turn -> session -> static lookup",
+	var: "handled as an alias of getvar",
+	getturnvar: "handled as a turn-only lookup",
+	getsessionvar: "handled as a session-only lookup",
+	clearvar: "handled as a turn variable clear by default, with {{clearvar::session::name}} for session scope",
+	clearturnvar: "handled as a turn variable clear",
+	clearsessionvar: "handled as a session variable clear",
+};
+
 // ── Macros we can strip entirely (produce no output) ───────────────────────
 
 const COMMENT_MACRO_RE = /\{\{\s*\/\/[\s\S]*?\}\}/g;
@@ -181,6 +266,7 @@ export function convertSillyTavernPreset(
 	const sourcePath = options.sourcePath ?? sourceName;
 	const allPrompts = preset.prompts ?? [];
 	const promptOrder = preset.prompt_order ?? [];
+	const regexScripts = summarizeRegexScripts(preset);
 
 	if (allPrompts.length === 0) {
 		return { error: "Preset has no prompts array." };
@@ -319,6 +405,7 @@ export function convertSillyTavernPreset(
 		mode: "replace",
 		variables: Object.keys(variables).length > 0 ? variables : undefined,
 		context: { allowDuplicateChatHistory: false },
+		regex: regexScripts && regexScripts.rules.length > 0 ? { schemaVersion: 1, rules: regexScripts.rules } : undefined,
 		items,
 		import: {
 			source: "sillytavern",
@@ -387,6 +474,47 @@ export function convertSillyTavernPreset(
 		reportLines.push("");
 	}
 
+	// Regex scripts
+	if (regexScripts && regexScripts.total > 0) {
+		reportLines.push("## SillyTavern regex scripts");
+		reportLines.push("");
+		reportLines.push(`- **Total scripts**: ${regexScripts.total}`);
+		reportLines.push(`- **Enabled scripts**: ${regexScripts.enabled}`);
+		reportLines.push(`- **Disabled scripts**: ${regexScripts.disabled}`);
+		reportLines.push(`- **Prompt-only**: ${regexScripts.promptOnly}`);
+		reportLines.push(`- **Markdown-only / display-only**: ${regexScripts.markdownOnly}`);
+		reportLines.push(`- **Prompt + markdown mixed**: ${regexScripts.mixed}`);
+		if (regexScripts.unspecified > 0) {
+			reportLines.push(`- **Enabled with unspecified mode**: ${regexScripts.unspecified}`);
+		}
+		reportLines.push(`- **Converted to pi-forge rules**: ${regexScripts.converted}`);
+		reportLines.push("");
+			reportLines.push("| Script | Enabled | Mode | Converted | Warnings | Find regex | Replacement preview |");
+			reportLines.push("|--------|---------|------|-----------|----------|------------|---------------------|");
+			for (const script of regexScripts.scripts) {
+				const converted = script.convertedRuleId ? `yes: ${script.convertedRuleId}` : script.conversionNote ?? "no";
+				const warnings = script.conversionWarnings.length > 0 ? script.conversionWarnings.join("; ") : "-";
+				reportLines.push(`| ${markdownTableCell(script.name)} | ${script.enabled ? "yes" : "no"} | ${script.mode} | ${markdownTableCell(converted)} | ${markdownTableCell(warnings)} | ${markdownTableCell(script.findRegex)} | ${markdownTableCell(script.replaceString)} |`);
+			}
+			reportLines.push("");
+			const warningEntries = regexScripts.scripts.filter((script) => script.conversionWarnings.length > 0);
+			if (warningEntries.length > 0) {
+				reportLines.push("Conversion warnings:");
+				for (const script of warningEntries) {
+					for (const warning of script.conversionWarnings) {
+						reportLines.push(`- ${script.name}: ${warning}`);
+					}
+				}
+				reportLines.push("");
+			}
+			reportLines.push("pi-forge does not run SillyTavern markdown rewriting, DOM/browser automation, CSS/HTML decoration, toasts, embedded JavaScript, or UI panel behavior.");
+			if (regexScripts.converted > 0) {
+				reportLines.push("Enabled and disabled prompt-only deterministic regex scripts were converted to `regex.rules` with `stage: \"history\"`, `effect: \"outgoing\"`, JavaScript replacement syntax, and preserved SillyTavern metadata under `source.sillytavern`. History-stage depth is relative to the filtered chat history inserted at the `chat-history` slot, matching SillyTavern's chat-relative depth, and rules do not touch the compiled system prompt. Use `stage: \"compiled\"` manually for global prompt transforms.");
+			}
+			reportLines.push("Markdown-only, mixed prompt/markdown, unspecified, invalid, or unsupported regex scripts remain report-only and require manual review.");
+		reportLines.push("");
+	}
+
 	// Auto-populated variables
 	if (Object.keys(variables).length > 0) {
 		reportLines.push("## Auto-populated variables");
@@ -397,7 +525,7 @@ export function convertSillyTavernPreset(
 			reportLines.push(`- \`${key}\` = \`${val}\` — replace with your character/persona name`);
 		}
 		reportLines.push("");
-		reportLines.push("Use `/state set <name> <value>` or edit the stack JSON to set real values.");
+		reportLines.push("Edit `stack.variables` in the stack JSON or web editor to set real values.");
 		reportLines.push("");
 	}
 
@@ -414,19 +542,6 @@ export function convertSillyTavernPreset(
 		}
 		reportLines.push("");
 
-		// Specific guidance for heavy variable usage
-		if (macroUsage.migrationNeeded.setvar || macroUsage.migrationNeeded.getvar) {
-			reportLines.push("### Variable system migration");
-			reportLines.push("");
-			reportLines.push("ST uses `setvar`/`getvar` for ephemeral state. pi-forge has a different variable model:");
-			reportLines.push("");
-			reportLines.push("- **Static variables** — set in the stack JSON's `variables` object (character names, fixed config)");
-			reportLines.push("- **Session state** — persists across turns, set by the user via `/state set` or by the agent via `forge_state_set` for `agent.*` names");
-			reportLines.push("- **Turn variables** — ephemeral, set via `{{setvar::name::value}}` macros in blocks");
-			reportLines.push("");
-			reportLines.push("Review ST `setvar`/`getvar` calls and migrate to the appropriate pi-forge scope.");
-			reportLines.push("");
-		}
 	}
 
 	// Native macros handled
@@ -440,6 +555,8 @@ export function convertSillyTavernPreset(
 				reportLines.push(`- \`{{${displayName}}}\` → auto-populated as static variable`);
 			} else if (name === "lastusermessage") {
 				reportLines.push(`- \`{{${displayName}}}\` → handled by pi-forge runtime (chat-history slot)`);
+			} else if (NATIVE_MACRO_NOTES[name]) {
+				reportLines.push(`- \`{{${displayName}}}\` → ${NATIVE_MACRO_NOTES[name]}`);
 			} else {
 				reportLines.push(`- \`{{${displayName}}}\` → handled natively by pi-forge`);
 			}
@@ -479,9 +596,9 @@ export function convertSillyTavernPreset(
 	reportLines.push("");
 	reportLines.push("## Suggested next steps");
 	reportLines.push("");
-	reportLines.push("1. Set real values for auto-populated variables with `/state set`.");
+	reportLines.push("1. Set real values for auto-populated variables by editing `stack.variables`.");
 	reportLines.push("2. Review items with migration-needed macros and rewrite for pi-forge's macro system.");
-	reportLines.push("3. Consider adding a `variables` slot for agent state visibility.");
+	reportLines.push("3. Consider adding a `variables` slot for template variable visibility.");
 	reportLines.push(`4. Run \`/preset validate ${stackId}\` to check for issues.`);
 
 	return {
@@ -490,6 +607,274 @@ export function convertSillyTavernPreset(
 	};
 }
 
+// ── Regex script reporting ─────────────────────────────────────────────────
+
+function summarizeRegexScripts(preset: StPreset): RegexScriptReport | undefined {
+	const rawScripts = preset.extensions?.regex_scripts;
+	if (!Array.isArray(rawScripts)) return undefined;
+
+	const scripts = rawScripts
+		.map((raw, index) => classifyRegexScript(raw, index))
+		.filter((script): script is RegexScriptReportEntry => script !== undefined);
+
+	const report: RegexScriptReport = {
+		total: scripts.length,
+		enabled: 0,
+		disabled: 0,
+		promptOnly: 0,
+		markdownOnly: 0,
+		mixed: 0,
+		unspecified: 0,
+		converted: 0,
+		scripts,
+		rules: [],
+	};
+
+	const seenRuleIds = new Set<string>();
+	for (const [index, script] of scripts.entries()) {
+		const conversion = convertPromptOnlyRegexScript(script, index, seenRuleIds);
+		if (conversion.rule) {
+			report.rules.push(conversion.rule);
+			report.converted++;
+			script.convertedRuleId = conversion.rule.id;
+		} else if (conversion.note) {
+			script.conversionNote = conversion.note;
+		}
+
+		if (!script.enabled) {
+			report.disabled++;
+			continue;
+		}
+		report.enabled++;
+		if (script.mode === "prompt-only") report.promptOnly++;
+		else if (script.mode === "markdown-only") report.markdownOnly++;
+		else if (script.mode === "prompt+markdown") report.mixed++;
+		else if (script.mode === "unspecified") report.unspecified++;
+	}
+
+	return report;
+}
+
+function classifyRegexScript(raw: unknown, index: number): RegexScriptReportEntry | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const script = raw as StRegexScript;
+	const enabled = script.disabled !== true;
+	const promptOnly = script.promptOnly === true;
+	const markdownOnly = script.markdownOnly === true;
+	const mode: RegexScriptMode = enabled
+		? promptOnly && markdownOnly
+			? "prompt+markdown"
+			: promptOnly
+				? "prompt-only"
+				: markdownOnly
+					? "markdown-only"
+					: "unspecified"
+		: "disabled";
+
+	return {
+		name: firstString(script.script_name, script.scriptName, script.name) ?? `regex-${index + 1}`,
+		mode,
+		enabled,
+		promptOnly,
+		markdownOnly,
+		findRegex: firstString(script.findRegex),
+		replaceString: firstString(script.replaceString),
+		trimStrings: normalizeTrimStrings(script.trimStrings),
+		placement: normalizeNumberArray(script.placement),
+		substituteRegex: normalizeNumber(script.substituteRegex),
+		minDepth: normalizeDepth(script.minDepth, -1),
+		maxDepth: normalizeDepth(script.maxDepth, 0),
+		conversionWarnings: [],
+	};
+}
+
+function convertPromptOnlyRegexScript(
+	entry: RegexScriptReportEntry,
+	index: number,
+	seenRuleIds: Set<string>,
+): { rule?: PromptRegexRule; note?: string } {
+	if (!entry.promptOnly) return { note: entry.enabled ? "not prompt-only" : "disabled non-prompt script" };
+	if (entry.markdownOnly) return { note: "mixed prompt/display script requires review" };
+	if (!entry.findRegex) return { note: "missing findRegex" };
+
+	const parsed = parseSillyTavernRegex(entry.findRegex);
+	if ("error" in parsed) return { note: parsed.error };
+	if (entry.placement && entry.placement.length > 0 && !entry.placement.some((placement) => placement === 1 || placement === 2)) {
+		return { note: "placement has no pi-forge runtime mapping" };
+	}
+	const replacement = normalizeSillyTavernReplacement(entry.replaceString ?? "", entry.conversionWarnings);
+	const roles = rolesForSillyTavernPlacement(entry.placement, entry.conversionWarnings);
+	if (entry.substituteRegex && entry.substituteRegex !== 0) {
+		entry.conversionWarnings.push("substituteRegex is preserved as metadata but dynamic find-regex macro substitution is not executed");
+	}
+	for (const placement of entry.placement ?? []) {
+		if (placement !== 1 && placement !== 2) {
+			entry.conversionWarnings.push(`placement ${placementLabel(placement)} is preserved as metadata but not directly mapped`);
+		}
+	}
+
+	const id = uniqueRegexRuleId(`st-${entry.name || `regex-${index + 1}`}`, seenRuleIds);
+	const rule: PromptRegexRule = {
+		id,
+		name: entry.name,
+		enabled: entry.enabled,
+		stage: "history",
+		effect: "outgoing",
+		pattern: parsed.pattern,
+		replace: replacement,
+		source: {
+			sillytavern: {
+				scriptName: entry.name,
+				findRegex: entry.findRegex,
+				replaceString: entry.replaceString ?? "",
+				trimStrings: entry.trimStrings ?? [],
+				placement: entry.placement ?? [],
+				placementNames: (entry.placement ?? []).map(placementLabel),
+				promptOnly: entry.promptOnly,
+				markdownOnly: entry.markdownOnly,
+				substituteRegex: entry.substituteRegex ?? 0,
+				minDepth: entry.minDepth,
+				maxDepth: entry.maxDepth,
+			},
+		},
+	};
+	if (parsed.flags) rule.flags = parsed.flags;
+	if (entry.trimStrings && entry.trimStrings.length > 0) rule.trimStrings = entry.trimStrings;
+	if (roles && roles.length > 0) rule.roles = roles;
+	if (isNonNegativeInteger(entry.minDepth)) rule.minDepth = entry.minDepth;
+	if (isNonNegativeInteger(entry.maxDepth)) rule.maxDepth = entry.maxDepth;
+	return {
+		rule,
+	};
+}
+
+function parseSillyTavernRegex(value: string): { pattern: string; flags?: string } | { error: string } {
+	const trimmed = value.trim();
+	if (!trimmed) return { error: "empty findRegex" };
+
+	if (!trimmed.startsWith("/")) return validateParsedRegex(trimmed, "");
+
+	const closingSlash = findRegexLiteralClosingSlash(trimmed);
+	if (closingSlash <= 0) return { error: "could not parse regex literal" };
+
+	const pattern = trimmed.slice(1, closingSlash);
+	const flags = trimmed.slice(closingSlash + 1);
+	return validateParsedRegex(pattern, flags);
+}
+
+function normalizeSillyTavernReplacement(value: string, warnings: string[]): string {
+	let result = value;
+	if (/\{\{\s*match\s*\}\}/i.test(result)) {
+		result = result.replace(/\{\{\s*match\s*\}\}/gi, () => "$&");
+		warnings.push("converted SillyTavern {{match}} to JavaScript $&");
+	}
+	if (/\$0(?!\d)/.test(result)) {
+		result = result.replace(/\$0(?!\d)/g, () => "$&");
+		warnings.push("converted SillyTavern-style $0 full match to JavaScript $&");
+	}
+	return result;
+}
+
+function rolesForSillyTavernPlacement(placement: number[] | undefined, warnings: string[]): string[] | undefined {
+	if (!placement || placement.length === 0) return undefined;
+	const roles: string[] = [];
+	if (placement.includes(1)) roles.push("user");
+	if (placement.includes(2)) roles.push("assistant");
+	if (placement.includes(6)) warnings.push("reasoning placement is preserved as metadata; use stripAssistantThinking or manual rules for thinking content");
+	return roles.length > 0 ? roles : undefined;
+}
+
+function placementLabel(value: number): string {
+	return ST_REGEX_PLACEMENT_LABELS[value] ? `${ST_REGEX_PLACEMENT_LABELS[value]} (${value})` : `unknown (${value})`;
+}
+
+function normalizeTrimStrings(value: unknown): string[] | undefined {
+	if (typeof value === "string") {
+		const strings = value.split(/\r?\n/).filter((entry) => entry.length > 0);
+		return strings.length > 0 ? strings : undefined;
+	}
+	if (!Array.isArray(value)) return undefined;
+	const strings = value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
+	return strings.length > 0 ? strings : undefined;
+}
+
+function normalizeNumberArray(value: unknown): number[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const numbers = value
+		.map(normalizeNumber)
+		.filter((entry): entry is number => entry !== undefined);
+	return numbers.length > 0 ? numbers : undefined;
+}
+
+function normalizeNumber(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim()) {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	if (typeof value === "boolean") return value ? 1 : 0;
+	return undefined;
+}
+
+function normalizeDepth(value: unknown, minimum: number): number | undefined {
+	const number = normalizeNumber(value);
+	if (number === undefined || !Number.isInteger(number) || number < minimum) return undefined;
+	return number;
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function validateParsedRegex(pattern: string, flags: string): { pattern: string; flags?: string } | { error: string } {
+	if (!pattern) return { error: "empty regex pattern" };
+	const seen = new Set<string>();
+	for (const flag of flags) {
+		if (!["g", "i", "m", "s", "u"].includes(flag)) return { error: `unsupported regex flag: ${flag}` };
+		if (seen.has(flag)) return { error: `duplicate regex flag: ${flag}` };
+		seen.add(flag);
+	}
+	try {
+		new RegExp(pattern, flags);
+	} catch (error) {
+		return { error: `regex failed to compile: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	return { pattern, flags: flags || undefined };
+}
+
+function findRegexLiteralClosingSlash(value: string): number {
+	for (let index = value.length - 1; index > 0; index--) {
+		if (value[index] !== "/") continue;
+		let slashCount = 0;
+		for (let backslash = index - 1; backslash >= 0 && value[backslash] === "\\"; backslash--) slashCount++;
+		if (slashCount % 2 === 0) return index;
+	}
+	return -1;
+}
+
+function uniqueRegexRuleId(base: string, seen: Set<string>): string {
+	const normalized = base.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase() || "st-regex";
+	let candidate = normalized;
+	let suffix = 2;
+	while (seen.has(candidate)) candidate = `${normalized}-${suffix++}`;
+	seen.add(candidate);
+	return candidate;
+}
+
+function firstString(...values: unknown[]): string | undefined {
+	for (const value of values) {
+		if (typeof value === "string" && value.trim()) return value;
+	}
+	return undefined;
+}
+
+function markdownTableCell(value: unknown): string {
+	if (typeof value !== "string" || !value.trim()) return "-";
+	const collapsed = value.replace(/\s+/g, " ").trim();
+	const truncated = collapsed.length > 96 ? `${collapsed.slice(0, 93)}...` : collapsed;
+	return truncated.replace(/\|/g, "\\|");
+}
+
 // ── Macro detection ────────────────────────────────────────────────────────
 
 interface MacroDetection {

package/src/stack-migration.ts

@@ -0,0 +1,159 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { legacyPromptStacksDir, promptStacksDir } from "./storage.ts";
+
+export interface PromptStackMigrationOptions {
+	dryRun?: boolean;
+	overwrite?: boolean;
+	deleteLegacy?: boolean;
+}
+
+export interface PromptStackMigrationFile {
+	name: string;
+	sourcePath: string;
+	targetPath: string;
+	action: "copy" | "overwrite" | "skip" | "error";
+	reason?: string;
+	deleteLegacy: boolean;
+}
+
+export interface PromptStackMigrationReport {
+	sourceDir: string;
+	targetDir: string;
+	dryRun: boolean;
+	overwrite: boolean;
+	deleteLegacy: boolean;
+	files: PromptStackMigrationFile[];
+	copied: number;
+	overwritten: number;
+	skipped: number;
+	errors: number;
+	deletedLegacy: number;
+}
+
+export function migrateLegacyPromptStacks(cwd: string, options: PromptStackMigrationOptions = {}): PromptStackMigrationReport {
+	const sourceDir = legacyPromptStacksDir(cwd);
+	const targetDir = promptStacksDir(cwd);
+	const report: PromptStackMigrationReport = {
+		sourceDir,
+		targetDir,
+		dryRun: options.dryRun === true,
+		overwrite: options.overwrite === true,
+		deleteLegacy: options.deleteLegacy === true,
+		files: [],
+		copied: 0,
+		overwritten: 0,
+		skipped: 0,
+		errors: 0,
+		deletedLegacy: 0,
+	};
+
+	if (!existsSync(sourceDir)) return report;
+
+	let entries: string[];
+	try {
+		entries = readdirSync(sourceDir).filter((name) => name.endsWith(".json")).sort();
+	} catch (error) {
+		report.files.push({
+			name: "(legacy directory)",
+			sourcePath: sourceDir,
+			targetPath: targetDir,
+			action: "error",
+			reason: error instanceof Error ? error.message : String(error),
+			deleteLegacy: false,
+		});
+		report.errors++;
+		return report;
+	}
+
+	for (const name of entries) {
+		const sourcePath = join(sourceDir, name);
+		const targetPath = join(targetDir, name);
+		const targetExists = existsSync(targetPath);
+		if (targetExists && !report.overwrite) {
+			report.files.push({
+				name,
+				sourcePath,
+				targetPath,
+				action: "skip",
+				reason: "target already exists",
+				deleteLegacy: false,
+			});
+			report.skipped++;
+			continue;
+		}
+
+		const action = targetExists ? "overwrite" : "copy";
+		try {
+			if (!report.dryRun) {
+				mkdirSync(dirname(targetPath), { recursive: true });
+				copyFileSync(sourcePath, targetPath);
+				if (report.deleteLegacy) {
+					unlinkSync(sourcePath);
+					report.deletedLegacy++;
+				}
+			}
+			if (action === "overwrite") report.overwritten++;
+			else report.copied++;
+			report.files.push({
+				name,
+				sourcePath,
+				targetPath,
+				action,
+				deleteLegacy: report.deleteLegacy,
+			});
+		} catch (error) {
+			report.files.push({
+				name,
+				sourcePath,
+				targetPath,
+				action: "error",
+				reason: error instanceof Error ? error.message : String(error),
+				deleteLegacy: false,
+			});
+			report.errors++;
+		}
+	}
+
+	return report;
+}
+
+export function renderMigrationReport(report: PromptStackMigrationReport): string {
+	const lines = [
+		"# Prompt Stack Migration",
+		"",
+		`Source: ${report.sourceDir}`,
+		`Target: ${report.targetDir}`,
+		`Mode: ${report.dryRun ? "dry run" : "write"}`,
+		`Overwrite existing target files: ${report.overwrite ? "yes" : "no"}`,
+		`Delete legacy files after copy: ${report.deleteLegacy ? "yes" : "no"}`,
+		"",
+		`Copied: ${report.copied}`,
+		`Overwritten: ${report.overwritten}`,
+		`Skipped: ${report.skipped}`,
+		`Errors: ${report.errors}`,
+		`Deleted legacy files: ${report.deletedLegacy}`,
+		"",
+		"## Files",
+		"",
+	];
+
+	if (report.files.length === 0) {
+		lines.push("No legacy prompt-stack JSON files found.");
+		return lines.join("\n");
+	}
+
+	for (const file of report.files) {
+		const suffix = file.reason ? ` (${file.reason})` : "";
+		lines.push(`- ${file.action}: ${file.name}${suffix}`);
+		lines.push(`  from: ${file.sourcePath}`);
+		lines.push(`  to:   ${file.targetPath}`);
+		if (file.deleteLegacy) lines.push("  legacy delete: yes");
+	}
+
+	if (!report.deleteLegacy && !report.dryRun && (report.copied || report.overwritten)) {
+		lines.push("", "Legacy files were left in place. Re-run with `--delete-legacy` after checking the migrated stacks if you want to remove them.");
+	}
+
+	return lines.join("\n");
+}