@gavin-hu/my-pi-agent 0.16.0 → 0.18.0

package/lib/plans/split.ts

@@ -0,0 +1,215 @@
+/**
+ * Whether a plan can be executed in parallel, and by whom (pure).
+ *
+ * The model proposes the split; this decides whether it is one. Nothing here
+ * reads the disk: the refusal rules are facts about the table the plan would be
+ * approved with, so they are testable in isolation and identical on every
+ * platform.
+ *
+ * A refusal is the point of the feature. A split whose units overlap, or whose
+ * dependency graph loops, or that hands a shared file to an owner, is what costs
+ * sessions rather than one tool call — so each rule names the offending pair
+ * instead of returning a boolean.
+ */
+
+import { claimsConflict, findClaimOverlap, normalizeClaimPath } from "../claims/overlap.ts";
+import { type PlanTeam, type PlanUnit, UNIT_NAME, unsafeValue } from "./team.ts";
+
+/** Most non-lead units a team may have: the user switches to each one every round. */
+export const MAX_OWNERS = 2;
+
+/**
+ * Files every workstream touches, so an owner that writes one is a merge conflict
+ * by rule. The lead lands them; the project can extend the list through config.
+ */
+export const SHARED_FILES: readonly string[] = [
+	"package.json",
+	"bun.lock",
+	"bun.lockb",
+	"package-lock.json",
+	"CHANGELOG.md",
+	"README.md",
+	"README.zh-CN.md",
+	"test/suite-manifest.ts",
+	"test/naming.test.ts",
+	"test/structure.test.ts",
+	"lib/tool-names.ts",
+	"lib/requirements.ts",
+];
+
+/** What approval does with a proposed split. */
+export type SplitCheck =
+	| { ok: true; verdict: "serial"; note: string }
+	| ({ ok: true; verdict: "pair" | "team" } & PlanTeam)
+	| { ok: false; reason: string };
+
+/** A unit named in a refusal, so the message says which two collide. */
+function unitAt(units: readonly PlanUnit[], index: number): string {
+	return units[index]?.name ?? `unit ${index + 1}`;
+}
+
+/** Whether `path` covers, or is covered by, any shared file. */
+function sharedHit(path: string, shared: readonly string[]): string | undefined {
+	return shared.find((file) => claimsConflict(path, file));
+}
+
+/**
+ * Walk the `dependsOn` graph and report the first cycle as a readable path.
+ *
+ * A cycle means no unit can start, so it is refused rather than reordered: a
+ * dependency that points both ways usually means the split cut through one
+ * workstream instead of between two.
+ */
+function findCycle(units: readonly PlanUnit[]): string[] | undefined {
+	const byName = new Map(units.map((unit) => [unit.name, unit]));
+	const state = new Map<string, "open" | "done">();
+	const path: string[] = [];
+
+	const visit = (name: string): string[] | undefined => {
+		const mark = state.get(name);
+		if (mark === "done") return undefined;
+		if (mark === "open") return [...path.slice(path.indexOf(name)), name];
+		state.set(name, "open");
+		path.push(name);
+		for (const next of byName.get(name)?.dependsOn ?? []) {
+			const cycle = visit(next);
+			if (cycle) return cycle;
+		}
+		path.pop();
+		state.set(name, "done");
+		return undefined;
+	};
+
+	for (const unit of units) {
+		const cycle = visit(unit.name);
+		if (cycle) return cycle;
+	}
+	return undefined;
+}
+
+/**
+ * Decide what approval does with `units`.
+ *
+ * No units means the plan approves as one flow, which is the common case and
+ * never a failure. One unit is refused with the skeleton advice: a single path
+ * proven end to end is what a split should be cut from, and approving it as a
+ * team would produce a table with nobody to join.
+ */
+export function checkSplit(
+	units: readonly PlanUnit[] | undefined,
+	shared: readonly string[] = SHARED_FILES,
+): SplitCheck {
+	if (!units || units.length === 0) {
+		return { ok: true, verdict: "serial", note: "Approved as one flow." };
+	}
+	if (units.length === 1) {
+		return {
+			ok: false,
+			reason:
+				"A split needs at least two units. Approve as one flow, or build the thinnest end-to-end path first and approve a split once the boundary is real.",
+		};
+	}
+
+	const names = new Set<string>();
+	for (const unit of units) {
+		if (!UNIT_NAME.test(unit.name)) {
+			return { ok: false, reason: `"${unit.name}" is not a unit name; use lowercase letters, digits, and hyphens.` };
+		}
+		if (names.has(unit.name)) return { ok: false, reason: `Two units are both named "${unit.name}".` };
+		names.add(unit.name);
+		if (unit.paths.length === 0) return { ok: false, reason: `Unit "${unit.name}" claims no paths.` };
+		if (!unit.test.trim())
+			return { ok: false, reason: `Unit "${unit.name}" has no test; name the command that proves it.` };
+	}
+	const unsafe = unsafeValue({ lead: units.find((unit) => unit.lead)?.name ?? "", units: [...units] });
+	if (unsafe !== undefined) {
+		return { ok: false, reason: `"${unsafe}" would break the team table; remove the pipe or the line break.` };
+	}
+
+	const leads = units.filter((unit) => unit.lead);
+	if (leads.length !== 1) {
+		return {
+			ok: false,
+			reason:
+				leads.length === 0
+					? "No unit is marked as the lead's; the approving session needs one unit of its own."
+					: `Units ${leads.map((unit) => `"${unit.name}"`).join(" and ")} are both marked lead; only one may be.`,
+		};
+	}
+	const lead = leads[0].name;
+	const owners = units.filter((unit) => !unit.lead);
+	if (owners.length > MAX_OWNERS) {
+		return {
+			ok: false,
+			reason: `A team has at most ${MAX_OWNERS} owners plus the lead; ${owners.length} owners means the split is wrong, not the team too small.`,
+		};
+	}
+
+	// Overlap is checked across units, naming the pair: the same predicate the bus
+	// applies to claims, so approval and claiming cannot disagree.
+	for (const unit of units) {
+		const inside = findClaimOverlap(unit.paths.map(normalizeClaimPath));
+		if (inside) {
+			return {
+				ok: false,
+				reason: `Unit "${unit.name}" lists paths that cover each other: ${inside[0]} and ${inside[1]}. Keep the narrower one.`,
+			};
+		}
+	}
+	for (let i = 0; i < units.length; i++) {
+		for (let j = i + 1; j < units.length; j++) {
+			for (const left of units[i].paths) {
+				for (const right of units[j].paths) {
+					if (claimsConflict(left, right)) {
+						return {
+							ok: false,
+							reason: `Units "${unitAt(units, i)}" and "${unitAt(units, j)}" overlap: ${left} and ${right}. Combine them or serialize.`,
+						};
+					}
+				}
+			}
+		}
+	}
+
+	for (const unit of units) {
+		if (unit.lead) continue;
+		const hit = unit.paths.flatMap((path) => sharedHit(path, shared)).at(0);
+		if (hit !== undefined) {
+			return {
+				ok: false,
+				reason: `Unit "${unit.name}" claims ${hit}, which every workstream touches; the lead lands shared files.`,
+			};
+		}
+	}
+
+	for (const unit of units) {
+		const unknown = unit.dependsOn.find((name) => !names.has(name));
+		if (unknown !== undefined) {
+			return { ok: false, reason: `Unit "${unit.name}" depends on "${unknown}", which is not a unit.` };
+		}
+	}
+	const cycle = findCycle(units);
+	if (cycle) return { ok: false, reason: `Dependencies loop: ${cycle.join(" → ")}.` };
+
+	return { ok: true, verdict: owners.length === 1 ? "pair" : "team", lead, units: units.map((unit) => ({ ...unit })) };
+}
+
+/**
+ * Merge order: the units in dependency order, ties broken by their place in the
+ * table, so the lead merges what everything else builds on first.
+ */
+export function mergeOrder(units: readonly PlanUnit[]): string[] {
+	const placed: string[] = [];
+	const done = new Set<string>();
+	const remaining = [...units];
+	const names = new Set(units.map((unit) => unit.name));
+	while (remaining.length > 0) {
+		// The first unit whose dependencies are all placed. Approval refuses a cycle,
+		// so a search that finds nothing falls back to table order rather than looping.
+		const index = remaining.findIndex((unit) => unit.dependsOn.every((name) => done.has(name) || !names.has(name)));
+		const [next] = remaining.splice(index < 0 ? 0 : index, 1);
+		placed.push(next.name);
+		done.add(next.name);
+	}
+	return placed;
+}

package/lib/plans/store.ts

@@ -0,0 +1,19 @@
+/**
+ * Where a repository's plans live (pure).
+ *
+ * One rule, two readers: `plan` writes here, and `session-bus` reads a team out of
+ * here to resolve a joining unit's paths without importing the plan extension.
+ * The directory is keyed by the repository — see `lib/repo-key.ts` — and a
+ * directory outside a repository has no key, which is the same store plans had
+ * before the key existed.
+ */
+
+import { join } from "node:path";
+
+/** The agent-directory entry plans are filed under. */
+export const PLANS_DIRNAME = "plans";
+
+/** The plan store: `<agent-dir>/plans`, or `<agent-dir>/plans/<key>` inside a repository. */
+export function plansDir(agentDir: string, key?: string): string {
+	return key === undefined ? join(agentDir, PLANS_DIRNAME) : join(agentDir, PLANS_DIRNAME, key);
+}

package/lib/plans/team.ts

@@ -0,0 +1,151 @@
+/**
+ * The plan's `## Team` section (pure): the split a plan was approved with.
+ *
+ * The section is a sentence naming the lead's unit plus a GFM table, because the
+ * review screen already renders a heading and a table — the block model has a
+ * `table` kind — so the split needs no renderer of its own, and the browser page
+ * anchors its comments to the same source lines everything else reads.
+ *
+ * Render and parse are the same module on purpose: the table's shape is a wire
+ * format between approval (`plan`) and joining (`session-bus`), which never
+ * imports this extension, so both sides must agree on one writer.
+ */
+
+import { replaceSection, teamSectionBody } from "./sections.ts";
+
+/** One workstream a plan was split into. */
+export interface PlanUnit {
+	/** Lowercase slug used to address the unit; also the session label its owner takes. */
+	name: string;
+	/** Repository-relative path prefixes the unit owns. */
+	paths: string[];
+	/** The command that proves the unit is done. */
+	test: string;
+	/** Units that must land first. */
+	dependsOn: string[];
+	/** True for the one unit the approving session keeps. */
+	lead?: boolean;
+}
+
+/** A split as it was written into a plan. */
+export interface PlanTeam {
+	/** The unit the approving session works. */
+	lead: string;
+	units: PlanUnit[];
+}
+
+/** Where the section's own heading lives, so a caller can name it in an error. */
+export const TEAM_SECTION = "Team";
+
+/** Unit names are addressed as session labels, so they take the same shape. */
+export const UNIT_NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+/** A value that would break the table or a message. */
+const UNSAFE = /[|\n\r]/;
+const NONE = "—";
+
+/**
+ * Render the section's body.
+ *
+ * Values are narrowed to one line so a path or a title cannot break the table it
+ * is written into; a caller that validates first gets a refusal instead of a
+ * mangled table.
+ */
+export function renderTeam(team: PlanTeam): string {
+	const rows = team.units.map((unit) => {
+		const paths = unit.paths.join(", ");
+		const depends = unit.dependsOn.length > 0 ? unit.dependsOn.join(", ") : NONE;
+		return `| ${unit.name} | ${paths} | ${unit.test} | ${depends} |`;
+	});
+	return [`Lead: ${team.lead}`, "", "| unit | paths | test | depends on |", "| --- | --- | --- | --- |", ...rows].join(
+		"\n",
+	);
+}
+
+/** One cell's text, without the inline code a writer may have used. */
+function clean(cell: string | undefined): string {
+	return (cell ?? "")
+		.trim()
+		.replace(/^`+|`+$/g, "")
+		.trim();
+}
+
+/** Split a table cell into its values, dropping backticks and padding. */
+function cells(cell: string): string[] {
+	return cell
+		.split(",")
+		.map((value) =>
+			value
+				.trim()
+				.replace(/^`+|`+$/g, "")
+				.trim(),
+		)
+		.filter((value) => value !== "" && value !== NONE);
+}
+
+/**
+ * Parse a section body back into a team.
+ *
+ * Every malformed row is an error rather than a silent skip: a team read wrong is
+ * a session joining the wrong paths, which is the one failure this feature exists
+ * to prevent.
+ */
+export function parseTeam(body: string): PlanTeam | { error: string } {
+	const lines = body.split("\n").map((line) => line.trim());
+	const leadLine = lines.find((line) => /^lead:/i.test(line));
+	const rows = lines.filter((line) => line.startsWith("|") && !/^\|\s*-{3}/.test(line));
+	const lead = clean(leadLine?.replace(/^lead:/i, ""));
+	if (!lead) return { error: "The team section has no `Lead: <unit>` line." };
+
+	const [header, ...data] = rows;
+	if (!header) return { error: "The team section has no table." };
+	const columns = header
+		.split("|")
+		.slice(1, -1)
+		.map((cell) => cell.trim().toLowerCase());
+	const at = (name: string): number => columns.indexOf(name);
+	const nameAt = at("unit");
+	const pathsAt = at("paths");
+	const testAt = at("test");
+	const dependsAt = at("depends on");
+	if (nameAt < 0 || pathsAt < 0 || testAt < 0) {
+		return { error: "The team table needs `unit`, `paths`, and `test` columns." };
+	}
+
+	const units: PlanUnit[] = [];
+	for (const row of data) {
+		const values = row.split("|").slice(1, -1);
+		const name = clean(values[nameAt]);
+		if (!name || !UNIT_NAME.test(name)) return { error: `"${name}" is not a unit name.` };
+		const paths = cells(values[pathsAt] ?? "");
+		const test = clean(values[testAt]);
+		if (paths.length === 0) return { error: `Unit "${name}" lists no paths.` };
+		if (!test) return { error: `Unit "${name}" lists no test.` };
+		const dependsOn = dependsAt < 0 ? [] : cells(values[dependsAt] ?? "");
+		units.push({ name, paths, test, dependsOn, ...(name === lead ? { lead: true } : {}) });
+	}
+	if (units.length === 0) return { error: "The team table has no units." };
+	if (!units.some((unit) => unit.name === lead)) return { error: `The lead "${lead}" is not one of the units.` };
+	return { lead, units };
+}
+
+/** The team a plan was approved with, or undefined when it has none. */
+export function readTeam(plan: string): PlanTeam | { error: string } | undefined {
+	const body = teamSectionBody(plan);
+	return body === undefined ? undefined : parseTeam(body);
+}
+
+/** The plan with its team section rewritten. */
+export function writeTeam(plan: string, team: PlanTeam): string {
+	return replaceSection(plan, TEAM_SECTION, renderTeam(team));
+}
+
+/** Whether any rendered value would break the table. */
+export function unsafeValue(team: PlanTeam): string | undefined {
+	for (const unit of team.units) {
+		for (const value of [unit.name, unit.test, ...unit.paths, ...unit.dependsOn]) {
+			if (UNSAFE.test(value)) return value;
+		}
+	}
+	return UNSAFE.test(team.lead) ? team.lead : undefined;
+}

package/lib/qr.ts

@@ -0,0 +1,64 @@
+/**
+ * A QR code as terminal lines or an inline SVG.
+ *
+ * Uses the `qrcode` package only for the module matrix, then draws Unicode
+ * half-blocks for a terminal and hands the package's SVG to a page. The package
+ * loads on the first QR, not when an extension registers: a session that never
+ * shows one pays nothing for it. No ANSI is emitted; the caller decides colours,
+ * and the width is the matrix width plus a quiet zone.
+ *
+ * Two surfaces share this: `wechat` shows a login QR, and `plan` shows a review
+ * link a teammate can scan.
+ */
+
+interface QrModules {
+	size: number;
+	get(row: number, col: number): boolean;
+}
+
+/** QR error-correction level, one setting for both surfaces. */
+const ERROR_CORRECTION = "M" as const;
+
+/** Build the module matrix for `text`, loading `qrcode` on first use. */
+export async function qrMatrix(text: string): Promise<QrModules> {
+	const { default: QRCode } = await import("qrcode");
+	const qr = QRCode.create(text, { errorCorrectionLevel: ERROR_CORRECTION });
+	return qr.modules as unknown as QrModules;
+}
+
+/**
+ * The QR as terminal lines. Each string is exactly `matrix.size + 2 * quiet`
+ * columns wide (half-block characters are single width), so a caller can test
+ * `qrLines(text)[0].length` against the terminal width.
+ */
+export async function qrLines(text: string, options: { quiet?: number } = {}): Promise<string[]> {
+	const quiet = Math.max(0, options.quiet ?? 2);
+	const matrix = await qrMatrix(text);
+	const size = matrix.size;
+	const isDark = (row: number, col: number): boolean =>
+		row >= 0 && col >= 0 && row < size && col < size && matrix.get(row, col);
+
+	const lines: string[] = [];
+	for (let y = -quiet; y < size + quiet; y += 2) {
+		let line = "";
+		for (let x = -quiet; x < size + quiet; x += 1) {
+			const top = isDark(y, x);
+			const bottom = isDark(y + 1, x);
+			line += top && bottom ? "█" : top ? "▀" : bottom ? "▄" : " ";
+		}
+		lines.push(line);
+	}
+	return lines;
+}
+
+/**
+ * The QR as an inline SVG, for a page that can paste markup instead of pixels.
+ *
+ * The markup is generated by the package from a URL this process built, so it
+ * carries no caller-supplied text; a page still serves it under its own CSP,
+ * which allows no external image.
+ */
+export async function qrSvg(text: string): Promise<string> {
+	const { default: QRCode } = await import("qrcode");
+	return QRCode.toString(text, { type: "svg", errorCorrectionLevel: ERROR_CORRECTION, margin: 1 });
+}

package/lib/repo-key.ts

@@ -0,0 +1,74 @@
+/**
+ * The per-repository storage key that outlives one checkout.
+ *
+ * Two extensions file state by repository — `session-bus` its sessions, mail, and
+ * claims, `plan` its plans — and both must resolve the same key from any
+ * worktree, so a plan approved in `.pi/worktrees/x` is the same plan from the
+ * main checkout. The key is the repository's *common* git directory, which every
+ * worktree of that repository shares; outside a repository the working directory
+ * is the identity.
+ *
+ * Hashing keeps a mail directory, a claims directory, and a plans directory short
+ * enough to read and safe on every filesystem, while staying unique per
+ * repository.
+ */
+
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createExecRunner, gitCommonDir, repoRoot } from "./git/index.ts";
+
+/** Hex characters kept from the digest: collision-free in practice and short enough for a path. */
+export const REPO_KEY_LENGTH = 12;
+
+/** The key for one identity string, hashed and shortened. */
+export function repoKeyOf(value: string): string {
+	return createHash("sha256").update(canonical(value)).digest("hex").slice(0, REPO_KEY_LENGTH);
+}
+
+/**
+ * One path, one spelling.
+ *
+ * git prints the path it was told to work from, so a repository reached through a
+ * symlinked prefix reports a different common dir for the same repository. Two
+ * spellings would file one repository's plans and claims under two keys, so the
+ * real path is what gets hashed; a path that cannot be resolved keeps its own
+ * spelling rather than failing.
+ */
+function canonical(value: string): string {
+	try {
+		return realpathSync.native(value);
+	} catch {
+		return value;
+	}
+}
+
+/** A resolved repository identity. */
+export interface RepoKey {
+	/** Absolute repository root, or `cwd` when git did not answer. */
+	root: string;
+	/** The shared key, derived from the common git directory. */
+	key: string;
+	/**
+	 * Whether git resolved the repository. A caller that needs a *project-local*
+	 * location branches on this; one that only needs a stable directory does not.
+	 */
+	fromGit: boolean;
+}
+
+/**
+ * Resolve the repository identity for `cwd`.
+ *
+ * Never throws: without git, or when a git call fails, the working directory is
+ * the identity — which is what a caller outside a repository wants anyway.
+ */
+export async function repoKeyFor(pi: Pick<ExtensionAPI, "exec">, cwd: string): Promise<RepoKey> {
+	try {
+		const run = createExecRunner(pi);
+		const [common, root] = await Promise.all([gitCommonDir(run, cwd), repoRoot(run, cwd)]);
+		if (root) return { root, key: repoKeyOf(common ?? root), fromGit: true };
+	} catch {
+		// Fall through: no git, or a git call that failed, is the same answer here.
+	}
+	return { root: cwd, key: repoKeyOf(cwd), fromGit: false };
+}