whitesmith 0.0.0 → 0.0.2

package/src/comment.ts

@@ -0,0 +1,531 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type {AgentHarness} from './harnesses/agent-harness.js';
+import type {IssueProvider} from './providers/issue-provider.js';
+import {GitManager} from './git.js';
+import {TaskManager} from './task-manager.js';
+import {LABELS} from './types.js';
+
+export interface CommentConfig {
+	/** Issue or PR number */
+	number: number;
+	/** The comment body text */
+	commentBody: string;
+	/** Working directory (the repo) */
+	workDir: string;
+	/** GitHub repo in "owner/repo" format (auto-detected if not set) */
+	repo?: string;
+	/** Log file path */
+	logFile?: string;
+	/** Whether to post the response as a GitHub comment (issue-only) */
+	post: boolean;
+}
+
+/** A related PR with its metadata */
+interface RelatedPR {
+	branch: string;
+	number: number;
+	title: string;
+	state: string;
+	url: string;
+}
+
+/** Whitesmith context gathered for prompts */
+interface WhitesmithContext {
+	/** The issue this comment relates to (for PR comments, the parent issue) */
+	parentIssue?: {number: number; title: string; body: string; url: string; labels: string[]};
+	/** Task proposal PR (investigate/<N>) */
+	taskPR?: RelatedPR;
+	/** Implementation PRs (task/<N>-*) */
+	implementationPRs: RelatedPR[];
+	/** Task files on the current branch (if tasks-accepted) */
+	tasks: Array<{id: string; title: string; filePath: string}>;
+	/** Whitesmith state label, if any */
+	stateLabel?: string;
+	/** The issue/PR number (used to tell the agent how to fetch comments) */
+	number: number;
+}
+
+/**
+ * Handle a comment on a PR.
+ */
+export async function handlePRComment(
+	config: CommentConfig,
+	issues: IssueProvider,
+	agent: AgentHarness,
+): Promise<void> {
+	const git = new GitManager(config.workDir);
+
+	// Get PR details
+	const pr = await issues.getPR(config.number);
+	if (!pr) {
+		throw new Error(`Could not find PR #${config.number}`);
+	}
+
+	console.log(`PR #${config.number}: ${pr.title}`);
+	console.log(`Branch: ${pr.branch}`);
+
+	// Clean up temp files before checkout to avoid conflicts
+	git.cleanupTempFiles();
+
+	// Checkout PR branch
+	await git.fetch();
+	await git.checkout(pr.branch);
+
+	// Gather whitesmith context based on branch naming
+	const context = await gatherContextForPR(pr.branch, config.workDir, issues, config.number);
+
+	const responseFile = '.whitesmith-response.md';
+
+	const prompt = buildPRCommentPrompt({
+		title: pr.title,
+		url: pr.url,
+		number: config.number,
+		body: pr.body,
+		branch: pr.branch,
+		commentBody: config.commentBody,
+		context,
+		responseFile,
+	});
+
+	const {exitCode} = await agent.run({
+		prompt,
+		workDir: config.workDir,
+		logFile: config.logFile,
+	});
+
+	if (exitCode !== 0) {
+		throw new Error(`Agent failed with exit code ${exitCode}`);
+	}
+
+	// Read the response file before committing (so it doesn't get committed)
+	const responsePath = path.join(config.workDir, responseFile);
+	let response: string | null = null;
+	if (fs.existsSync(responsePath)) {
+		response = fs.readFileSync(responsePath, 'utf-8');
+		try {
+			fs.unlinkSync(responsePath);
+		} catch {
+			// ignore
+		}
+	}
+
+	// Commit and push any changes
+	const committed = await git.commitAll(`fix(#${config.number}): address review comment`);
+	if (committed) {
+		await git.forcePush(pr.branch);
+		console.log(`Changes pushed to ${pr.branch}`);
+	} else {
+		console.log('No changes to commit.');
+	}
+
+	// Post the response as a PR comment
+	if (response) {
+		if (config.post) {
+			await issues.comment(config.number, response);
+			console.log(`Response posted as comment on PR #${config.number}`);
+		} else {
+			process.stdout.write(response);
+		}
+	} else {
+		console.log('Agent did not produce a response file.');
+	}
+}
+
+/**
+ * Handle a comment on an issue (not a PR).
+ */
+export async function handleIssueComment(
+	config: CommentConfig,
+	issues: IssueProvider,
+	agent: AgentHarness,
+): Promise<void> {
+	const git = new GitManager(config.workDir);
+	const issue = await issues.getIssue(config.number);
+	console.log(`Issue #${config.number}: ${issue.title}`);
+
+	// Fetch so the agent can checkout related PR branches if needed
+	await git.fetch();
+
+	// Gather whitesmith context for this issue
+	const context = await gatherContextForIssue(config.number, config.workDir, issues);
+
+	const responseFile = '.whitesmith-response.md';
+	const prompt = buildIssueCommentPrompt({
+		title: issue.title,
+		url: issue.url,
+		number: config.number,
+		body: issue.body,
+		commentBody: config.commentBody,
+		responseFile,
+		context,
+	});
+
+	const {exitCode} = await agent.run({
+		prompt,
+		workDir: config.workDir,
+		logFile: config.logFile,
+	});
+
+	if (exitCode !== 0) {
+		throw new Error(`Agent failed with exit code ${exitCode}`);
+	}
+
+	// Read the response file
+	const responsePath = path.join(config.workDir, responseFile);
+
+	if (!fs.existsSync(responsePath)) {
+		console.error('Agent did not produce a response file.');
+		process.exitCode = 1;
+		return;
+	}
+
+	const response = fs.readFileSync(responsePath, 'utf-8');
+
+	// Clean up the response file
+	try {
+		fs.unlinkSync(responsePath);
+	} catch {
+		// ignore
+	}
+
+	if (config.post) {
+		await issues.comment(config.number, response);
+		console.log(`Response posted as comment on issue #${config.number}`);
+	} else {
+		// Print to stdout
+		process.stdout.write(response);
+	}
+}
+
+/**
+ * Detect whether a given number is a PR or an issue.
+ */
+export async function isPullRequest(issues: IssueProvider, number: number): Promise<boolean> {
+	const pr = await issues.getPR(number);
+	return pr !== null;
+}
+
+// --- Context gathering ---
+
+/**
+ * Parse a whitesmith branch name to extract the issue number.
+ *
+ * - `investigate/<N>` → issue N (task proposal PR)
+ * - `task/<N>-<seq>` → issue N (implementation PR)
+ */
+function parseWhitesmithBranch(
+	branch: string,
+): {type: 'investigate' | 'task'; issueNumber: number; taskId?: string} | null {
+	const investigateMatch = branch.match(/^investigate\/(\d+)$/);
+	if (investigateMatch) {
+		return {type: 'investigate', issueNumber: parseInt(investigateMatch[1], 10)};
+	}
+
+	const taskMatch = branch.match(/^task\/(\d+)-(\d+.*)$/);
+	if (taskMatch) {
+		return {
+			type: 'task',
+			issueNumber: parseInt(taskMatch[1], 10),
+			taskId: `${taskMatch[1]}-${taskMatch[2]}`,
+		};
+	}
+
+	return null;
+}
+
+/**
+ * Gather whitesmith context for a PR comment based on its branch name.
+ */
+async function gatherContextForPR(
+	branch: string,
+	workDir: string,
+	issues: IssueProvider,
+	commentNumber: number,
+): Promise<WhitesmithContext> {
+	const context: WhitesmithContext = {implementationPRs: [], tasks: [], number: commentNumber};
+
+	const parsed = parseWhitesmithBranch(branch);
+	if (!parsed) return context;
+
+	// Fetch the parent issue
+	try {
+		const issue = await issues.getIssue(parsed.issueNumber);
+		context.parentIssue = {
+			number: issue.number,
+			title: issue.title,
+			body: issue.body,
+			url: issue.url,
+			labels: issue.labels,
+		};
+		context.stateLabel = issue.labels.find((l) => l.startsWith('whitesmith:'));
+	} catch {
+		// Issue might not exist
+	}
+
+	// Find related PRs for this issue
+	await gatherRelatedPRs(parsed.issueNumber, issues, context);
+
+	// If tasks are on main, list them
+	const taskManager = new TaskManager(workDir);
+	context.tasks = taskManager.listTasks(parsed.issueNumber).map((t) => ({
+		id: t.id,
+		title: t.title,
+		filePath: t.filePath,
+	}));
+
+	return context;
+}
+
+/**
+ * Gather whitesmith context for an issue comment.
+ */
+async function gatherContextForIssue(
+	issueNumber: number,
+	workDir: string,
+	issues: IssueProvider,
+): Promise<WhitesmithContext> {
+	const context: WhitesmithContext = {implementationPRs: [], tasks: [], number: issueNumber};
+
+	// Get the issue's labels for state
+	try {
+		const issue = await issues.getIssue(issueNumber);
+		context.stateLabel = issue.labels.find((l) => l.startsWith('whitesmith:'));
+	} catch {
+		// ignore
+	}
+
+	// Find related PRs
+	await gatherRelatedPRs(issueNumber, issues, context);
+
+	// List tasks on main
+	const taskManager = new TaskManager(workDir);
+	context.tasks = taskManager.listTasks(issueNumber).map((t) => ({
+		id: t.id,
+		title: t.title,
+		filePath: t.filePath,
+	}));
+
+	return context;
+}
+
+/**
+ * Find task proposal and implementation PRs related to an issue.
+ */
+async function gatherRelatedPRs(
+	issueNumber: number,
+	issues: IssueProvider,
+	context: WhitesmithContext,
+): Promise<void> {
+	// Task proposal PR
+	const taskPR = await issues.getPRForBranch(`investigate/${issueNumber}`);
+	if (taskPR) {
+		context.taskPR = {
+			branch: `investigate/${issueNumber}`,
+			number: taskPR.number,
+			title: '',
+			state: taskPR.state,
+			url: taskPR.url,
+		};
+	}
+
+	// Implementation PRs
+	const implPRs = await issues.listPRsByBranchPrefix(`task/${issueNumber}-`);
+	context.implementationPRs = implPRs;
+}
+
+// --- Prompt builders ---
+
+function formatWhitesmithContext(context: WhitesmithContext): string {
+	const sections: string[] = [];
+
+	if (context.stateLabel) {
+		const stateDescriptions: Record<string, string> = {
+			[LABELS.INVESTIGATING]:
+				'The agent is currently investigating this issue and generating tasks.',
+			[LABELS.TASKS_PROPOSED]: 'Tasks have been proposed in a PR and are awaiting review.',
+			[LABELS.TASKS_ACCEPTED]: 'Tasks have been accepted and are being implemented.',
+			[LABELS.COMPLETED]: 'All tasks for this issue have been completed.',
+		};
+		const desc = stateDescriptions[context.stateLabel] || context.stateLabel;
+		sections.push(`### Whitesmith State\n\n**${context.stateLabel}**: ${desc}`);
+	}
+
+	if (context.parentIssue) {
+		sections.push(
+			`### Parent Issue\n\n` +
+				`- **Title:** ${context.parentIssue.title}\n` +
+				`- **URL:** ${context.parentIssue.url}\n` +
+				`- **Number:** #${context.parentIssue.number}\n` +
+				`- **Labels:** ${context.parentIssue.labels.join(', ') || 'none'}\n\n` +
+				`#### Issue Description\n\n${context.parentIssue.body}`,
+		);
+	}
+
+	if (context.taskPR) {
+		sections.push(
+			`### Task Proposal PR\n\n` +
+				`- **Branch:** \`${context.taskPR.branch}\`\n` +
+				`- **State:** ${context.taskPR.state}\n` +
+				`- **URL:** ${context.taskPR.url}`,
+		);
+	}
+
+	if (context.implementationPRs.length > 0) {
+		const prList = context.implementationPRs
+			.map((pr) => `- **#${pr.number}** ${pr.title} — \`${pr.branch}\` (${pr.state}) — ${pr.url}`)
+			.join('\n');
+		sections.push(`### Implementation PRs\n\n${prList}`);
+	}
+
+	if (context.tasks.length > 0) {
+		const taskList = context.tasks
+			.map((t) => `- **${t.id}**: ${t.title} (\`${t.filePath}\`)`)
+			.join('\n');
+		sections.push(`### Pending Tasks\n\n${taskList}`);
+	}
+
+	sections.push(
+		`### Conversation History\n\n` +
+			`Previous comments are **not** included here to save context space. ` +
+			`If you need to read the conversation history, run:\n\n` +
+			`\`\`\`bash\ngh issue view ${context.number} --comments\n\`\`\``,
+	);
+
+	if (sections.length === 0) {
+		return '';
+	}
+
+	return (
+		`\n## Whitesmith Context\n\n` +
+		`The following is the current whitesmith pipeline state and conversation history related to this issue/PR. ` +
+		`Use this context to provide informed responses.\n\n` +
+		sections.join('\n\n') +
+		'\n'
+	);
+}
+
+interface PRCommentPromptArgs {
+	title: string;
+	url: string;
+	number: number;
+	body: string;
+	branch: string;
+	commentBody: string;
+	context: WhitesmithContext;
+	responseFile: string;
+}
+
+function buildPRCommentPrompt(args: PRCommentPromptArgs): string {
+	return `# Agent Task from PR Comment
+
+## Pull Request
+
+- **Title:** ${args.title}
+- **URL:** ${args.url}
+- **PR Number:** #${args.number}
+- **Branch:** ${args.branch}
+
+### PR Description
+
+${args.body}
+${formatWhitesmithContext(args.context)}
+## Triggering Comment
+
+${args.commentBody}
+
+## Instructions
+
+You are responding to a comment on a pull request. The comment may be a question, feedback,
+a request for changes, or a general discussion point.
+
+1. You are already on the PR branch: \`${args.branch}\`
+2. Read and understand the comment.
+3. Review the whitesmith context above to understand the pipeline state.
+4. You have full access to the repository code — read files, explore the codebase as needed.
+5. If the comment requests code changes, make them. Do NOT commit — the caller will handle committing and pushing.
+6. **Always** write a response in Markdown to the file \`${args.responseFile}\`. This will be posted as a reply comment on the PR.
+   - If you made changes, summarize what you changed and why.
+   - If the comment is a question or discussion, provide a thoughtful answer.
+   - Be thorough but concise.
+
+Do NOT push. Do NOT create a new PR. Do NOT commit. The caller handles all of that.
+`;
+}
+
+interface IssueCommentPromptArgs {
+	title: string;
+	url: string;
+	number: number;
+	body: string;
+	commentBody: string;
+	responseFile: string;
+	context: WhitesmithContext;
+}
+
+function buildIssueCommentPrompt(args: IssueCommentPromptArgs): string {
+	// Build the list of related PR branches the agent can work on
+	const relatedBranches: string[] = [];
+	if (args.context.taskPR && args.context.taskPR.state === 'open') {
+		relatedBranches.push(args.context.taskPR.branch);
+	}
+	for (const pr of args.context.implementationPRs) {
+		if (pr.state === 'open') {
+			relatedBranches.push(pr.branch);
+		}
+	}
+
+	let workOnPRInstructions = '';
+	if (relatedBranches.length > 0) {
+		const branchList = relatedBranches.map((b) => `  - \`${b}\``).join('\n');
+		workOnPRInstructions = `
+
+### Working on related PRs
+
+If the comment asks you to make changes to a related PR (e.g. update the task plan,
+fix something in an implementation), you **can and should** do so. The related open PR branches are:
+
+${branchList}
+
+To work on a PR branch:
+
+1. \`git checkout <branch>\` (branches have been fetched already)
+2. Make your changes.
+3. Commit with a descriptive message.
+4. \`git push origin <branch>\`
+5. Still write \`${args.responseFile}\` summarizing what you did.
+
+When done, \`git checkout main\` to return to the default branch.`;
+	}
+
+	return `# Agent Task from Issue Comment
+
+## Issue
+
+- **Title:** ${args.title}
+- **URL:** ${args.url}
+- **Issue Number:** #${args.number}
+
+### Issue Description
+
+${args.body}
+${formatWhitesmithContext(args.context)}
+## Triggering Comment
+
+${args.commentBody}
+
+## Instructions
+
+You are responding to a comment on an issue.
+
+1. Read and understand the issue description and the triggering comment.
+2. Review the whitesmith context above to understand what work is already in progress.
+3. You have full access to the repository code — read files, explore the codebase as needed.
+4. Analyze the request and formulate a helpful response.
+5. Write your response in Markdown to the file \`${args.responseFile}\`.
+
+Your response will be posted as a comment on the issue.
+Be thorough but concise. Include code snippets, file references, or suggestions as appropriate.
+If there are pending PRs or tasks, reference them in your response when relevant.${workOnPRInstructions}
+`;
+}

package/src/git.ts

@@ -1,4 +1,6 @@
 import {exec} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {promisify} from 'node:util';
 
 const execAsync = promisify(exec);
@@ -25,6 +27,21 @@ export class GitManager {
 		return this.git('rev-parse --abbrev-ref HEAD');
 	}
 
+	/**
+	 * Remove all .whitesmith-* temp files from the working directory.
+	 */
+	cleanupTempFiles(): void {
+		for (const entry of fs.readdirSync(this.workDir)) {
+			if (entry.startsWith('.whitesmith-')) {
+				try {
+					fs.unlinkSync(path.join(this.workDir, entry));
+				} catch {
+					// ignore
+				}
+			}
+		}
+	}
+
 	/**
 	 * Fetch latest from origin
 	 */
@@ -56,25 +73,30 @@ export class GitManager {
 	 * Stage all changes and commit
 	 */
 	async commitAll(message: string, exclude?: string[]): Promise<boolean> {
+		// Always exclude whitesmith temp files
+		const allExclude = ['.whitesmith-*', ...(exclude || [])];
+
+		// Remove any whitesmith temp files from the working tree
+		this.cleanupTempFiles();
+
 		// 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
-				}
+		// Add all then unstage excluded patterns
+		await this.git('add -A');
+		for (const pattern of allExclude) {
+			try {
+				await this.git(`reset HEAD -- ${pattern}`);
+			} catch {
+				// File might not be staged
 			}
-		} else {
-			await this.git('add -A');
 		}
 
+		// Check if anything is still staged after exclusions
+		const staged = await this.git('diff --cached --name-only');
+		if (!staged) return false;
+
 		await this.git(`commit -m "${message.replace(/"/g, '\\"')}"`);
 		return true;
 	}
@@ -136,6 +158,30 @@ export class GitManager {
 		}
 	}
 
+	/**
+	 * Check if a file exists on a remote ref (without checking out)
+	 */
+	async remoteFileExists(ref: string, filePath: string): Promise<boolean> {
+		try {
+			await this.git(`show ${ref}:${filePath}`);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Check if a path has any files on a remote ref (without checking out)
+	 */
+	async remotePathHasFiles(ref: string, dirPath: string): Promise<boolean> {
+		try {
+			const result = await this.git(`ls-tree ${ref} -- ${dirPath}`);
+			return result.length > 0;
+		} catch {
+			return false;
+		}
+	}
+
 	/**
 	 * Verify we're on the expected branch
 	 */

package/src/harnesses/agent-harness.ts

@@ -3,6 +3,12 @@
  * Implementations wrap specific tools (pi, claude CLI, aider, etc.)
  */
 export interface AgentHarness {
+	/**
+	 * Validate that the agent is available and properly configured.
+	 * Throws an error with a descriptive message if validation fails.
+	 */
+	validate(): Promise<void>;
+
 	/**
 	 * Run the agent with a prompt and return its output.
 	 * The agent is expected to execute in the given working directory.
@@ -13,3 +19,12 @@ export interface AgentHarness {
 		logFile?: string;
 	}): Promise<{output: string; exitCode: number}>;
 }
+
+export interface AgentHarnessConfig {
+	/** Command to invoke the agent (e.g. 'pi') */
+	cmd: string;
+	/** AI provider name (e.g. 'anthropic', 'openai') */
+	provider: string;
+	/** AI model ID (e.g. 'claude-opus-4-6') */
+	model: string;
+}

package/src/harnesses/index.ts

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