@zihanw/pi-forge 0.2.0 → 0.3.0

package/src/loader.ts

@@ -1,38 +1,51 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { validateRegexConfig } from "./regex.ts";
+import { promptStackReadDirs } from "./storage.ts";
 import type {
 	LoadedPromptStack,
+	PromptResourcePolicy,
 	PromptStack,
 	PromptStackDiagnostic,
 	PromptStackItem,
 	PromptStackRole,
-	PromptStateConfig,
-	PromptStateDefinition,
-	PromptStateScope,
-	PromptStateValue,
 } from "./types.ts";
 import { SUPPORTED_SLOTS } from "./types.ts";
 
 const VALID_ROLES = new Set<PromptStackRole>(["system", "user", "assistant", "custom"]);
+const VALID_CHAT_HISTORY_TOOL_MODES = new Set(["keep", "drop"]);
 
-export function promptStacksDir(cwd: string): string {
-	return join(cwd, ".pi", "prompt-stacks");
-}
+export { isInsidePromptStackStorage, legacyPromptStacksDir, promptStackPath, promptStackReadDirs, promptStacksDir } from "./storage.ts";
 
 export function loadPromptStacks(cwd: string): LoadedPromptStack[] {
-	const dir = promptStacksDir(cwd);
-	if (!existsSync(dir)) return [];
+	const files = promptStackFiles(cwd);
+	const loaded = files.map(loadPromptStackFile);
+	annotateDuplicateStackIds(loaded);
+	return loaded;
+}
 
-	let entries: string[];
-	try {
-		entries = readdirSync(dir).filter((name) => name.endsWith(".json"));
-	} catch {
-		return [];
+function promptStackFiles(cwd: string): string[] {
+	const files: string[] = [];
+	const shadowedNames = new Set<string>();
+
+	for (const dir of promptStackReadDirs(cwd)) {
+		if (!existsSync(dir)) continue;
+
+		let entries: string[];
+		try {
+			entries = readdirSync(dir).filter((name) => name.endsWith(".json"));
+		} catch {
+			continue;
+		}
+
+		for (const name of entries.sort()) {
+			if (shadowedNames.has(name)) continue;
+			shadowedNames.add(name);
+			files.push(join(dir, name));
+		}
 	}
 
-	const loaded = entries.sort().map((name) => loadPromptStackFile(join(dir, name)));
-	annotateDuplicateStackIds(loaded);
-	return loaded;
+	return files;
 }
 
 function annotateDuplicateStackIds(stacks: LoadedPromptStack[]): void {
@@ -129,7 +142,7 @@ function normalizeStack(raw: unknown, filePath: string, diagnostics: PromptStack
 
 	const obj = raw as Record<string, unknown>;
 	const id = typeof obj.id === "string" && obj.id.trim() ? obj.id.trim() : basename(filePath, ".json");
-	const schemaVersion = obj.schemaVersion === 1 ? 1 : 1;
+	const schemaVersion = 1;
 	if (obj.schemaVersion !== 1) {
 		diagnostics.push({ level: "warning", message: "Missing or unsupported schemaVersion; assuming 1." });
 	}
@@ -139,6 +152,13 @@ function normalizeStack(raw: unknown, filePath: string, diagnostics: PromptStack
 		diagnostics.push({ level: "error", message: "Prompt stack must contain an items array." });
 	}
 
+	if (isPlainObject(obj.state) && Object.keys(obj.state).length > 0) {
+		diagnostics.push({
+			level: "info",
+			message: "state is no longer supported and was ignored; use stack.variables and template variable macros instead.",
+		});
+	}
+
 	return {
 		schemaVersion,
 		type: obj.type === "pi-forge.prompt-stack" ? "pi-forge.prompt-stack" : undefined,
@@ -149,8 +169,10 @@ function normalizeStack(raw: unknown, filePath: string, diagnostics: PromptStack
 		mode: obj.mode === "append" || obj.mode === "prepend" || obj.mode === "replace" ? obj.mode : undefined,
 		defaults: isPlainObject(obj.defaults) ? (obj.defaults as PromptStack["defaults"]) : undefined,
 		context: isPlainObject(obj.context) ? (obj.context as PromptStack["context"]) : undefined,
+		tools: normalizeResourcePolicy(obj.tools, "tools", diagnostics),
+		skills: normalizeResourcePolicy(obj.skills, "skills", diagnostics),
 		variables: normalizeStringRecord(obj.variables),
-		state: normalizeStateConfig(obj.state, diagnostics),
+		regex: normalizeRegexConfig(obj.regex, diagnostics),
 		items,
 		import: isPlainObject(obj.import) ? (obj.import as Record<string, unknown>) : undefined,
 	};
@@ -213,6 +235,7 @@ export function validatePromptStack(stack: PromptStack): PromptStackDiagnostic[]
 				diagnostics.push({ level: "warning", message: `Unsupported slot: ${item.slot}`, itemId: item.id });
 			}
 			if (item.enabled !== false && item.slot === "chat-history") chatHistoryCount++;
+			if (item.slot === "chat-history") validateChatHistoryOptions(item, diagnostics);
 		}
 
 		if (item.kind === "block" && item.role !== "system" && item.enabled !== false && !item.role) {
@@ -232,15 +255,64 @@ export function validatePromptStack(stack: PromptStack): PromptStackDiagnostic[]
 		});
 	}
 
+	diagnostics.push(...validateResourcePolicy(stack.tools, "tools"));
+	diagnostics.push(...validateResourcePolicy(stack.skills, "skills"));
+	if ((stack.mode === "append" || stack.mode === "prepend") && hasPolicyEntries(stack.skills)) {
+		diagnostics.push({
+			level: "warning",
+			message: "skills policy only filters pi-forge skills slots. Use mode \"replace\" if you need the base Pi prompt to omit filtered skills.",
+		});
+	}
+
+	diagnostics.push(...validateRegexConfig(stack.regex));
+
 	return diagnostics;
 }
 
+function validateChatHistoryOptions(
+	item: Extract<PromptStackItem, { kind: "slot" }>,
+	diagnostics: PromptStackDiagnostic[],
+): void {
+	const options = item.options;
+	if (!options) return;
+
+	for (const key of ["includeLastUserMessage", "stripAssistantThinking", "includeSummaries"]) {
+		const value = options[key];
+		if (value !== undefined && typeof value !== "boolean") {
+			diagnostics.push({ level: "warning", message: `chat-history option ${key} should be a boolean.`, itemId: item.id });
+		}
+	}
+
+	if (options.roles !== undefined && !isStringArray(options.roles)) {
+		diagnostics.push({ level: "error", message: "chat-history option roles must be an array of strings.", itemId: item.id });
+	}
+
+	if (options.toolMode !== undefined && (typeof options.toolMode !== "string" || !VALID_CHAT_HISTORY_TOOL_MODES.has(options.toolMode))) {
+		diagnostics.push({ level: "error", message: 'chat-history option toolMode must be "keep" or "drop".', itemId: item.id });
+	}
+
+	for (const key of ["maxMessages", "maxChars"]) {
+		const value = options[key];
+		if (value !== undefined && !isPositiveInteger(value)) {
+			diagnostics.push({ level: "error", message: `chat-history option ${key} must be a positive integer.`, itemId: item.id });
+		}
+	}
+}
+
 function normalizeId(value: unknown, fallback: string): string {
 	if (typeof value === "string" && value.trim()) return value.trim();
 	if (typeof value === "number" && Number.isFinite(value)) return String(value);
 	return fallback;
 }
 
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isPositiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -254,56 +326,69 @@ function normalizeStringRecord(value: unknown): Record<string, string> | undefin
 	return result;
 }
 
-function normalizeStateConfig(value: unknown, diagnostics: PromptStackDiagnostic[]): PromptStateConfig | undefined {
+function normalizeResourcePolicy(value: unknown, label: string, diagnostics: PromptStackDiagnostic[]): PromptResourcePolicy | undefined {
 	if (value === undefined) return undefined;
 	if (!isPlainObject(value)) {
-		diagnostics.push({ level: "warning", message: "state must be an object when provided." });
+		diagnostics.push({ level: "error", message: `${label} policy must be an object when provided.` });
 		return undefined;
 	}
+	const allow = normalizePolicyPatterns(value.allow, `${label}.allow`, diagnostics);
+	const deny = normalizePolicyPatterns(value.deny, `${label}.deny`, diagnostics);
+	if (allow && deny) {
+		diagnostics.push({ level: "error", message: `${label} policy must use either allow or deny, not both.` });
+		return { allow };
+	}
+	if (allow) return { allow };
+	if (deny) return { deny };
+	return {};
+}
 
-	const definitionsRaw = value.definitions;
-	const definitions: Record<string, PromptStateDefinition> = {};
-
-	if (definitionsRaw !== undefined && !isPlainObject(definitionsRaw)) {
-		diagnostics.push({ level: "warning", message: "state.definitions must be an object when provided." });
+function normalizePolicyPatterns(value: unknown, label: string, diagnostics: PromptStackDiagnostic[]): string[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) {
+		diagnostics.push({ level: "error", message: `${label} must be an array of strings when provided.` });
+		return undefined;
 	}
 
-	if (isPlainObject(definitionsRaw)) {
-		for (const [name, rawDefinition] of Object.entries(definitionsRaw)) {
-			if (!isPlainObject(rawDefinition)) {
-				diagnostics.push({ level: "warning", message: `state definition for ${name} must be an object.` });
-				continue;
-			}
+	const patterns: string[] = [];
+	for (const [index, item] of value.entries()) {
+		if (typeof item !== "string" || !item.trim()) {
+			diagnostics.push({ level: "error", message: `${label}[${index}] must be a non-empty string.` });
+			continue;
+		}
+		patterns.push(item.trim());
+	}
+	return patterns.length > 0 ? patterns : undefined;
+}
 
-			const definition: PromptStateDefinition = {};
-			if (typeof rawDefinition.type === "string") definition.type = rawDefinition.type;
-			if (isStateScope(rawDefinition.scope)) definition.scope = rawDefinition.scope;
-			if (typeof rawDefinition.description === "string") definition.description = rawDefinition.description;
-			if (typeof rawDefinition.agentWritable === "boolean") definition.agentWritable = rawDefinition.agentWritable;
-			if (typeof rawDefinition.userWritable === "boolean") definition.userWritable = rawDefinition.userWritable;
-			if (isPromptStateValue(rawDefinition.default)) definition.default = rawDefinition.default;
-			else if (rawDefinition.default !== undefined) {
-				diagnostics.push({ level: "warning", message: `state definition default for ${name} is not a JSON-compatible value.` });
+function validateResourcePolicy(policy: PromptResourcePolicy | undefined, label: string): PromptStackDiagnostic[] {
+	const diagnostics: PromptStackDiagnostic[] = [];
+	if ((policy?.allow?.length ?? 0) > 0 && (policy?.deny?.length ?? 0) > 0) {
+		diagnostics.push({ level: "error", message: `${label} policy must use either allow or deny, not both.` });
+	}
+	for (const key of ["allow", "deny"] as const) {
+		const values = policy?.[key];
+		if (!values) continue;
+		const seen = new Set<string>();
+		for (const value of values) {
+			if (seen.has(value)) {
+				diagnostics.push({ level: "warning", message: `Duplicate ${label}.${key} pattern: ${value}.` });
 			}
-			definitions[name] = definition;
+			seen.add(value);
 		}
 	}
-
-	return {
-		schemaVersion: value.schemaVersion === 1 ? 1 : undefined,
-		definitions: Object.keys(definitions).length > 0 ? definitions : undefined,
-	};
+	return diagnostics;
 }
 
-function isStateScope(value: unknown): value is PromptStateScope {
-	return value === "static" || value === "session" || value === "turn";
+function hasPolicyEntries(policy: PromptResourcePolicy | undefined): boolean {
+	return !!policy && ((policy.allow?.length ?? 0) > 0 || (policy.deny?.length ?? 0) > 0);
 }
 
-function isPromptStateValue(value: unknown): value is PromptStateValue {
-	if (value === null) return true;
-	const type = typeof value;
-	if (type === "string" || type === "number" || type === "boolean") return Number.isFinite(value as number) || type !== "number";
-	if (Array.isArray(value)) return value.every(isPromptStateValue);
-	if (!isPlainObject(value)) return false;
-	return Object.values(value).every(isPromptStateValue);
+function normalizeRegexConfig(value: unknown, diagnostics: PromptStackDiagnostic[]): PromptStack["regex"] | undefined {
+	if (value === undefined) return undefined;
+	if (!isPlainObject(value)) {
+		diagnostics.push({ level: "warning", message: "regex must be an object when provided." });
+		return undefined;
+	}
+	return value as PromptStack["regex"];
 }

package/src/payload-capture.ts

@@ -0,0 +1,85 @@
+import type { WebEditorPayloadCapture } from "./web-editor/index.ts";
+
+export function createProviderPayloadCapture(value: unknown, options: { stackId?: string; savePath?: string } = {}): WebEditorPayloadCapture {
+	const formatted = formatProviderPayload(value);
+	return {
+		capturedAt: new Date().toISOString(),
+		stackId: options.stackId,
+		savePath: options.savePath,
+		payload: formatted.payload,
+		text: formatted.text,
+		chars: formatted.chars,
+		approxTokens: formatted.approxTokens,
+		truncated: formatted.truncated,
+		error: formatted.error,
+	};
+}
+
+export function formatProviderPayload(value: unknown): { payload?: unknown; text: string; chars: number; approxTokens: number; truncated: boolean; error?: string } {
+	try {
+		const payload = redactPayload(value);
+		const renderedJson = JSON.stringify(payload, null, 2);
+		const text = renderedJson === undefined ? String(payload) : renderedJson;
+		const maxChars = 200_000;
+		const truncated = text.length > maxChars;
+		const rendered = truncated ? `${text.slice(0, maxChars)}\n\n[pi-forge: payload truncated after ${maxChars} chars]` : text;
+		return {
+			payload: truncated ? undefined : payload,
+			text: rendered,
+			chars: rendered.length,
+			approxTokens: estimatePayloadTokens(rendered),
+			truncated,
+		};
+	} catch (error) {
+		const text = `Failed to stringify provider payload: ${error instanceof Error ? error.message : String(error)}`;
+		return {
+			text,
+			chars: text.length,
+			approxTokens: estimatePayloadTokens(text),
+			truncated: false,
+			error: text,
+		};
+	}
+}
+
+export function estimatePayloadTokens(payload: string): number {
+	return Math.max(1, Math.ceil(payload.length / 4));
+}
+
+function redactPayload(value: unknown, depth = 0): unknown {
+	if (depth > 8) return "[pi-forge: max depth reached]";
+	if (typeof value === "string") return redactLongString(value);
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) {
+		const maxItems = 80;
+		const items = value.slice(0, maxItems).map((item) => redactPayload(item, depth + 1));
+		if (value.length > maxItems) items.push(`[pi-forge: ${value.length - maxItems} more items omitted]`);
+		return items;
+	}
+
+	const result: Record<string, unknown> = {};
+	let count = 0;
+	for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+		if (++count > 120) {
+			result["[pi-forge: omitted]"] = "object has more than 120 keys";
+			break;
+		}
+		if (isSecretKey(key)) {
+			result[key] = "[redacted]";
+			continue;
+		}
+		result[key] = redactPayload(raw, depth + 1);
+	}
+	return result;
+}
+
+function isSecretKey(key: string): boolean {
+	return /(api[-_]?key|authorization|bearer|token|secret|password|cookie|credential)/i.test(key);
+}
+
+function redactLongString(value: string): string {
+	if (/^data:image\//.test(value)) return "[image data omitted]";
+	if (value.length > 8_000 && /^[A-Za-z0-9+/=\r\n]+$/.test(value)) return `[base64-like data omitted: ${value.length} chars]`;
+	if (value.length > 12_000) return `${value.slice(0, 12_000)}\n[pi-forge: string truncated from ${value.length} chars]`;
+	return value;
+}

package/src/policy.ts

@@ -0,0 +1,42 @@
+import type { PromptResourcePolicy } from "./types.ts";
+
+export function hasResourcePolicy(policy: PromptResourcePolicy | undefined): boolean {
+	return !!policy && (hasEffectiveAllowPolicy(policy.allow) || hasPatterns(policy.deny));
+}
+
+export function applyResourcePolicy(names: string[], policy: PromptResourcePolicy | undefined): string[] {
+	if (!hasResourcePolicy(policy)) return names;
+	if (hasEffectiveAllowPolicy(policy?.allow)) {
+		return names.filter((name) => matchesAnyPattern(name, policy.allow!));
+	}
+	if (hasPatterns(policy?.deny)) {
+		return names.filter((name) => !matchesAnyPattern(name, policy.deny!));
+	}
+	return names;
+}
+
+export function matchesAnyPattern(name: string, patterns: string[]): boolean {
+	return patterns.some((pattern) => resourcePatternMatches(name, pattern));
+}
+
+export function resourcePatternMatches(name: string, pattern: string): boolean {
+	if (pattern === "*") return true;
+	if (!pattern.includes("*")) return name === pattern;
+	const escaped = pattern
+		.split("*")
+		.map(escapeRegExp)
+		.join(".*");
+	return new RegExp(`^${escaped}$`).test(name);
+}
+
+function hasPatterns(value: string[] | undefined): value is string[] {
+	return Array.isArray(value) && value.length > 0;
+}
+
+function hasEffectiveAllowPolicy(value: string[] | undefined): value is string[] {
+	return hasPatterns(value) && value.some((pattern) => pattern !== "*");
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}