@zihanw/pi-forge 0.3.2 → 0.4.0

package/src/runtime-state.ts

@@ -1,40 +0,0 @@
-import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
-import type { WebEditorPayloadCapture } from "./web-editor/index.ts";
-import type { LoadedPromptStack, PromptStackDiagnostic, PromptVariableStore, PromptVariableValue } from "./types.ts";
-
-export const STATE_ENTRY_TYPE = "pi-forge-prompt-stack-state";
-export const VARIABLE_ENTRY_TYPE = "pi-forge-variable-state";
-
-export type PayloadDisplayTarget = "editor" | "web";
-
-export interface PiForgeRuntimeState {
-	stacks: LoadedPromptStack[];
-	active?: LoadedPromptStack;
-	currentSystemPromptOptions?: BuildSystemPromptOptions;
-	currentLatestUserMessage?: string;
-	currentVariableStore?: PromptVariableStore;
-	contextRewritePending: boolean;
-	sessionVariables: Record<string, PromptVariableValue>;
-	lastPersistedActiveId?: string;
-	latestCompileDiagnostics: PromptStackDiagnostic[];
-	forgeExtensionDiagnostics: PromptStackDiagnostic[];
-	forgeExtensionPaths: string[];
-	interceptNextProviderPayload: boolean;
-	interceptPayloadSavePath?: string;
-	interceptPayloadDisplayTarget: PayloadDisplayTarget;
-	payloadCaptureArmedAt?: string;
-	latestProviderPayloadCapture?: WebEditorPayloadCapture;
-}
-
-export function createRuntimeState(): PiForgeRuntimeState {
-	return {
-		stacks: [],
-		contextRewritePending: false,
-		sessionVariables: {},
-		latestCompileDiagnostics: [],
-		forgeExtensionDiagnostics: [],
-		forgeExtensionPaths: [],
-		interceptNextProviderPayload: false,
-		interceptPayloadDisplayTarget: "editor",
-	};
-}

package/src/sillytavern-importer/items.ts

@@ -1,98 +0,0 @@
-import type { PromptStackItem } from "../types.ts";
-import { COMMENT_MACRO_RE, TRIM_MACRO_RE } from "./macros.ts";
-import type { PromptConversionResult, StConversionItem } from "./types.ts";
-
-const MARKER_CHAT_HISTORY = "chatHistory";
-const MARKER_SKIP = new Set([
-	"worldInfoBefore",
-	"worldInfoAfter",
-	"charDescription",
-	"charPersonality",
-	"personaDescription",
-	"scenario",
-	"dialogueExamples",
-]);
-
-export function convertPromptItems(conversionItems: StConversionItem[]): PromptConversionResult {
-	let nextId = 1;
-	const items: PromptStackItem[] = [];
-	let usesLastUserMessage = false;
-	const disabledCount = { marker: 0, empty: 0, orderDisable: 0 };
-
-	for (const { def, orderEnabled, orderIndex } of conversionItems) {
-		const id = String(nextId++);
-
-		if (def.marker) {
-			if (def.identifier === MARKER_CHAT_HISTORY) {
-				items.push({
-					kind: "slot",
-					id,
-					name: def.name || "Chat History",
-					enabled: orderEnabled,
-					slot: "chat-history",
-					source: { previousId: def.identifier, name: def.name },
-				});
-			} else if (MARKER_SKIP.has(def.identifier)) {
-				disabledCount.marker++;
-			}
-			continue;
-		}
-
-		let content = def.content ?? "";
-		if (!content.trim()) {
-			disabledCount.empty++;
-			continue;
-		}
-
-		content = content.replace(COMMENT_MACRO_RE, "");
-		content = content.replace(TRIM_MACRO_RE, "");
-
-		if (!content.trim()) {
-			disabledCount.empty++;
-			continue;
-		}
-
-		if (/\{\{\s*lastUserMessage\b/i.test(content)) {
-			usesLastUserMessage = true;
-		}
-
-		const role = normalizeRole(def.role);
-		if (!role) {
-			disabledCount.empty++;
-			continue;
-		}
-
-		if (!orderEnabled) {
-			disabledCount.orderDisable++;
-		}
-
-		items.push({
-			kind: "block",
-			id,
-			name: def.name,
-			enabled: orderEnabled,
-			role,
-			content: cleanContent(content),
-			source: {
-				previousId: def.identifier,
-				previousName: def.name,
-				orderIndex,
-			},
-		});
-	}
-
-	return { items, usesLastUserMessage, disabledCount };
-}
-
-function cleanContent(content: string): string {
-	return content.replace(/\n{3,}/g, "\n\n").trim();
-}
-
-function normalizeRole(role: string | undefined): "system" | "user" | "assistant" | undefined {
-	if (!role) return undefined;
-	const lower = role.trim().toLowerCase();
-	if (lower === "system") return "system";
-	if (lower === "user") return "user";
-	if (lower === "assistant") return "assistant";
-	return undefined;
-}

package/src/sillytavern-importer/macros.ts

@@ -1,159 +0,0 @@
-import type { StConversionItem } from "./types.ts";
-
-export const NATIVE_MACROS = new Set([
-	"char",
-	"user",
-	"lastusermessage",
-	"cwd",
-	"date",
-	"time",
-	"selectedtools",
-	"tools",
-	"activemodel",
-	"setvar",
-	"setturnvar",
-	"setsessionvar",
-	"getvar",
-	"var",
-	"getturnvar",
-	"getsessionvar",
-	"clearvar",
-	"clearturnvar",
-	"clearsessionvar",
-	"trim",
-	"upper",
-	"lower",
-	"json",
-	"xml",
-	"ifvar",
-	"ifeq",
-	"iftools",
-	"ifslot",
-]);
-
-const MACRO_DISPLAY_NAMES: Record<string, string> = {
-	lastusermessage: "lastUserMessage",
-	selectedtools: "selectedTools",
-	activemodel: "activeModel",
-	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",
-};
-
-export const MACRO_NEEDS_MIGRATION: Record<string, string> = {
-	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}}",
-	random: "precompute or rewrite manually with simple pi-forge conditionals when applicable",
-	pick: "precompute or rewrite manually with simple pi-forge conditionals when applicable",
-	roll: "precompute or rewrite manually with simple pi-forge conditionals when applicable",
-	if: "rewrite as {{ifvar::...}}, {{ifeq::...}}, {{iftools::...}}, or {{ifslot::...}} when applicable",
-	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",
-	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",
-	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",
-};
-
-export 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",
-	selectedtools: "handled as comma-separated active tool names after stack tool policy",
-	tools: "handled as an alias of selectedTools",
-	activemodel: "handled as provider/model when available",
-	trim: "handled as an expanded-text trim filter",
-	upper: "handled as an expanded-text uppercase filter",
-	lower: "handled as an expanded-text lowercase filter",
-	json: "handled as JSON string escaping for expanded text",
-	xml: "handled as XML escaping for expanded text",
-	ifvar: "handled as a lazy variable-existence conditional",
-	ifeq: "handled as a lazy variable equality conditional",
-	iftools: "handled as a lazy active-tool conditional",
-	ifslot: "handled as a lazy enabled-slot conditional",
-};
-
-export const COMMENT_MACRO_RE = /\{\{\s*\/\/[\s\S]*?\}\}/g;
-export const TRIM_MACRO_RE = /\{\{\s*trim\s*\}\}/gi;
-
-export interface MacroDetection {
-	detected: Set<string>;
-	commentsStripped: number;
-	trimStripped: number;
-	migrationNeeded: Record<string, number>;
-}
-
-export function detectMacros(conversionItems: StConversionItem[]): MacroDetection {
-	const detected = new Set<string>();
-	let commentsStripped = 0;
-	let trimStripped = 0;
-	const migrationNeeded: Record<string, number> = {};
-	const macroFindRe = /\{\{(?!\/\/)([a-zA-Z_][a-zA-Z0-9_-]*)/gi;
-
-	for (const { def } of conversionItems) {
-		const content = def.content ?? "";
-		if (!content) continue;
-
-		const commentMatches = content.match(COMMENT_MACRO_RE);
-		if (commentMatches) commentsStripped += commentMatches.length;
-
-		const trimMatches = content.match(TRIM_MACRO_RE);
-		if (trimMatches) trimStripped += trimMatches.length;
-
-		const cleaned = content.replace(COMMENT_MACRO_RE, "").replace(TRIM_MACRO_RE, "");
-
-		let match: RegExpExecArray | null;
-		macroFindRe.lastIndex = 0;
-		while ((match = macroFindRe.exec(cleaned)) !== null) {
-			const name = match[1].toLowerCase();
-			detected.add(name);
-
-			if (MACRO_NEEDS_MIGRATION[name]) {
-				migrationNeeded[name] = (migrationNeeded[name] ?? 0) + 1;
-			}
-		}
-	}
-
-	return { detected, commentsStripped, trimStripped, migrationNeeded };
-}
-
-export function displayMacroName(name: string): string {
-	return MACRO_DISPLAY_NAMES[name] ?? name;
-}

package/src/sillytavern-importer/prompt-order.ts

@@ -1,54 +0,0 @@
-import type { StConversionItem, StPromptDef, StPromptOrderEntry } from "./types.ts";
-
-export function selectCharacterEntry(
-	order: StPromptOrderEntry[],
-	preferredId?: number,
-): StPromptOrderEntry | undefined {
-	if (order.length === 0) return undefined;
-
-	if (preferredId !== undefined) {
-		return order.find((entry) => entry.character_id === preferredId);
-	}
-
-	if (order.length === 1) return order[0];
-
-	return undefined;
-}
-
-export function buildPromptMap(prompts: StPromptDef[]): Map<string, StPromptDef> {
-	const promptMap = new Map<string, StPromptDef>();
-	for (const def of prompts) {
-		promptMap.set(def.identifier, def);
-	}
-	return promptMap;
-}
-
-export function buildConversionItems(
-	selectedEntry: StPromptOrderEntry,
-	promptMap: Map<string, StPromptDef>,
-): StConversionItem[] {
-	const conversionItems: StConversionItem[] = [];
-	let orderIndex = 0;
-
-	for (const orderItem of selectedEntry.order ?? []) {
-		const def = promptMap.get(orderItem.identifier);
-		if (def) {
-			conversionItems.push({ def, orderEnabled: orderItem.enabled, orderIndex: orderIndex++ });
-		}
-	}
-
-	return conversionItems;
-}
-
-export function findMissingIdentifiers(
-	selectedEntry: StPromptOrderEntry,
-	promptMap: Map<string, StPromptDef>,
-): string[] {
-	const missingIdentifiers: string[] = [];
-	for (const orderItem of selectedEntry.order ?? []) {
-		if (!promptMap.has(orderItem.identifier)) {
-			missingIdentifiers.push(orderItem.identifier);
-		}
-	}
-	return missingIdentifiers;
-}

package/src/sillytavern-importer/regex.ts

@@ -1,270 +0,0 @@
-import type { PromptRegexRule } from "../types.ts";
-import type { RegexScriptMode, RegexScriptReport, RegexScriptReportEntry, StPreset, StRegexScript } from "./types.ts";
-
-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",
-};
-
-export 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;
-}