@zihanw/pi-forge 0.1.0 → 0.3.0

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");
+}

package/src/storage.ts

@@ -0,0 +1,28 @@
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+export function promptStacksDir(cwd: string): string {
+	return join(cwd, ".pi", "forge", "prompt-stacks");
+}
+
+export function legacyPromptStacksDir(cwd: string): string {
+	return join(cwd, ".pi", "prompt-stacks");
+}
+
+export function promptStackReadDirs(cwd: string): string[] {
+	return [promptStacksDir(cwd), legacyPromptStacksDir(cwd)];
+}
+
+export function promptStackPath(cwd: string, id: string): string {
+	return join(promptStacksDir(cwd), `${id}.json`);
+}
+
+export function isInsidePromptStackStorage(cwd: string, filePath: string): boolean {
+	return promptStackReadDirs(cwd).some((dir) => isInsideDir(dir, filePath));
+}
+
+function isInsideDir(rootDir: string, filePath: string): boolean {
+	const root = resolve(rootDir);
+	const target = resolve(filePath);
+	const rel = relative(root, target);
+	return !!rel && !rel.startsWith("..") && !isAbsolute(rel);
+}

package/src/types.ts

@@ -19,6 +19,42 @@ export type PromptStackSlot =
 	| "pi-docs"
 	| "variables";
 
+export type PromptStackSlotFormat = "xml" | "json" | "plain";
+
+export type PromptRegexStage = "history" | "compiled";
+
+export type PromptRegexEffect = "outgoing" | "display" | "both" | "finalize";
+
+export type PromptRegexTarget = "system" | "messages";
+
+export interface PromptRegexRule {
+	id: string;
+	name?: string;
+	enabled?: boolean;
+	stage: PromptRegexStage;
+	effect?: PromptRegexEffect;
+	pattern: string;
+	flags?: string;
+	replace?: string;
+	trimStrings?: string[];
+	roles?: string[];
+	targets?: PromptRegexTarget[];
+	maxMessages?: number;
+	maxChars?: number;
+	minDepth?: number;
+	maxDepth?: number;
+	source?: Record<string, unknown>;
+}
+
+export interface PromptRegexConfig {
+	schemaVersion?: 1;
+	rules?: PromptRegexRule[];
+}
+
+export type PromptResourcePolicy =
+	| { allow?: string[]; deny?: never }
+	| { allow?: never; deny?: string[] };
+
 export interface PromptStackDefaults {
 	syntheticMessagesVisible?: boolean;
 	unresolvedMacroPolicy?: "warn" | "keep" | "error";
@@ -50,15 +86,40 @@ export interface VariablesSlotOptions {
 	includeSession?: boolean;
 	/** Include turn variables. Default: true. */
 	includeTurn?: boolean;
+	/** Render format. Default: xml. */
+	format?: Exclude<PromptStackSlotFormat, "json">;
 }
 
 export interface PromptStackSlotOptions {
 	/** For chat-history: include the latest user message in the expanded history. Default: true. */
 	includeLastUserMessage?: boolean;
+	/** For chat-history: remove assistant thinking content blocks from inserted history. Default: false. */
+	stripAssistantThinking?: boolean;
+	/** For chat-history: keep only messages with these roles. Default: all roles. */
+	roles?: string[];
+	/** For chat-history: include Pi branch/compaction summaries. Default: true. */
+	includeSummaries?: boolean;
+	/** For chat-history: keep or drop tool-call/tool-result history. Default: keep. */
+	toolMode?: "keep" | "drop";
+	/** For chat-history: keep only the most recent N messages after filtering. */
+	maxMessages?: number;
+	/** For chat-history: keep only the most recent messages within an approximate character budget. */
+	maxChars?: number;
 	/** For variables: control which variable scopes are included. */
 	includeStatic?: boolean;
 	includeSession?: boolean;
 	includeTurn?: boolean;
+	format?: PromptStackSlotFormat;
+	/** For tools: only render tools that provide prompt snippets, matching Pi's default prompt builder. */
+	onlyWithSnippets?: boolean;
+	/** For tool-guidelines: override the plain-format section heading. */
+	heading?: string;
+	/** For tool-guidelines: include Pi's default concise/file-path guideline bullets. */
+	includePiDefaultGuidelines?: boolean;
+	/** For tool-guidelines: match Pi's default wording where it differs from pi-forge's generic wording. */
+	piStyle?: boolean;
+	/** For skills: omit the skills section unless the read tool is active, matching Pi's default prompt builder. */
+	requireReadTool?: boolean;
 	[key: string]: unknown;
 }
 
@@ -70,6 +131,10 @@ export interface PromptStackSlotItem extends PromptStackBaseItem {
 
 export type PromptStackItem = PromptStackBlockItem | PromptStackSlotItem;
 
+export type PromptVariablePrimitive = string | number | boolean | null;
+
+export type PromptVariableValue = PromptVariablePrimitive | PromptVariableValue[] | { [key: string]: PromptVariableValue };
+
 export interface PromptStack {
 	schemaVersion: 1;
 	type?: "pi-forge.prompt-stack";
@@ -80,7 +145,10 @@ export interface PromptStack {
 	mode?: PromptStackMode;
 	defaults?: PromptStackDefaults;
 	context?: PromptStackContextOptions;
+	tools?: PromptResourcePolicy;
+	skills?: PromptResourcePolicy;
 	variables?: Record<string, string>;
+	regex?: PromptRegexConfig;
 	items: PromptStackItem[];
 	import?: Record<string, unknown>;
 }
@@ -100,8 +168,8 @@ export interface PromptStackDiagnostic {
 }
 
 export interface PromptVariableStore {
-	turn: Record<string, string>;
-	session: Record<string, string>;
+	turn: Record<string, PromptVariableValue>;
+	session: Record<string, PromptVariableValue>;
 	sessionDirty?: boolean;
 }
 
@@ -118,8 +186,21 @@ export interface CompileSystemPromptResult {
 	diagnostics: PromptStackDiagnostic[];
 }
 
+export type CompileMessageSourceKind = "stack-item" | "chat-history" | "implicit-history";
+
+export interface CompileMessageSource {
+	kind: CompileMessageSourceKind;
+	itemId?: string;
+	itemName?: string;
+	slot?: string;
+	historyIndex?: number;
+	historyCount?: number;
+	role?: string;
+}
+
 export interface CompileMessagesResult {
 	messages: AgentMessage[];
+	messageSources: CompileMessageSource[];
 	diagnostics: PromptStackDiagnostic[];
 }
 

package/src/web-editor/index.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_WEB_EDITOR_PORT, startWebEditorServer } from "./server.ts";
+export type * from "./types.ts";