@backburner/cli 0.1.0

package/dist/src/state/loader.js

@@ -0,0 +1,473 @@
+import * as path from "node:path";
+import { ProviderLimitStateFileSchema } from "../config/schemas.js";
+import { readJsonFileIfExists, writeJsonFileAtomic } from "../utils/json.js";
+import { outputsStateRoot, outputsLogsRoot } from "../utils/paths.js";
+export class StateStore {
+    stateDir;
+    executionDir;
+    constructor(baseDirOrOptions = { stateDir: outputsStateRoot, executionDir: outputsLogsRoot }) {
+        if (typeof baseDirOrOptions === "string") {
+            this.stateDir = baseDirOrOptions;
+            this.executionDir = baseDirOrOptions;
+            return;
+        }
+        const hasExplicitStateDir = baseDirOrOptions.stateDir !== undefined;
+        this.stateDir = baseDirOrOptions.stateDir ?? outputsStateRoot;
+        this.executionDir =
+            baseDirOrOptions.executionDir ??
+                (hasExplicitStateDir ? this.stateDir : outputsLogsRoot);
+    }
+    async load() {
+        const issuesState = await this.loadIssueState();
+        const prsState = await this.loadPullRequestState();
+        const commentsState = await this.loadCommentState();
+        const state = {
+            issueMetadata: issuesState.metadata,
+            prMetadata: prsState.metadata,
+            commentMetadata: commentsState.metadata,
+            issues: issuesState.issues,
+            prs: prsState.prs,
+            comments: commentsState.comments,
+            tasks: await this.loadArrayFile(this.stateDir, "tasks.json", "tasks"),
+            executions: await this.loadArrayFile(this.executionDir, "executions.json", "executions"),
+            worktrees: await this.loadArrayFile(this.stateDir, "worktrees.json", "worktrees"),
+            workstreams: await this.loadArrayFile(this.stateDir, "workstreams.json", "workstreams"),
+            attention: await this.loadArrayFile(this.stateDir, "attention.json", "attention"),
+            repos: await this.loadArrayFile(this.stateDir, "repos.json", "repos"),
+            providerSessions: await this.loadArrayFile(this.stateDir, "provider-sessions.json", "providerSessions"),
+            jobAgentAssignments: await this.loadArrayFile(this.stateDir, "job-agent-assignments.json", "assignments"),
+            retrospectiveCandidates: await this.loadArrayFile(this.stateDir, "retrospective-candidates.json", "retrospectiveCandidates"),
+            retrospectiveProblems: await this.loadArrayFile(this.stateDir, "retrospective-problems.json", "retrospectiveProblems"),
+            retrospectiveOpportunities: await this.loadArrayFile(this.stateDir, "retrospective-opportunities.json", "retrospectiveOpportunities"),
+            learningProposals: await this.loadArrayFile(this.stateDir, "learning-proposals.json", "learningProposals"),
+            managementPrs: await this.loadArrayFile(this.stateDir, "management-prs.json", "managementPrs"),
+            mcpStatuses: await this.loadArrayFile(this.stateDir, "mcp-status.json", "mcpStatuses"),
+            workspaceRecoveries: await this.loadArrayFile(this.stateDir, "workspace-recovery.json", "records"),
+            providerLimits: await this.loadProviderLimitsState()
+        };
+        return state;
+    }
+    async writeRepoSyncState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "repos.json"), {
+            repos: [...records].sort(compareRepoSyncRecords).map(sortRepoSyncRecord)
+        });
+    }
+    async writeEntityState(snapshot) {
+        await Promise.all([
+            writeJsonFileAtomic(path.join(this.stateDir, "issues.json"), {
+                metadata: sortMetadata(snapshot.issueMetadata),
+                issues: [...snapshot.issues].sort(compareIssueLikeEntities)
+            }),
+            writeJsonFileAtomic(path.join(this.stateDir, "prs.json"), {
+                metadata: sortMetadata(snapshot.prMetadata),
+                prs: [...snapshot.prs].sort(compareIssueLikeEntities)
+            }),
+            writeJsonFileAtomic(path.join(this.stateDir, "comments.json"), {
+                metadata: sortMetadata(snapshot.commentMetadata),
+                comments: [...snapshot.comments].sort(compareComments)
+            })
+        ]);
+    }
+    async writeTaskState(tasks) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "tasks.json"), {
+            tasks: [...tasks].sort(compareTasks)
+        });
+    }
+    async writeExecutionState(executions) {
+        await writeJsonFileAtomic(path.join(this.executionDir, "executions.json"), {
+            executions: [...executions].sort(compareExecutions)
+        });
+    }
+    async writeWorktreeState(worktrees) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "worktrees.json"), {
+            worktrees: [...worktrees].sort(compareWorktrees)
+        });
+    }
+    async writeWorkstreamState(workstreams) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "workstreams.json"), {
+            workstreams: [...workstreams].sort(compareWorkstreams)
+        });
+    }
+    async writeAttentionState(attention) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "attention.json"), {
+            attention: [...attention].sort(compareAttentionRecords).map(sortAttentionRecord)
+        });
+    }
+    async writeProviderSessionState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "provider-sessions.json"), {
+            providerSessions: [...records].sort(compareProviderSessions)
+        });
+    }
+    async writeJobAgentAssignmentState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "job-agent-assignments.json"), {
+            assignments: [...records].sort(compareJobAgentAssignments)
+        });
+    }
+    async writeRetrospectiveCandidateState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "retrospective-candidates.json"), {
+            retrospectiveCandidates: [...records].sort(compareRetrospectiveCandidates)
+        });
+    }
+    async writeRetrospectiveProblemState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "retrospective-problems.json"), {
+            retrospectiveProblems: [...records].sort(compareRetrospectiveProblems)
+        });
+    }
+    async writeRetrospectiveOpportunityState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "retrospective-opportunities.json"), {
+            retrospectiveOpportunities: [...records].sort(compareLearningOpportunities)
+        });
+    }
+    async writeLearningProposalState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "learning-proposals.json"), {
+            learningProposals: [...records].sort(compareLearningProposals)
+        });
+    }
+    async writeManagementPrState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "management-prs.json"), {
+            managementPrs: [...records].sort(compareManagementPrs)
+        });
+    }
+    async writeMcpStatusState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "mcp-status.json"), {
+            mcpStatuses: [...records].sort((a, b) => a.handle.localeCompare(b.handle))
+        });
+    }
+    async writeWorkspaceRecoveryState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "workspace-recovery.json"), {
+            records: [...records].sort(compareWorkspaceRecoveryRecords)
+        });
+    }
+    async writeProviderLimitState(records) {
+        await writeJsonFileAtomic(path.join(this.stateDir, "provider-limits.json"), {
+            providerLimits: [...records].sort(compareProviderLimits)
+        });
+    }
+    async loadWorkspaceRecoveryState() {
+        return this.loadArrayFile(this.stateDir, "workspace-recovery.json", "records");
+    }
+    async loadProviderLimitsState() {
+        const filePath = path.join(this.stateDir, "provider-limits.json");
+        const existing = await readJsonFileIfExists(filePath);
+        if (!existing) {
+            return [];
+        }
+        const result = ProviderLimitStateFileSchema.safeParse(existing);
+        if (!result.success) {
+            console.error(`Failed to parse provider limits state file from ${filePath}.\n` +
+                `Rejected payload: ${JSON.stringify(existing, null, 2)}\n` +
+                `Reason: ${result.error.message}`);
+            throw result.error;
+        }
+        return result.data.providerLimits;
+    }
+    async loadArrayFile(baseDir, fileName, key) {
+        const filePath = path.join(baseDir, fileName);
+        const existing = await readJsonFileIfExists(filePath);
+        if (!existing) {
+            const defaultValue = { [key]: [] };
+            await writeJsonFileAtomic(filePath, defaultValue);
+            return defaultValue[key];
+        }
+        const value = existing[key];
+        if (!Array.isArray(value)) {
+            throw new Error(`${filePath}: "${key}" must be an array`);
+        }
+        return value;
+    }
+    async loadIssueState() {
+        const value = await this.loadEntityFile("issues.json", "issues");
+        return {
+            metadata: value.metadata,
+            issues: value.records
+        };
+    }
+    async loadPullRequestState() {
+        const value = await this.loadEntityFile("prs.json", "prs");
+        return {
+            metadata: value.metadata,
+            prs: value.records
+        };
+    }
+    async loadCommentState() {
+        const value = await this.loadEntityFile("comments.json", "comments");
+        return {
+            metadata: value.metadata,
+            comments: value.records
+        };
+    }
+    async loadEntityFile(fileName, key) {
+        const filePath = path.join(this.stateDir, fileName);
+        const existing = await readJsonFileIfExists(filePath);
+        if (!existing) {
+            const defaultValue = {
+                metadata: defaultEntityStateMetadata(),
+                [key]: []
+            };
+            await writeJsonFileAtomic(filePath, defaultValue);
+            return {
+                metadata: defaultValue.metadata,
+                records: defaultValue[key]
+            };
+        }
+        const entities = existing[key];
+        if (!Array.isArray(entities)) {
+            throw new Error(`${filePath}: "${key}" must be an array`);
+        }
+        const metadata = validateMetadata(existing.metadata, filePath);
+        return {
+            metadata,
+            records: entities
+        };
+    }
+}
+export async function loadState(baseDirOrOptions = { stateDir: outputsStateRoot, executionDir: outputsLogsRoot }) {
+    return new StateStore(baseDirOrOptions).load();
+}
+function defaultEntityStateMetadata() {
+    return {
+        partialFailures: []
+    };
+}
+function validateMetadata(value, filePath) {
+    if (value === undefined) {
+        return defaultEntityStateMetadata();
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${filePath}: "metadata" must be an object when provided`);
+    }
+    const metadata = value;
+    const partialFailures = metadata.partialFailures;
+    if (partialFailures !== undefined && !Array.isArray(partialFailures)) {
+        throw new Error(`${filePath}: "metadata.partialFailures" must be an array when provided`);
+    }
+    return {
+        ...(typeof metadata.generatedAt === "string" ? { generatedAt: metadata.generatedAt } : {}),
+        ...(typeof metadata.repoCount === "number" ? { repoCount: metadata.repoCount } : {}),
+        ...(typeof metadata.entityCount === "number" ? { entityCount: metadata.entityCount } : {}),
+        partialFailures: sortFailures(partialFailures ?? [])
+    };
+}
+function sortMetadata(metadata) {
+    return {
+        ...(metadata.generatedAt ? { generatedAt: metadata.generatedAt } : {}),
+        ...(metadata.repoCount !== undefined ? { repoCount: metadata.repoCount } : {}),
+        ...(metadata.entityCount !== undefined ? { entityCount: metadata.entityCount } : {}),
+        partialFailures: sortFailures(metadata.partialFailures)
+    };
+}
+function sortFailures(failures) {
+    return [...failures].sort((left, right) => {
+        const repoComparison = left.repoSlug.localeCompare(right.repoSlug);
+        if (repoComparison !== 0) {
+            return repoComparison;
+        }
+        const stepComparison = left.step.localeCompare(right.step);
+        if (stepComparison !== 0) {
+            return stepComparison;
+        }
+        return left.scope.localeCompare(right.scope);
+    });
+}
+function compareIssueLikeEntities(left, right) {
+    const repoComparison = left.repoSlug.localeCompare(right.repoSlug);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    if (left.number !== right.number) {
+        return left.number - right.number;
+    }
+    return left.id.localeCompare(right.id);
+}
+function compareComments(left, right) {
+    const repoComparison = left.repoSlug.localeCompare(right.repoSlug);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    if (left.parentNumber !== right.parentNumber) {
+        return left.parentNumber - right.parentNumber;
+    }
+    return left.id.localeCompare(right.id);
+}
+function compareTasks(left, right) {
+    const repoComparison = left.repoSlug.localeCompare(right.repoSlug);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    const kindComparison = left.kind.localeCompare(right.kind);
+    if (kindComparison !== 0) {
+        return kindComparison;
+    }
+    return left.id.localeCompare(right.id);
+}
+function compareExecutions(left, right) {
+    const repoComparison = left.repoSlug.localeCompare(right.repoSlug);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    const taskComparison = left.taskId.localeCompare(right.taskId);
+    if (taskComparison !== 0) {
+        return taskComparison;
+    }
+    return left.startedAt.localeCompare(right.startedAt);
+}
+function compareWorktrees(left, right) {
+    const repoComparison = left.repoSlug.localeCompare(right.repoSlug);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    return left.id.localeCompare(right.id);
+}
+function compareRepoSyncRecords(left, right) {
+    return left.repoSlug.localeCompare(right.repoSlug);
+}
+function compareWorkstreams(left, right) {
+    const repoComparison = left.repoKey.localeCompare(right.repoKey);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    return left.id.localeCompare(right.id);
+}
+function compareAttentionRecords(left, right) {
+    const repoComparison = left.repoKey.localeCompare(right.repoKey);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    return left.workstreamId.localeCompare(right.workstreamId);
+}
+function compareProviderSessions(left, right) {
+    const sL = left.scope;
+    const sR = right.scope;
+    const repoComparison = sL.repoKey.localeCompare(sR.repoKey);
+    if (repoComparison !== 0)
+        return repoComparison;
+    const workstreamComparison = sL.workstreamId.localeCompare(sR.workstreamId);
+    if (workstreamComparison !== 0)
+        return workstreamComparison;
+    const jobComparison = sL.job.localeCompare(sR.job);
+    if (jobComparison !== 0)
+        return jobComparison;
+    const modelComparison = sL.modelClass.localeCompare(sR.modelClass);
+    if (modelComparison !== 0)
+        return modelComparison;
+    const providerComparison = sL.provider.localeCompare(sR.provider);
+    if (providerComparison !== 0)
+        return providerComparison;
+    const agentComparison = sL.configuredAgentId.localeCompare(sR.configuredAgentId);
+    if (agentComparison !== 0)
+        return agentComparison;
+    const pathComparison = sL.localRepoPath.localeCompare(sR.localRepoPath);
+    if (pathComparison !== 0)
+        return pathComparison;
+    const branchComparison = sL.branchName.localeCompare(sR.branchName);
+    if (branchComparison !== 0)
+        return branchComparison;
+    return left.id.localeCompare(right.id);
+}
+function compareJobAgentAssignments(left, right) {
+    const repoComparison = left.repoKey.localeCompare(right.repoKey);
+    if (repoComparison !== 0) {
+        return repoComparison;
+    }
+    const workstreamComparison = left.workstreamId.localeCompare(right.workstreamId);
+    if (workstreamComparison !== 0) {
+        return workstreamComparison;
+    }
+    const jobKeyComparison = left.jobKey.localeCompare(right.jobKey);
+    if (jobKeyComparison !== 0) {
+        return jobKeyComparison;
+    }
+    return left.id.localeCompare(right.id);
+}
+function compareWorkspaceRecoveryRecords(left, right) {
+    const taskComparison = left.taskId.localeCompare(right.taskId);
+    if (taskComparison !== 0) {
+        return taskComparison;
+    }
+    return left.recoveredAt.localeCompare(right.recoveredAt);
+}
+function compareProviderLimits(left, right) {
+    return left.provider.localeCompare(right.provider);
+}
+function compareRetrospectiveCandidates(left, right) {
+    const repoComparison = left.repoSlug.localeCompare(right.repoSlug);
+    if (repoComparison !== 0)
+        return repoComparison;
+    const workstreamComparison = left.sourceWorkstreamId.localeCompare(right.sourceWorkstreamId);
+    if (workstreamComparison !== 0)
+        return workstreamComparison;
+    return left.id.localeCompare(right.id);
+}
+function compareRetrospectiveProblems(left, right) {
+    const candidateComparison = left.candidateId.localeCompare(right.candidateId);
+    if (candidateComparison !== 0)
+        return candidateComparison;
+    return left.id.localeCompare(right.id);
+}
+function compareLearningOpportunities(left, right) {
+    const problemComparison = left.problemId.localeCompare(right.problemId);
+    if (problemComparison !== 0)
+        return problemComparison;
+    return left.id.localeCompare(right.id);
+}
+function compareLearningProposals(left, right) {
+    if (!left.selectedScope && !right.selectedScope)
+        return left.id.localeCompare(right.id);
+    if (!left.selectedScope)
+        return 1;
+    if (!right.selectedScope)
+        return -1;
+    const scopeKindComparison = left.selectedScope.kind.localeCompare(right.selectedScope.kind);
+    if (scopeKindComparison !== 0)
+        return scopeKindComparison;
+    return left.id.localeCompare(right.id);
+}
+function compareManagementPrs(left, right) {
+    const modeComparison = left.mode.localeCompare(right.mode);
+    if (modeComparison !== 0)
+        return modeComparison;
+    const statusComparison = left.status.localeCompare(right.status);
+    if (statusComparison !== 0)
+        return statusComparison;
+    if (left.prNumber !== undefined && right.prNumber !== undefined) {
+        return left.prNumber - right.prNumber;
+    }
+    if (left.branchName !== undefined && right.branchName !== undefined) {
+        return left.branchName.localeCompare(right.branchName);
+    }
+    return left.id.localeCompare(right.id);
+}
+function sortAttentionRecord(record) {
+    return {
+        workstreamId: record.workstreamId,
+        repoKey: record.repoKey,
+        needsAction: record.needsAction,
+        reasons: [...record.reasons].sort((left, right) => left.localeCompare(right)),
+        ...(record.issueNumber !== undefined ? { issueNumber: record.issueNumber } : {}),
+        ...(record.pullRequestNumbers?.length
+            ? { pullRequestNumbers: [...record.pullRequestNumbers].sort((left, right) => left - right) }
+            : {}),
+        ...(record.commentIds?.length
+            ? { commentIds: [...record.commentIds].sort((left, right) => left.localeCompare(right)) }
+            : {}),
+        ...(record.retryTargetCommentId !== undefined ? { retryTargetCommentId: record.retryTargetCommentId } : {}),
+        lastObservedAt: record.lastObservedAt,
+        ...(record.lastHandledAt ? { lastHandledAt: record.lastHandledAt } : {}),
+        ...(record.currentPullRequestHeadSha ? { currentPullRequestHeadSha: record.currentPullRequestHeadSha } : {}),
+        ...(record.lastHandledReviewHeadSha ? { lastHandledReviewHeadSha: record.lastHandledReviewHeadSha } : {}),
+        ...(record.gaps?.length ? { gaps: [...record.gaps].sort((left, right) => left.localeCompare(right)) } : {})
+    };
+}
+function sortRepoSyncRecord(record) {
+    return {
+        ...record,
+        ...(record.githubScan
+            ? {
+                githubScan: {
+                    ...record.githubScan,
+                    failures: sortFailures(record.githubScan.failures)
+                }
+            }
+            : {})
+    };
+}

package/dist/src/state/types.js

@@ -0,0 +1,15 @@
+export const WORKSTREAM_PHASES = [
+    "product_discovery",
+    "product_specification",
+    "issue_triage",
+    "issue_waiting",
+    "planning",
+    "plan_feedback",
+    "implementation_ready",
+    "implementing",
+    "implementation_done",
+    "implementation_feedback",
+    "pr_review",
+    "resolved",
+    "abandoned"
+];

package/dist/src/tasks/derivation/builders.js

@@ -0,0 +1,70 @@
+import { workflowRegistry } from "../../workflows/registry.js";
+export function createIssueTask(kind, issue, repoSyncRecord, input, workstreamId) {
+    return buildTaskRecord(buildTaskId(kind, issue.id), kind, issue, repoSyncRecord, input, input.contextBuilder.build({
+        taskKind: kind,
+        repoIdentifier: issue.repoSlug,
+        sourceKind: "issue",
+        sourceUrl: issue.url,
+        labels: issue.labels,
+        issueTitle: issue.title,
+        issueBody: issue.body,
+        ...(repoSyncRecord?.localPath ? { localRepoPath: repoSyncRecord.localPath } : {})
+    }), workstreamId);
+}
+export function createPullRequestTask(kind, pr, repoSyncRecord, input, worktree, workstreamId) {
+    return buildTaskRecord(buildTaskId(kind, pr.id), kind, pr, repoSyncRecord, input, input.contextBuilder.build({
+        taskKind: kind,
+        repoIdentifier: pr.repoSlug,
+        sourceKind: "pull_request",
+        sourceUrl: pr.url,
+        labels: pr.labels,
+        ...(pr.headSha ? { headSha: pr.headSha } : {}),
+        ...(worktree?.path
+            ? {
+                localRepoPath: worktree.path,
+                branchName: worktree.branchName,
+                planDocumentPath: worktree.planDocumentPath,
+                ...(worktree.productSpecDocumentPath ? { productSpecDocumentPath: worktree.productSpecDocumentPath } : {}),
+                logDocumentPath: worktree.logDocumentPath
+            }
+            : repoSyncRecord?.localPath
+                ? { localRepoPath: repoSyncRecord.localPath }
+                : {}),
+        ...(worktree?.packet?.packetId ? { packetId: worktree.packet.packetId } : {})
+    }), workstreamId);
+}
+export function buildTaskRecord(id, kind, source, repoSyncRecord, input, context, workstreamId) {
+    const executionPolicy = workflowRegistry.resolveTaskExecutionPolicy(kind);
+    return {
+        id,
+        kind,
+        status: "pending",
+        executionPermission: executionPolicy.executionPermission,
+        handoffPolicy: executionPolicy.handoffPolicy,
+        repoId: source.repoId,
+        repoName: source.repoName,
+        repoSlug: source.repoSlug,
+        sourceKind: source.kind,
+        sourceId: source.id,
+        sourceUrl: source.url,
+        relevant: true,
+        reason: input.reason,
+        summary: input.summary,
+        workstreamId,
+        context,
+        createdAt: input.now,
+        updatedAt: input.now
+    };
+}
+export function buildTaskId(kind, sourceId) {
+    return `task:${kind}:${sourceId}`;
+}
+export function buildCommentReason(comment, previousComment) {
+    if (!previousComment) {
+        return `Comment is newly seen and needs a response path for ${comment.parentType.replace("_", " ")} #${comment.parentNumber}.`;
+    }
+    return `Comment changed since the last seen state (updatedAt ${previousComment.updatedAt} -> ${comment.updatedAt}).`;
+}
+export function isAgentAuthoredComment(comment) {
+    return comment.body.trimStart().startsWith("🤖");
+}