whitesmith 0.0.0

package/src/providers/github.ts

@@ -0,0 +1,180 @@
+import {exec} from 'node:child_process';
+import {promisify} from 'node:util';
+import type {IssueProvider} from './issue-provider.js';
+import type {Issue} from '../types.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * GitHub Issues provider using the `gh` CLI.
+ */
+export class GitHubProvider implements IssueProvider {
+	private workDir: string;
+	private repo?: string;
+
+	constructor(workDir: string, repo?: string) {
+		this.workDir = workDir;
+		this.repo = repo;
+	}
+
+	private repoFlag(): string {
+		return this.repo ? ` --repo ${this.repo}` : '';
+	}
+
+	private async gh(args: string): Promise<string> {
+		try {
+			const {stdout} = await execAsync(`gh ${args}${this.repoFlag()}`, {
+				cwd: this.workDir,
+				maxBuffer: 10 * 1024 * 1024,
+			});
+			return stdout.trim();
+		} catch (error) {
+			const e = error as {stdout?: string; stderr?: string; message?: string};
+			// Some gh commands return exit code 1 for "not found" results
+			if (e.stdout !== undefined) {
+				return e.stdout.trim();
+			}
+			throw new Error(`gh ${args} failed: ${e.stderr || e.message}`);
+		}
+	}
+
+	async listIssues(options?: {labels?: string[]; noLabels?: string[]}): Promise<Issue[]> {
+		let cmd = 'issue list --state open --json number,title,body,labels,url --limit 100';
+
+		if (options?.labels && options.labels.length > 0) {
+			cmd += ` --label "${options.labels.join(',')}"`;
+		}
+
+		const raw = await this.gh(cmd);
+		if (!raw || raw === '[]') return [];
+
+		const issues: Array<{
+			number: number;
+			title: string;
+			body: string;
+			labels: Array<{name: string}>;
+			url: string;
+		}> = JSON.parse(raw);
+
+		let result: Issue[] = issues.map((i) => ({
+			number: i.number,
+			title: i.title,
+			body: i.body || '',
+			labels: i.labels.map((l) => l.name),
+			url: i.url,
+		}));
+
+		// Client-side filter for "no labels" (gh CLI doesn't support negation)
+		if (options?.noLabels && options.noLabels.length > 0) {
+			result = result.filter((issue) => !issue.labels.some((l) => options.noLabels!.includes(l)));
+		}
+
+		return result;
+	}
+
+	async getIssue(number: number): Promise<Issue> {
+		const raw = await this.gh(`issue view ${number} --json number,title,body,labels,url`);
+		const i = JSON.parse(raw) as {
+			number: number;
+			title: string;
+			body: string;
+			labels: Array<{name: string}>;
+			url: string;
+		};
+		return {
+			number: i.number,
+			title: i.title,
+			body: i.body || '',
+			labels: i.labels.map((l) => l.name),
+			url: i.url,
+		};
+	}
+
+	async addLabel(number: number, label: string): Promise<void> {
+		await this.gh(`issue edit ${number} --add-label "${label}"`);
+	}
+
+	async removeLabel(number: number, label: string): Promise<void> {
+		try {
+			await this.gh(`issue edit ${number} --remove-label "${label}"`);
+		} catch {
+			// Ignore if label wasn't present
+		}
+	}
+
+	async comment(number: number, body: string): Promise<void> {
+		// Use stdin to avoid shell escaping issues
+		await new Promise<void>((resolve, reject) => {
+			const child = exec(
+				`gh issue comment ${number} --body-file -${this.repoFlag()}`,
+				{cwd: this.workDir},
+				(err) => (err ? reject(err) : resolve()),
+			);
+			child.stdin!.write(body);
+			child.stdin!.end();
+		});
+	}
+
+	async closeIssue(number: number): Promise<void> {
+		await this.gh(`issue close ${number}`);
+	}
+
+	async createPR(options: {
+		head: string;
+		base: string;
+		title: string;
+		body: string;
+	}): Promise<string> {
+		const url = await new Promise<string>((resolve, reject) => {
+			const child = exec(
+				`gh pr create --head "${options.head}" --base "${options.base}" --title "${options.title}" --body-file -${this.repoFlag()}`,
+				{cwd: this.workDir},
+				(err, stdout) => (err ? reject(err) : resolve(stdout.trim())),
+			);
+			child.stdin!.write(options.body);
+			child.stdin!.end();
+		});
+		return url;
+	}
+
+	async remoteBranchExists(branch: string): Promise<boolean> {
+		try {
+			const {stdout} = await execAsync(`git ls-remote --heads origin ${branch}`, {
+				cwd: this.workDir,
+			});
+			return stdout.trim().length > 0;
+		} catch {
+			return false;
+		}
+	}
+
+	async getPRForBranch(
+		branch: string,
+	): Promise<{state: 'open' | 'merged' | 'closed'; url: string} | null> {
+		try {
+			const raw = await this.gh(
+				`pr list --head "${branch}" --state all --json state,url --limit 1`,
+			);
+			if (!raw || raw === '[]') return null;
+			const prs = JSON.parse(raw) as Array<{state: string; url: string}>;
+			if (prs.length === 0) return null;
+			const pr = prs[0];
+			const state = pr.state.toLowerCase() as 'open' | 'merged' | 'closed';
+			return {state, url: pr.url};
+		} catch {
+			return null;
+		}
+	}
+
+	async ensureLabels(labels: string[]): Promise<void> {
+		for (const label of labels) {
+			try {
+				await this.gh(
+					`label create "${label}" --force --color 7B68EE --description "whitesmith automation"`,
+				);
+			} catch {
+				// Label might already exist
+			}
+		}
+	}
+}

package/src/providers/index.ts

@@ -0,0 +1,2 @@
+export type {IssueProvider} from './issue-provider.js';
+export {GitHubProvider} from './github.js';

package/src/providers/issue-provider.ts

@@ -0,0 +1,59 @@
+import type {Issue} from '../types.js';
+
+/**
+ * Interface for issue sources.
+ * Implementations can back this with GitHub Issues, GitLab, Jira, etc.
+ */
+export interface IssueProvider {
+	/**
+	 * List open issues, optionally filtered by labels
+	 */
+	listIssues(options?: {labels?: string[]; noLabels?: string[]}): Promise<Issue[]>;
+
+	/**
+	 * Get a single issue by number
+	 */
+	getIssue(number: number): Promise<Issue>;
+
+	/**
+	 * Add a label to an issue
+	 */
+	addLabel(number: number, label: string): Promise<void>;
+
+	/**
+	 * Remove a label from an issue
+	 */
+	removeLabel(number: number, label: string): Promise<void>;
+
+	/**
+	 * Post a comment on an issue
+	 */
+	comment(number: number, body: string): Promise<void>;
+
+	/**
+	 * Close an issue
+	 */
+	closeIssue(number: number): Promise<void>;
+
+	/**
+	 * Create a pull request and return its URL
+	 */
+	createPR(options: {head: string; base: string; title: string; body: string}): Promise<string>;
+
+	/**
+	 * Check if a remote branch exists
+	 */
+	remoteBranchExists(branch: string): Promise<boolean>;
+
+	/**
+	 * Check if there's an open or merged PR for a given head branch
+	 */
+	getPRForBranch(
+		branch: string,
+	): Promise<{state: 'open' | 'merged' | 'closed'; url: string} | null>;
+
+	/**
+	 * Ensure required labels exist in the repo (create if missing)
+	 */
+	ensureLabels(labels: string[]): Promise<void>;
+}

package/src/task-manager.ts

@@ -0,0 +1,190 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {parse as parseYaml, stringify as stringifyYaml} from 'yaml';
+import type {Task, TaskFrontmatter} from './types.js';
+
+const TASKS_DIR = 'tasks';
+
+/**
+ * Manages task files in the tasks/ directory.
+ *
+ * Task files live at: tasks/<issue-number>/<seq>-<slug>.md
+ * Each file has YAML frontmatter with id, issue, title, depends_on.
+ */
+export class TaskManager {
+	private workDir: string;
+
+	constructor(workDir: string) {
+		this.workDir = workDir;
+	}
+
+	/**
+	 * Get the tasks directory path
+	 */
+	getTasksDir(): string {
+		return path.join(this.workDir, TASKS_DIR);
+	}
+
+	/**
+	 * Get the directory for a specific issue's tasks
+	 */
+	getIssueTasksDir(issueNumber: number): string {
+		return path.join(this.workDir, TASKS_DIR, String(issueNumber));
+	}
+
+	/**
+	 * List all pending tasks for an issue (files in tasks/<issue>/)
+	 */
+	listTasks(issueNumber: number): Task[] {
+		const dir = this.getIssueTasksDir(issueNumber);
+		if (!fs.existsSync(dir)) return [];
+
+		const files = fs
+			.readdirSync(dir)
+			.filter((f) => f.endsWith('.md'))
+			.sort();
+
+		return files.map((f) => this.readTask(path.join(dir, f)));
+	}
+
+	/**
+	 * List all pending tasks across all issues
+	 */
+	listAllTasks(): Task[] {
+		const tasksDir = this.getTasksDir();
+		if (!fs.existsSync(tasksDir)) return [];
+
+		const issueDirs = fs
+			.readdirSync(tasksDir)
+			.filter((d) => {
+				const fullPath = path.join(tasksDir, d);
+				return fs.statSync(fullPath).isDirectory() && /^\d+$/.test(d);
+			})
+			.sort();
+
+		const tasks: Task[] = [];
+		for (const issueDir of issueDirs) {
+			const issueNumber = parseInt(issueDir, 10);
+			tasks.push(...this.listTasks(issueNumber));
+		}
+		return tasks;
+	}
+
+	/**
+	 * Check if an issue has any remaining (pending) tasks
+	 */
+	hasRemainingTasks(issueNumber: number): boolean {
+		return this.listTasks(issueNumber).length > 0;
+	}
+
+	/**
+	 * Get issue numbers that have task files
+	 */
+	getIssuesWithTasks(): number[] {
+		const tasksDir = this.getTasksDir();
+		if (!fs.existsSync(tasksDir)) return [];
+
+		return fs
+			.readdirSync(tasksDir)
+			.filter((d) => {
+				const fullPath = path.join(tasksDir, d);
+				return fs.statSync(fullPath).isDirectory() && /^\d+$/.test(d);
+			})
+			.map((d) => parseInt(d, 10))
+			.sort((a, b) => a - b);
+	}
+
+	/**
+	 * Read and parse a single task file
+	 */
+	readTask(filePath: string): Task {
+		const content = fs.readFileSync(filePath, 'utf-8');
+		const frontmatter = this.parseFrontmatter(content);
+		const relativePath = path.relative(this.workDir, filePath);
+
+		return {
+			id: frontmatter.id,
+			issue: frontmatter.issue,
+			title: frontmatter.title,
+			dependsOn: frontmatter.depends_on || [],
+			content,
+			filePath: relativePath,
+		};
+	}
+
+	/**
+	 * Write a task file
+	 */
+	writeTask(
+		issueNumber: number,
+		seq: number,
+		slug: string,
+		frontmatter: TaskFrontmatter,
+		body: string,
+	): string {
+		const dir = this.getIssueTasksDir(issueNumber);
+		fs.mkdirSync(dir, {recursive: true});
+
+		const seqStr = String(seq).padStart(3, '0');
+		const fileName = `${seqStr}-${slug}.md`;
+		const filePath = path.join(dir, fileName);
+
+		const content = `---\n${stringifyYaml(frontmatter).trim()}\n---\n\n${body}`;
+		fs.writeFileSync(filePath, content, 'utf-8');
+
+		return path.relative(this.workDir, filePath);
+	}
+
+	/**
+	 * Delete a task file (called when task is implemented)
+	 */
+	deleteTask(taskFilePath: string): void {
+		const fullPath = path.resolve(this.workDir, taskFilePath);
+		if (fs.existsSync(fullPath)) {
+			fs.unlinkSync(fullPath);
+		}
+
+		// Clean up empty issue directory
+		const dir = path.dirname(fullPath);
+		if (fs.existsSync(dir)) {
+			const remaining = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+			if (remaining.length === 0) {
+				// Remove directory if no more task files
+				fs.rmSync(dir, {recursive: true, force: true});
+			}
+		}
+	}
+
+	/**
+	 * Check if all dependencies of a task are satisfied
+	 * (i.e. their task files have been deleted from the tasks directory)
+	 */
+	areDependenciesSatisfied(task: Task): boolean {
+		if (task.dependsOn.length === 0) return true;
+
+		const allTasks = this.listAllTasks();
+		const pendingIds = new Set(allTasks.map((t) => t.id));
+
+		// A dependency is satisfied if its task file no longer exists (deleted = completed)
+		return task.dependsOn.every((depId) => !pendingIds.has(depId));
+	}
+
+	/**
+	 * Parse YAML frontmatter from a markdown file
+	 */
+	private parseFrontmatter(content: string): TaskFrontmatter {
+		const match = content.match(/^---\n([\s\S]*?)\n---/);
+		if (!match) {
+			throw new Error('Task file is missing YAML frontmatter');
+		}
+
+		const parsed = parseYaml(match[1]) as TaskFrontmatter;
+		if (!parsed.id || parsed.issue === undefined || !parsed.title) {
+			throw new Error(
+				`Task frontmatter is missing required fields (id, issue, title). Got: ${JSON.stringify(parsed)}`,
+			);
+		}
+
+		return parsed;
+	}
+}

package/src/types.ts

@@ -0,0 +1,88 @@
+/**
+ * A GitHub issue (or equivalent) created by a human.
+ * Represents a problem, feature request, or improvement.
+ */
+export interface Issue {
+	/** Issue number (e.g. 42) */
+	number: number;
+	/** Issue title */
+	title: string;
+	/** Issue body/description (markdown) */
+	body: string;
+	/** Current labels on the issue */
+	labels: string[];
+	/** Issue URL */
+	url: string;
+}
+
+/**
+ * A task generated from an issue.
+ * Each task represents a single PR's worth of work.
+ */
+export interface Task {
+	/** Unique task ID: "<issue>-<seq>" e.g. "42-001" */
+	id: string;
+	/** Parent issue number */
+	issue: number;
+	/** Human-readable title */
+	title: string;
+	/** Task IDs this depends on (must be completed first) */
+	dependsOn: string[];
+	/** Full markdown content of the task file (including frontmatter) */
+	content: string;
+	/** File path relative to repo root */
+	filePath: string;
+}
+
+/**
+ * Parsed frontmatter from a task file
+ */
+export interface TaskFrontmatter {
+	id: string;
+	issue: number;
+	title: string;
+	depends_on?: string[];
+}
+
+/**
+ * Labels used by whitesmith to track issue state
+ */
+export const LABELS = {
+	/** Agent is generating tasks for this issue */
+	INVESTIGATING: 'whitesmith:investigating',
+	/** A PR with generated tasks has been opened */
+	TASKS_PROPOSED: 'whitesmith:tasks-proposed',
+	/** Task PR has been merged — tasks are on main */
+	TASKS_ACCEPTED: 'whitesmith:tasks-accepted',
+	/** All tasks for this issue have been completed */
+	COMPLETED: 'whitesmith:completed',
+} as const;
+
+/**
+ * Configuration for whitesmith
+ */
+export interface DevPulseConfig {
+	/** Command to run the agent harness */
+	agentCmd: string;
+	/** Maximum iterations per run */
+	maxIterations: number;
+	/** Working directory (the repo) */
+	workDir: string;
+	/** Skip pushing branches and creating PRs */
+	noPush: boolean;
+	/** Skip sleep between iterations (for testing) */
+	noSleep: boolean;
+	/** Log file path */
+	logFile?: string;
+	/** GitHub repo in "owner/repo" format (auto-detected if not set) */
+	repo?: string;
+}
+
+/**
+ * What the orchestrator should do next
+ */
+export type Action =
+	| {type: 'reconcile'; issue: Issue}
+	| {type: 'investigate'; issue: Issue}
+	| {type: 'implement'; task: Task; issue: Issue}
+	| {type: 'idle'};