@fyeeme/pi-goal 1.0.0

package/src/template.ts

@@ -0,0 +1,154 @@
+/**
+ * pi-goal — minimal template renderer.
+ *
+ * Replaces oh-my-pi's `prompt.render` (from @oh-my-pi/pi-utils) for the goal
+ * prompt templates, which use exactly three constructs:
+ *
+ *   {{variable}}                 interpolate (values arrive pre-stringified)
+ *   {{#if var}}A{{else}}B{{/if}} conditional; `else` branch optional
+ *   {{#each arr}}...{{/each}}    iteration; item fields shadow outer scope
+ *
+ * Unknown variables render as empty strings. This is a renderer, not an
+ * escaper: callers escape XML-sensitive text with escapeXmlText before passing
+ * values in, matching omp call sites.
+ */
+
+export type TemplateValue = string | number | boolean | undefined | null | TemplateValue[] | Record<string, unknown>;
+export type TemplateScope = Record<string, TemplateValue>;
+
+type Node =
+	| { kind: "text"; text: string }
+	| { kind: "var"; name: string }
+	| { kind: "if"; name: string; whenTrue: Node[]; whenFalse: Node[] }
+	| { kind: "each"; name: string; body: Node[] };
+
+const TAG = /\{\{([^}]+)\}\}/;
+
+/**
+ * Parse from `start` until the closing tag named `stopName` ("if" / "each" /
+ * null for top level). When parsing an if-body, an `{{else}}` ends the
+ * then-branch and is reported via `sawElse`; the caller parses the else branch.
+ */
+function parseUntil(
+	template: string,
+	start: number,
+	stopName: "if" | "each" | null,
+): { nodes: Node[]; end: number; sawElse: boolean } {
+	const nodes: Node[] = [];
+	let cursor = start;
+	while (cursor < template.length) {
+		const rest = template.slice(cursor);
+		const match = TAG.exec(rest);
+		if (!match || match.index === undefined) {
+			if (stopName !== null) {
+				throw new Error(`goal template: unclosed {{#${stopName}}}`);
+			}
+			nodes.push({ kind: "text", text: rest });
+			return { nodes, end: template.length, sawElse: false };
+		}
+		const tagStart = cursor + match.index;
+		if (tagStart > cursor) {
+			nodes.push({ kind: "text", text: template.slice(cursor, tagStart) });
+		}
+		const raw = match[1].trim();
+		const afterTag = tagStart + match[0].length;
+
+		if (raw === "else") {
+			if (stopName === "if") {
+				return { nodes, end: afterTag, sawElse: true };
+			}
+			throw new Error("goal template: unexpected {{else}} outside {{#if}}");
+		}
+		if (raw.startsWith("/")) {
+			const closing = raw.slice(1);
+			if (stopName !== null && closing === stopName) {
+				return { nodes, end: afterTag, sawElse: false };
+			}
+			throw new Error(`goal template: unexpected closing tag {{${raw}}}`);
+		}
+		if (raw.startsWith("#if ")) {
+			const name = raw.slice(4).trim();
+			const thenPart = parseUntil(template, afterTag, "if");
+			let otherwise: Node[] = [];
+			let end = thenPart.end;
+			if (thenPart.sawElse) {
+				const elsePart = parseUntil(template, thenPart.end, "if");
+				otherwise = elsePart.nodes;
+				end = elsePart.end;
+			}
+			nodes.push({ kind: "if", name, whenTrue: thenPart.nodes, whenFalse: otherwise });
+			cursor = end;
+			continue;
+		}
+		if (raw.startsWith("#each ")) {
+			const name = raw.slice(6).trim();
+			const body = parseUntil(template, afterTag, "each");
+			nodes.push({ kind: "each", name, body: body.nodes });
+			cursor = body.end;
+			continue;
+		}
+		nodes.push({ kind: "var", name: raw });
+		cursor = afterTag;
+	}
+	if (stopName !== null) {
+		throw new Error(`goal template: unclosed {{#${stopName}}}`);
+	}
+	return { nodes, end: template.length, sawElse: false };
+}
+
+function lookup(scope: TemplateScope, name: string): TemplateValue {
+	if (!(name in scope)) return "";
+	return scope[name];
+}
+
+function isTruthy(value: TemplateValue): boolean {
+	if (Array.isArray(value)) return value.length > 0;
+	return Boolean(value);
+}
+
+function renderNodes(nodes: Node[], scope: TemplateScope): string {
+	let out = "";
+	for (const node of nodes) {
+		if (node.kind === "text") {
+			out += node.text;
+		} else if (node.kind === "var") {
+			out += String(lookup(scope, node.name) ?? "");
+		} else if (node.kind === "if") {
+			out += isTruthy(lookup(scope, node.name))
+				? renderNodes(node.whenTrue, scope)
+				: renderNodes(node.whenFalse, scope);
+		} else {
+			const value = lookup(scope, node.name);
+			if (!Array.isArray(value)) continue;
+			for (const item of value) {
+				const itemScope: TemplateScope =
+					item !== null && typeof item === "object" && !Array.isArray(item)
+						? { ...scope, ...(item as TemplateScope) }
+						: { ...scope, this: item as TemplateValue };
+				out += renderNodes(node.body, itemScope);
+			}
+		}
+	}
+	return out;
+}
+
+const parseCache = new Map<string, Node[]>();
+
+/** Render a goal prompt template. Templates are static; parse results are cached. */
+export function renderTemplate(template: string, scope: TemplateScope): string {
+	let nodes = parseCache.get(template);
+	if (!nodes) {
+		nodes = parseUntil(template, 0, null).nodes;
+		parseCache.set(template, nodes);
+	}
+	return renderNodes(nodes, scope);
+}
+
+/**
+ * Escape XML-sensitive characters — omp `escapeXmlText`
+ * (packages/utils/src/sanitize-text.ts) escapes ONLY the & < > trio; quotes
+ * stay verbatim (element-body semantics, pinned by omp's goal-runtime tests).
+ */
+export function escapeXmlText(text: string): string {
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}

package/src/todo-bridge.ts

@@ -0,0 +1,136 @@
+/**
+ * pi-goal — todo bridge.
+ *
+ * omp rendered a `<todo_context>` block inside the goal-mode context message
+ * by reading the host todo state directly (`session.getTodoPhases()`), gated
+ * on `todo.enabled` + the todo tool being active. pi-goal is a separate
+ * extension, so the state arrives over the documented pi-todo integration
+ * contract instead:
+ *
+ *   - `pi.events.on("todo_updated")` keeps the live phases (pi-todo emits
+ *     after every successful mutation, never on view or failure)
+ *   - session entries (`todo-phases` full snapshots, pi-todo's documented
+ *     entry type) restore the phases on session_start
+ *
+ * The rendered block is byte-identical to omp's goal-todo-context.md output:
+ * phase names and task contents are XML-escaped with control characters
+ * flattened (omp #sanitizeGoalTodoText).
+ */
+
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { escapeXmlText, renderTemplate } from "./template.ts";
+
+const goalTodoContextPrompt = readFileSync(
+	path.join(path.dirname(fileURLToPath(import.meta.url)), "prompts", "goal-todo-context.md"),
+	"utf8",
+);
+
+/** pi-todo session entry customType for phase snapshots. */
+const TODO_PHASES_ENTRY_TYPE = "todo-phases";
+
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned" | "blocked";
+
+export interface TodoItem {
+	content: string;
+	status: TodoStatus;
+	blocker?: string;
+}
+
+export interface TodoPhase {
+	name: string;
+	tasks: TodoItem[];
+}
+
+interface EntryLike {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+}
+
+function isTodoStatus(value: unknown): value is TodoStatus {
+	return (
+		value === "pending" ||
+		value === "in_progress" ||
+		value === "completed" ||
+		value === "abandoned" ||
+		value === "blocked"
+	);
+}
+
+function isTodoPhase(value: unknown): value is TodoPhase {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value as Record<string, unknown>;
+	if (typeof record.name !== "string" || !Array.isArray(record.tasks)) return false;
+	return record.tasks.every((task) => {
+		if (typeof task !== "object" || task === null) return false;
+		const t = task as Record<string, unknown>;
+		return typeof t.content === "string" && isTodoStatus(t.status);
+	});
+}
+
+/**
+ * Restore todo phases from session entries (pi-todo's `todo-phases` snapshots).
+ * Latest valid snapshot wins; malformed entries are skipped.
+ */
+export function restoreTodoPhases(entries: readonly unknown[]): TodoPhase[] {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i] as EntryLike | undefined;
+		if (!entry || entry.type !== "custom" || entry.customType !== TODO_PHASES_ENTRY_TYPE) continue;
+		const data = entry.data as { phases?: unknown } | undefined;
+		if (data && Array.isArray(data.phases) && data.phases.every(isTodoPhase)) {
+			return data.phases.map((phase) => ({
+				name: phase.name,
+				tasks: phase.tasks.map((task) => ({ content: task.content, status: task.status })),
+			}));
+		}
+	}
+	return [];
+}
+
+/** omp #sanitizeGoalTodoText: XML-escape and flatten control characters. */
+function sanitizeTodoText(text: string): string {
+	return escapeXmlText(text)
+		.replace(/\r\n/g, "\\n")
+		.replace(/\r/g, "\\r")
+		.replace(/\n/g, "\\n")
+		.replace(/\t/g, "\\t")
+		.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u2028\u2029]/g, " ");
+}
+
+/**
+ * Render the `<todo_context>` block for the goal-mode context message.
+ * Returns undefined when the todo tool is not active or there are no
+ * non-empty phases (omp #buildGoalTodoContext gates).
+ */
+export function buildTodoContext(phases: TodoPhase[], todoToolActive: boolean): string | undefined {
+	const canCallTodoTool = todoToolActive;
+	if (!canCallTodoTool) return undefined;
+	const nonEmpty = phases.filter((phase) => phase.tasks.length > 0);
+	if (nonEmpty.length === 0) return undefined;
+
+	let total = 0;
+	let closed = 0;
+	let open = 0;
+	const promptPhases = nonEmpty.map((phase) => ({
+		name: sanitizeTodoText(phase.name),
+		tasks: phase.tasks.map((task) => {
+			total++;
+			if (task.status === "completed" || task.status === "abandoned") {
+				closed++;
+			} else {
+				open++;
+			}
+			return { content: sanitizeTodoText(task.content), status: task.status };
+		}),
+	}));
+
+	return renderTemplate(goalTodoContextPrompt, {
+		canCallTodoTool,
+		closed: String(closed),
+		open: String(open),
+		phases: promptPhases,
+		total: String(total),
+	});
+}