@zihanw/pi-forge 0.1.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,22 +107,58 @@ 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([
-	"char",           // → static variable
-	"user",           // → static variable
-	"lastUserMessage", // → handled by pi-forge runtime
+	"char",            // → static variable
+	"user",            // → static variable
+	"lastusermessage", // → handled by pi-forge runtime
 	"cwd",
 	"date",
 	"time",
+	"setvar",
+	"setturnvar",
+	"setsessionvar",
+	"getvar",
+	"var",
+	"getturnvar",
+	"getsessionvar",
+	"clearvar",
+	"clearturnvar",
+	"clearsessionvar",
 ]);
 
+const MACRO_DISPLAY_NAMES: Record<string, string> = {
+	lastusermessage: "lastUserMessage",
+	groupnotmuted: "groupNotMuted",
+	notchar: "notChar",
+	charifnotgroup: "charIfNotGroup",
+	mesexamples: "mesExamples",
+	mesexamplesraw: "mesExamplesRaw",
+	charprompt: "charPrompt",
+	charinstruction: "charInstruction",
+	charversion: "charVersion",
+	charfirstmessage: "charFirstMessage",
+	wibefore: "wiBefore",
+	wiafter: "wiAfter",
+	lorebefore: "loreBefore",
+	loreafter: "loreAfter",
+	anchorbefore: "anchorBefore",
+	anchorafter: "anchorAfter",
+};
+
 // ── 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}}",
@@ -78,26 +169,39 @@ const MACRO_NEEDS_MIGRATION: Record<string, string> = {
 	"original": "SillyTavern-specific — no direct equivalent; set as session variable if needed",
 	"outlet": "SillyTavern extension outlet — no pi-forge equivalent",
 	"group": "SillyTavern group chat — no pi-forge equivalent",
-	"groupNotMuted": "SillyTavern group chat — no pi-forge equivalent",
-	"notChar": "SillyTavern group chat — no pi-forge equivalent",
-	"charIfNotGroup": "SillyTavern group chat — no pi-forge equivalent",
+	"groupnotmuted": "SillyTavern group chat — no pi-forge equivalent",
+	"notchar": "SillyTavern group chat — no pi-forge equivalent",
+	"charifnotgroup": "SillyTavern group chat — no pi-forge equivalent",
 	"description": "ST character card field — set as session variable or static variable if needed",
 	"personality": "ST character card field — set as session variable or static variable if needed",
 	"scenario": "ST character card field — set as session variable or static variable if needed",
 	"persona": "ST persona field — set as session variable or static variable if needed",
-	"mesExamples": "ST character dialogue examples — add inline or as context file if needed",
-	"mesExamplesRaw": "ST character dialogue examples — add inline or as context file if needed",
-	"charPrompt": "ST character prompt override — merge into system prompt blocks if needed",
-	"charInstruction": "ST character instruction override — merge into post-history blocks if needed",
-	"charVersion": "ST character version — set as static variable if needed",
-	"charFirstMessage": "ST character first message — add as static variable if needed",
+	"mesexamples": "ST character dialogue examples — add inline or as context file if needed",
+	"mesexamplesraw": "ST character dialogue examples — add inline or as context file if needed",
+	"charprompt": "ST character prompt override — merge into system prompt blocks if needed",
+	"charinstruction": "ST character instruction override — merge into post-history blocks if needed",
+	"charversion": "ST character version — set as static variable if needed",
+	"charfirstmessage": "ST character first message — add as static variable if needed",
 	"system": "ST context template system prompt — handled by pi-forge system prompt replacement",
-	"wiBefore": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
-	"wiAfter": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
-	"loreBefore": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
-	"loreAfter": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
-	"anchorBefore": "ST extension injection point — no pi-forge equivalent",
-	"anchorAfter": "ST extension injection point — no pi-forge equivalent",
+	"wibefore": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
+	"wiafter": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
+	"lorebefore": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
+	"loreafter": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
+	"anchorbefore": "ST extension injection point — no pi-forge equivalent",
+	"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) ───────────────────────
@@ -118,6 +222,12 @@ export interface SillyTavernImportError {
 
 export type SillyTavernImportOutcome = SillyTavernImportResult | SillyTavernImportError;
 
+export interface SillyTavernConvertOptions {
+	sourceName?: string;
+	sourcePath?: string;
+	characterId?: number;
+}
+
 // ── Importer ───────────────────────────────────────────────────────────────
 
 export function importSillyTavernPreset(
@@ -135,23 +245,42 @@ export function importSillyTavernPreset(
 		return { error: "Preset root must be a JSON object." };
 	}
 
+	return convertSillyTavernPreset(raw, { sourceName: filePath, sourcePath: filePath, characterId });
+}
+
+export function convertSillyTavernPreset(
+	raw: unknown,
+	options: SillyTavernConvertOptions = {},
+): SillyTavernImportOutcome {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		return { error: "Preset root must be a JSON object." };
+	}
+
 	const preset = raw as StPreset;
+	const fallbackName = typeof preset.preset_name === "string" && preset.preset_name.trim()
+		? preset.preset_name
+		: typeof preset.name === "string" && preset.name.trim()
+			? preset.name
+			: "imported.json";
+	const sourceName = options.sourceName ?? fallbackName;
+	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." };
 	}
 
 	// Select character_id
-	const selectedEntry = selectCharacterEntry(promptOrder, characterId);
+	const selectedEntry = selectCharacterEntry(promptOrder, options.characterId);
 	if (!selectedEntry) {
 		const ids = promptOrder.map((entry) => entry.character_id);
 		if (ids.length === 0) {
-			return { error: "Preset has no prompt_order entries. Specify a character_id with /preset import-silly <path> <character_id>." };
+			return { error: "Preset has no prompt_order entries. Choose a character_id and retry." };
 		}
 		return {
-			error: `Multiple character configs found: [${ids.join(", ")}]. Re-run with /preset import-silly <path> <character_id>.`,
+			error: `Multiple character configs found: [${ids.join(", ")}]. Choose a character_id and retry.`,
 		};
 	}
 
@@ -219,8 +348,8 @@ export function importSillyTavernPreset(
 			continue;
 		}
 
-		// Detect {{lastUserMessage}} usage
-		if (content.includes("{{lastUserMessage}}")) {
+		// Detect {{lastUserMessage}} usage, case-insensitively.
+		if (/\{\{\s*lastUserMessage\b/i.test(content)) {
 			usesLastUserMessage = true;
 		}
 
@@ -258,7 +387,7 @@ export function importSillyTavernPreset(
 	}
 
 	// Build stack name from file
-	const fileName = basename(filePath, ".json");
+	const fileName = basename(sourceName).replace(/\.json$/i, "") || "imported";
 	const styleName = preset.names_behavior === 1 ? "names" : preset.names_behavior === 2 ? "nonames" : "default";
 	const stackId = fileName.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase() || "imported";
 
@@ -276,6 +405,7 @@ export function importSillyTavernPreset(
 		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",
@@ -285,7 +415,8 @@ export function importSillyTavernPreset(
 		},
 	};
 
-	// Add chat-history option if {{lastUserMessage}} is used after history
+	// Add chat-history option if {{lastUserMessage}} is used after history.
+	if (macroUsage.detected.has("lastusermessage")) usesLastUserMessage = true;
 	if (usesLastUserMessage) {
 		const chatHistoryItem = items.find(
 			(item) => item.kind === "slot" && item.slot === "chat-history",
@@ -299,7 +430,7 @@ export function importSillyTavernPreset(
 	const reportLines: string[] = [];
 	reportLines.push(`# SillyTavern Import Report: ${fileName}`);
 	reportLines.push("");
-	reportLines.push(`- **Source file**: ${filePath}`);
+	reportLines.push(`- **Source file**: ${sourcePath}`);
 	reportLines.push(`- **Character ID**: ${selectedEntry.character_id}`);
 	reportLines.push(`- **Output stack ID**: ${stackId}`);
 	reportLines.push(`- **Names behavior**: ${styleName} (ST value ${preset.names_behavior ?? "?"})`);
@@ -343,6 +474,47 @@ export function importSillyTavernPreset(
 		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");
@@ -353,7 +525,7 @@ export function importSillyTavernPreset(
 			reportLines.push(`- \`${key}\` = \`${val}\` — replace with your character/persona name`);
 		}
 		reportLines.push("");
-		reportLines.push("Use `/preset vars 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("");
 	}
 
@@ -366,23 +538,10 @@ export function importSillyTavernPreset(
 		reportLines.push("");
 		for (const [name, count] of migrationEntries) {
 			const note = MACRO_NEEDS_MIGRATION[name] ?? "no mapping available";
-			reportLines.push(`- **\`{{${name}}}\`** (${count} occurrence${count > 1 ? "s" : ""}) — ${note}`);
+			reportLines.push(`- **\`{{${displayMacroName(name)}}}\`** (${count} occurrence${count > 1 ? "s" : ""}) — ${note}`);
 		}
 		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 variables** — persist across turns, set via `/preset vars set` or `forge_set_var` tool");
-			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
@@ -391,12 +550,15 @@ export function importSillyTavernPreset(
 		reportLines.push("## Handled macros");
 		reportLines.push("");
 		for (const name of nativeDetected) {
+			const displayName = displayMacroName(name);
 			if (name === "char" || name === "user") {
-				reportLines.push(`- \`{{${name}}}\` → auto-populated as static variable`);
-			} else if (name === "lastUserMessage") {
-				reportLines.push(`- \`{{${name}}}\` → handled by pi-forge runtime (chat-history slot)`);
+				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(`- \`{{${name}}}\` → handled natively by pi-forge`);
+				reportLines.push(`- \`{{${displayName}}}\` → handled natively by pi-forge`);
 			}
 		}
 		reportLines.push("");
@@ -434,9 +596,9 @@ export function importSillyTavernPreset(
 	reportLines.push("");
 	reportLines.push("## Suggested next steps");
 	reportLines.push("");
-	reportLines.push("1. Set real values for auto-populated variables with `/preset vars 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 {
@@ -445,6 +607,274 @@ export function importSillyTavernPreset(
 	};
 }
 
+// ── 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 {
@@ -495,6 +925,10 @@ function detectMacros(conversionItems: StConversionItem[]): MacroDetection {
 
 // ── Content cleaning ──────────────────────────────────────────────────────
 
+function displayMacroName(name: string): string {
+	return MACRO_DISPLAY_NAMES[name] ?? name;
+}
+
 function cleanContent(content: string): string {
 	// Collapse multiple blank lines (max 1 blank line between paragraphs)
 	return content.replace(/\n{3,}/g, "\n\n").trim();