stonecut 1.2.1 → 1.4.0

package/src/execute.ts

@@ -0,0 +1,159 @@
+/**
+ * Execution orchestration — non-interactive, prompt-free.
+ *
+ * executeLocal: set up session, checkout branch, run loop, push/PR.
+ * pushAndMaybePr: push branch and conditionally create PR.
+ * buildReport: format iteration results for PR body.
+ *
+ * This module never imports @clack/prompts — the interactive/execution
+ * boundary is enforced by module structure.
+ */
+
+import { checkoutOrCreateBranch, createPr, pushBranch } from "./git";
+import { LocalSource } from "./local";
+import { slugifyBranchComponent } from "./naming";
+import { renderLocal } from "./prompt";
+import { Logger } from "./logger";
+import { defaultGitOps, formatTokens, runAfkLoop } from "./runner";
+import { getRunner } from "./runners/index";
+import type { Issue, IterationResult, Session } from "./types";
+
+// ---------------------------------------------------------------------------
+// Stonecut report
+// ---------------------------------------------------------------------------
+
+/** Build the metrics parenthetical for a report line. */
+function formatMetrics(r: IterationResult): string {
+	const parts: string[] = [];
+	if (r.turns != null) {
+		parts.push(`${r.turns} turns`);
+	}
+	const totalTokens =
+		r.inputTokens != null || r.outputTokens != null
+			? (r.inputTokens ?? 0) + (r.outputTokens ?? 0)
+			: undefined;
+	if (totalTokens != null) {
+		parts.push(`${formatTokens(totalTokens)} tokens`);
+	}
+	return parts.length > 0 ? ` (${parts.join(", ")})` : "";
+}
+
+/**
+ * Build the Stonecut Report section for a PR body.
+ */
+export function buildReport(
+	results: IterationResult[],
+	runnerName: string,
+	closingRefs?: string[],
+): string {
+	const lines = ["## Stonecut Report", `**Runner:** ${runnerName}`, ""];
+	for (const r of results) {
+		const metrics = formatMetrics(r);
+		if (r.success) {
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: completed${metrics}`);
+		} else {
+			const reason = r.error || "unknown error";
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: failed — ${reason}${metrics}`);
+		}
+	}
+
+	if (closingRefs && closingRefs.length > 0) {
+		lines.push("");
+		lines.push(closingRefs.join("\n"));
+	}
+
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Post-loop: push and conditionally create PR
+// ---------------------------------------------------------------------------
+
+export async function pushAndMaybePr(
+	results: IterationResult[],
+	source: {
+		getRemainingCount(): Promise<[number, number]>;
+		getClosingRefs?(completedIssueNumbers: number[]): string[];
+	},
+	branch: string,
+	baseBranch: string,
+	prTitle: string,
+	runnerName: string,
+	logger: { log(message: string): void },
+): Promise<void> {
+	if (!results.some((r) => r.success)) {
+		return;
+	}
+
+	pushBranch(branch);
+	logger.log(`Pushed branch '${branch}'.`);
+
+	const [remaining, total] = await source.getRemainingCount();
+	if (remaining === 0) {
+		const completed = results.filter((r) => r.success).map((r) => r.issueNumber);
+		const closingRefs = source.getClosingRefs?.(completed);
+		const body = buildReport(results, runnerName, closingRefs);
+		createPr(prTitle, body, baseBranch);
+		logger.log("Created PR.");
+	} else {
+		logger.log(`${remaining}/${total} issues remaining — PR deferred.`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execution orchestration
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a local PRD run — non-interactive orchestration.
+ *
+ * All parameters are explicit: no interactive prompts, no @clack/prompts.
+ * Handles branch checkout, runner session, loop, push, and PR creation.
+ */
+export async function executeLocal(
+	name: string,
+	branch: string,
+	baseBranch: string,
+	iterations: number | "all",
+	runnerName: string,
+): Promise<void> {
+	const source = new LocalSource(name);
+	const prdIdentifier = slugifyBranchComponent(name) || "spec";
+	const logger = new Logger(prdIdentifier);
+	const runner = getRunner(runnerName, logger);
+
+	const session: Session = { logger, git: defaultGitOps, runner, runnerName };
+
+	try {
+		checkoutOrCreateBranch(branch);
+		console.log("");
+
+		const prdContent = await source.getPrdContent();
+		const results = await runAfkLoop<Issue>(
+			source,
+			iterations,
+			(issue) =>
+				renderLocal({
+					prdContent,
+					issueNumber: issue.number,
+					issueFilename: issue.filename,
+					issueContent: issue.content,
+				}),
+			(issue) => issue.filename,
+			(issue) => `Issue ${issue.number}: ${issue.filename}`,
+			session,
+		);
+
+		await pushAndMaybePr(
+			results,
+			source,
+			branch,
+			baseBranch,
+			`Stonecut: ${name}`,
+			runnerName,
+			logger,
+		);
+	} finally {
+		logger.close();
+	}
+}

package/src/git.ts

@@ -5,28 +5,9 @@
  * All functions throw on failure. No process.exit, no console output.
  */
 
+import { runSync } from "./spawn";
 import type { WorkingTreeSnapshot } from "./types";
 
-/**
- * Run a command synchronously, optionally in a specific working directory.
- * When cwd is omitted, uses the current process working directory.
- */
-function runSync(
-	cmd: string[],
-	cwd?: string,
-): { exitCode: number; stdout: string; stderr: string } {
-	const proc = Bun.spawnSync(cmd, {
-		stdout: "pipe",
-		stderr: "pipe",
-		...(cwd && { cwd }),
-	});
-	return {
-		exitCode: proc.exitCode,
-		stdout: proc.stdout.toString(),
-		stderr: proc.stderr.toString(),
-	};
-}
-
 /** Detect the remote's default branch, falling back to "main". */
 export function defaultBranch(cwd?: string): string {
 	const result = runSync(["git", "symbolic-ref", "refs/remotes/origin/HEAD"], cwd);

package/src/import.ts

@@ -37,7 +37,7 @@ export async function importSpec(options: ImportOptions): Promise<ImportResult>
 		throw new Error("Could not derive a spec name from the PRD title. Use --name to specify one.");
 	}
 
-	const specDir = join(".stonecut", "prd", specName);
+	const specDir = join(".stonecut", "specs", specName);
 
 	if (existsSync(specDir)) {
 		if (!options.force) {

package/src/local.ts

@@ -1,4 +1,4 @@
-/** Local spec source — reads issues from .stonecut/prd/<name>/. */
+/** Local spec source — reads issues from .stonecut/specs/<name>/. */
 
 import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, statSync } from "fs";
 import { join } from "path";
@@ -11,7 +11,7 @@ export class LocalSource implements Source<Issue> {
 
 	constructor(name: string) {
 		this.name = name;
-		this.specDir = join(".stonecut", "prd", name);
+		this.specDir = join(".stonecut", "specs", name);
 		this.validate();
 	}
 
@@ -86,6 +86,32 @@ export class LocalSource implements Source<Issue> {
 		return null;
 	}
 
+	getClosingRefs(completedIssueNumbers: number[]): string[] {
+		const completed = new Set(completedIssueNumbers);
+		const refs: string[] = [];
+		const all = this.allIssues();
+
+		for (const issue of all) {
+			if (!completed.has(issue.number)) continue;
+			const raw = readFileSync(issue.path, "utf-8");
+			const num = parseInt(parseFrontmatter(raw).meta.issue, 10);
+			if (num && !isNaN(num)) {
+				refs.push(`Closes #${num}`);
+			}
+		}
+
+		const allComplete = all.every((i) => completed.has(i.number));
+		if (allComplete) {
+			const raw = readFileSync(join(this.specDir, "prd.md"), "utf-8");
+			const num = parseInt(parseFrontmatter(raw).meta.issue, 10);
+			if (num && !isNaN(num)) {
+				refs.push(`Closes #${num}`);
+			}
+		}
+
+		return refs;
+	}
+
 	async getRemainingCount(): Promise<[number, number]> {
 		const completed = this.readStatus();
 		const all = this.allIssues();

package/src/logger.ts

@@ -29,6 +29,10 @@ export class Logger implements LogWriter {
 
 	log(message: string): void {
 		console.log(message);
+		this.logFile(message);
+	}
+
+	logFile(message: string): void {
 		const ts = new Date().toISOString();
 		const fileWasMissing = !existsSync(this.filePath);
 		try {

package/src/prd.ts

@@ -0,0 +1,136 @@
+/**
+ * PRD selection UI — filesystem scanning, interactive picker, and inline
+ * GitHub import flow.
+ *
+ * This is the only extracted module that imports @clack/prompts, as it is
+ * part of the interactive UI layer.
+ */
+
+import * as clack from "@clack/prompts";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { importSpec } from "./import";
+import { getSourceProvider } from "./sources/index";
+
+/** A locally available PRD with its completion status. */
+export interface LocalPrdEntry {
+	name: string;
+	completed: number;
+	total: number;
+}
+
+/**
+ * Scan .stonecut subdirectories for directories containing prd.md and compute
+ * completion counts from status.json.
+ */
+export function scanLocalPrds(baseDir: string = ".stonecut/specs"): LocalPrdEntry[] {
+	if (!existsSync(baseDir)) return [];
+
+	const entries: LocalPrdEntry[] = [];
+	for (const name of readdirSync(baseDir)) {
+		const specDir = join(baseDir, name);
+		if (!statSync(specDir).isDirectory()) continue;
+		if (!existsSync(join(specDir, "prd.md"))) continue;
+
+		const issuesDir = join(specDir, "issues");
+		let total = 0;
+		if (existsSync(issuesDir) && statSync(issuesDir).isDirectory()) {
+			total = readdirSync(issuesDir).filter((f) => f.endsWith(".md")).length;
+		}
+
+		let completed = 0;
+		const statusPath = join(specDir, "status.json");
+		if (existsSync(statusPath)) {
+			try {
+				const data = JSON.parse(readFileSync(statusPath, "utf-8"));
+				completed = Array.isArray(data.completed) ? data.completed.length : 0;
+			} catch {
+				// Malformed status.json — treat as 0 completed
+			}
+		}
+
+		entries.push({ name, completed, total });
+	}
+	return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Format a PRD entry for display in the wizard.
+ */
+export function formatPrdOption(entry: LocalPrdEntry): string {
+	if (entry.total === 0) return `${entry.name} (no issues)`;
+	if (entry.completed === 0) return `${entry.name} (not started)`;
+	return `${entry.name} (${entry.completed}/${entry.total} done)`;
+}
+
+/** Sentinel value for the "Import from GitHub" wizard option. */
+const IMPORT_FROM_GITHUB = "__import_from_github__";
+
+/**
+ * Prompt the user to select a local PRD or import from GitHub.
+ * Returns the local spec name to run.
+ */
+export async function promptForPrd(): Promise<{ kind: "local"; name: string }> {
+	const prds = scanLocalPrds();
+
+	const options: Array<{ value: string; label: string }> = prds.map((entry) => ({
+		value: entry.name,
+		label: formatPrdOption(entry),
+	}));
+	options.push({ value: IMPORT_FROM_GITHUB, label: "Import from GitHub" });
+
+	const selection = await clack.select({
+		message: "Select a PRD:",
+		options,
+	});
+
+	if (clack.isCancel(selection)) {
+		throw new Error("Cancelled.");
+	}
+
+	if (selection === IMPORT_FROM_GITHUB) {
+		const specName = await inlineGitHubImport();
+		return { kind: "local", name: specName };
+	}
+
+	return { kind: "local", name: selection as string };
+}
+
+/**
+ * Inline GitHub import flow within the wizard.
+ * Lists PRDs by `prd` label, user picks one, import runs.
+ * Returns the imported spec name.
+ */
+async function inlineGitHubImport(): Promise<string> {
+	const provider = getSourceProvider("github");
+	const prdList = await provider.listPrds();
+
+	if (prdList.length === 0) {
+		throw new Error("No open PRDs with the 'prd' label found on GitHub.");
+	}
+
+	const prdOptions = prdList.map((p) => ({
+		value: String(p.number),
+		label: `#${p.number}: ${p.title}`,
+	}));
+
+	const selected = await clack.select({
+		message: "Select a GitHub PRD to import:",
+		options: prdOptions,
+	});
+
+	if (clack.isCancel(selected)) {
+		throw new Error("Cancelled.");
+	}
+
+	const result = await importSpec({
+		provider: "github",
+		identifier: selected as string,
+	});
+
+	console.log(
+		`Imported PRD #${result.prdIssueNumber} → ${result.specDir}/ (${result.issueCount} issues)`,
+	);
+
+	return result.specName;
+}

package/src/runner.ts

@@ -1,11 +1,12 @@
 /**
- * Runner — commit flow, orchestration loop, and session helpers.
+ * Runner — orchestration loop, commit flow, and session helpers.
  *
  * verifyAndFix: single check → fix cycle.
  * commitIssue: stage, commit, retry on failure up to maxRetries times.
  * runAfkLoop: main orchestration loop over issues from any source.
  * fmtTime / printSummary: session output formatting.
  *
+ * Sync-back logic lives in sync-back.ts.
  * Modules throw on failure. No process.exit, no console output.
  */
 
@@ -15,9 +16,8 @@ import {
 	snapshotWorkingTree as realSnapshotWorkingTree,
 	stageChanges as realStageChanges,
 } from "./git";
-import { readFileSync } from "fs";
-import { parseFrontmatter } from "./frontmatter";
-import { getSourceProvider } from "./sources/index";
+import { syncBackIssue, syncBackPrd } from "./sync-back";
+import type { SyncBackConfig } from "./sync-back";
 import type {
 	GitOps,
 	IterationResult,
@@ -39,84 +39,10 @@ export const defaultGitOps: GitOps = {
 /** Console-only logger for backward compatibility. */
 export const consoleLogger: LogWriter = {
 	log: (message: string) => console.log(message),
+	logFile: () => {},
 	close: () => {},
 };
 
-/**
- * Configuration for syncing issue/PRD completion back to an external source.
- *
- * When provided to runAfkLoop, the runner reads frontmatter from completed
- * issue files. If a `source` field is present, the corresponding provider
- * is resolved and notified of the completion.
- */
-export interface SyncBackConfig<T> {
-	/** Return the file path for a completed issue, or undefined to skip sync-back. */
-	getIssuePath: (issue: T) => string | undefined;
-	/** Path to the PRD file, used for sync-back after all issues complete. */
-	prdPath?: string;
-	/** Read a file's contents. Injectable for testing; defaults to fs.readFileSync. */
-	readFile?: (path: string) => string;
-	/** Resolve a source provider by name. Injectable for testing; defaults to getSourceProvider. */
-	resolveProvider?: (name: string) => {
-		onIssueComplete(id: string): Promise<void>;
-		onPrdComplete(id: string): Promise<void>;
-	};
-}
-
-/**
- * Sync a completed issue back to its external source.
- *
- * Reads frontmatter from the issue file. If `source` and `issue` fields
- * are present, resolves the provider and calls onIssueComplete.
- * Failures are logged as warnings but never thrown.
- */
-export async function syncBackIssue(
-	filePath: string,
-	logger: LogWriter,
-	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
-	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
-): Promise<void> {
-	try {
-		const content = readFile(filePath);
-		const { meta } = parseFrontmatter(content);
-		if (!meta.source || !meta.issue) return;
-
-		const provider = resolveProvider!(meta.source);
-		await provider.onIssueComplete(meta.issue);
-		logger.log(`Synced issue #${meta.issue} back to ${meta.source}`);
-	} catch (err: unknown) {
-		const message = err instanceof Error ? err.message : String(err);
-		logger.log(`Warning: sync-back failed for issue at ${filePath}: ${message}`);
-	}
-}
-
-/**
- * Sync PRD completion back to its external source.
- *
- * Reads frontmatter from the PRD file. If `source` and `issue` fields
- * are present, resolves the provider and calls onPrdComplete.
- * Failures are logged as warnings but never thrown.
- */
-export async function syncBackPrd(
-	filePath: string,
-	logger: LogWriter,
-	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
-	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
-): Promise<void> {
-	try {
-		const content = readFile(filePath);
-		const { meta } = parseFrontmatter(content);
-		if (!meta.source || !meta.issue) return;
-
-		const provider = resolveProvider!(meta.source);
-		await provider.onPrdComplete(meta.issue);
-		logger.log(`Synced PRD #${meta.issue} back to ${meta.source}`);
-	} catch (err: unknown) {
-		const message = err instanceof Error ? err.message : String(err);
-		logger.log(`Warning: sync-back failed for PRD at ${filePath}: ${message}`);
-	}
-}
-
 /**
  * Single check → fix cycle.
  *
@@ -199,7 +125,6 @@ export async function runAfkLoop<T extends { number: number }>(
 	const { logger, git, runner, runnerName } = session;
 
 	logger.log(`Session started — runner: ${runnerName}, iterations: ${iterations}`);
-	runner.logEnvironment(logger);
 	logger.log("");
 	const results: IterationResult[] = [];
 	const sessionStart = performance.now();
@@ -257,6 +182,9 @@ export async function runAfkLoop<T extends { number: number }>(
 				success: false,
 				elapsedSeconds: runResult.durationSeconds,
 				error: runResult.error,
+				turns: runResult.turns,
+				inputTokens: runResult.inputTokens,
+				outputTokens: runResult.outputTokens,
 			});
 
 			if (lastFailedIssueNumber === issue.number) {
@@ -284,6 +212,9 @@ export async function runAfkLoop<T extends { number: number }>(
 				success: false,
 				elapsedSeconds: runResult.durationSeconds,
 				error: errorMsg,
+				turns: runResult.turns,
+				inputTokens: runResult.inputTokens,
+				outputTokens: runResult.outputTokens,
 			});
 
 			if (lastFailedIssueNumber === issue.number) {
@@ -313,6 +244,9 @@ export async function runAfkLoop<T extends { number: number }>(
 				success: false,
 				elapsedSeconds: runResult.durationSeconds,
 				error: "commit failed after retries",
+				turns: runResult.turns,
+				inputTokens: runResult.inputTokens,
+				outputTokens: runResult.outputTokens,
 			});
 			// Commit failures always stop the session immediately
 			logger.log("Stopping session: unable to commit.");
@@ -339,6 +273,9 @@ export async function runAfkLoop<T extends { number: number }>(
 			issueFilename: name,
 			success: true,
 			elapsedSeconds: runResult.durationSeconds,
+			turns: runResult.turns,
+			inputTokens: runResult.inputTokens,
+			outputTokens: runResult.outputTokens,
 		});
 
 		lastFailedIssueNumber = null;
@@ -359,6 +296,19 @@ export async function runAfkLoop<T extends { number: number }>(
 	return results;
 }
 
+/** Format a token count as a human-readable string (e.g., 12400 → "12.4k"). */
+export function formatTokens(count: number): string {
+	if (count >= 1_000_000) {
+		const m = count / 1_000_000;
+		return m % 1 === 0 ? `${m}M` : `${parseFloat(m.toFixed(1))}M`;
+	}
+	if (count >= 1_000) {
+		const k = count / 1_000;
+		return k % 1 === 0 ? `${k}k` : `${parseFloat(k.toFixed(1))}k`;
+	}
+	return `${count}`;
+}
+
 /** Format seconds as a human-readable duration. */
 export function fmtTime(seconds: number): string {
 	if (seconds < 60) {
@@ -386,7 +336,18 @@ export function printSummary(
 	for (const r of results) {
 		const status = r.success ? "completed" : "failed";
 		const elapsed = fmtTime(r.elapsedSeconds);
-		logger.log(`  Issue ${r.issueNumber} (${r.issueFilename}): ${status} (${elapsed})`);
+		const details = [elapsed];
+		if (r.turns != null) {
+			details.push(`${r.turns} turns`);
+		}
+		const totalTokens =
+			r.inputTokens != null || r.outputTokens != null
+				? (r.inputTokens ?? 0) + (r.outputTokens ?? 0)
+				: undefined;
+		if (totalTokens != null) {
+			details.push(`${formatTokens(totalTokens)} tokens`);
+		}
+		logger.log(`  Issue ${r.issueNumber} (${r.issueFilename}): ${status} (${details.join(", ")})`);
 	}
 
 	logger.log("");