pi-do-always 0.9.0 → 0.10.0

package/extensions/pi-do-always/tasks.ts

@@ -51,13 +51,13 @@ export interface DoAlwaysTask {
  * The task stays visible but selecting it notifies instead of injecting.
  * `requireDirty` needs no `value`; the others require a string `value`.
  */
-export interface Guard {
+interface Guard {
 	type: "requireDirty" | "requireBranch" | "requireRepo" | "requireFilePattern";
 	value?: string;
 }
 
 /** The set of known guard types (used for validation at parse time). */
-export const GUARD_TYPES = [
+const GUARD_TYPES = [
 	"requireDirty",
 	"requireBranch",
 	"requireRepo",
@@ -72,19 +72,24 @@ export const GUARD_TYPES = [
  * `override` (default) replaces a global task with the same name;
  * `append` keeps globals and only adds new project task names (a cascade).
  */
-export type DoAlwaysConfig =
+type DoAlwaysConfig =
 	| DoAlwaysTask[]
 	| {
 			tasks: DoAlwaysTask[];
 			shortcut?: string | null;
 			merge?: "append" | "override";
+			/**
+			 * Whether chain runs write a Markdown report file (one per run, in
+			 * the project root). Default true; set false to disable.
+			 */
+			report?: boolean;
 		};
 
 /** Shortcut used when neither config file specifies one. */
 export const DEFAULT_SHORTCUT = "f4";
 
 /** Result of parsing a config file. */
-export interface ParsedDoAlwaysConfig {
+interface ParsedDoAlwaysConfig {
 	tasks: DoAlwaysTask[];
 	/**
 	 * The `shortcut` field, if present: a key id string, null when explicitly
@@ -96,10 +101,15 @@ export interface ParsedDoAlwaysConfig {
 	 * file does not set one.
 	 */
 	merge?: "append" | "override" | undefined;
+	/**
+	 * The `report` field, if present: whether chain runs write a Markdown
+	 * report file. undefined when the file does not set one (default: on).
+	 */
+	report: boolean | undefined;
 }
 
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve, sep } from "node:path";
 
 /**
  * Structured facts about the working tree and git state, gathered once per
@@ -326,14 +336,14 @@ export function parseConfig(
 		data = JSON.parse(raw);
 	} catch (err) {
 		onError(`do-always: invalid JSON in ${path}: ${err}`);
-		return { tasks: [], shortcut: undefined };
+		return { tasks: [], shortcut: undefined, report: undefined };
 	}
 
 	const list = Array.isArray(data) ? data : data?.tasks;
 
 	if (!Array.isArray(list)) {
 		onError(`do-always: ${path} must be a JSON array of tasks or {"tasks": [...]}`);
-		return { tasks: [], shortcut: undefined };
+		return { tasks: [], shortcut: undefined, report: undefined };
 	}
 
 	const tasks: DoAlwaysTask[] = [];
@@ -384,8 +394,13 @@ export function parseConfig(
 	if (!Array.isArray(data) && "merge" in data) {
 		merge = parseMerge(data.merge, path, onError);
 	}
+	let report: boolean | undefined;
+	if (!Array.isArray(data) && "report" in data) {
+		if (typeof data.report === "boolean") report = data.report;
+		else onError(`do-always: ignoring invalid "report" in ${path} (expected true or false)`);
+	}
 
-	return { tasks, shortcut, merge };
+	return { tasks, shortcut, merge, report };
 }
 
 const KEY_MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
@@ -514,7 +529,12 @@ export function isValidWhen(when: unknown): boolean {
 /** True when `relativePath` exists (as file or directory) under `cwd`. */
 function pathExists(cwd: string, relativePath: string): boolean {
 	try {
-		return existsSync(join(cwd, relativePath));
+		const resolved = resolve(cwd, relativePath);
+		// Containment check: reject paths that escape the project root.
+		// `resolve` normalizes `..` sequences, so this catches
+		// "../../.ssh/id_rsa" → "/home/user/.ssh/id_rsa" when cwd is "/home/user/project".
+		if (!resolved.startsWith(cwd + sep) && resolved !== cwd) return false;
+		return existsSync(resolved);
 	} catch {
 		return false;
 	}
@@ -571,7 +591,7 @@ export function evaluateWhen(task: DoAlwaysTask, ctx: TaskContext): boolean {
 export const DEFAULT_CATEGORY_ORDER = ["Plan", "Do", "Docs", "Ops", "Other"];
 
 /** A category group: a display name and the tasks that belong to it. */
-export interface TaskGroup {
+interface TaskGroup {
 	name: string;
 	items: DoAlwaysTask[];
 }
@@ -685,8 +705,13 @@ function filesMatchPattern(files: string[], pattern: string): boolean {
 /** Regex metacharacters that must be escaped when matching a literal path char. */
 const METACHARACTERS = ".+^${}()|[]";
 
+/** Compiled regex cache: glob patterns are static config, so we memoize. */
+const globRegexCache = new Map<string, RegExp>();
+
 /** Convert a glob to an anchored RegExp (`**` -> `.*`, `*` -> `[^/]*`, `?` -> `[^/]`). */
 function globToRegex(pattern: string): RegExp {
+	let cached = globRegexCache.get(pattern);
+	if (cached) return cached;
 	let out = "";
 	let i = 0;
 	while (i < pattern.length) {
@@ -706,7 +731,9 @@ function globToRegex(pattern: string): RegExp {
 			i++;
 		}
 	}
-	return new RegExp(`^${out}$`);
+	cached = new RegExp(`^${out}$`);
+	globRegexCache.set(pattern, cached);
+	return cached;
 }
 
 /**
@@ -789,3 +816,300 @@ export function formatList(tasks: DoAlwaysTask[]): string {
 	}
 	return lines.join("\n");
 }
+
+// ---------------------------------------------------------------------------
+// Chains
+//
+// A chain is an ordered, duplicate-free list of tasks the user builds in the
+// selector table (ORDER column) and runs from the pinned Run row. All
+// operations are pure: they return new states, never mutate.
+// ---------------------------------------------------------------------------
+
+/** Maximum number of tasks in a chain. */
+export const CHAIN_MAX = 8;
+
+/**
+ * A task chain: ordered task names plus a LIFO history of adds (for undo).
+ * Pure state — every operation returns a new state.
+ */
+interface ChainState {
+	/** Task names in execution order (duplicate-free). */
+	items: string[];
+	/** LIFO history of added names, consumed by `chainUndo`. */
+	history: string[];
+}
+
+/** An empty chain. */
+export function chainClear(): ChainState {
+	return { items: [], history: [] };
+}
+
+/**
+ * Add a task to the chain. A name already in the chain is moved to the end
+ * (`movedToEnd`); when the chain is at CHAIN_MAX the state is returned
+ * unchanged (`full`).
+ */
+export function chainAdd(
+	state: ChainState,
+	name: string,
+): { state: ChainState; result: "added" | "movedToEnd" | "full" } {
+	if (state.items.includes(name)) {
+		return {
+			state: {
+				items: [...state.items.filter((n) => n !== name), name],
+				history: [...state.history, name],
+			},
+			result: "movedToEnd",
+		};
+	}
+	if (state.items.length >= CHAIN_MAX) {
+		return { state, result: "full" };
+	}
+	return {
+		state: { items: [...state.items, name], history: [...state.history, name] },
+		result: "added",
+	};
+}
+
+/** Remove a task from the chain (no-op when absent). History is untouched. */
+export function chainRemove(state: ChainState, name: string): ChainState {
+	if (!state.items.includes(name)) return state;
+	return { ...state, items: state.items.filter((n) => n !== name) };
+}
+
+/**
+ * Undo the most recent add that is still in the chain, skipping names that
+ * were removed in the meantime. Returns `removed: null` when there is
+ * nothing left to undo.
+ */
+export function chainUndo(state: ChainState): { state: ChainState; removed: string | null } {
+	for (let i = state.history.length - 1; i >= 0; i--) {
+		const name = state.history[i];
+		if (state.items.includes(name)) {
+			return {
+				state: {
+					items: state.items.filter((n) => n !== name),
+					history: state.history.slice(0, i),
+				},
+				removed: name,
+			};
+		}
+	}
+	return { state, removed: null };
+}
+
+/**
+ * Move a task one position up (-1) or down (1) in the chain. No-op at the
+ * ends or when the name is not in the chain.
+ */
+export function chainMove(state: ChainState, name: string, dir: -1 | 1): ChainState {
+	const idx = state.items.indexOf(name);
+	const target = idx + dir;
+	if (idx < 0 || target < 0 || target >= state.items.length) return state;
+	const items = [...state.items];
+	items[idx] = items[target];
+	items[target] = name;
+	return { ...state, items };
+}
+
+/**
+ * Label for the pinned Run row: a dimmed placeholder for an empty chain,
+ * singular for one task, plural with the count otherwise.
+ */
+export function chainRunLabel(count: number): string {
+	if (count === 0) return "run the chain (0)";
+	if (count === 1) return "Run the task";
+	return `Run the chain (${count})`;
+}
+
+/** One row of the task table (see `buildTableRows`). */
+export interface TableRow {
+	kind: "header" | "task" | "run";
+	/** Header text (kind=header) or the run label (kind=run). */
+	name?: string;
+	/** The task (kind=task). */
+	task?: DoAlwaysTask;
+	/** 1-based chain position (kind=task, only when the task is chained). */
+	order?: number;
+}
+
+/**
+ * Build the table rows: a header row per non-empty category, a task row per
+ * task carrying its ORDER position, and the pinned Run row last (label from
+ * `chainRunLabel`).
+ */
+export function buildTableRows(groups: TaskGroup[], chain: ChainState): TableRow[] {
+	const rows: TableRow[] = [];
+	for (const g of groups) {
+		if (g.items.length === 0) continue;
+		rows.push({ kind: "header", name: g.name });
+		for (const t of g.items) {
+			const pos = chain.items.indexOf(t.name);
+			rows.push({
+				kind: "task",
+				task: t,
+				...(pos >= 0 ? { order: pos + 1 } : {}),
+			});
+		}
+	}
+	rows.push({ kind: "run", name: chainRunLabel(chain.items.length) });
+	return rows;
+}
+
+/**
+ * Footer preview of the chain: "1.⚡ Review changes → 2.Build". Tasks are
+ * looked up in `tasks`; unknown names (a stale chain) are skipped.
+ */
+export function formatChainSequence(tasks: DoAlwaysTask[], chain: ChainState): string {
+	// O(n) index map so find → O(1) lookup.
+	const taskByName = new Map(tasks.map((t) => [t.name, t]));
+	const parts = chain.items
+		.map((name, i) => {
+			const t = taskByName.get(name);
+			if (!t) return null;
+			const marker = shouldAutoRun(t) ? "⚡" : "";
+			return `${i + 1}.${marker}${t.name}`;
+		})
+		.filter((p): p is string => p !== null);
+	return parts.join(" → ");
+}
+
+/**
+ * Validate a chain against the context: every task must pass its guards.
+ * Returns the first failing step (1-based) with the guard message, or null
+ * when the whole chain may run. Stale names (not found in `tasks`) are
+ * skipped — the runner drops them.
+ */
+export function validateChain(
+	tasks: DoAlwaysTask[],
+	chain: ChainState,
+	ctx: TaskContext,
+): { step: number; task: DoAlwaysTask; message: string } | null {
+	for (let i = 0; i < chain.items.length; i++) {
+		const task = tasks.find((t) => t.name === chain.items[i]);
+		if (!task) continue;
+		const message = evaluateGuards(task, ctx);
+		if (message) return { step: i + 1, task, message };
+	}
+	return null;
+}
+
+// ── Chain report ─────────────────────────────────────────────────────────
+//
+// A chain run's results are appended to a Markdown report file (one file
+// per run, in the project root) as each step finishes, so earlier steps'
+// results survive later steps' output scrolling them off screen. The file
+// is written incrementally: even if the session dies mid-chain, the
+// finished steps' results are on disk.
+
+/** HH:MM in the local timezone. */
+function reportTime(d: Date): string {
+	return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+/** File name for one chain run's report, e.g. do-always-report-tasks-2025-01-15-1432.md. */
+export function reportFileName(now: Date): string {
+	const p = (n: number) => String(n).padStart(2, "0");
+	return `do-always-report-tasks-${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}-${p(now.getHours())}${p(now.getMinutes())}.md`;
+}
+
+/**
+ * Resolve the report file path in `cwd`, appending -2, -3, … when a file
+ * with the same name already exists (two runs within the same minute).
+ */
+export function resolveReportPath(
+	cwd: string,
+	now: Date,
+	exists: (path: string) => boolean = existsSync,
+): string {
+	const base = reportFileName(now);
+	const first = join(cwd, base);
+	if (!exists(first)) return first;
+	const stem = base.slice(0, -3); // drop ".md"
+	for (let i = 2; ; i++) {
+		const candidate = join(cwd, `${stem}-${i}.md`);
+		if (!exists(candidate)) return candidate;
+	}
+}
+
+/** Markdown header for a new report file. */
+export function reportHeader(projectPath: string, stepNames: string[], now: Date): string {
+	const p = (n: number) => String(n).padStart(2, "0");
+	const stamp = `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())} ${reportTime(now)}`;
+	return [
+		`# do-always chain report — ${stamp}`,
+		"",
+		`- Project: ${projectPath}`,
+		`- Steps: ${stepNames.join(" → ")}`,
+		"",
+		"",
+	].join("\n");
+}
+
+/**
+ * Markdown section for one finished step: its number, name, outcome, run
+ * time, and the final assistant message (the step's result). `startedAt`
+ * is null when the run never started (failed-to-start).
+ */
+export function reportStepSection(
+	index: number,
+	name: string,
+	status: string,
+	startedAt: Date | null,
+	endedAt: Date,
+	text: string,
+): string {
+	const times = startedAt ? `${reportTime(startedAt)} → ${reportTime(endedAt)}` : reportTime(endedAt);
+	const lines = [`## ${index + 1}. ${name} — ${status} (${times})`, ""];
+	const trimmed = text.trim();
+	lines.push(trimmed === "" ? "_(no result text)_" : trimmed, "", "");
+	return lines.join("\n");
+}
+
+/** Markdown footer summarizing the whole run. */
+export function reportFooter(stepStatuses: string[], now: Date): string {
+	const done = stepStatuses.filter((s) => s === "completed").length;
+	const total = stepStatuses.length;
+	const p = (n: number) => String(n).padStart(2, "0");
+	const stamp = `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())} ${reportTime(now)}`;
+	const summary =
+		done === total ? `${done}/${total} completed` : `${done}/${total} completed — chain stopped early`;
+	return `---\n\n**Chain finished:** ${stamp} — ${summary}\n`;
+}
+
+/** Markdown footer for a chain that never reached a terminal path (e.g., the session ended mid-chain). */
+export function reportAbandonedFooter(stepStatuses: string[], now: Date): string {
+	const done = stepStatuses.filter((s) => s === "completed").length;
+	const total = stepStatuses.length;
+	const p = (n: number) => String(n).padStart(2, "0");
+	const stamp = `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())} ${reportTime(now)}`;
+	return `---\n\n**Chain abandoned:** ${stamp} — ${done}/${total} completed\n`;
+}
+
+/**
+ * Whether a finished run's report file is worth keeping on disk: at least
+ * one completed step, or some step section carried result text. A run that
+ * produced neither (e.g. step 1 errored before any output, or the chain was
+ * blocked before running) leaves no file behind — the failure is already
+ * surfaced by the notification, and a quick same-minute retry would
+ * otherwise get a `-N` sibling next to an empty report.
+ */
+export function reportWorthKeeping(stepStatuses: string[], hasContent: boolean): boolean {
+	return hasContent || stepStatuses.some((s) => s === "completed");
+}
+
+/**
+ * Extract an assistant message's text: string content as-is, or the text
+ * parts of a content array joined with newlines (tool-call parts are not
+ * text and are skipped). Same shape pi's own runtime uses. Null/undefined
+ * content (a run that produced no assistant text) yields "".
+ */
+export function assistantText(
+	content: string | Array<{ type?: string; text?: string }> | null | undefined,
+): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.flatMap((part) => (part && part.type === "text" && typeof part.text === "string" ? [part.text] : []))
+		.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-do-always",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"type": "module",
 	"description": "Pi extension: /do-always — pick a common task by number, it fills your prompt",
 	"author": {