pi-do-always 0.9.0 → 0.12.0

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

@@ -46,24 +46,26 @@ export interface DoAlwaysTask {
 	guards?: Guard[];
 }
 
+/** The set of known guard types (used for validation at parse time). */
+export const GUARD_TYPES = [
+	"requireDirty",
+	"requireBranch",
+	"requireRepo",
+	"requireFilePattern",
+] as const;
+
+export type GuardType = (typeof GUARD_TYPES)[number];
+
 /**
  * A selection-time guard that blocks a task when its condition is not met.
  * The task stays visible but selecting it notifies instead of injecting.
  * `requireDirty` needs no `value`; the others require a string `value`.
  */
 export interface Guard {
-	type: "requireDirty" | "requireBranch" | "requireRepo" | "requireFilePattern";
+	type: GuardType;
 	value?: string;
 }
 
-/** The set of known guard types (used for validation at parse time). */
-export const GUARD_TYPES = [
-	"requireDirty",
-	"requireBranch",
-	"requireRepo",
-	"requireFilePattern",
-] as const;
-
 /**
  * A config file can be a bare array of tasks, or {"tasks": [...], "shortcut": ...}.
  * `shortcut` is a key id string (e.g. "f4", "ctrl+shift+p"), or null to disable
@@ -72,19 +74,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 +103,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
@@ -159,7 +171,7 @@ export const PROMPT_CONTEXT_KEYS = [
 /** A fully populated prompt context: one entry per PROMPT_CONTEXT_KEYS. */
 export type PromptContext = Record<(typeof PROMPT_CONTEXT_KEYS)[number], string>;
 
-/** Max number of file paths listed in the `files_changed` string view (the count stays exact). */
+/** Max number of file paths listed in the `files_changed` string view (the count stays exact). Exported for tests. */
 export const MAX_FILES_LISTED = 20;
 
 /**
@@ -184,6 +196,9 @@ export function toPromptContext(ctx: TaskContext): PromptContext {
 	};
 }
 
+/** Max number of file paths listed in the `staged_files` / `unstaged_files` string views. Exported for tests. */
+export const MAX_FILE_LINES = 50;
+
 /** Comma-joined list, capped at MAX_FILES_LISTED entries; "none" when empty. */
 function formatFileList(files: string[]): string {
 	if (files.length === 0) return "none";
@@ -193,9 +208,31 @@ function formatFileList(files: string[]): string {
 	return files.join(", ");
 }
 
-/** Newline-joined list; "none" when empty. */
+/** Newline-joined list, capped at MAX_FILE_LINES entries; "none" when empty. */
 function formatFileLines(files: string[]): string {
-	return files.length === 0 ? "none" : files.join("\n");
+	if (files.length === 0) return "none";
+	if (files.length > MAX_FILE_LINES) {
+		const shown = files.slice(0, MAX_FILE_LINES);
+		const remaining = files.length - MAX_FILE_LINES;
+		return [...shown, `… (+${remaining} more)`].join("\n");
+	}
+	return files.join("\n");
+}
+
+/**
+ * Extract and normalize a file path from a git status porcelain line (v1).
+ * Handles rename targets (`old -> new`) and unquotes quoted paths (`"file with space"`).
+ */
+function extractPorcelainPath(line: string): string | null {
+	if (line.length < 4) return null;
+	let path = line.slice(3).trim();
+	if (path.includes(" -> ")) {
+		path = path.split(" -> ").pop()!.trim();
+	}
+	if (path.startsWith('"') && path.endsWith('"') && path.length >= 2) {
+		path = path.slice(1, -1).replace(/\\"/g, '"');
+	}
+	return path || null;
 }
 
 /**
@@ -205,19 +242,70 @@ function formatFileLines(files: string[]): string {
  */
 export function parseStatusPorcelain(status: string): string[] {
 	const files: string[] = [];
+	const seen = new Set<string>();
 	for (const line of status.split("\n")) {
-		if (line.length < 4) continue;
-		const path = line.slice(3);
-		if (path && !files.includes(path)) files.push(path);
+		const path = extractPorcelainPath(line);
+		if (path && !seen.has(path)) {
+			seen.add(path);
+			files.push(path);
+		}
 	}
-	files.sort();
+	files.sort((a, b) => a.localeCompare(b));
 	return files;
 }
 
-/** Split raw `git diff --name-only` output into file paths (trimmed, non-empty lines). */
-export function splitFileLines(raw: string | undefined): string[] {
-	if (!raw) return [];
-	return raw.split("\n").map((line) => line.trim()).filter(Boolean);
+/**
+ * Split `git status --porcelain` (v1) output into staged and unstaged file
+ * lists. Lines are "XY <path>" (X = index, Y = worktree; the path starts at
+ * index 3): a space in the X column means the change is unstaged (worktree
+ * only), anything else is staged or untracked. Short lines are skipped and
+ * paths are deduplicated across both lists.
+ */
+export function parseStatusStagedUnstaged(
+	status: string,
+): { staged: string[]; unstaged: string[] } {
+	const staged: string[] = [];
+	const unstaged: string[] = [];
+	const seen = new Set<string>();
+	for (const line of status.split("\n")) {
+		const path = extractPorcelainPath(line);
+		if (!path || seen.has(path)) continue;
+		seen.add(path);
+		if (line[0] === " ") unstaged.push(path);
+		else staged.push(path);
+	}
+	return { staged, unstaged };
+}
+
+/**
+ * Extract the commit subject from a `git log --format=%H %s` line
+ * ("<hash> <subject>"). The subject may contain spaces, so everything after
+ * the first space is the subject. Returns "unknown" when the line is missing
+ * or carries no subject.
+ */
+export function parseCommitSubject(commitLine: string | undefined): string {
+	if (!commitLine) return "unknown";
+	const space = commitLine.indexOf(" ");
+	return space > 0 ? commitLine.slice(space + 1) || "unknown" : "unknown";
+}
+
+/**
+ * Extract one key's value from `git config --get-regexp` output (one
+ * "key value" pair per line). The value may contain spaces (e.g.
+ * user.name "John Doe"), so everything after the first space is the value.
+ * Returns undefined when the key is absent or its value is empty.
+ */
+export function parseConfigRegexpValueForKey(
+	raw: string | undefined,
+	key: string,
+): string | undefined {
+	if (!raw) return undefined;
+	for (const line of raw.split("\n")) {
+		if (!line.startsWith(key + " ")) continue;
+		const value = line.slice(key.length + 1);
+		return value || undefined;
+	}
+	return undefined;
 }
 
 /** Used when neither config file defines any task. */
@@ -232,7 +320,7 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 			"Change summary: {{diff_stat}}. Last commit: {{last_commit}}. " +
 			"Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, " +
 			"edge cases, security issues, and consistency with the rest of the codebase. " +
-			"Do a plan proposal for the fixes if needed. Do a summary of your findings",
+			"Do a plan proposal for the fixes if needed. Do a summary of your findings.",
 	},
 	{
 		name: "Review code",
@@ -306,7 +394,7 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		category: "Plan",
 		description: "Propose new features (Plan)",
 		prompt:
-			"Review this project and propose new features that would add value. For each idea, describe the problem it solves, the user benefit, and a rough implementation approach. Prioritize by impact and effort. Do not make any changes yet. Try to evaluate how many lines this will be in term of changes, if this will breaks API, compatibility issue.",
+			"Review this project and propose new features that would add value. For each idea, describe the problem it solves, the user benefit, and a rough implementation approach. Prioritize by impact and effort. Do not make any changes yet. Try to evaluate how many lines this will be in terms of changes, whether this will break APIs, or introduce compatibility issues.",
 	},
 ];
 
@@ -326,14 +414,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 +472,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 +607,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;
 	}
@@ -567,11 +665,11 @@ export function evaluateWhen(task: DoAlwaysTask, ctx: TaskContext): boolean {
 	return true;
 }
 
-/** Default order for category headers in the selector. */
+/** Default order for category headers in the selector. Exported for tests. */
 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[];
 }
@@ -586,6 +684,11 @@ function titleCase(s: string): string {
  * `order` (case-insensitive), then alphabetically; the original order within a
  * group is preserved. The group `name` is the title-cased category. Tasks
  * without a (non-empty) category fall under "Other".
+ *
+ * Not memoized: every caller passes a fresh array (selector open, config
+ * load, list), so an identity-keyed cache would never hit — and would go
+ * stale if a caller ever mutated its array in place. The input is small
+ * (a dozen tasks), so recomputing is cheap.
  */
 export function groupTasksByCategory(
 	tasks: DoAlwaysTask[],
@@ -685,8 +788,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 +814,9 @@ function globToRegex(pattern: string): RegExp {
 			i++;
 		}
 	}
-	return new RegExp(`^${out}$`);
+	cached = new RegExp(`^${out}$`);
+	globRegexCache.set(pattern, cached);
+	return cached;
 }
 
 /**
@@ -789,3 +899,367 @@ 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 };
+}
+
+/**
+ * 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. Exported for tests. */
+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");
+}
+
+// ── Chain step summary ───────────────────────────────────────────────────
+//
+// Compact per-step and chain-end summary strings for notifications.
+// These are derived from the existing report data (outcome, timing, file count)
+// and provide immediate, scannable feedback after each chain step.
+
+/** Outcome of one chain step's run (see `sendAndWait`). */
+export type ChainStepOutcome = "completed" | "aborted" | "error" | "failed-to-start";
+
+/**
+ * Generate a compact per-step summary string for notifications.
+ * Examples:
+ *   "✓ Build — 3 files changed — 2m14s"
+ *   "✗ Tests — 45s"
+ *   "⊘ Review changes"
+ *
+ * @param outcome      the step outcome
+ * @param stepName     the task name
+ * @param durationMs   how long the step took (0 if not timed)
+ * @param fileCount    number of changed files after the step (0 if unknown)
+ * @returns the summary string
+ */
+export function stepSummary(
+	outcome: ChainStepOutcome,
+	stepName: string,
+	durationMs: number,
+	fileCount: number,
+): string {
+	const marker = outcomeToMarker(outcome);
+	const parts: string[] = [marker, stepName];
+	if (fileCount > 0) {
+		parts.push(`${fileCount} file${fileCount === 1 ? "" : "s"} changed`);
+	}
+	if (durationMs > 0) {
+		parts.push(formatDuration(durationMs));
+	}
+	// Only add " — " separator when there are parts beyond marker+name.
+	if (parts.length > 2) {
+		return `${marker} ${stepName} — ${parts.slice(2).join(" — ")}`;
+	}
+	return `${marker} ${stepName}`;
+}
+
+/**
+ * Generate a compact chain-end summary string, e.g.
+ * "✅ 4/4 steps completed in 6m42s". Only reachable when every step
+ * completed — the stop paths return early with their own per-step
+ * notification, so `completed` always equals `total` here.
+ */
+export function chainSummary(completed: number, total: number, totalMs: number): string {
+	const time = totalMs > 0 ? formatDuration(totalMs) : "";
+	return `✅ ${completed}/${total} steps completed${time ? ` in ${time}` : ""}`;
+}
+
+/** Format milliseconds to a human-readable duration string. Exported for tests. */
+export function formatDuration(ms: number): string {
+	if (ms < 1000) return `${ms}ms`;
+	const s = Math.floor(ms / 1000);
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	const rem = s % 60;
+	return rem > 0 ? `${m}m${rem}s` : `${m}m`;
+}
+
+/** Map a step outcome to its display marker character. */
+function outcomeToMarker(outcome: ChainStepOutcome): string {
+	switch (outcome) {
+		case "completed":
+			return "✓";
+		case "aborted":
+			return "⊘";
+		case "error":
+			return "✗";
+		case "failed-to-start":
+			return "✗";
+		default:
+			// Exhaustive check: the type is a literal union, so this is unreachable.
+			throw new Error(`unexpected outcome: ${outcome as string}`);
+	}
+}

package/package.json

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