pi-plans 0.1.1 → 0.2.0

package/src/plan.ts

@@ -35,6 +35,149 @@ export function scanDoneMarkers(text: string): string[] {
 	return [...text.matchAll(/\[DONE:(VC-\d+)\]/g)].map((match) => match[1]);
 }
 
+export interface CurrentIMarker {
+	id: string;
+}
+
+/** Extract current implementation-item anchors from an assistant message. */
+export function scanCurrentIMarkers(text: string): CurrentIMarker[] {
+	return [...text.matchAll(/\[(I-\d+):current\]/g)].map((match) => ({ id: match[1] }));
+}
+
+export const scanCurrentMarkers = scanCurrentIMarkers;
+
+/** Resolve the last known current-I marker, ignoring unknown ids. */
+export function resolveCurrentI(
+	implItems: ImplItem[],
+	markers: CurrentIMarker[] | string[],
+	fallback?: string,
+): string | undefined {
+	const known = new Set(implItems.map((item) => item.id));
+	let current: string | undefined;
+	for (const marker of markers) {
+		const id = typeof marker === "string" ? marker : marker.id;
+		if (known.has(id)) current = id;
+	}
+	return current ?? fallback;
+}
+
+/** Deterministic frontier used by snapshots written before currentI existed. */
+export function inferCurrentI(
+	implItems: ImplItem[] | undefined,
+	items: CheckItem[],
+	implStatus: Record<string, ImplMarkerState> | undefined,
+): string | undefined {
+	if (!implItems?.length) return undefined;
+	const statuses = resolveImplStatuses(implItems, items, implStatus);
+	return implItems.find((item) => statuses[item.id] !== "vc-passed")?.id ?? implItems.at(-1)?.id;
+}
+
+export type ImplMarkerState = "implemented" | "validating";
+
+export interface ImplMarker {
+	id: string;
+	state: ImplMarkerState;
+}
+
+/** Extract every [I-xxx:implemented|validating] marker from an assistant message. */
+export function scanImplMarkers(text: string): ImplMarker[] {
+	return [...text.matchAll(/\[(I-\d+):(implemented|validating)\]/g)].map((match) => ({
+		id: match[1],
+		state: match[2] as ImplMarkerState,
+	}));
+}
+
+export interface ImplItem {
+	id: string;
+	text: string;
+}
+
+/**
+ * Parse the `## Implementation Items` section of a PLAN_vN.md. Strict grammar:
+ * top-level `- `I-001`: text` single lines only; multi-line bodies and nested
+ * sub-bullets are ignored (text stops at end of the first line).
+ */
+export function parseImplItems(planText: string): ImplItem[] {
+	const lines = planText.split("\n");
+	const headerIndex = lines.findIndex((line) => /^##\s+Implementation Items\s*$/.test(line.trim()));
+	if (headerIndex < 0) return [];
+	const items: ImplItem[] = [];
+	const seen = new Set<string>();
+	for (let i = headerIndex + 1; i < lines.length; i++) {
+		const line = lines[i];
+		if (/^##\s/.test(line.trim())) break; // next section ends the items
+		const match = line.match(/^\s*-\s+`(I-\d+)`\s*:\s+(.*)$/);
+		if (!match) continue;
+		const id = match[1];
+		if (seen.has(id)) continue;
+		seen.add(id);
+		items.push({ id, text: match[2].trim() });
+	}
+	return items;
+}
+
+/**
+ * One-sentence description: cut at the first sentence boundary (。/.) or
+ * semicolon (；/;), then cap at 80 characters with an ellipsis.
+ */
+export function shortImplDescription(text: string): string {
+	const clipped = text.split(/[。；;]/)[0] ?? text;
+	const sentence = clipped.split(/(?<=[.])\s/)[0] ?? clipped;
+	const trimmed = sentence.trim();
+	if (trimmed.length <= 80) return trimmed;
+	return `${trimmed.slice(0, 79)}…`;
+}
+
+/**
+ * Extract the covered I-ids from a VC checklist line's coverage clause
+ * ("`VC-001` covers `I-002` and `I-003`; pass condition: ..." → ["I-002",
+ * "I-003"]). Only references before the first ";" count.
+ */
+export function extractCoverage(vcText: string): string[] {
+	const clause = vcText.split(";")[0] ?? "";
+	return [...clause.matchAll(/\bI-\d+\b/g)].map((match) => match[0]);
+}
+
+export type ImplDisplayState = "pending" | "implementing" | "implemented" | "validating" | "vc-passed";
+
+/**
+ * Resolve the display state for every I-item. Precedence: vc-passed (all
+ * covering VCs done, final) > explicit marker (validating / implemented) >
+ * derivation (some covering VC done → validating; first I with no covering
+ * VC done → implementing; rest → pending).
+ */
+export function resolveImplStatuses(
+	implItems: ImplItem[],
+	items: CheckItem[],
+	implStatus: Record<string, ImplMarkerState> | undefined,
+): Record<string, ImplDisplayState> {
+	const result: Record<string, ImplDisplayState> = {};
+	let frontierAssigned = false;
+	for (const impl of implItems) {
+		const coverage = items.filter((item) => extractCoverage(item.text).includes(impl.id));
+		if (coverage.length > 0 && coverage.every((item) => item.done)) {
+			result[impl.id] = "vc-passed";
+			continue;
+		}
+		const marker = implStatus?.[impl.id];
+		if (marker === "validating" || marker === "implemented") {
+			result[impl.id] = marker;
+			continue;
+		}
+		if (coverage.some((item) => item.done)) {
+			result[impl.id] = "validating";
+			continue;
+		}
+		if (!frontierAssigned) {
+			result[impl.id] = "implementing";
+			frontierAssigned = true;
+			continue;
+		}
+		result[impl.id] = "pending";
+	}
+	return result;
+}
+
 export interface PlanVersionFile {
 	path: string;
 	version: number;

package/src/query-hook.ts

@@ -0,0 +1,82 @@
+import type { ExtensionAPI, ExtensionContext, InputEvent } from "@earendil-works/pi-coding-agent";
+
+export const QUERY_INTERVIEW_MESSAGE_CUSTOM_TYPE = "pi-plans-query-interview";
+export const QUERY_INTERVIEW_MESSAGE =
+	"Before implementing a new user request, if any requirement, constraint, expected behavior, or acceptance criterion is unclear, interview the user with focused clarification questions and confirm the answers before making changes. If the request is clear, proceed directly with the implementation.";
+
+interface QueryHookState {
+	pendingQueries: number;
+}
+
+type QueryHookSession = { __piPlansQueryHook?: QueryHookState };
+
+function sessionCarrier(ctx: ExtensionContext): QueryHookSession | undefined {
+	return ctx.sessionManager as unknown as QueryHookSession | undefined;
+}
+
+function ensureState(ctx: ExtensionContext): QueryHookState | undefined {
+	const session = sessionCarrier(ctx);
+	if (!session) return undefined;
+	return (session.__piPlansQueryHook ??= { pendingQueries: 0 });
+}
+
+export function isOrdinaryExternalQuery(
+	input: Pick<InputEvent, "text" | "source" | "streamingBehavior">,
+): boolean {
+	const text = input.text.trim();
+	return (
+		(input.source === "interactive" || input.source === "rpc")
+		&& input.streamingBehavior === undefined
+		&& text.length > 0
+		&& !text.startsWith("/")
+	);
+}
+
+export function recordOrdinaryQuery(
+	ctx: ExtensionContext,
+	input: Pick<InputEvent, "text" | "source" | "streamingBehavior">,
+): boolean {
+	if (!isOrdinaryExternalQuery(input)) return false;
+	const state = ensureState(ctx);
+	if (!state) return false;
+	state.pendingQueries += 1;
+	return true;
+}
+
+export function consumeOrdinaryQuery(ctx: ExtensionContext): boolean {
+	const session = sessionCarrier(ctx);
+	const state = session?.__piPlansQueryHook;
+	if (!state || state.pendingQueries <= 0) return false;
+	state.pendingQueries -= 1;
+	if (state.pendingQueries === 0) delete session.__piPlansQueryHook;
+	return true;
+}
+
+export function resetOrdinaryQueryState(ctx: ExtensionContext): void {
+	const session = sessionCarrier(ctx);
+	if (session) delete session.__piPlansQueryHook;
+}
+
+export function registerQueryInterviewHooks(
+	pi: ExtensionAPI,
+	suppressForWorkflow: (ctx: ExtensionContext) => boolean,
+): void {
+	pi.on("input", async (event, ctx) => {
+		recordOrdinaryQuery(ctx, event);
+	});
+
+	pi.on("before_agent_start", async (_event, ctx) => {
+		if (!consumeOrdinaryQuery(ctx) || suppressForWorkflow(ctx)) return;
+		return {
+			message: {
+				customType: QUERY_INTERVIEW_MESSAGE_CUSTOM_TYPE,
+				content: QUERY_INTERVIEW_MESSAGE,
+				display: false,
+			},
+		};
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		resetOrdinaryQueryState(ctx);
+	});
+}

package/src/refine-ui-helpers.ts

@@ -0,0 +1,89 @@
+/**
+ * Lightweight, dependency-free replacements for the pi-tui text utilities used
+ * by the refine overlay. Keeping these local lets the overlay render correctly
+ * in contexts where the pi-tui module is not on the resolver path (notably the
+ * standalone `node:test` runs in this repository, since `@earendil-works/pi-tui`
+ * is a peer of `@earendil-works/pi-coding-agent` rather than a direct
+ * dependency of pi-plans).
+ */
+
+const ELLIPSIS = "…";
+
+export function visibleWidth(text: string): number {
+	if (!text) return 0;
+	let width = 0;
+	for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)) {
+		const cp = segment.segment.codePointAt(0) ?? 0;
+		if (cp < 0x20) continue;
+		if (cp === 0x09) { width += 3; continue; }
+		if (cp >= 0x1100 && cp <= 0x115f) { width += 2; continue; }
+		if (cp >= 0x2e80 && cp <= 0x9fff) { width += 2; continue; }
+		if (cp >= 0xac00 && cp <= 0xd7a3) { width += 2; continue; }
+		if (cp >= 0xff00 && cp <= 0xff60) { width += 2; continue; }
+		if (cp >= 0x1f300 && cp <= 0x1faff) { width += 2; continue; }
+		width += 1;
+	}
+	return width;
+}
+
+export function truncateToWidth(text: string, maxWidth: number, ellipsis = ELLIPSIS): string {
+	const measured = visibleWidth(text);
+	if (measured <= maxWidth) return text;
+	const ellipsisWidth = ellipsis ? visibleWidth(ellipsis) : 0;
+	const target = Math.max(0, maxWidth - ellipsisWidth);
+	let result = "";
+	let used = 0;
+	for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)) {
+		const w = visibleWidth(segment.segment);
+		if (used + w > target) break;
+		result += segment.segment;
+		used += w;
+	}
+	return ellipsis ? `${result}${ellipsis}` : result;
+}
+
+export function wrapTextWithAnsi(text: string, maxWidth: number): string[] {
+	if (maxWidth <= 0) return [text];
+	const normalized = text.replace(/\r\n/g, "\n");
+	const words = normalized.split(/(\s+)/);
+	const lines: string[] = [];
+	let current = "";
+	let currentWidth = 0;
+	for (const word of words) {
+		if (word === "") continue;
+		const wordWidth = visibleWidth(word);
+		if (wordWidth > maxWidth) {
+			// Hard split a single overlong word.
+			if (current) { lines.push(current); current = ""; currentWidth = 0; }
+			let buffer = "";
+			let bufferWidth = 0;
+			for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(word)) {
+				const w = visibleWidth(segment.segment);
+				if (bufferWidth + w > maxWidth) {
+					lines.push(buffer);
+					buffer = segment.segment;
+					bufferWidth = w;
+				} else {
+					buffer += segment.segment;
+					bufferWidth += w;
+				}
+			}
+			if (buffer) { lines.push(buffer); buffer = ""; bufferWidth = 0; }
+			continue;
+		}
+		if (currentWidth + wordWidth > maxWidth) {
+			lines.push(current.trimEnd());
+			current = word.trimStart();
+			currentWidth = visibleWidth(current);
+		} else {
+			current += word;
+			currentWidth += wordWidth;
+		}
+	}
+	if (current.trim().length > 0) lines.push(current.trimEnd());
+	return lines;
+}
+
+export function matchesEscape(data: string): boolean {
+	return data === "\x1b" || data === "\x1b\x1b" || /^(\x1b\[\??\d*[A-Za-z])|(\x1bO[A-Za-z])$/.test(data);
+}

package/src/refine-ui-state.ts

@@ -0,0 +1,78 @@
+import type { SubagentProgressEvent, SubagentResult } from "./subagent.ts";
+
+export type RefineOverlayRole = "reviewer" | "criticizer";
+export type RefineLaneStatus = "queued" | "running" | "complete" | "failed" | "cancelled";
+
+export interface RefineLaneState {
+	id: string;
+	label: string;
+	status: RefineLaneStatus;
+	phase: string;
+	detail: string;
+}
+
+function shorten(text: string, maxLength: number): string {
+	const normalized = text.replace(/\s+/g, " ").trim();
+	return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 3)}...` : normalized;
+}
+
+export function statusLabel(status: RefineLaneStatus): string {
+	switch (status) {
+		case "queued":
+			return "queued";
+		case "running":
+			return "running";
+		case "complete":
+			return "done";
+		case "failed":
+			return "failed";
+		case "cancelled":
+			return "cancelled";
+	}
+}
+
+export function applyRefineProgress(lane: RefineLaneState, event: SubagentProgressEvent): void {
+	if (lane.status === "complete" || lane.status === "failed" || lane.status === "cancelled") return;
+
+	switch (event.type) {
+		case "process":
+			lane.phase = event.phase === "started" ? "starting" : "exiting";
+			return;
+		case "turn":
+			lane.status = "running";
+			lane.phase = event.phase === "start" ? "thinking" : "waiting";
+			return;
+		case "message":
+			lane.status = "running";
+			lane.phase = event.role === "assistant" ? "responding" : event.role;
+			if (event.text) lane.detail = shorten(event.text, 180);
+			return;
+		case "tool":
+			lane.status = "running";
+			lane.phase = `tool: ${event.toolName}`;
+			if (event.detail) lane.detail = shorten(event.detail, 180);
+			return;
+		case "stderr":
+			lane.phase = "diagnostic";
+			if (event.text) lane.detail = shorten(event.text, 180);
+			return;
+	}
+}
+
+export function applyRefineResult(lane: RefineLaneState, result: SubagentResult): void {
+	if (result.ok) {
+		lane.status = "complete";
+		lane.phase = "complete";
+		lane.detail = shorten(result.output, 180);
+		return;
+	}
+	if (result.cancelled) {
+		lane.status = "cancelled";
+		lane.phase = "cancelled";
+		lane.detail = shorten(result.errorMessage ?? "Subagent was aborted", 180);
+		return;
+	}
+	lane.status = "failed";
+	lane.phase = result.timedOut ? "timed out" : "failed";
+	lane.detail = shorten((result.errorMessage ?? result.stderr) || "Subagent failed", 180);
+}