whitesmith 0.0.0

package/src/git.ts

@@ -0,0 +1,148 @@
+import {exec} from 'node:child_process';
+import {promisify} from 'node:util';
+
+const execAsync = promisify(exec);
+
+/**
+ * Git operations for whitesmith.
+ */
+export class GitManager {
+	private workDir: string;
+
+	constructor(workDir: string) {
+		this.workDir = workDir;
+	}
+
+	private async git(args: string): Promise<string> {
+		const {stdout} = await execAsync(`git ${args}`, {cwd: this.workDir});
+		return stdout.trim();
+	}
+
+	/**
+	 * Get the current branch name
+	 */
+	async getCurrentBranch(): Promise<string> {
+		return this.git('rev-parse --abbrev-ref HEAD');
+	}
+
+	/**
+	 * Fetch latest from origin
+	 */
+	async fetch(): Promise<void> {
+		await this.git('fetch origin');
+	}
+
+	/**
+	 * Checkout a branch (create if it doesn't exist)
+	 */
+	async checkout(branch: string, options?: {create?: boolean; startPoint?: string}): Promise<void> {
+		if (options?.create) {
+			const startPoint = options.startPoint || 'origin/main';
+			await this.git(`checkout -b ${branch} ${startPoint}`);
+		} else {
+			await this.git(`checkout ${branch}`);
+		}
+	}
+
+	/**
+	 * Checkout main and pull latest
+	 */
+	async checkoutMain(): Promise<void> {
+		await this.git('checkout main');
+		await this.git('pull origin main');
+	}
+
+	/**
+	 * Stage all changes and commit
+	 */
+	async commitAll(message: string, exclude?: string[]): Promise<boolean> {
+		// Check if there are changes
+		const status = await this.git('status --porcelain');
+		if (!status) return false;
+
+		let addCmd = 'git add -A';
+		if (exclude && exclude.length > 0) {
+			// Add all then unstage excluded
+			await this.git('add -A');
+			for (const pattern of exclude) {
+				try {
+					await this.git(`reset HEAD -- ${pattern}`);
+				} catch {
+					// File might not be staged
+				}
+			}
+		} else {
+			await this.git('add -A');
+		}
+
+		await this.git(`commit -m "${message.replace(/"/g, '\\"')}"`);
+		return true;
+	}
+
+	/**
+	 * Push branch to origin
+	 */
+	async push(branch: string): Promise<void> {
+		await this.git(`push origin ${branch}`);
+	}
+
+	/**
+	 * Force push branch to origin
+	 */
+	async forcePush(branch: string): Promise<void> {
+		await this.git(`push --force-with-lease origin ${branch}`);
+	}
+
+	/**
+	 * Check if there are uncommitted changes
+	 */
+	async hasChanges(): Promise<boolean> {
+		const status = await this.git('status --porcelain');
+		return status.length > 0;
+	}
+
+	/**
+	 * Check if a local branch exists
+	 */
+	async localBranchExists(branch: string): Promise<boolean> {
+		try {
+			await this.git(`rev-parse --verify ${branch}`);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Delete a local branch
+	 */
+	async deleteLocalBranch(branch: string): Promise<void> {
+		try {
+			await this.git(`branch -D ${branch}`);
+		} catch {
+			// Branch might not exist
+		}
+	}
+
+	/**
+	 * Get the default branch (usually main)
+	 */
+	async getDefaultBranch(): Promise<string> {
+		try {
+			const ref = await this.git('symbolic-ref refs/remotes/origin/HEAD');
+			return ref.replace('refs/remotes/origin/', '');
+		} catch {
+			return 'main';
+		}
+	}
+
+	/**
+	 * Verify we're on the expected branch
+	 */
+	async verifyBranch(expected: string): Promise<void> {
+		const current = await this.getCurrentBranch();
+		if (current !== expected) {
+			throw new Error(`Expected to be on branch '${expected}' but on '${current}'`);
+		}
+	}
+}

package/src/harnesses/agent-harness.ts

@@ -0,0 +1,15 @@
+/**
+ * Interface for AI agent harnesses.
+ * Implementations wrap specific tools (pi, claude CLI, aider, etc.)
+ */
+export interface AgentHarness {
+	/**
+	 * Run the agent with a prompt and return its output.
+	 * The agent is expected to execute in the given working directory.
+	 */
+	run(options: {
+		prompt: string;
+		workDir: string;
+		logFile?: string;
+	}): Promise<{output: string; exitCode: number}>;
+}

package/src/harnesses/index.ts

@@ -0,0 +1,2 @@
+export type {AgentHarness} from './agent-harness.js';
+export {PiHarness} from './pi.js';

package/src/harnesses/pi.ts

@@ -0,0 +1,82 @@
+import {exec} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type {AgentHarness} from './agent-harness.js';
+
+/**
+ * Agent harness for @mariozechner/pi-coding-agent.
+ *
+ * Runs `pi` with a prompt passed via a temp file, captures output.
+ */
+export class PiHarness implements AgentHarness {
+	private cmd: string;
+
+	/**
+	 * @param cmd - Command to invoke pi (default: "pi")
+	 */
+	constructor(cmd: string = 'pi') {
+		this.cmd = cmd;
+	}
+
+	async run(options: {
+		prompt: string;
+		workDir: string;
+		logFile?: string;
+	}): Promise<{output: string; exitCode: number}> {
+		// Write prompt to a temp file to avoid shell escaping issues
+		const promptFile = path.join(options.workDir, '.whitesmith-prompt.md');
+		fs.writeFileSync(promptFile, options.prompt, 'utf-8');
+
+		try {
+			const result = await this.exec(
+				`${this.cmd} --prompt-file "${promptFile}" --yes`,
+				options.workDir,
+				options.logFile,
+			);
+			return result;
+		} finally {
+			// Clean up prompt file
+			try {
+				fs.unlinkSync(promptFile);
+			} catch {
+				// Ignore
+			}
+		}
+	}
+
+	private exec(
+		cmd: string,
+		workDir: string,
+		logFile?: string,
+	): Promise<{output: string; exitCode: number}> {
+		return new Promise((resolve) => {
+			const child = exec(cmd, {
+				cwd: workDir,
+				maxBuffer: 50 * 1024 * 1024,
+				timeout: 30 * 60 * 1000, // 30 minute timeout
+			});
+
+			let output = '';
+			const logStream = logFile
+				? fs.createWriteStream(path.resolve(workDir, logFile), {flags: 'a'})
+				: null;
+
+			child.stdout?.on('data', (data: string) => {
+				output += data;
+				process.stdout.write(data);
+				logStream?.write(data);
+			});
+
+			child.stderr?.on('data', (data: string) => {
+				output += data;
+				process.stderr.write(data);
+				logStream?.write(data);
+			});
+
+			child.on('close', (code) => {
+				logStream?.end();
+				resolve({output, exitCode: code ?? 1});
+			});
+		});
+	}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export {Orchestrator} from './orchestrator.js';
+export {TaskManager} from './task-manager.js';
+export {GitManager} from './git.js';
+export {buildInvestigatePrompt, buildImplementPrompt} from './prompts.js';
+
+export type {IssueProvider} from './providers/issue-provider.js';
+export {GitHubProvider} from './providers/github.js';
+
+export type {AgentHarness} from './harnesses/agent-harness.js';
+export {PiHarness} from './harnesses/pi.js';
+
+export type {Issue, Task, TaskFrontmatter, DevPulseConfig, Action} from './types.js';
+export {LABELS} from './types.js';

package/src/orchestrator.ts

@@ -0,0 +1,294 @@
+import type {DevPulseConfig, Issue, Task, Action} from './types.js';
+import {LABELS} from './types.js';
+import type {IssueProvider} from './providers/issue-provider.js';
+import type {AgentHarness} from './harnesses/agent-harness.js';
+import {TaskManager} from './task-manager.js';
+import {GitManager} from './git.js';
+import {buildInvestigatePrompt, buildImplementPrompt} from './prompts.js';
+
+/**
+ * Main orchestrator for whitesmith.
+ *
+ * The loop:
+ * 1. Reconcile — check if any issues with tasks-accepted have all tasks done
+ * 2. Investigate — pick an unlabeled issue, generate tasks
+ * 3. Implement — pick an available task, implement it
+ */
+export class Orchestrator {
+	private config: DevPulseConfig;
+	private issues: IssueProvider;
+	private agent: AgentHarness;
+	private tasks: TaskManager;
+	private git: GitManager;
+
+	constructor(config: DevPulseConfig, issues: IssueProvider, agent: AgentHarness) {
+		this.config = config;
+		this.issues = issues;
+		this.agent = agent;
+		this.tasks = new TaskManager(config.workDir);
+		this.git = new GitManager(config.workDir);
+	}
+
+	/**
+	 * Run the main loop
+	 */
+	async run(): Promise<void> {
+		console.log('=== whitesmith ===');
+		console.log(`Working directory: ${this.config.workDir}`);
+		console.log(`Max iterations: ${this.config.maxIterations}`);
+		console.log(`Agent command: ${this.config.agentCmd}`);
+		console.log('');
+
+		// Ensure labels exist
+		await this.issues.ensureLabels(Object.values(LABELS));
+
+		for (let i = 1; i <= this.config.maxIterations; i++) {
+			console.log('');
+			console.log(`=== Iteration ${i}/${this.config.maxIterations} ===`);
+
+			// Make sure we're on main with latest
+			await this.git.fetch();
+			await this.git.checkoutMain();
+
+			// Decide what to do
+			const action = await this.decideAction();
+			console.log(`Action: ${action.type}`);
+
+			switch (action.type) {
+				case 'reconcile':
+					await this.reconcile(action.issue);
+					break;
+				case 'investigate':
+					await this.investigate(action.issue);
+					break;
+				case 'implement':
+					await this.implement(action.task, action.issue);
+					break;
+				case 'idle':
+					console.log('Nothing to do. All issues are either in-progress or completed.');
+					return;
+			}
+
+			if (!this.config.noSleep && i < this.config.maxIterations) {
+				console.log('Sleeping 5s...');
+				await new Promise((r) => setTimeout(r, 5000));
+			}
+		}
+
+		console.log('');
+		console.log('=== Iteration limit reached ===');
+	}
+
+	/**
+	 * Decide the next action to take
+	 */
+	private async decideAction(): Promise<Action> {
+		// Priority 1: Reconcile — issues with tasks-accepted where all tasks are done
+		const acceptedIssues = await this.issues.listIssues({labels: [LABELS.TASKS_ACCEPTED]});
+		for (const issue of acceptedIssues) {
+			if (!this.tasks.hasRemainingTasks(issue.number)) {
+				return {type: 'reconcile', issue};
+			}
+		}
+
+		// Priority 2: Implement — find an available task
+		const implementAction = await this.findAvailableTask(acceptedIssues);
+		if (implementAction) {
+			return implementAction;
+		}
+
+		// Priority 3: Investigate — find a new issue (no whitesmith labels)
+		const allDevPulseLabels = Object.values(LABELS);
+		const newIssues = await this.issues.listIssues({noLabels: allDevPulseLabels});
+		if (newIssues.length > 0) {
+			// Pick the oldest issue
+			const issue = newIssues[newIssues.length - 1];
+			return {type: 'investigate', issue};
+		}
+
+		return {type: 'idle'};
+	}
+
+	/**
+	 * Find an available task to implement
+	 */
+	private async findAvailableTask(
+		acceptedIssues: Issue[],
+	): Promise<{type: 'implement'; task: Task; issue: Issue} | null> {
+		for (const issue of acceptedIssues) {
+			const issueTasks = this.tasks.listTasks(issue.number);
+
+			for (const task of issueTasks) {
+				// Check dependencies are satisfied
+				if (!this.tasks.areDependenciesSatisfied(task)) {
+					continue;
+				}
+
+				// Check if someone is already working on it (branch exists)
+				const branch = `task/${task.id}`;
+				const branchExists = await this.issues.remoteBranchExists(branch);
+				if (branchExists) {
+					continue;
+				}
+
+				return {type: 'implement', task, issue};
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Phase 1: Reconcile — mark issue as completed, close it
+	 */
+	private async reconcile(issue: Issue): Promise<void> {
+		console.log(`Reconciling issue #${issue.number}: ${issue.title}`);
+		console.log('All tasks completed. Marking issue as done.');
+
+		await this.issues.addLabel(issue.number, LABELS.COMPLETED);
+		await this.issues.removeLabel(issue.number, LABELS.TASKS_ACCEPTED);
+		await this.issues.comment(
+			issue.number,
+			`✅ All tasks for this issue have been implemented and merged. Closing.`,
+		);
+		await this.issues.closeIssue(issue.number);
+
+		console.log(`Issue #${issue.number} closed.`);
+	}
+
+	/**
+	 * Phase 2: Investigate — generate tasks for a new issue
+	 */
+	private async investigate(issue: Issue): Promise<void> {
+		console.log(`Investigating issue #${issue.number}: ${issue.title}`);
+
+		// Claim the issue
+		await this.issues.addLabel(issue.number, LABELS.INVESTIGATING);
+
+		const branch = `investigate/${issue.number}`;
+		const issueTasksDir = `tasks/${issue.number}`;
+
+		try {
+			// Create branch from main
+			await this.git.deleteLocalBranch(branch);
+			await this.git.checkout(branch, {create: true, startPoint: 'origin/main'});
+
+			// Run agent to generate tasks
+			const prompt = buildInvestigatePrompt(issue, issueTasksDir);
+			const {exitCode} = await this.agent.run({
+				prompt,
+				workDir: this.config.workDir,
+				logFile: this.config.logFile,
+			});
+
+			if (exitCode !== 0) {
+				console.error(`Agent failed with exit code ${exitCode}`);
+				await this.issues.removeLabel(issue.number, LABELS.INVESTIGATING);
+				await this.git.checkoutMain();
+				return;
+			}
+
+			// Verify task files were created
+			await this.git.verifyBranch(branch);
+			const tasks = this.tasks.listTasks(issue.number);
+			if (tasks.length === 0) {
+				console.error('Agent did not create any task files');
+				await this.issues.removeLabel(issue.number, LABELS.INVESTIGATING);
+				await this.git.checkoutMain();
+				return;
+			}
+
+			// Ensure changes are committed
+			await this.git.commitAll(`tasks(#${issue.number}): generate implementation tasks`);
+
+			console.log(`Generated ${tasks.length} task(s) for issue #${issue.number}`);
+
+			if (this.config.noPush) {
+				console.log(`Branch '${branch}' ready (--no-push mode)`);
+			} else {
+				// Push and create PR
+				await this.git.push(branch);
+
+				const taskList = tasks.map((t) => `- [ ] **${t.id}**: ${t.title}`).join('\n');
+				const prUrl = await this.issues.createPR({
+					head: branch,
+					base: 'main',
+					title: `tasks(#${issue.number}): ${issue.title}`,
+					body: `## Generated Tasks for #${issue.number}\n\n${taskList}\n\n---\n*Generated by whitesmith from issue #${issue.number}*`,
+				});
+
+				await this.issues.removeLabel(issue.number, LABELS.INVESTIGATING);
+				await this.issues.addLabel(issue.number, LABELS.TASKS_PROPOSED);
+				await this.issues.comment(
+					issue.number,
+					`📋 Tasks have been generated. Review the PR: ${prUrl}`,
+				);
+
+				console.log(`PR created: ${prUrl}`);
+			}
+		} catch (error) {
+			console.error('Investigation failed:', error instanceof Error ? error.message : error);
+			await this.issues.removeLabel(issue.number, LABELS.INVESTIGATING);
+		}
+
+		// Return to main
+		await this.git.checkoutMain();
+	}
+
+	/**
+	 * Phase 3: Implement — implement a task and create a PR
+	 */
+	private async implement(task: Task, issue: Issue): Promise<void> {
+		console.log(`Implementing task ${task.id}: ${task.title}`);
+		console.log(`For issue #${issue.number}: ${issue.title}`);
+
+		const branch = `task/${task.id}`;
+
+		try {
+			// Create branch from main
+			await this.git.deleteLocalBranch(branch);
+			await this.git.checkout(branch, {create: true, startPoint: 'origin/main'});
+
+			// Run agent to implement
+			const prompt = buildImplementPrompt(task, issue);
+			const {exitCode} = await this.agent.run({
+				prompt,
+				workDir: this.config.workDir,
+				logFile: this.config.logFile,
+			});
+
+			if (exitCode !== 0) {
+				console.error(`Agent failed with exit code ${exitCode}`);
+				await this.git.checkoutMain();
+				return;
+			}
+
+			// Verify we're still on the right branch
+			await this.git.verifyBranch(branch);
+
+			// Ensure changes are committed
+			await this.git.commitAll(`feat(#${issue.number}): ${task.title}`);
+
+			if (this.config.noPush) {
+				console.log(`Branch '${branch}' ready (--no-push mode)`);
+			} else {
+				// Push and create PR
+				await this.git.push(branch);
+
+				const prUrl = await this.issues.createPR({
+					head: branch,
+					base: 'main',
+					title: `feat(#${issue.number}): ${task.title}`,
+					body: `## Task: ${task.title}\n\nImplements task \`${task.id}\` from issue #${issue.number}.\n\n### From the task spec:\n\n${task.content}\n\n---\n*Implemented by whitesmith*\n\nCloses #${issue.number} (if all tasks are complete)`,
+				});
+
+				console.log(`PR created: ${prUrl}`);
+			}
+		} catch (error) {
+			console.error('Implementation failed:', error instanceof Error ? error.message : error);
+		}
+
+		// Return to main
+		await this.git.checkoutMain();
+	}
+}

package/src/prompts.ts

@@ -0,0 +1,114 @@
+import type {Issue, Task} from './types.js';
+
+/**
+ * Build the prompt for the "investigate" phase.
+ * The agent reads the issue, understands the codebase, and generates task files.
+ */
+export function buildInvestigatePrompt(issue: Issue, issueTasksDir: string): string {
+	return `# Task: Generate implementation tasks for Issue #${issue.number}
+
+## Issue
+**Title:** ${issue.title}
+**URL:** ${issue.url}
+
+### Description
+${issue.body}
+
+## Your Job
+
+You are an AI assistant helping break down a GitHub issue into concrete implementation tasks.
+
+1. **Read and understand** the issue above.
+2. **Explore the codebase** to understand the architecture, conventions, and relevant code.
+3. **Break the issue down** into 1 or more tasks. Each task should represent a single, reviewable PR's worth of work.
+4. **Write task files** to the \`${issueTasksDir}\` directory.
+
+## Task File Format
+
+Each task file should be named \`<seq>-<short-slug>.md\` (e.g., \`001-add-validation.md\`) and contain:
+
+\`\`\`markdown
+---
+id: "${issue.number}-<seq>"
+issue: ${issue.number}
+title: "<concise title>"
+depends_on: []
+---
+
+## Description
+<detailed description of what needs to be done>
+
+## Acceptance Criteria
+- <criterion 1>
+- <criterion 2>
+
+## Implementation Notes
+<any relevant notes about approach, files to modify, etc.>
+\`\`\`
+
+## Rules
+
+- Sequence numbers start at 001 and increment.
+- The \`id\` field must be \`"${issue.number}-<seq>"\` (e.g., "${issue.number}-001").
+- Use \`depends_on\` to list task IDs that must be completed before this task. For example, if task 002 depends on task 001, set \`depends_on: ["${issue.number}-001"]\`.
+- Each task should be a meaningful, self-contained unit of work that results in one PR.
+- Be specific in descriptions and acceptance criteria — another AI agent will implement these.
+- Consider the existing codebase patterns and conventions.
+- Create the \`${issueTasksDir}\` directory if it doesn't exist.
+
+## When Done
+
+After creating all task files, commit your changes:
+\`\`\`
+git add tasks/
+git commit -m "tasks(#${issue.number}): generate implementation tasks"
+\`\`\`
+
+Do NOT push. Do NOT create a PR. The orchestrator will handle that.
+`;
+}
+
+/**
+ * Build the prompt for the "implement" phase.
+ * The agent implements a specific task and deletes the task file.
+ */
+export function buildImplementPrompt(task: Task, issue: Issue): string {
+	return `# Task: Implement "${task.title}"
+
+## Context
+
+You are implementing a task generated from GitHub Issue #${issue.number}: "${issue.title}"
+
+**Issue URL:** ${issue.url}
+**Task ID:** ${task.id}
+**Task File:** ${task.filePath}
+
+## Task Details
+
+${task.content}
+
+## Your Job
+
+1. **Read the task** above carefully.
+2. **Explore the codebase** to understand the architecture and conventions.
+3. **Implement the changes** described in the task.
+4. **Verify** your implementation meets the acceptance criteria.
+5. **Delete the task file** at \`${task.filePath}\` — this marks the task as complete.
+6. **Clean up**: if the task directory \`tasks/${task.issue}/\` is now empty, delete it too.
+7. **Commit** all changes (implementation + task file deletion):
+
+\`\`\`
+git add -A
+git commit -m "feat(#${issue.number}): ${task.title}"
+\`\`\`
+
+## Rules
+
+- Follow existing code conventions and patterns.
+- Make clean, reviewable changes.
+- Do NOT push. Do NOT create a PR. The orchestrator will handle that.
+- Do NOT modify other task files.
+- You MUST delete \`${task.filePath}\` as part of your commit.
+- If the \`tasks/${task.issue}/\` directory is empty after deletion, remove it.
+`;
+}