@zihanw/pi-forge 0.3.2 → 0.4.0

package/src/slot-renderers.ts

@@ -1,414 +0,0 @@
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { applyResourcePolicy } from "./policy.ts";
-import type {
-	PromptRuntime,
-	PromptStack,
-	PromptStackDiagnostic,
-	PromptStackSlotFormat,
-	PromptStackSlotItem,
-	PromptVariableValue,
-} from "./types.ts";
-import {
-	collectStaticVariables,
-	createVariableAccess,
-	promptRenderHelpers,
-	selectedToolNames,
-	selectedVariableScopes,
-	type PromptRenderHelpers,
-	type PromptVariableAccess,
-	type PromptVariableScope,
-} from "./render-helpers.ts";
-import { assertRegistryName, type PromptExtensionOptionsSchema, type PromptRegistryEntry } from "./extension-registry.ts";
-
-export interface PromptSlotRenderContext {
-	item: PromptStackSlotItem;
-	stack: PromptStack;
-	runtime: PromptRuntime;
-	diagnostics: PromptStackDiagnostic[];
-	options: Record<string, unknown>;
-	helpers: PromptRenderHelpers;
-	variables: PromptVariableAccess;
-	format: (options?: { allowJson?: boolean }) => PromptStackSlotFormat;
-}
-
-export type PromptSlotRenderer = (context: PromptSlotRenderContext) => string | undefined;
-
-export interface PromptSlotDefinition extends PromptRegistryEntry {
-	options?: PromptExtensionOptionsSchema;
-	render: PromptSlotRenderer;
-}
-
-interface PromptSlotRegistryState {
-	slots: Map<string, PromptSlotDefinition>;
-	supportedSlots: Set<string>;
-}
-
-type PromptSlotGlobal = typeof globalThis & {
-	__piForgeSlotRegistry?: PromptSlotRegistryState;
-};
-
-function slotRegistryState(): PromptSlotRegistryState {
-	const globalScope = globalThis as PromptSlotGlobal;
-	globalScope.__piForgeSlotRegistry ??= { slots: new Map(), supportedSlots: new Set() };
-	return globalScope.__piForgeSlotRegistry;
-}
-
-const SLOT_REGISTRY = slotRegistryState();
-const SLOT_RENDERERS = SLOT_REGISTRY.slots;
-export const SUPPORTED_SLOTS = SLOT_REGISTRY.supportedSlots;
-let registeringBuiltInSlots = true;
-
-const FORMAT_OPTION = {
-	type: "enum",
-	values: ["xml", "plain"],
-	default: "xml",
-	description: "Render as XML-style wrappers or compact plain text.",
-} as const;
-
-const INCLUDE_TIME_OPTION = {
-	type: "boolean",
-	default: false,
-	description: "Include Current time: HH:MM:SS after the current date.",
-} as const;
-
-registerSlot({ name: "chat-history", description: "Conversation history insertion point.", render: () => "" });
-registerSlot({
-	name: "tools",
-	description: "Available tools and prompt snippets.",
-	options: {
-		format: FORMAT_OPTION,
-		onlyWithSnippets: { type: "boolean", default: false, description: "Only render tools that provide prompt snippets." },
-	},
-	render: renderTools,
-});
-registerSlot({
-	name: "tool-guidelines",
-	description: "Tool usage guidelines.",
-	options: {
-		format: FORMAT_OPTION,
-		heading: { type: "string", default: "Tool guidelines:", description: "Plain-format heading." },
-		includePiDefaultGuidelines: { type: "boolean", default: false, description: "Include Pi's default concise/file-path guideline bullets." },
-		piStyle: { type: "boolean", default: false, description: "Use Pi-style wording for default bash guidance." },
-	},
-	render: renderToolGuidelines,
-});
-registerSlot({
-	name: "skills",
-	description: "Available Pi skills.",
-	options: {
-		format: FORMAT_OPTION,
-		requireReadTool: { type: "boolean", default: false, description: "Omit the section unless the read tool is active." },
-	},
-	render: renderSkills,
-});
-registerSlot({ name: "project-context", description: "Project context files.", options: { format: FORMAT_OPTION }, render: renderProjectContext });
-registerSlot({ name: "append-system-prompt", description: "User appended system prompt text.", render: ({ runtime }) => runtime.options.appendSystemPrompt ?? "" });
-registerSlot({ name: "date", description: "Current date.", options: { includeTime: INCLUDE_TIME_OPTION }, render: renderDate });
-registerSlot({ name: "cwd", description: "Current working directory.", render: ({ runtime }) => renderCwd(runtime) });
-registerSlot({ name: "date-cwd", description: "Current date and working directory.", options: { includeTime: INCLUDE_TIME_OPTION }, render: (context) => [renderDate(context), renderCwd(context.runtime)].join("\n") });
-registerSlot({ name: "active-model", description: "Current model provider/id.", render: ({ runtime }) => renderActiveModel(runtime) });
-registerSlot({ name: "pi-docs", description: "Pi documentation guidance.", render: () => renderPiDocsGuidance() });
-registerSlot({
-	name: "variables",
-	description: "Static, session, and turn variables.",
-	options: {
-		format: FORMAT_OPTION,
-		includeStatic: { type: "boolean", default: true, description: "Include static stack variables." },
-		includeSession: { type: "boolean", default: true, description: "Include session variables." },
-		includeTurn: { type: "boolean", default: true, description: "Include turn variables." },
-	},
-	render: renderVariables,
-});
-registeringBuiltInSlots = false;
-
-export function renderSlotText(
-	item: PromptStackSlotItem,
-	stack: PromptStack,
-	runtime: PromptRuntime,
-	diagnostics: PromptStackDiagnostic[],
-): string {
-	const definition = SLOT_RENDERERS.get(item.slot);
-	if (!definition) {
-		diagnostics.push({ level: "warning", message: `Unsupported slot: ${item.slot}`, itemId: item.id });
-		return "";
-	}
-
-	try {
-		return definition.render(createSlotRenderContext(item, stack, runtime, diagnostics)) ?? "";
-	} catch (error) {
-		const detail = error instanceof Error ? error.message : String(error);
-		diagnostics.push({ level: "error", message: `Slot "${item.slot}" failed: ${detail}`, itemId: item.id });
-		return "";
-	}
-}
-
-export function registerSlot(definition: PromptSlotDefinition): () => void {
-	assertRegistryName("Slot", definition.name);
-	if (SLOT_RENDERERS.has(definition.name)) {
-		if (registeringBuiltInSlots) return () => {};
-		throw new Error(`Slot is already registered: ${definition.name}`);
-	}
-	SLOT_RENDERERS.set(definition.name, definition);
-	SUPPORTED_SLOTS.add(definition.name);
-	return () => {
-		if (SLOT_RENDERERS.get(definition.name) === definition) {
-			SLOT_RENDERERS.delete(definition.name);
-			SUPPORTED_SLOTS.delete(definition.name);
-		}
-	};
-}
-
-export function getRegisteredSlots(): readonly PromptSlotDefinition[] {
-	return [...SLOT_RENDERERS.values()];
-}
-
-function createSlotRenderContext(
-	item: PromptStackSlotItem,
-	stack: PromptStack,
-	runtime: PromptRuntime,
-	diagnostics: PromptStackDiagnostic[],
-): PromptSlotRenderContext {
-	return {
-		item,
-		stack,
-		runtime,
-		diagnostics,
-		options: item.options ?? {},
-		helpers: promptRenderHelpers,
-		variables: createVariableAccess(runtime, stack),
-		format: (options) => promptRenderHelpers.slotTextFormat(item, options),
-	};
-}
-
-function renderTools({ item, stack, runtime, format, helpers }: PromptSlotRenderContext): string {
-	const snippets = runtime.options.toolSnippets ?? {};
-	const tools = item.options?.onlyWithSnippets === true
-		? selectedToolNames(stack, runtime).filter((name) => !!snippets[name])
-		: selectedToolNames(stack, runtime);
-
-	if (format() === "plain") {
-		const lines = ["Available tools:"];
-		if (tools.length === 0) {
-			lines.push(item.options?.onlyWithSnippets === true ? "(none)" : "- (none)");
-		} else {
-			for (const name of tools) {
-				lines.push(helpers.plainBullet(name, snippets[name] ?? "No prompt snippet provided."));
-			}
-		}
-		return lines.join("\n");
-	}
-
-	const lines = ["<available_tools>"];
-
-	if (tools.length === 0) {
-		lines.push("  (none)");
-	} else {
-		for (const name of tools) {
-			const snippet = snippets[name] ?? "No prompt snippet provided.";
-			lines.push(`  <tool name=\"${helpers.escapeXml(name)}\">${helpers.escapeXml(snippet)}</tool>`);
-		}
-	}
-
-	lines.push("</available_tools>");
-	return lines.join("\n");
-}
-
-function renderToolGuidelines({ item, stack, runtime, format, helpers }: PromptSlotRenderContext): string {
-	const tools = selectedToolNames(stack, runtime);
-	const guidelines: string[] = [];
-	const seen = new Set<string>();
-	const add = (line: string) => {
-		const normalized = line.trim();
-		if (!normalized || seen.has(normalized)) return;
-		seen.add(normalized);
-		guidelines.push(normalized);
-	};
-
-	if (tools.includes("bash") && !tools.includes("grep") && !tools.includes("find") && !tools.includes("ls")) {
-		add(item.options?.piStyle === true ? "Use bash for file operations like ls, rg, find" : "Use bash for file operations like ls, rg, find.");
-	}
-
-	for (const guideline of runtime.options.promptGuidelines ?? []) add(guideline);
-	if (item.options?.includePiDefaultGuidelines === true) {
-		add("Be concise in your responses");
-		add("Show file paths clearly when working with files");
-	}
-
-	if (guidelines.length === 0) return "";
-	if (format() === "plain") {
-		const heading = typeof item.options?.heading === "string" ? item.options.heading.trim() : "Tool guidelines:";
-		return [
-			...(heading ? [heading] : []),
-			...guidelines.map((line) => `- ${helpers.plainContinuation(line, "  ")}`),
-		].join("\n");
-	}
-	return ["<tool_guidelines>", ...guidelines.map((line) => `- ${line}`), "</tool_guidelines>"].join("\n");
-}
-
-function renderSkills({ item, stack, runtime, format, helpers }: PromptSlotRenderContext): string {
-	if (item.options?.requireReadTool === true && !selectedToolNames(stack, runtime).includes("read")) return "";
-	const skills = (runtime.options.skills ?? [])
-		.filter((skill) => !skill.disableModelInvocation)
-		.filter((skill) => applyResourcePolicy([skill.name], stack.skills).length > 0);
-	if (skills.length === 0) return "";
-
-	const lines = [
-		"The following skills provide specialized instructions for specific tasks.",
-		"Use the read tool to load a skill's file when the task matches its description.",
-		"When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
-		"",
-	];
-
-	if (format() === "plain") {
-		lines.push("Available skills:");
-		for (const skill of skills) {
-			lines.push(helpers.plainBullet(skill.name, skill.description));
-			lines.push(`  Location: ${helpers.plainContinuation(skill.filePath, "  ")}`);
-		}
-		return lines.join("\n");
-	}
-
-	lines.push("<available_skills>");
-	for (const skill of skills) {
-		lines.push("  <skill>");
-		lines.push(`    <name>${helpers.escapeXml(skill.name)}</name>`);
-		lines.push(`    <description>${helpers.escapeXml(skill.description)}</description>`);
-		lines.push(`    <location>${helpers.escapeXml(skill.filePath)}</location>`);
-		lines.push("  </skill>");
-	}
-
-	lines.push("</available_skills>");
-	return lines.join("\n");
-}
-
-function renderProjectContext({ item, runtime, format, helpers }: PromptSlotRenderContext): string {
-	const contextFiles = runtime.options.contextFiles ?? [];
-	if (contextFiles.length === 0) return "";
-
-	if (format() === "plain") {
-		const lines = ["Project context:", "", "Project-specific instructions and guidelines:", ""];
-		for (const file of contextFiles) {
-			lines.push(`Path: ${file.path}`);
-			lines.push(helpers.indentPlainBlock(file.content, "  "), "");
-		}
-		return lines.join("\n").trimEnd();
-	}
-
-	const lines = ["<project_context>", "", "Project-specific instructions and guidelines:", ""];
-	for (const file of contextFiles) {
-		lines.push(`<project_instructions path=\"${helpers.escapeXml(file.path)}\">`);
-		lines.push(file.content);
-		lines.push("</project_instructions>", "");
-	}
-	lines.push("</project_context>");
-	return lines.join("\n");
-}
-
-function renderDate({ item, runtime, helpers }: PromptSlotRenderContext): string {
-	const lines = [`Current date: ${helpers.formatDate(runtime.now)}`];
-	if (item.options?.includeTime === true) {
-		lines.push(`Current time: ${helpers.formatTime(runtime.now)}`);
-	}
-	return lines.join("\n");
-}
-
-function renderCwd(runtime: PromptRuntime): string {
-	return `Current working directory: ${promptRenderHelpers.normalizePath(runtime.options.cwd)}`;
-}
-
-function renderActiveModel(runtime: PromptRuntime): string {
-	const model = runtime.ctx?.model;
-	return model ? `Current model: ${model.provider}/${model.id}` : "Current model: (none)";
-}
-
-function renderPiDocsGuidance(): string {
-	const paths = piDocsPaths();
-	return [
-		"Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):",
-		`- Main documentation: ${paths.readme}`,
-		`- Additional docs: ${paths.docs}`,
-		`- Examples: ${paths.examples} (extensions, custom tools, SDK)`,
-		"- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory",
-		"- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)",
-		"- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing",
-		"- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)",
-	].join("\n");
-}
-
-function piDocsPaths(): { readme: string; docs: string; examples: string } {
-	const fallbackRoot = "@earendil-works/pi-coding-agent";
-	try {
-		const resolve = (import.meta as unknown as { resolve?: (specifier: string) => string }).resolve;
-		if (!resolve) throw new Error("import.meta.resolve unavailable");
-		const resolved = resolve("@earendil-works/pi-coding-agent");
-		if (!resolved.startsWith("file:")) throw new Error("non-file package resolution");
-		const packageRoot = dirname(dirname(fileURLToPath(resolved)));
-		return {
-			readme: join(packageRoot, "README.md"),
-			docs: join(packageRoot, "docs"),
-			examples: join(packageRoot, "examples"),
-		};
-	} catch {
-		return {
-			readme: `${fallbackRoot}/README.md`,
-			docs: `${fallbackRoot}/docs`,
-			examples: `${fallbackRoot}/examples`,
-		};
-	}
-}
-
-function renderVariables({ stack, runtime, options, format, variables, helpers }: PromptSlotRenderContext): string {
-	const scopes = selectedVariableScopes(options);
-	const store = runtime.variables;
-	const grouped: Record<PromptVariableScope, Record<string, PromptVariableValue>> = {
-		static: {},
-		session: {},
-		turn: {},
-	};
-
-	if (scopes.includes("static")) grouped.static = collectStaticVariables(stack);
-	if (scopes.includes("session")) grouped.session = { ...(store?.session ?? {}) };
-	if (scopes.includes("turn")) grouped.turn = { ...(store?.turn ?? {}) };
-
-	const hasVariables = Object.values(grouped).some((values) => Object.keys(values).length > 0);
-	if (!hasVariables) return "";
-
-	if (format() === "plain") {
-		return renderPlainVariables(grouped, variables, helpers);
-	}
-
-	const parts: string[] = ["<variables>"];
-
-	for (const scope of scopes) {
-		const entries = Object.entries(grouped[scope]).sort(([a], [b]) => a.localeCompare(b));
-		if (entries.length === 0) continue;
-		parts.push(`  <${scope}>`);
-		for (const [name, value] of entries) {
-			parts.push(`    <var name=\"${helpers.escapeXml(name)}\">${helpers.escapeXml(variables.toPromptText(value))}</var>`);
-		}
-		parts.push(`  </${scope}>`);
-	}
-
-	parts.push("</variables>");
-	return parts.join("\n");
-}
-
-function renderPlainVariables(
-	grouped: Record<PromptVariableScope, Record<string, PromptVariableValue>>,
-	variables: PromptVariableAccess,
-	helpers: PromptRenderHelpers,
-): string {
-	const parts: string[] = ["Variables:"];
-
-	for (const scope of ["static", "session", "turn"] as const) {
-		const entries = Object.entries(grouped[scope]).sort(([a], [b]) => a.localeCompare(b));
-		if (entries.length === 0) continue;
-		parts.push(`${scope}:`);
-		for (const [name, value] of entries) {
-			parts.push(helpers.plainBullet(name, variables.toPromptText(value)));
-		}
-	}
-
-	return parts.join("\n");
-}

package/src/stack-migration.ts

@@ -1,159 +0,0 @@
-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

@@ -1,45 +0,0 @@
-import { homedir } from "node:os";
-import { isAbsolute, join, relative, resolve } from "node:path";
-
-export function promptStacksDir(cwd: string): string {
-	return join(cwd, ".pi", "forge", "prompt-stacks");
-}
-
-export function forgeDir(cwd: string): string {
-	return join(cwd, ".pi", "forge");
-}
-
-export function forgeExtensionsDir(cwd: string): string {
-	return join(forgeDir(cwd), "extensions");
-}
-
-export function globalForgeDir(): string {
-	return join(homedir(), ".pi", "forge");
-}
-
-export function globalForgeExtensionsDir(): string {
-	return join(globalForgeDir(), "extensions");
-}
-
-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);
-}