@zihanw/pi-forge 0.3.0 → 0.3.2

package/src/slot-renderers.ts

@@ -0,0 +1,414 @@
+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/storage.ts

@@ -1,9 +1,26 @@
+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");
 }

package/src/types.ts

@@ -112,6 +112,8 @@ export interface PromptStackSlotOptions {
 	format?: PromptStackSlotFormat;
 	/** For tools: only render tools that provide prompt snippets, matching Pi's default prompt builder. */
 	onlyWithSnippets?: boolean;
+	/** For date/date-cwd: include the exact current time. Default: false. */
+	includeTime?: boolean;
 	/** For tool-guidelines: override the plain-format section heading. */
 	heading?: string;
 	/** For tool-guidelines: include Pi's default concise/file-path guideline bullets. */
@@ -204,17 +206,4 @@ export interface CompileMessagesResult {
 	diagnostics: PromptStackDiagnostic[];
 }
 
-export const SUPPORTED_SLOTS = new Set<PromptStackSlot>([
-	"chat-history",
-	"tools",
-	"tool-guidelines",
-	"skills",
-	"project-context",
-	"append-system-prompt",
-	"date",
-	"cwd",
-	"date-cwd",
-	"active-model",
-	"pi-docs",
-	"variables",
-]);
+export { SUPPORTED_SLOTS } from "./slot-renderers.ts";