pi-soly 0.2.1

package/workflows/quick.ts

@@ -0,0 +1,258 @@
+// =============================================================================
+// workflows/quick.ts — Direct-response workflow handlers
+// =============================================================================
+//
+// These verbs (status, log, diff) return immediate results without an LLM
+// round-trip. The extension reads disk / runs git, formats a notification,
+// and the LLM never sees the request.
+//
+// Why: these are common, low-judgment operations where the LLM would just
+// regurgitate what the extension can compute more accurately and faster.
+// =============================================================================
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readIfExists, buildProgressBar, type SolyState } from "../core.js";
+import type { SolyConfig } from "../config.js";
+import type { SolyCommand } from "./parser.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Minimum UI surface needed for the quick handlers. */
+interface QuickUI {
+	notify: (text: string, kind?: "info" | "warning" | "error") => void;
+}
+
+// =============================================================================
+// soly status
+// =============================================================================
+
+export function showStatus(
+	_cmd: SolyCommand,
+	state: SolyState,
+	ui: QuickUI,
+	config?: SolyConfig,
+): void {
+	if (!state.exists) {
+		ui.notify("soly: no .soly/ directory in cwd", "error");
+		return;
+	}
+	const maxPhases = config?.display.maxPhasesInStatus ?? 20;
+
+	const lines: string[] = [];
+	lines.push("=== soly status ===");
+	lines.push("");
+	lines.push(
+		`milestone: ${state.milestone}${state.milestoneName ? ` — ${state.milestoneName}` : ""}`,
+	);
+	lines.push(`status:    ${state.status}`);
+	if (state.lastUpdated) lines.push(`updated:   ${state.lastUpdated}`);
+	lines.push("");
+
+	if (state.position) {
+		lines.push(`position:`);
+		lines.push(`  phase:  ${state.position.phase}`);
+		lines.push(`  plan:   ${state.position.plan}`);
+		lines.push(`  status: ${state.position.status}`);
+	} else {
+		lines.push("position: (none — run `soly plan <N>` to start a phase)");
+	}
+	lines.push("");
+
+	lines.push(
+		`progress:  ${buildProgressBar(state.progress.percent, 30)} ${state.progress.percent}%`,
+	);
+	lines.push(`           ${state.progress.completedPhases}/${state.progress.totalPhases} phases, ${state.progress.completedPlans}/${state.progress.totalPlans} plans`);
+	lines.push("");
+
+	if (state.phases.length > 0) {
+		lines.push("phases:");
+		const current = state.currentPhase?.number;
+		for (const p of state.phases.slice(0, maxPhases)) {
+			const marker = current === p.number ? "→" : " ";
+			const cr = (p.contextExists ? "C" : "·") + (p.researchExists ? "R" : "·");
+			lines.push(
+				`  ${marker} ${String(p.number).padStart(2, "0")}. ${p.name.padEnd(28)} [${cr}] plans=${p.planCount}`,
+			);
+		}
+		if (state.phases.length > maxPhases) {
+			lines.push(`  ... and ${state.phases.length - maxPhases} more (use config.display.maxPhasesInStatus to show more)`);
+		}
+	}
+
+	// NEW (A7): recent activity — last 3 iteration files
+	const iterDir = path.join(state.solyDir, "iterations");
+	if (fs.existsSync(iterDir)) {
+		const files = fs.readdirSync(iterDir)
+			.filter((f) => f.endsWith(".md"))
+			.map((f) => ({ f, stat: fs.statSync(path.join(iterDir, f)) }))
+			.sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs)
+			.slice(0, 3);
+		if (files.length > 0) {
+			lines.push("");
+			lines.push("recent iterations:");
+			for (const { f, stat } of files) {
+				const ago = humanizeAge(Date.now() - stat.mtimeMs);
+				lines.push(`  ${f}  (${ago})`);
+			}
+		}
+	}
+
+	ui.notify(lines.join("\n"), "info");
+}
+
+// =============================================================================
+// soly log
+// =============================================================================
+
+function humanizeAge(ms: number): string {
+	if (ms < 60_000) return "just now";
+	if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m ago`;
+	if (ms < 86_400_000) return `${Math.round(ms / 3_600_000)}h ago`;
+	if (ms < 30 * 86_400_000) return `${Math.round(ms / 86_400_000)}d ago`;
+	return `${Math.round(ms / (30 * 86_400_000))}mo ago`;
+}
+
+const DECISIONS_HEADER = /^##\s*Decisions\s*$/;
+const DECISIONS_TABLE_HEADER = /^\|\s*Decision\s*\|/;
+const DECISIONS_TABLE_SEPARATOR = /^\|[\s\-:|]+\|$/;
+const DECISIONS_TABLE_ROW = /^\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|\s*$/;
+
+export function showLog(cmd: SolyCommand, state: SolyState, ui: QuickUI): void {
+	if (!state.exists) {
+		ui.notify("soly log: no .soly/ directory in cwd", "error");
+		return;
+	}
+
+	const statePath = path.join(state.solyDir, "STATE.md");
+	const raw = readIfExists(statePath);
+	if (!raw) {
+		ui.notify("soly log: STATE.md not found", "error");
+		return;
+	}
+
+	const lines = raw.split(/\r?\n/);
+	const decisionsIdx = lines.findIndex((l) => DECISIONS_HEADER.test(l));
+	if (decisionsIdx === -1) {
+		ui.notify("soly log: no Decisions table in STATE.md", "info");
+		return;
+	}
+
+	// Collect rows from the table
+	const rows: Array<{ decision: string; rationale: string; phase: string }> = [];
+	for (let i = decisionsIdx + 1; i < lines.length; i++) {
+		const line = lines[i];
+		if (!line.startsWith("|")) break; // table ended
+		if (DECISIONS_TABLE_HEADER.test(line) || DECISIONS_TABLE_SEPARATOR.test(line)) continue;
+		const m = line.match(DECISIONS_TABLE_ROW);
+		if (m) rows.push({ decision: m[1].trim(), rationale: m[2].trim(), phase: m[3].trim() });
+	}
+
+	if (rows.length === 0) {
+		ui.notify("soly log: Decisions table is empty", "info");
+		return;
+	}
+
+	// Optional limit: `soly log 5` — last 5 decisions
+	const limitArg = cmd.args[0]?.trim();
+	if (limitArg) {
+		const parsed = parseInt(limitArg, 10);
+		if (!Number.isFinite(parsed) || parsed <= 0) {
+			ui.notify(
+				`soly log: invalid limit "${limitArg}" (must be a positive integer)`,
+				"error",
+			);
+			return;
+		}
+	}
+	const limit = limitArg ? parseInt(limitArg, 10) : 20;
+	const tail = Number.isFinite(limit) && limit > 0 ? rows.slice(-limit) : rows.slice(-20);
+
+	const out: string[] = [];
+	out.push(`=== last ${tail.length} of ${rows.length} decisions ===`);
+	out.push("");
+	for (const r of tail) {
+		out.push(`  [${r.phase}] ${r.decision}`);
+		out.push(`           ${r.rationale}`);
+		out.push("");
+	}
+	ui.notify(out.join("\n"), "info");
+}
+
+// =============================================================================
+// soly diff
+// =============================================================================
+
+interface DiffResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+}
+
+async function safeExec(file: string, args: string[], cwd: string): Promise<DiffResult> {
+	try {
+		const { stdout, stderr } = await execFileAsync(file, args, {
+			cwd,
+			maxBuffer: 4 * 1024 * 1024,
+			encoding: "utf-8",
+		});
+		return { stdout, stderr, code: 0 };
+	} catch (e) {
+		const err = e as { stdout?: string; stderr?: string; code?: number };
+		return {
+			stdout: err.stdout ?? "",
+			stderr: err.stderr ?? "",
+			code: typeof err.code === "number" ? err.code : 1,
+		};
+	}
+}
+
+export async function showDiff(
+	_cmd: SolyCommand,
+	state: SolyState,
+	ui: QuickUI,
+): Promise<void> {
+	// Graceful without .soly/: use cwd as project root, skip the .soly/ filter
+	const projectRoot = state.solyDir ? path.dirname(state.solyDir) : process.cwd();
+	const solyDir = state.solyDir; // may be empty when run outside a soly project
+
+	// 1. git status (short)
+	const status = await safeExec("git", ["status", "--short", "--branch"], projectRoot);
+	// 2. git diff (tracked changes, no untracked)
+	const diff = await safeExec("git", ["diff", "--stat"], projectRoot);
+	// 3. uncommitted .soly/ file changes (since last commit)
+	const solyChanges = await safeExec(
+		"git",
+		["status", "--short", "--", solyDir],
+		projectRoot,
+	);
+
+	const out: string[] = [];
+	out.push(state.exists ? "=== soly diff ===" : "=== git diff (no .soly/ in cwd) ===");
+	out.push("");
+
+	if (status.code !== 0) {
+		out.push("(git not available or not a git repo)");
+	} else {
+		out.push("git status --short --branch:");
+		out.push(status.stdout.trim() || "  (clean working tree)");
+		out.push("");
+		if (diff.stdout.trim()) {
+			out.push("git diff --stat:");
+			out.push(diff.stdout.trim());
+			out.push("");
+		}
+		if (solyDir) {
+			if (solyChanges.stdout.trim()) {
+				out.push("uncommitted .soly/ changes:");
+				out.push(solyChanges.stdout.trim());
+			} else {
+				out.push("uncommitted .soly/ changes: (none)");
+			}
+		}
+	}
+
+	ui.notify(out.join("\n"), "info");
+}

package/workflows/resume.ts

@@ -0,0 +1,201 @@
+// =============================================================================
+// workflows/resume.ts — `soly resume [phase]` handler
+// =============================================================================
+//
+// Intercepts "soly resume" (or "soly resume <N>" to scope to a specific phase)
+// and transforms it into a kickoff prompt that re-establishes the full
+// session context from the last handoff.
+//
+// Reads:
+//   - .soly/HANDOFF.json       (machine-readable state, written by pause/compact)
+//   - .soly/.continue-here.md  (human-readable context, written by pause/compact)
+//
+// If neither file exists, falls back to a "no prior handoff" message that
+// tells the LLM to load context from .soly/STATE.md + ROADMAP.md normally.
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { SolyCommand } from "./parser.js";
+import type { SolyState } from "../core.js";
+import { readIfExists } from "../core.js";
+
+interface HandoffJson {
+	schema_version?: string;
+	generated_at?: string;
+	milestone?: string;
+	milestone_name?: string;
+	status?: string;
+	position?: { phase?: string; plan?: string; status?: string } | null;
+	current_phase?: {
+		number?: number;
+		name?: string;
+		slug?: string;
+		dir?: string;
+		plan_count?: number;
+	} | null;
+	progress?: {
+		total_phases?: number;
+		completed_phases?: number;
+		total_plans?: number;
+		completed_plans?: number;
+		percent?: number;
+	};
+	work_completed?: string[];
+	work_remaining?: string[];
+	decisions?: string[];
+	blockers?: string[];
+	human_actions_pending?: string[];
+}
+
+export interface ResumeHandlerResult {
+	handled: boolean;
+	transformedText?: string;
+}
+
+function parseHandoff(solyDir: string): HandoffJson | null {
+	const handoffPath = path.join(solyDir, "HANDOFF.json");
+	const raw = readIfExists(handoffPath);
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		return parsed as HandoffJson;
+	} catch {
+		return null;
+	}
+}
+
+function formatListSection(label: string, items: string[] | undefined): string {
+	if (!items || items.length === 0) return `  (none)\n`;
+	return `  - ${items.join("\n  - ")}\n`;
+}
+
+function formatHandoffSummary(h: HandoffJson): string {
+	const lines: string[] = [];
+
+	lines.push("=== From .soly/HANDOFF.json ===");
+	if (h.generated_at) lines.push(`  generated_at: ${h.generated_at}`);
+	if (h.milestone) lines.push(`  milestone: ${h.milestone}${h.milestone_name ? ` — ${h.milestone_name}` : ""}`);
+	if (h.status) lines.push(`  status: ${h.status}`);
+
+	if (h.position) {
+		lines.push(`  position: phase=${h.position.phase ?? "?"}, plan=${h.position.plan ?? "?"}, status=${h.position.status ?? "?"}`);
+	}
+	if (h.current_phase) {
+		lines.push(
+			`  current_phase: #${h.current_phase.number ?? "?"} ${h.current_phase.name ?? ""} (${h.current_phase.plan_count ?? 0} plans)`,
+		);
+	}
+	if (h.progress) {
+		lines.push(
+			`  progress: ${h.progress.completed_phases ?? 0}/${h.progress.total_phases ?? 0} phases, ${h.progress.completed_plans ?? 0}/${h.progress.total_plans ?? 0} plans, ${h.progress.percent ?? 0}%`,
+		);
+	}
+
+	lines.push("");
+	lines.push("Work completed (from last session):");
+	lines.push(formatListSection("", h.work_completed));
+	lines.push("Work remaining:");
+	lines.push(formatListSection("", h.work_remaining));
+	lines.push("Decisions logged:");
+	lines.push(formatListSection("", h.decisions));
+	lines.push("Blockers / open questions:");
+	lines.push(formatListSection("", h.blockers));
+	lines.push("Human actions pending:");
+	lines.push(formatListSection("", h.human_actions_pending));
+
+	return lines.join("\n");
+}
+
+export function buildResumeTransform(cmd: SolyCommand, state: SolyState): ResumeHandlerResult {
+	if (!state.exists) {
+		return {
+			handled: true,
+			transformedText:
+				`soly resume: no .soly/ directory in cwd (${state.solyDir || "<cwd>"}) — nothing to resume.\n` +
+				`Initialize a soly project first, or run \`soly pause\` later to create handoff files.`,
+		};
+	}
+
+	const handoff = parseHandoff(state.solyDir);
+	const continueMd = readIfExists(path.join(state.solyDir, ".continue-here.md"));
+
+	// Optional phase scope: "soly resume 11" → focus kickoff on phase 11
+	const phaseArg = cmd.args[0]?.trim();
+	let phaseFilter: number | null = null;
+	let phaseFilterInvalid = false;
+	if (phaseArg) {
+		const m = phaseArg.match(/^(\d+)$/);
+		if (m) {
+			phaseFilter = parseInt(m[1], 10);
+			// Validate that the phase actually exists
+			if (state.phases.length > 0 && !state.phases.find((p) => p.number === phaseFilter)) {
+				phaseFilterInvalid = true;
+			}
+		} else {
+			phaseFilterInvalid = true;
+		}
+	}
+	if (phaseFilterInvalid) {
+		const known = state.phases.map((p) => p.number).join(", ") || "(none)";
+		const argStr = cmd.args[0] ?? "";
+		return {
+			handled: true,
+			transformedText:
+				`soly resume: invalid or unknown phase "${argStr}".\n` +
+				`Usage: soly resume [N]    (e.g. "soly resume 5")\n` +
+				`Known phases: ${known}`,
+		};
+	}
+
+	if (!handoff && !continueMd) {
+		// No prior handoff — fall back to loading from .soly/STATE.md directly.
+		const fallbackScope = phaseFilter != null
+			? `Focus: phase ${phaseFilter}.`
+			: "Scope: full project.";
+		return {
+			handled: true,
+			transformedText:
+				`soly resume: no handoff files found (looked for .soly/HANDOFF.json and .soly/.continue-here.md).\n` +
+				`No prior \`soly pause\` was run — loading context from .soly/STATE.md and .soly/ROADMAP.md directly.\n\n` +
+				`${fallbackScope}\n\n` +
+				`Read .soly/STATE.md (Current Position, Decisions, Blockers sections) and .soly/ROADMAP.md.\n` +
+				`Summarize: where the project is, what's next, what's blocking. Then ask the user what to focus on first.`,
+		};
+	}
+
+	const handoffBlock = handoff ? formatHandoffSummary(handoff) : "(no HANDOFF.json found)";
+	const continueBlock = continueMd
+		? `\n=== From .soly/.continue-here.md ===\n${continueMd.trim()}\n`
+		: "";
+
+	const focusLine = phaseFilter != null
+		? `Focus: phase ${phaseFilter} only.`
+		: "Focus: pick up exactly where the last session left off.";
+
+	const instruction = `soly resume — restoring session context from last handoff.
+
+${focusLine}
+
+${handoffBlock}
+${continueBlock}
+
+=== Resume protocol ===
+
+1. **Read .soly/docs/ first** — the project's 0-point intent. Pickup is meaningless without knowing what the user is building toward.
+2. Read .soly/STATE.md to confirm current position (the handoff may be stale).
+3. Read .soly/ROADMAP.md and any CONTEXT.md / RESEARCH.md for the active phase.
+4. Compare handoff's "work remaining" with the actual repo state (git status, recent commits, .soly/ files).
+5. Produce a one-screen "Where we are" summary:
+   - current phase + plan
+   - what's actually been done (verified via filesystem / git)
+   - what's still pending
+   - any new blockers discovered since handoff
+6. Surface any stale handoff data — if the handoff says "remaining: X" but the repo shows X is done, say so.
+7. Ask the user: "Pick up from <next concrete step> — confirm or change?" before doing any work.
+
+Do NOT start coding. Resume is about restoring shared understanding, not action.
+`;
+
+	return { handled: true, transformedText: instruction };
+}