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

package/lib/plans/sections.ts

@@ -0,0 +1,172 @@
+/**
+ * Plan-document sections (pure).
+ *
+ * One fence-aware scan of a plan's markdown, and one rewrite of a section in
+ * place. Two features need it: plan mode, whose review screen navigates by
+ * section and whose `set_plan_steps` rewrites `## Steps`, and the split, which
+ * writes and replaces `## Team` at approval. A second scanner would disagree
+ * about a heading inside a fence, so both go through this module.
+ *
+ * The scan is deliberately smaller than CommonMark: a heading is up to three
+ * leading spaces, a space after the hashes, and an optional closing run; a fence
+ * is three backticks or tildes anywhere a fence may start. Inside a fence
+ * nothing is a heading, which is what keeps a `# comment` in a shell example out
+ * of the outline. Every section keeps its raw source lines, so a caller can edit
+ * exactly what it read.
+ */
+
+/** A heading-delimited chunk of a plan, for navigation and in-place edits. */
+export interface PlanSection {
+	/** Plain heading text, or `""` for the content before the first heading. */
+	title: string;
+	/** The section's markdown, including its heading line. */
+	text: string;
+	/** 0-based source line of the section's heading (0 for the preamble). */
+	line: number;
+	/** Heading level, or 0 for the preamble before the first heading. */
+	level: number;
+}
+
+/**
+ * A markdown heading outside a fence, capturing its level and text: up to three
+ * leading spaces, a space after the hashes, and a closing hash run only when a
+ * space separates it. Shared with the block model, so the section split and the
+ * browser outline read a heading line the same way, and `## C#` keeps its title.
+ */
+export const HEADING = /^ {0,3}(#{1,6})\s+(.*?)(?:\s+#+)?\s*$/;
+
+/**
+ * A markdown code-fence opener or closer (backticks or tildes). Shared with the
+ * block model: a tab-indented fence is prose for both parsers, never code for one
+ * and prose for the other.
+ */
+export const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+
+/**
+ * A heading or step label as the review surfaces compare it: inline emphasis and
+ * code removed, whitespace collapsed. Exported so a renderer labels an outline
+ * entry the same way {@link extractSections} labels its section, which is what
+ * lets the browser mark a changed section.
+ */
+export function normalizeHeadingText(text: string): string {
+	return text
+		.replace(/\*\*([^*]+)\*\*/g, "$1")
+		.replace(/\*([^*]+)\*/g, "$1")
+		.replace(/(?<![A-Za-z0-9_])_([^_]+)_(?![A-Za-z0-9_])/g, "$1")
+		.replace(/`([^`]+)`/g, "$1")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/**
+ * Sections of a plan, split at heading lines outside code fences. The content
+ * before the first heading is a section titled `""`. Pi's `Markdown` renderer
+ * exposes no source-line map, so the review screen renders these chunks
+ * separately to know where each section begins.
+ */
+export function extractSections(plan: string): PlanSection[] {
+	const sections: PlanSection[] = [];
+	let current: PlanSection | undefined;
+	let fence: string | undefined;
+
+	const flush = (): void => {
+		if (current && (current.title !== "" || current.text.trim() !== "")) sections.push(current);
+		current = undefined;
+	};
+
+	plan.split("\n").forEach((line, index) => {
+		const fenceMatch = line.match(FENCE);
+		if (fenceMatch) {
+			if (fence === undefined) fence = fenceMatch[1][0];
+			else if (fence === fenceMatch[1][0]) fence = undefined;
+		} else if (fence === undefined) {
+			const heading = line.match(HEADING);
+			if (heading) {
+				flush();
+				current = { title: normalizeHeadingText(heading[2]), text: line, line: index, level: heading[1].length };
+				return;
+			}
+		}
+		if (current === undefined) current = { title: "", text: line, line: 0, level: 0 };
+		else current.text += `\n${line}`;
+	});
+
+	flush();
+	return sections;
+}
+
+/**
+ * The index one past a section's last line: the next heading at its level or
+ * shallower, outside a fence, or the end of the document.
+ */
+function sectionEnd(lines: readonly string[], start: number): number {
+	const level = lines[start].match(HEADING)?.[1].length ?? 2;
+	let fence: string | undefined;
+	for (let index = start + 1; index < lines.length; index++) {
+		const line = lines[index];
+		const fenceMatch = line.match(FENCE);
+		if (fenceMatch) {
+			if (fence === undefined) fence = fenceMatch[1][0];
+			else if (fence === fenceMatch[1][0]) fence = undefined;
+			continue;
+		}
+		if (fence !== undefined) continue;
+		const heading = line.match(HEADING);
+		if (heading && heading[1].length <= level) return index;
+	}
+	return lines.length;
+}
+
+/**
+ * Replace a level-2 section's body, or remove the section, or append one.
+ *
+ * `body` is the section's markdown after its heading, without the heading line —
+ * the caller keeps the heading text so a refinement cannot rename the section
+ * that other code looks for. An empty `body` removes the whole section, which is
+ * how a team stops existing; a missing section with a body appends one, so the
+ * write is idempotent rather than order-dependent.
+ */
+export function replaceSection(plan: string, title: string, body: string | undefined): string {
+	const lines = plan.split("\n");
+	const wanted = normalizeHeadingText(title).toLowerCase();
+	const sections = extractSections(plan);
+	const found = sections.find(
+		(candidate) => candidate.level === 2 && normalizeHeadingText(candidate.title).toLowerCase() === wanted,
+	);
+
+	if (!found) {
+		if (body === undefined) return plan;
+		const prefix = plan.trim() === "" ? "" : `${plan.replace(/\s+$/, "")}\n\n`;
+		return `${prefix}## ${title}\n${body.replace(/\s+$/, "")}\n`;
+	}
+
+	const end = sectionEnd(lines, found.line);
+	const head = lines.slice(0, found.line);
+	const tail = lines.slice(end);
+	if (body === undefined) {
+		// Drop the blank line that separated the section from what follows, so a
+		// removed section leaves one gap rather than two.
+		const joined = [...head, ...tail];
+		return (
+			joined
+				.join("\n")
+				.replace(/\n{3,}/g, "\n\n")
+				.replace(/\s+$/, "") + (plan.endsWith("\n") ? "\n" : "")
+		);
+	}
+	const replacement = [`## ${title}`, "", ...body.replace(/\s+$/, "").split("\n")];
+	// Keep one blank line between the rewritten section and whatever followed it.
+	const gap = tail.length > 0 && tail[0].trim() !== "" ? [""] : [];
+	return [...head, ...replacement, ...gap, ...tail].join("\n");
+}
+
+/** The `## Team` section's body, without its heading or surrounding blank lines. */
+export function teamSectionBody(plan: string): string | undefined {
+	const lines = plan.split("\n");
+	const section = extractSections(plan).find(
+		(candidate) => candidate.level === 2 && normalizeHeadingText(candidate.title).toLowerCase() === "team",
+	);
+	if (!section) return undefined;
+	const body = lines.slice(section.line + 1, sectionEnd(lines, section.line)).join("\n");
+	return body.replace(/^(?:[ \t]*\n)+/, "").replace(/\s+$/, "");
+}

package/lib/plans/setting.ts

@@ -0,0 +1,52 @@
+/**
+ * The switch that turns the split on, and the words the user flips it with.
+ *
+ * It lives in `lib/` because three places must agree: the settings row that
+ * writes it, plan approval that reads it, and the bus that refuses a join while
+ * it is off. A second copy of the key would mean a panel row that changes
+ * nothing — the failure this module exists to prevent.
+ *
+ * Off by default: the split changes what approval means and adds work nobody
+ * asked for, so it ships closed and an existing user upgrades into the single
+ * flow they already know.
+ */
+
+import { asBoolean, configValueAt, loadConfigSection } from "../config.ts";
+
+/** The shared document's section and key that hold the switch. */
+export const SPLIT_SECTION = "plan";
+export const SPLIT_KEY = "split";
+export const SPLIT_DEFAULT = false;
+
+/** The settings-panel row, so a refusal can name what the user flips. */
+export const SPLIT_SETTING_ID = "plan.split";
+export const SPLIT_SETTING_LABEL = "Split plans into slices";
+
+/** The section's shape and its default, so a loader and its documentation agree. */
+export interface SplitConfig {
+	split: boolean;
+}
+
+export const DEFAULT_SPLIT_CONFIG: SplitConfig = { split: SPLIT_DEFAULT };
+
+/** Read the section over `base`, ignoring a value that is not a boolean. */
+export function normalizeSplitConfig(raw: Record<string, unknown> | undefined, base: SplitConfig): SplitConfig {
+	return { split: asBoolean(configValueAt(raw, [SPLIT_KEY]), base.split) };
+}
+
+/**
+ * Whether this repository (or the user's global config) has the split on.
+ *
+ * The project file is read at `root` when the caller knows it: a split belongs to
+ * the repository, so a session started in a subdirectory must honour what the
+ * repository turned on. Without a root the session's cwd is used, which is what a
+ * caller outside a repository has.
+ */
+export function splitEnabled(cwd: string, root?: string): boolean {
+	return loadConfigSection(root ?? cwd, SPLIT_SECTION, DEFAULT_SPLIT_CONFIG, normalizeSplitConfig).split;
+}
+
+/** The one line a refusal or a note uses to say the switch is off and where it lives. */
+export const SPLIT_OFF_NOTE =
+	`Parallel slices are off (${SPLIT_SETTING_ID}). ` +
+	`Enable "${SPLIT_SETTING_LABEL}" in /bytefly settings to split a plan.`;

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 });
+}