stonecut 1.1.1 → 1.2.1

package/src/cli.ts

@@ -17,15 +17,20 @@ import {
 	ensureCleanTree,
 	pushBranch,
 } from "./git";
-import { GitHubSource } from "./github";
 import { LocalSource } from "./local";
 import { slugifyBranchComponent } from "./naming";
-import { renderGithub, renderLocal } from "./prompt";
+import { renderLocal } from "./prompt";
 import { Logger } from "./logger";
 import { defaultGitOps, runAfkLoop } from "./runner";
 import { getRunner } from "./runners/index";
 import { setupSkills, removeSkills } from "./skills";
-import type { GitHubIssue, Issue, IterationResult, Session } from "./types";
+import { init } from "./init";
+import { importSpec } from "./import";
+import { loadConfig } from "./config";
+import { getSourceProvider } from "./sources/index";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import type { Issue, IterationResult, Session } from "./types";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
@@ -60,68 +65,137 @@ export function parseGitHubIssueNumber(value: string): number {
 }
 
 /**
- * Ensure exactly one of --local or --github was provided.
- * Returns a tagged tuple so the caller can dispatch.
+ * Check if --local was provided.
+ * Returns a tagged union so the caller can dispatch.
  */
 export function validateRunSource(
 	local: string | undefined,
-	github: number | undefined,
-): { kind: "local"; name: string } | { kind: "github"; number: number } | { kind: "prompt" } {
-	if (local !== undefined && github !== undefined) {
-		throw new Error("Use exactly one of --local or --github.");
-	}
-	if (local === undefined && github === undefined) {
-		return { kind: "prompt" };
-	}
+): { kind: "local"; name: string } | { kind: "prompt" } {
 	if (local !== undefined) return { kind: "local", name: local };
-	return { kind: "github", number: github! };
+	return { kind: "prompt" };
+}
+
+/** 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/prd"): 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));
 }
 
 /**
- * Prompt the user interactively for the source type and value.
- * Returns a tagged tuple matching the shape of validateRunSource().
+ * Format a PRD entry for display in the wizard.
  */
-export async function promptForSource(): Promise<
-	{ kind: "local"; name: string } | { kind: "github"; number: number }
-> {
-	const sourceType = await clack.select({
-		message: "Source type:",
-		options: [
-			{ value: "local", label: "Local PRD (.stonecut/<name>/)" },
-			{ value: "github", label: "GitHub PRD (issue number)" },
-		],
+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(sourceType)) {
+	if (clack.isCancel(selection)) {
 		throw new Error("Cancelled.");
 	}
 
-	if (sourceType === "local") {
-		const name = await clack.text({
-			message: "Spec name:",
-			placeholder: "my-spec",
-			validate: (value) => {
-				if (!value.trim()) return "Spec name is required.";
-			},
-		});
-		if (clack.isCancel(name)) {
-			throw new Error("Cancelled.");
-		}
-		return { kind: "local", name };
+	if (selection === IMPORT_FROM_GITHUB) {
+		const specName = await inlineGitHubImport();
+		return { kind: "local", name: specName };
 	}
 
-	const issueStr = await clack.text({
-		message: "GitHub issue number:",
-		placeholder: "42",
-		validate: (value) => {
-			const n = Number(value);
-			if (!Number.isInteger(n) || n <= 0) return "Must be a positive integer.";
-		},
+	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(issueStr)) {
+
+	if (clack.isCancel(selected)) {
 		throw new Error("Cancelled.");
 	}
-	return { kind: "github", number: Number(issueStr) };
+
+	const result = await importSpec({
+		provider: "github",
+		identifier: selected as string,
+	});
+
+	console.log(
+		`Imported PRD #${result.prdIssueNumber} → ${result.specDir}/ (${result.issueCount} issues)`,
+	);
+
+	return result.specName;
 }
 
 // ---------------------------------------------------------------------------
@@ -154,23 +228,6 @@ export function buildReport(
 	return lines.join("\n");
 }
 
-// ---------------------------------------------------------------------------
-// GitHub comment on no-changes
-// ---------------------------------------------------------------------------
-
-function commentOnIssue(issueNumber: number, runnerOutput: string | undefined): void {
-	let body = "**Stonecut:** Runner completed but produced no file changes.\n";
-	if (runnerOutput) {
-		body +=
-			"\n<details><summary>Runner output</summary>\n\n" +
-			`\`\`\`\n${runnerOutput}\n\`\`\`\n\n</details>`;
-	}
-	Bun.spawnSync(["gh", "issue", "comment", String(issueNumber), "--body", body], {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-}
-
 // ---------------------------------------------------------------------------
 // Pre-execution flow
 // ---------------------------------------------------------------------------
@@ -183,8 +240,6 @@ export async function preExecution(
 	suggestedBranch: string,
 	prefilled?: { branch?: string; baseBranch?: string },
 ): Promise<[string, string]> {
-	ensureCleanTree();
-
 	let branch: string;
 	if (prefilled?.branch) {
 		branch = prefilled.branch;
@@ -306,48 +361,6 @@ export async function runLocal(
 	}
 }
 
-export async function runGitHub(
-	number: number,
-	iterations: number | "all",
-	runnerName: string,
-	prefilled?: { branch?: string; baseBranch?: string },
-): Promise<void> {
-	const runner = getRunner(runnerName);
-	const source = new GitHubSource(number);
-	const logger = new Logger(`prd-${number}`);
-
-	const session: Session = { logger, git: defaultGitOps, runner, runnerName };
-
-	try {
-		const prd = source.getPrd();
-		const prdSlug = slugifyBranchComponent(prd.title);
-		const suggestedBranch = prdSlug ? `stonecut/${prdSlug}` : `stonecut/issue-${number}`;
-		const prTitle = prd.title || `PRD #${number}`;
-		const [branch, baseBranch] = await preExecution(suggestedBranch, prefilled);
-
-		const prdContent = prd.body;
-		const results = await runAfkLoop<GitHubIssue>(
-			source,
-			iterations,
-			(issue) =>
-				renderGithub({
-					prdContent,
-					issueNumber: issue.number,
-					issueTitle: issue.title,
-					issueContent: issue.body,
-				}),
-			(issue) => issue.title,
-			(issue) => `Issue #${issue.number}: ${issue.title}`,
-			session,
-			(issue, output) => commentOnIssue(issue.number, output),
-		);
-
-		await pushAndMaybePr(results, source, branch, baseBranch, prTitle, runnerName, logger, number);
-	} finally {
-		logger.close();
-	}
-}
-
 // ---------------------------------------------------------------------------
 // Program definition
 // ---------------------------------------------------------------------------
@@ -357,19 +370,30 @@ export function buildProgram(): Command {
 
 	program
 		.name("stonecut")
-		.description("Stonecut — execute PRD-driven development workflows using agentic coding CLIs.")
+		.description(
+			"Stonecut — PRD-driven development with agentic coding CLIs.\n\nRun bare `stonecut` to start the interactive run wizard (the most common workflow).\nUse `stonecut <command>` for other operations.",
+		)
 		.version(`stonecut ${version}`, "-V, --version");
 
 	program
-		.command("run")
-		.description("Execute issues from a local PRD or GitHub PRD.")
-		.option("--local <name>", "Local PRD name (.stonecut/<name>/)")
-		.option("--github <number>", "GitHub PRD issue number", parseGitHubIssueNumber)
+		.command("run", { isDefault: true })
+		.description("Execute issues from a local PRD.")
+		.option("--local <name>", "Local PRD name (.stonecut/prd/<name>/)")
 		.option("-i, --iterations <value>", "Number of issues to process, or 'all'")
-		.option("--runner <name>", "Agentic CLI runner (claude, codex)", "claude")
+		.option("--runner <name>", "Agentic CLI runner (claude, codex)")
 		.action(async (opts) => {
-			const validated = validateRunSource(opts.local, opts.github);
-			const source = validated.kind === "prompt" ? await promptForSource() : validated;
+			ensureCleanTree();
+
+			const config = loadConfig();
+
+			const validated = validateRunSource(opts.local);
+			let source: { kind: "local"; name: string };
+
+			if (validated.kind === "local") {
+				source = validated;
+			} else {
+				source = await promptForPrd();
+			}
 
 			let iterations: number | "all";
 			const needsIterationPrompt = opts.iterations === undefined;
@@ -398,10 +422,12 @@ export function buildProgram(): Command {
 			let prefilled: { branch?: string; baseBranch?: string } | undefined;
 
 			if (isWizard) {
-				const suggestedBranch =
-					source.kind === "local"
-						? `stonecut/${slugifyBranchComponent(source.name) || "spec"}`
-						: `stonecut/issue-${source.number}`;
+				if (!existsSync(".stonecut")) {
+					console.log("Hint: run `stonecut init` to set up project config and gitignore.\n");
+				}
+
+				const branchPrefix = config?.branchPrefix ?? "stonecut/";
+				const suggestedBranch = `${branchPrefix}${slugifyBranchComponent(source.name) || "spec"}`;
 
 				const branch = await clack.text({
 					message: "Branch name:",
@@ -412,7 +438,7 @@ export function buildProgram(): Command {
 					throw new Error("Cancelled.");
 				}
 
-				const detectedDefault = defaultBranch();
+				const detectedDefault = config?.baseBranch ?? defaultBranch();
 				const baseBranch = await clack.text({
 					message: "Base branch / PR target:",
 					defaultValue: detectedDefault,
@@ -425,13 +451,39 @@ export function buildProgram(): Command {
 				prefilled = { branch, baseBranch };
 			}
 
-			const runnerName: string = opts.runner;
+			const runnerName: string = opts.runner ?? config?.runner ?? "claude";
+			await runLocal(source.name, iterations, runnerName, prefilled);
+		});
 
-			if (source.kind === "local") {
-				await runLocal(source.name, iterations, runnerName, prefilled);
-			} else {
-				await runGitHub(source.number, iterations, runnerName, prefilled);
+	program
+		.command("init")
+		.description("Initialize a .stonecut/ directory with project config and gitignore.")
+		.action(() => {
+			init();
+			console.log("Created .stonecut/config.json and .stonecut/.gitignore");
+		});
+
+	program
+		.command("import")
+		.description("Import a PRD and its issues from an external source into .stonecut/.")
+		.option("--github <number>", "GitHub PRD issue number", parseGitHubIssueNumber)
+		.option("--name <name>", "Override the auto-derived spec name")
+		.option("--force", "Overwrite an existing spec directory")
+		.action(async (opts) => {
+			if (opts.github === undefined) {
+				throw new Error("Specify a source: --github <number>");
 			}
+
+			const result = await importSpec({
+				provider: "github",
+				identifier: String(opts.github),
+				name: opts.name,
+				force: opts.force,
+			});
+
+			console.log(
+				`Imported PRD #${result.prdIssueNumber} → ${result.specDir}/ (${result.issueCount} issues)`,
+			);
 		});
 
 	program

package/src/config.ts

@@ -0,0 +1,56 @@
+/**
+ * Project-level configuration for Stonecut.
+ *
+ * Reads and writes `.stonecut/config.json` in the current working directory.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+
+/** Shape of `.stonecut/config.json`. All fields are optional. */
+export interface StonecutConfig {
+	runner?: string;
+	baseBranch?: string;
+	branchPrefix?: string;
+}
+
+const CONFIG_DIR = ".stonecut";
+const CONFIG_FILE = "config.json";
+
+function configPath(cwd?: string): string {
+	return join(cwd ?? process.cwd(), CONFIG_DIR, CONFIG_FILE);
+}
+
+/**
+ * Load project config from `.stonecut/config.json`.
+ * Returns null if the file does not exist.
+ * Returns an empty object if the file contains malformed JSON.
+ */
+export function loadConfig(cwd?: string): StonecutConfig | null {
+	const path = configPath(cwd);
+	if (!existsSync(path)) return null;
+
+	try {
+		const raw = readFileSync(path, "utf-8");
+		return JSON.parse(raw) as StonecutConfig;
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Write a default config file to `.stonecut/config.json`.
+ * Creates the `.stonecut/` directory if it doesn't exist.
+ */
+export function writeDefaultConfig(cwd?: string): void {
+	const dir = join(cwd ?? process.cwd(), CONFIG_DIR);
+	mkdirSync(dir, { recursive: true });
+
+	const defaults: StonecutConfig = {
+		runner: "claude",
+		baseBranch: "main",
+		branchPrefix: "stonecut/",
+	};
+
+	writeFileSync(configPath(cwd), JSON.stringify(defaults, null, 2) + "\n");
+}

package/src/frontmatter.ts

@@ -0,0 +1,73 @@
+/** Frontmatter utilities — parse and serialize YAML frontmatter in markdown files. */
+
+export interface Frontmatter {
+	meta: Record<string, string>;
+	body: string;
+}
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Returns empty meta and full body if no frontmatter is present.
+ */
+export function parseFrontmatter(content: string): Frontmatter {
+	if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+		return { meta: {}, body: content };
+	}
+
+	const lineBreak = content.startsWith("---\r\n") ? "\r\n" : "\n";
+	const fence = `${lineBreak}---`;
+	let searchFrom = 3;
+	let closingIndex = -1;
+	while (true) {
+		const idx = content.indexOf(fence, searchFrom);
+		if (idx === -1) break;
+		const afterFence = idx + fence.length;
+		// Valid closing fence: followed by a newline or at end of string
+		if (
+			afterFence === content.length ||
+			content[afterFence] === "\n" ||
+			content[afterFence] === "\r"
+		) {
+			closingIndex = idx;
+			break;
+		}
+		searchFrom = afterFence;
+	}
+	if (closingIndex === -1) {
+		return { meta: {}, body: content };
+	}
+
+	const yamlBlock = content.slice(3 + lineBreak.length, closingIndex);
+	const body = content.slice(closingIndex + lineBreak.length + 3);
+	// Strip leading newline from body (the one right after closing ---)
+	const trimmedBody = body.startsWith("\r\n")
+		? body.slice(2)
+		: body.startsWith("\n")
+			? body.slice(1)
+			: body;
+
+	const meta: Record<string, string> = {};
+	for (const line of yamlBlock.split(lineBreak)) {
+		const colonIndex = line.indexOf(":");
+		if (colonIndex === -1) continue;
+		const key = line.slice(0, colonIndex).trim();
+		if (!key) continue;
+		const value = line.slice(colonIndex + 1).trim();
+		meta[key] = value;
+	}
+
+	return { meta, body: trimmedBody };
+}
+
+/**
+ * Serialize metadata and body into a frontmatter-delimited markdown string.
+ * If meta is empty, returns body as-is (no frontmatter block).
+ */
+export function serializeFrontmatter(meta: Record<string, string>, body: string): string {
+	if (Object.keys(meta).length === 0) {
+		return body;
+	}
+
+	const lines = Object.entries(meta).map(([key, value]) => `${key}: ${value}`);
+	return `---\n${lines.join("\n")}\n---\n${body}`;
+}

package/src/import.ts

@@ -0,0 +1,92 @@
+/**
+ * Import module — pulls PRDs and issues from external sources into
+ * the local .stonecut/ directory structure.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, rmSync } from "fs";
+import { join } from "path";
+import { getSourceProvider } from "./sources/index";
+import type { SourceProvider } from "./sources/types";
+import { serializeFrontmatter } from "./frontmatter";
+import { slugifyBranchComponent } from "./naming";
+
+export interface ImportOptions {
+	provider: string;
+	identifier: string;
+	name?: string;
+	force?: boolean;
+	/** Override the source provider (used in tests). */
+	_sourceProvider?: SourceProvider;
+}
+
+export interface ImportResult {
+	specName: string;
+	specDir: string;
+	prdIssueNumber: number;
+	issueCount: number;
+}
+
+export async function importSpec(options: ImportOptions): Promise<ImportResult> {
+	const source = options._sourceProvider ?? getSourceProvider(options.provider);
+
+	const prd = await source.fetchPrd(options.identifier);
+	const issues = await source.fetchIssues(options.identifier);
+
+	const specName = deriveSpecName(options.name ?? prd.title);
+	if (!specName) {
+		throw new Error("Could not derive a spec name from the PRD title. Use --name to specify one.");
+	}
+
+	const specDir = join(".stonecut", "prd", specName);
+
+	if (existsSync(specDir)) {
+		if (!options.force) {
+			throw new Error(
+				`Spec '${specName}' already exists at ${specDir}/. Use --force to overwrite.`,
+			);
+		}
+		rmSync(specDir, { recursive: true });
+	}
+
+	const issuesDir = join(specDir, "issues");
+	mkdirSync(issuesDir, { recursive: true });
+
+	// Write PRD with frontmatter
+	const prdMeta: Record<string, string> = {
+		source: options.provider,
+		issue: String(prd.issueNumber),
+		title: prd.title,
+	};
+	writeFileSync(join(specDir, "prd.md"), serializeFrontmatter(prdMeta, prd.body + "\n"));
+
+	// Write issues with frontmatter
+	for (let i = 0; i < issues.length; i++) {
+		const issue = issues[i];
+		const num = String(i + 1).padStart(2, "0");
+		const slug = slugifyBranchComponent(issue.title);
+		const filename = `${num}-${slug}.md`;
+
+		const issueMeta: Record<string, string> = {
+			source: options.provider,
+			issue: String(issue.number),
+		};
+		const body = issue.body ? issue.body + "\n" : "";
+		writeFileSync(join(issuesDir, filename), serializeFrontmatter(issueMeta, body));
+	}
+
+	// Create initial status.json (pre-populate with already-closed issues) and progress.txt
+	const completed = issues.filter((issue) => issue.state === "CLOSED").map((issue) => issue.number);
+	writeFileSync(join(specDir, "status.json"), JSON.stringify({ completed }, null, 2) + "\n");
+	writeFileSync(join(specDir, "progress.txt"), "");
+
+	return {
+		specName,
+		specDir,
+		prdIssueNumber: prd.issueNumber,
+		issueCount: issues.length,
+	};
+}
+
+function deriveSpecName(title: string): string {
+	return slugifyBranchComponent(title);
+}

package/src/init.ts

@@ -0,0 +1,38 @@
+/**
+ * Scaffolds a `.stonecut/` project directory with config and gitignore.
+ */
+
+import { existsSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { writeDefaultConfig } from "./config";
+
+const CONFIG_DIR = ".stonecut";
+const CONFIG_FILE = "config.json";
+const GITIGNORE_FILE = ".gitignore";
+
+const GITIGNORE_CONTENT = `# Stonecut runtime artifacts
+logs/
+status.json
+progress.txt
+`;
+
+/**
+ * Initialize a `.stonecut/` directory with config and gitignore.
+ * Throws if `config.json` already exists to prevent accidental overwrites.
+ */
+export function init(cwd?: string): void {
+	const base = cwd ?? process.cwd();
+	const configPath = join(base, CONFIG_DIR, CONFIG_FILE);
+
+	if (existsSync(configPath)) {
+		throw new Error(
+			`.stonecut/config.json already exists. Remove it first if you want to reinitialize.`,
+		);
+	}
+
+	const dir = join(base, CONFIG_DIR);
+	mkdirSync(dir, { recursive: true });
+
+	writeDefaultConfig(cwd);
+	writeFileSync(join(dir, GITIGNORE_FILE), GITIGNORE_CONTENT);
+}