stonecut 1.0.0

package/src/git.ts

@@ -0,0 +1,189 @@
+/**
+ * Git branch-level operations — branch management, working tree checks,
+ * working tree lifecycle (snapshot/stage/commit/revert), and PR creation.
+ *
+ * All functions throw on failure. No process.exit, no console output.
+ */
+
+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);
+	if (result.exitCode === 0) {
+		const ref = result.stdout.trim();
+		const prefix = "refs/remotes/origin/";
+		if (ref.startsWith(prefix)) {
+			const branch = ref.slice(prefix.length);
+			if (branch) {
+				return branch;
+			}
+		}
+	}
+	return "main";
+}
+
+/** Throw if the working tree has uncommitted changes. */
+export function ensureCleanTree(cwd?: string): void {
+	const result = runSync(["git", "status", "--porcelain"], cwd);
+	if (result.stdout.trim()) {
+		throw new Error("Working tree has uncommitted changes. Commit or stash them first.");
+	}
+}
+
+/** Check out the branch if it exists locally, otherwise create it. */
+export function checkoutOrCreateBranch(branch: string, cwd?: string): void {
+	const verify = runSync(["git", "rev-parse", "--verify", branch], cwd);
+	if (verify.exitCode === 0) {
+		const checkout = runSync(["git", "checkout", branch], cwd);
+		if (checkout.exitCode !== 0) {
+			throw new Error(`Failed to checkout branch ${branch}: ${checkout.stderr.trim()}`);
+		}
+	} else {
+		const create = runSync(["git", "checkout", "-b", branch], cwd);
+		if (create.exitCode !== 0) {
+			throw new Error(`Failed to create branch ${branch}: ${create.stderr.trim()}`);
+		}
+	}
+}
+
+/** Push the branch to the remote with upstream tracking. */
+export function pushBranch(branch: string, cwd?: string): void {
+	const result = runSync(["git", "push", "-u", "origin", branch], cwd);
+	if (result.exitCode !== 0) {
+		throw new Error(`Failed to push branch ${branch}: ${result.stderr.trim()}`);
+	}
+}
+
+/** Create a pull request via the gh CLI. */
+export function createPr(title: string, body: string, baseBranch: string): void {
+	const result = runSync([
+		"gh",
+		"pr",
+		"create",
+		"--title",
+		title,
+		"--body",
+		body,
+		"--base",
+		baseBranch,
+	]);
+	if (result.exitCode !== 0) {
+		throw new Error(`Failed to create PR: ${result.stderr.trim()}`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Working tree lifecycle — snapshot / stage / commit / revert
+// ---------------------------------------------------------------------------
+
+/** Capture the current set of untracked files before a runner session. */
+export function snapshotWorkingTree(cwd?: string): WorkingTreeSnapshot {
+	const result = runSync(["git", "status", "--porcelain"], cwd);
+	const untracked = new Set<string>();
+	for (const line of result.stdout.split("\n")) {
+		if (line.startsWith("??")) {
+			untracked.add(line.slice(3).trim());
+		}
+	}
+	return { untracked };
+}
+
+/**
+ * Stage files changed during a runner session.
+ *
+ * Stages modified tracked files and new untracked files that were not
+ * present in the snapshot. Returns true if anything was staged.
+ */
+export function stageChanges(snapshot: WorkingTreeSnapshot, cwd?: string): boolean {
+	// Stage all modified tracked files
+	const addU = runSync(["git", "add", "-u"], cwd);
+	if (addU.exitCode !== 0) {
+		throw new Error(`Failed to stage tracked changes: ${addU.stderr.trim()}`);
+	}
+
+	// Find new untracked files (not in pre-run snapshot)
+	const status = runSync(["git", "status", "--porcelain"], cwd);
+	const newFiles: string[] = [];
+	for (const line of status.stdout.split("\n")) {
+		if (line.startsWith("??")) {
+			const path = line.slice(3).trim();
+			if (!snapshot.untracked.has(path)) {
+				newFiles.push(path);
+			}
+		}
+	}
+
+	if (newFiles.length > 0) {
+		const addNew = runSync(["git", "add", "--", ...newFiles], cwd);
+		if (addNew.exitCode !== 0) {
+			throw new Error(`Failed to stage new files: ${addNew.stderr.trim()}`);
+		}
+	}
+
+	// Check if anything is staged
+	const diff = runSync(["git", "diff", "--cached", "--quiet"], cwd);
+	return diff.exitCode !== 0;
+}
+
+/**
+ * Create a git commit with the given message.
+ *
+ * Returns [success, output]. On failure the output contains the
+ * error details (e.g. pre-commit hook output).
+ */
+export function commitChanges(message: string, cwd?: string): [boolean, string] {
+	const result = runSync(["git", "commit", "-m", message], cwd);
+	const output = `${result.stdout}\n${result.stderr}`.trim();
+	return [result.exitCode === 0, output];
+}
+
+/**
+ * Revert uncommitted changes, restoring the tree to the last commit.
+ *
+ * Removes new untracked files created during the runner session (those
+ * not in the snapshot) and restores modified tracked files.
+ */
+export function revertUncommitted(snapshot: WorkingTreeSnapshot, cwd?: string): void {
+	// Unstage everything (clear the index back to HEAD)
+	runSync(["git", "reset", "HEAD"], cwd);
+
+	// Restore modified tracked files
+	runSync(["git", "checkout", "."], cwd);
+
+	// Remove new untracked files (only those created during the session)
+	const status = runSync(["git", "status", "--porcelain"], cwd);
+	const newFiles: string[] = [];
+	for (const line of status.stdout.split("\n")) {
+		if (line.startsWith("??")) {
+			const path = line.slice(3).trim();
+			if (!snapshot.untracked.has(path)) {
+				newFiles.push(path);
+			}
+		}
+	}
+
+	if (newFiles.length > 0) {
+		runSync(["git", "clean", "-fd", "--", ...newFiles], cwd);
+	}
+}

package/src/github.ts

@@ -0,0 +1,178 @@
+/** GitHub source — wraps the gh CLI to interact with GitHub issues. */
+
+import type { GitHubIssue, GitHubPrd, Source } from "./types";
+
+function runSync(cmd: string[]): { exitCode: number; stdout: string; stderr: string } {
+	const proc = Bun.spawnSync(cmd, {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	return {
+		exitCode: proc.exitCode,
+		stdout: proc.stdout.toString(),
+		stderr: proc.stderr.toString(),
+	};
+}
+
+export class GitHubSource implements Source<GitHubIssue> {
+	readonly prdNumber: number;
+	readonly owner: string;
+	readonly repo: string;
+
+	constructor(prdNumber: number) {
+		this.prdNumber = prdNumber;
+		GitHubSource.validateGhCli();
+		const [owner, repo] = GitHubSource.getOwnerRepo();
+		this.owner = owner;
+		this.repo = repo;
+		this.validatePrd();
+	}
+
+	static validateGhCli(): void {
+		try {
+			runSync(["gh", "--version"]);
+		} catch {
+			throw new Error("Error: gh CLI is not installed. See https://cli.github.com");
+		}
+		const result = runSync(["gh", "auth", "status"]);
+		if (result.exitCode !== 0) {
+			throw new Error("Error: gh CLI is not authenticated. Run 'gh auth login'.");
+		}
+	}
+
+	static getOwnerRepo(): [string, string] {
+		const result = runSync(["git", "remote", "get-url", "origin"]);
+		if (result.exitCode !== 0) {
+			throw new Error("Error: could not determine git remote origin.");
+		}
+		const url = result.stdout.trim();
+
+		// SSH: git@github.com:owner/repo.git
+		const sshMatch = url.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/);
+		if (sshMatch) {
+			return [sshMatch[1], sshMatch[2]];
+		}
+
+		// HTTPS or SSH protocol: https://github.com/owner/repo.git
+		const httpsMatch = url.match(
+			/^(?:https?|ssh):\/\/[^/]*github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/,
+		);
+		if (httpsMatch) {
+			return [httpsMatch[1], httpsMatch[2]];
+		}
+
+		throw new Error(`Error: could not parse owner/repo from remote URL: ${url}`);
+	}
+
+	validatePrd(): void {
+		const result = runSync([
+			"gh",
+			"issue",
+			"view",
+			String(this.prdNumber),
+			"--json",
+			"labels",
+			"-q",
+			".labels[].name",
+		]);
+		if (result.exitCode !== 0) {
+			throw new Error(`Error: GitHub issue #${this.prdNumber} not found.`);
+		}
+		const labels = result.stdout
+			.trim()
+			.split("\n")
+			.filter((l) => l);
+		if (!labels.includes("prd")) {
+			throw new Error(`Error: Issue #${this.prdNumber} does not have the 'prd' label.`);
+		}
+	}
+
+	async getPrdContent(): Promise<string> {
+		const prd = this.getPrd();
+		return prd.body;
+	}
+
+	getPrd(): GitHubPrd {
+		const result = runSync(["gh", "issue", "view", String(this.prdNumber), "--json", "title,body"]);
+		if (result.exitCode !== 0) {
+			throw new Error(`Error: failed to fetch PRD issue #${this.prdNumber}.`);
+		}
+		const data = JSON.parse(result.stdout);
+		return {
+			number: this.prdNumber,
+			title: (data.title ?? "").trim(),
+			body: (data.body ?? "").trim(),
+		};
+	}
+
+	private fetchSubIssues(): Array<{
+		number: number;
+		title: string;
+		state: string;
+		body: string;
+	}> {
+		const query = `
+query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) {
+    issue(number: $number) {
+      subIssues(first: 100) {
+        nodes {
+          number
+          title
+          state
+          body
+        }
+      }
+    }
+  }
+}`;
+		const result = runSync([
+			"gh",
+			"api",
+			"graphql",
+			"-F",
+			`owner=${this.owner}`,
+			"-F",
+			`repo=${this.repo}`,
+			"-F",
+			`number=${this.prdNumber}`,
+			"-f",
+			`query=${query}`,
+		]);
+		if (result.exitCode !== 0) {
+			throw new Error(`Error fetching sub-issues: ${result.stderr.trim()}`);
+		}
+		const data = JSON.parse(result.stdout);
+		return data.data.repository.issue.subIssues.nodes;
+	}
+
+	async getNextIssue(): Promise<GitHubIssue | null> {
+		const subIssues = this.fetchSubIssues();
+		const openIssues = subIssues
+			.filter((i) => i.state === "OPEN")
+			.sort((a, b) => a.number - b.number);
+		if (openIssues.length === 0) {
+			return null;
+		}
+		const first = openIssues[0];
+		return {
+			number: first.number,
+			title: first.title,
+			body: first.body ?? "",
+		};
+	}
+
+	async getRemainingCount(): Promise<[number, number]> {
+		const subIssues = this.fetchSubIssues();
+		const total = subIssues.length;
+		const remaining = subIssues.filter((i) => i.state === "OPEN").length;
+		return [remaining, total];
+	}
+
+	async completeIssue(issue: GitHubIssue): Promise<void> {
+		const result = runSync(["gh", "issue", "close", String(issue.number)]);
+		if (result.exitCode !== 0) {
+			throw new Error(`Error: failed to close issue #${issue.number}: ${result.stderr.trim()}`);
+		}
+	}
+}

package/src/local.ts

@@ -0,0 +1,116 @@
+/** Local spec source — reads issues from .stonecut/<name>/. */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, statSync } from "fs";
+import { join } from "path";
+import type { Issue, Source } from "./types";
+
+export class LocalSource implements Source<Issue> {
+	readonly name: string;
+	private readonly specDir: string;
+
+	constructor(name: string) {
+		this.name = name;
+		this.specDir = join(".stonecut", name);
+		this.validate();
+	}
+
+	private validate(): void {
+		if (!existsSync(this.specDir) || !statSync(this.specDir).isDirectory()) {
+			throw new Error(`Error: spec directory not found: ${this.specDir}/`);
+		}
+		if (
+			!existsSync(join(this.specDir, "prd.md")) ||
+			!statSync(join(this.specDir, "prd.md")).isFile()
+		) {
+			throw new Error(`Error: ${this.specDir}/prd.md not found`);
+		}
+		if (
+			!existsSync(join(this.specDir, "issues")) ||
+			!statSync(join(this.specDir, "issues")).isDirectory()
+		) {
+			throw new Error(`Error: ${this.specDir}/issues/ not found`);
+		}
+	}
+
+	private statusPath(): string {
+		return join(this.specDir, "status.json");
+	}
+
+	private readStatus(): Set<number> {
+		const path = this.statusPath();
+		if (!existsSync(path)) {
+			writeFileSync(path, '{ "completed": [] }\n');
+			return new Set();
+		}
+		const data = JSON.parse(readFileSync(path, "utf-8"));
+		return new Set<number>(data.completed ?? []);
+	}
+
+	private allIssues(): Array<{ number: number; filename: string; path: string }> {
+		const issuesDir = join(this.specDir, "issues");
+		const entries = readdirSync(issuesDir).sort();
+		const results: Array<{ number: number; filename: string; path: string }> = [];
+		for (const name of entries) {
+			if (!name.endsWith(".md")) continue;
+			const match = name.match(/^(\d+)/);
+			if (match) {
+				results.push({
+					number: parseInt(match[1], 10),
+					filename: name,
+					path: join(issuesDir, name),
+				});
+			}
+		}
+		return results;
+	}
+
+	async getPrdContent(): Promise<string> {
+		return readFileSync(join(this.specDir, "prd.md"), "utf-8");
+	}
+
+	async getNextIssue(): Promise<Issue | null> {
+		const completed = this.readStatus();
+		for (const issue of this.allIssues()) {
+			if (!completed.has(issue.number)) {
+				return {
+					number: issue.number,
+					filename: issue.filename,
+					path: issue.path,
+					content: readFileSync(issue.path, "utf-8"),
+				};
+			}
+		}
+		return null;
+	}
+
+	async getRemainingCount(): Promise<[number, number]> {
+		const completed = this.readStatus();
+		const all = this.allIssues();
+		const total = all.length;
+		const remaining = all.filter((i) => !completed.has(i.number)).length;
+		return [remaining, total];
+	}
+
+	async completeIssue(issue: Issue): Promise<void> {
+		// Update status.json
+		const path = this.statusPath();
+		let data: { completed: number[] };
+		if (existsSync(path)) {
+			data = JSON.parse(readFileSync(path, "utf-8"));
+		} else {
+			data = { completed: [] };
+		}
+		const completed = new Set<number>(data.completed ?? []);
+		completed.add(issue.number);
+		data.completed = [...completed].sort((a, b) => a - b);
+		writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+
+		// Append to progress.txt
+		const now = new Date();
+		const timestamp = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")} ${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}`;
+		appendFileSync(
+			join(this.specDir, "progress.txt"),
+			`${timestamp} — Issue ${issue.number} complete: ${issue.filename}\n`,
+		);
+	}
+}

package/src/logger.ts

@@ -0,0 +1,32 @@
+/**
+ * Logger — dual-output session logger.
+ *
+ * Writes to both console and a project-scoped log file at
+ * .stonecut/logs/<prdIdentifier>-<timestamp>.log.
+ */
+
+import { appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import type { LogWriter } from "./types";
+
+export class Logger implements LogWriter {
+	readonly filePath: string;
+
+	constructor(prdIdentifier: string) {
+		const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+		const logDir = join(".stonecut", "logs");
+		mkdirSync(logDir, { recursive: true });
+		this.filePath = join(logDir, `${prdIdentifier}-${timestamp}.log`);
+	}
+
+	log(message: string): void {
+		console.log(message);
+		const ts = new Date().toISOString();
+		appendFileSync(this.filePath, `[${ts}] ${message}\n`);
+	}
+
+	close(): void {
+		// No-op: appendFileSync doesn't hold a file handle.
+		// Exists as a lifecycle hook for future buffered/async writers.
+	}
+}

package/src/naming.ts

@@ -0,0 +1,14 @@
+/**
+ * Naming helpers for branches and pull requests.
+ */
+
+/** Normalize a free-form title into a branch-safe slug. */
+export function slugifyBranchComponent(value: string): string {
+	let normalized = value
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-");
+	normalized = normalized.replace(/-{2,}/g, "-");
+	normalized = normalized.replace(/^-+|-+$/g, "");
+	return normalized;
+}

package/src/prompt.ts

@@ -0,0 +1,50 @@
+/**
+ * Prompt builder — loads and renders the execute.md template.
+ */
+
+import { join } from "node:path";
+
+async function renderTemplate(vars: Record<string, string | number>): Promise<string> {
+	const template = await Bun.file(join(import.meta.dir, "templates", "execute.md")).text();
+	return template.replace(/\{(\w+)\}/g, (_, key: string) => String(vars[key] ?? `{${key}}`));
+}
+
+export async function renderLocal({
+	prdContent,
+	issueNumber,
+	issueFilename,
+	issueContent,
+}: {
+	prdContent: string;
+	issueNumber: number;
+	issueFilename: string;
+	issueContent: string;
+}): Promise<string> {
+	return renderTemplate({
+		task_source: "a structured spec",
+		prd_content: prdContent,
+		issue_number: issueNumber,
+		issue_filename: issueFilename,
+		issue_content: issueContent,
+	});
+}
+
+export async function renderGithub({
+	prdContent,
+	issueNumber,
+	issueTitle,
+	issueContent,
+}: {
+	prdContent: string;
+	issueNumber: number;
+	issueTitle: string;
+	issueContent: string;
+}): Promise<string> {
+	return renderTemplate({
+		task_source: "a GitHub issue",
+		prd_content: prdContent,
+		issue_number: issueNumber,
+		issue_filename: issueTitle,
+		issue_content: issueContent,
+	});
+}