pi-do-always 0.8.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,6 +101,49 @@ 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, resolve, sep } from "node:path";
+
+/**
+ * Structured facts about the working tree and git state, gathered once per
+ * use (see `buildContext` in index.ts). `when` conditions and guards are
+ * evaluated against this; `renderPrompt` consumes the derived string view
+ * from `toPromptContext`.
+ *
+ * Keeping the structured form here (instead of re-parsing the rendered
+ * strings) means guards see the complete file list — `files_changed` in the
+ * string view is capped for display, but `files` is never truncated.
+ */
+export interface TaskContext {
+	/** Absolute path of the working directory. */
+	cwd: string;
+	/** Local date, YYYY-MM-DD. */
+	date: string;
+	/** Current git branch, or "unknown" when unavailable. */
+	branch: string;
+	/** Subject of the latest commit, or "unknown" when unavailable. */
+	lastCommit: string;
+	/** All changed files (staged, unstaged, untracked), deduplicated and sorted. */
+	files: string[];
+	/** `git config user.name`, or "unknown" when unset. */
+	user: string;
+	/** Output of `git diff --shortstat`, or "none" when unavailable. */
+	diffStat: string;
+	/** Basename of the git remote (or cwd), to disambiguate monorepo work. */
+	repo: string;
+	/** Files staged for commit. */
+	stagedFiles: string[];
+	/** Modified-but-unstaged files. */
+	unstagedFiles: string[];
+	/** True when cwd is inside a git working tree (authoritative, not inferred from the branch name). */
+	isGitRepo: boolean;
 }
 
 /**
@@ -112,17 +160,75 @@ export const PROMPT_CONTEXT_KEYS = [
 	"files_changed",
 	"files_changed_count",
 	"user",
-	"diff_stat", // NEW: "3 files changed, 41 insertions(+), 7 deletions(-)"
-	"repo", // NEW: basename of cwd or git remote (disambiguates monorepos)
-	"staged_files", // NEW: files staged for commit
-	"unstaged_files", // NEW: modified-but-unstaged files
+	"diff_stat",
+	"repo",
+	"staged_files",
+	"unstaged_files",
 ] as const;
 
 /** A fully populated prompt context: one entry per PROMPT_CONTEXT_KEYS. */
 export type PromptContext = Record<(typeof PROMPT_CONTEXT_KEYS)[number], string>;
 
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+/** Max number of file paths listed in the `files_changed` string view (the count stays exact). */
+export const MAX_FILES_LISTED = 20;
+
+/**
+ * Derive the string view consumed by `renderPrompt` from a structured context.
+ * `files_changed` lists at most MAX_FILES_LISTED paths (with a "… (+N more)"
+ * suffix) and `files_changed_count` stays exact; `staged_files` and
+ * `unstaged_files` are newline-separated. Empty lists render as "none".
+ */
+export function toPromptContext(ctx: TaskContext): PromptContext {
+	return {
+		cwd: ctx.cwd,
+		date: ctx.date,
+		branch: ctx.branch,
+		last_commit: ctx.lastCommit,
+		files_changed: formatFileList(ctx.files),
+		files_changed_count: String(ctx.files.length),
+		user: ctx.user,
+		diff_stat: ctx.diffStat,
+		repo: ctx.repo,
+		staged_files: formatFileLines(ctx.stagedFiles),
+		unstaged_files: formatFileLines(ctx.unstagedFiles),
+	};
+}
+
+/** Comma-joined list, capped at MAX_FILES_LISTED entries; "none" when empty. */
+function formatFileList(files: string[]): string {
+	if (files.length === 0) return "none";
+	if (files.length > MAX_FILES_LISTED) {
+		return [...files.slice(0, MAX_FILES_LISTED), `… (+${files.length - MAX_FILES_LISTED} more)`].join(", ");
+	}
+	return files.join(", ");
+}
+
+/** Newline-joined list; "none" when empty. */
+function formatFileLines(files: string[]): string {
+	return files.length === 0 ? "none" : files.join("\n");
+}
+
+/**
+ * Parse `git status --porcelain` (v1) output into changed file paths. Lines
+ * are "XY <path>" (X = index, Y = worktree); short lines are skipped,
+ * duplicates removed, and the result sorted.
+ */
+export function parseStatusPorcelain(status: string): string[] {
+	const files: 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);
+	}
+	files.sort();
+	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);
+}
 
 /** Used when neither config file defines any task. */
 export const DEFAULT_TASKS: DoAlwaysTask[] = [
@@ -230,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[] = [];
@@ -288,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"]);
@@ -415,33 +526,29 @@ export function isValidWhen(when: unknown): boolean {
 	return true;
 }
 
-/**
- * True when the current directory is inside a git working tree. The `branch`
- * context falls back to "unknown" outside a repo (and on an empty repo), so a
- * non-"unknown" branch is the git-repo signal.
- */
-function isGitRepo(ctx: PromptContext): boolean {
-	return ctx.branch !== "unknown";
-}
-
 /** 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;
 	}
 }
 
 /**
- * Evaluate a single `when` object entry against the current prompt context.
+ * Evaluate a single `when` object entry against the current context.
  * Unknown keys are treated as no-ops (permissive) so a typo never hides a task
  * at runtime (parse time rejects them with a warning instead).
  */
-function evaluateWhenEntry(key: string, value: unknown, ctx: PromptContext): boolean {
+function evaluateWhenEntry(key: string, value: unknown, ctx: TaskContext): boolean {
 	switch (key) {
 		case "git":
-			return typeof value === "boolean" ? isGitRepo(ctx) === value : false;
+			return typeof value === "boolean" ? ctx.isGitRepo === value : false;
 		case "branch":
 			return typeof value === "string" && ctx.branch === value;
 		case "file":
@@ -462,13 +569,13 @@ function evaluateWhenEntry(key: string, value: unknown, ctx: PromptContext): boo
  * set of conditions that must all hold (logical AND): `git`, `branch`, `file`,
  * or `repo` (see the `DoAlwaysTask.when` field).
  */
-export function evaluateWhen(task: DoAlwaysTask, ctx: PromptContext): boolean {
+export function evaluateWhen(task: DoAlwaysTask, ctx: TaskContext): boolean {
 	const when = task.when;
 	if (when === undefined || when === null) return true;
 	if (typeof when === "string") {
 		const negated = when.startsWith("!");
 		const key = negated ? when.slice(1) : when;
-		if (key === "git") return negated ? !isGitRepo(ctx) : isGitRepo(ctx);
+		if (key === "git") return negated ? !ctx.isGitRepo : ctx.isGitRepo;
 		return true; // an invalid string condition is rejected at parse time
 	}
 	if (typeof when === "object") {
@@ -484,7 +591,7 @@ export function evaluateWhen(task: DoAlwaysTask, ctx: PromptContext): 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[];
 }
@@ -550,7 +657,7 @@ export function shouldAutoRun(task: DoAlwaysTask): boolean {
  * Guards keep low-value round-trips down: e.g. `requireDirty` blocks Review and
  * Commit on a clean tree so the agent is never asked to inspect nothing.
  */
-export function evaluateGuards(task: DoAlwaysTask, ctx: PromptContext): string | null {
+export function evaluateGuards(task: DoAlwaysTask, ctx: TaskContext): string | null {
 	// Legacy `requireDirty` is folded into the guard table so the set of guards
 	// is extensible without touching this function's callers.
 	const guards: Guard[] = [];
@@ -568,45 +675,43 @@ export function evaluateGuards(task: DoAlwaysTask, ctx: PromptContext): string |
  * when the guard passes. All guards are evaluated against the current prompt
  * context, so a task is only injected when every guard is met.
  */
-function guardFailureMessage(g: Guard, ctx: PromptContext): string | null {
+function guardFailureMessage(g: Guard, ctx: TaskContext): string | null {
 	switch (g.type) {
 		case "requireDirty":
-			return ctx.files_changed_count === "0" ? "working tree is clean — nothing to review" : null;
+			return ctx.files.length === 0 ? "working tree is clean — nothing to review" : null;
 		case "requireBranch":
 			return ctx.branch === g.value ? null : `not on branch "${g.value}" (currently ${ctx.branch})`;
 		case "requireRepo":
 			return ctx.repo === g.value ? null : `not in repo "${g.value}" (currently ${ctx.repo})`;
 		case "requireFilePattern":
-			return filesMatchPattern(ctx, g.value!) ? null : `no changed files match "${g.value}"`;
+			return filesMatchPattern(ctx.files, g.value!) ? null : `no changed files match "${g.value}"`;
 		default:
 			return null; // an unknown type is rejected at parse time
 	}
 }
 
-/**
- * The changed files for `ctx`, split on commas (matching how `files_changed`
- * is rendered). Empty on a clean tree or outside a git repo.
- */
-function changedFiles(ctx: PromptContext): string[] {
-	if (ctx.files_changed_count === "0" || ctx.files_changed === "none") return [];
-	return ctx.files_changed.split(",");
-}
-
 /**
  * Whether any changed file matches `pattern`, treated as a glob: `*` matches
  * within a path segment, `**` crosses segments, `?` matches one non-separator
- * character, and other regex metacharacters are literal.
+ * character, and other regex metacharacters are literal. Matches against the
+ * complete file list (never the capped display string), so files beyond
+ * MAX_FILES_LISTED are still considered.
  */
-function filesMatchPattern(ctx: PromptContext, pattern: string): boolean {
+function filesMatchPattern(files: string[], pattern: string): boolean {
 	const re = globToRegex(pattern);
-	return changedFiles(ctx).some((f) => re.test(f.trim()));
+	return files.some((f) => re.test(f));
 }
 
 /** 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) {
@@ -626,7 +731,9 @@ function globToRegex(pattern: string): RegExp {
 			i++;
 		}
 	}
-	return new RegExp(`^${out}$`);
+	cached = new RegExp(`^${out}$`);
+	globRegexCache.set(pattern, cached);
+	return cached;
 }
 
 /**
@@ -709,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.8.0",
+	"version": "0.10.0",
 	"type": "module",
 	"description": "Pi extension: /do-always — pick a common task by number, it fills your prompt",
 	"author": {
@@ -23,7 +23,7 @@
 	},
 	"homepage": "https://github.com/aginies/pi-do-always",
 	"bugs": {
-		"url": "https://github.com/aginies/pi-do-always/issues"
+		"url": "git+https://github.com/aginies/pi-do-always/issues"
 	},
 	"files": [
 		"extensions/pi-do-always/index.ts",