xforce 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,434 @@
+/** Parsed from a structured GitHub Issue body */
+interface TaskSpec {
+    title: string;
+    context: string;
+    acceptanceCriteria: string[];
+    affectedFiles: string[];
+    edgeCases: string[];
+    priority: "critical" | "high" | "medium" | "low";
+    type: "feature" | "bugfix" | "refactor" | "test" | "docs";
+    size: "xs" | "s" | "m" | "l" | "xl";
+    issueNumber: number;
+    issueUrl: string;
+    repoOwner: string;
+    repoName: string;
+}
+/** Configuration for a single target repository */
+interface RepoConfig {
+    owner: string;
+    name: string;
+    defaultBranch: string;
+    testCommand: string;
+    lintCommand?: string;
+    buildCommand?: string;
+    runCommand?: string;
+    claudeMdPath?: string;
+    maxTurns?: number;
+    maxReviewCycles?: number;
+    maxTestRetries?: number;
+    budgetPerTaskUsd?: number;
+    autoMerge: boolean;
+    autoMergeRules?: AutoMergeRules;
+    allowedTools?: string[];
+    localPath?: string;
+}
+/** Label configuration */
+interface LabelsConfig {
+    ready: string;
+    inProgress: string;
+    done: string;
+    failed: string;
+}
+/** Default settings applied to all repos unless overridden */
+interface DefaultsConfig {
+    model: string;
+    reviewerModel: string;
+    plannerModel: string;
+    maxTurns: number;
+    maxReviewCycles: number;
+    maxTestRetries: number;
+    timeoutMinutes: number;
+    budgetPerTaskUsd: number;
+    branchPrefix: string;
+    labels: LabelsConfig;
+    allowedTools: string[];
+    enablePlanning: boolean;
+    enableSecurityScan: boolean;
+}
+/** Slack notification config */
+interface SlackConfig {
+    webhookUrl: string;
+    channels?: {
+        success?: string;
+        failure?: string;
+    };
+}
+/** GitHub notification config */
+interface GitHubNotifyConfig {
+    mentionOnFailure?: string[];
+    mentionOnReview?: string[];
+}
+/** Notifications config */
+interface NotificationsConfig {
+    slack?: SlackConfig;
+    github?: GitHubNotifyConfig;
+}
+/** Top-level xforce configuration */
+interface XForceConfig {
+    version: string;
+    defaults: DefaultsConfig;
+    repos: RepoConfig[];
+    notifications?: NotificationsConfig;
+}
+/** Resolved config for a specific repo (defaults merged with repo overrides) */
+interface ResolvedRepoConfig {
+    owner: string;
+    name: string;
+    defaultBranch: string;
+    testCommand: string;
+    lintCommand?: string;
+    buildCommand?: string;
+    runCommand?: string;
+    claudeMdPath?: string;
+    model: string;
+    reviewerModel: string;
+    plannerModel: string;
+    maxTurns: number;
+    maxReviewCycles: number;
+    maxTestRetries: number;
+    timeoutMinutes: number;
+    budgetPerTaskUsd: number;
+    branchPrefix: string;
+    labels: LabelsConfig;
+    autoMerge: boolean;
+    autoMergeRules: AutoMergeRules;
+    allowedTools: string[];
+    enablePlanning: boolean;
+    enableSecurityScan: boolean;
+    localPath?: string;
+}
+/** Rules for auto-merging approved PRs */
+interface AutoMergeRules {
+    types: Array<TaskSpec["type"]>;
+    maxSize: TaskSpec["size"];
+    mergeStrategy: "squash" | "merge" | "rebase";
+    requireCleanSecurityScan: boolean;
+}
+/** Pipeline execution state */
+type PipelineStatus = "parsing_issue" | "creating_branch" | "planning" | "coding" | "running_tests" | "reviewing" | "addressing_review" | "merging" | "awaiting_human" | "completed" | "failed";
+/** A single log entry in the pipeline */
+interface PipelineLogEntry {
+    timestamp: Date;
+    status: PipelineStatus;
+    message: string;
+    costUsd?: number;
+}
+/** Full pipeline state at any point */
+interface PipelineState {
+    id: string;
+    taskSpec: TaskSpec;
+    status: PipelineStatus;
+    branchName: string;
+    prNumber?: number;
+    prUrl?: string;
+    reviewCycle: number;
+    testRetry: number;
+    totalCostUsd: number;
+    logs: PipelineLogEntry[];
+    startedAt: Date;
+    completedAt?: Date;
+    error?: string;
+    plan?: ImplementationPlan;
+}
+/** Result from the coding agent */
+interface CodingResult {
+    sessionId: string;
+    costUsd: number;
+    result: string;
+    numTurns: number;
+    filesChanged?: string[];
+}
+/** A single issue found during review */
+interface ReviewIssue {
+    severity: "critical" | "major" | "minor" | "suggestion";
+    file: string;
+    line?: number;
+    description: string;
+    suggestedFix?: string;
+}
+/** Result from the reviewer agent */
+interface ReviewResult {
+    approved: boolean;
+    summary: string;
+    issues: ReviewIssue[];
+    securityConcerns: string[];
+    specAdherence: {
+        met: string[];
+        unmet: string[];
+    };
+}
+/** Result from running the target repo's test suite */
+interface TestResult {
+    passed: boolean;
+    output: string;
+    durationMs: number;
+}
+/** A single step in an implementation plan */
+interface ImplementationStep {
+    order: number;
+    description: string;
+    files: string[];
+    rationale: string;
+}
+/** Structured plan produced by the planning agent */
+interface ImplementationPlan {
+    approach: string;
+    filesToModify: string[];
+    filesToCreate: string[];
+    estimatedComplexity: "low" | "medium" | "high";
+    risks: string[];
+    implementationSteps: ImplementationStep[];
+    estimatedTurns: number;
+}
+/** Result from the planning agent */
+interface PlanningResult {
+    plan: ImplementationPlan;
+    costUsd: number;
+    numTurns: number;
+}
+/** A single security finding from the scanner */
+interface SecurityFinding {
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    category: string;
+    file: string;
+    line?: number;
+    description: string;
+    recommendation: string;
+}
+/** Full security scan report */
+interface SecurityReport {
+    riskLevel: "critical" | "high" | "medium" | "low" | "none";
+    findings: SecurityFinding[];
+    recommendations: string[];
+    summary: string;
+}
+/** Result from the security scanner agent */
+interface SecurityScanResult {
+    report: SecurityReport;
+    costUsd: number;
+}
+/** Result from attempting to merge a PR */
+interface MergeResult {
+    merged: boolean;
+    sha?: string;
+    error?: string;
+}
+/** A record of a completed pipeline run, persisted to disk */
+interface PipelineRunRecord {
+    id: string;
+    repo: string;
+    issueNumber: number;
+    issueUrl: string;
+    prNumber?: number;
+    prUrl?: string;
+    status: "completed" | "failed";
+    totalCostUsd: number;
+    durationMs: number;
+    reviewCycles: number;
+    model: string;
+    startedAt: string;
+    completedAt: string;
+    taskTitle: string;
+    taskType: string;
+    taskSize: string;
+    error?: string;
+}
+/** Summary of cost tracking data for display */
+interface CostSummary {
+    totalCostUsd: number;
+    totalRuns: number;
+    successfulRuns: number;
+    failedRuns: number;
+    avgCostPerRun: number;
+    avgDurationMs: number;
+    costByRepo: Record<string, number>;
+}
+
+interface RunPipelineParams {
+    issueUrl?: string;
+    repoOwner?: string;
+    repoName?: string;
+    issueNumber?: number;
+    config: XForceConfig;
+    localDir?: string;
+}
+declare function runPipeline(params: RunPipelineParams): Promise<PipelineState>;
+
+/** Load and validate the xforce config file */
+declare function loadConfig(configPath?: string): XForceConfig;
+/** Resolve config for a specific repo by merging defaults with repo overrides */
+declare function resolveRepoConfig(config: XForceConfig, owner: string, name: string): ResolvedRepoConfig;
+
+/** Parse a structured GitHub issue body into a TaskSpec */
+declare function parseIssueBody(params: {
+    title: string;
+    body: string;
+    labels: string[];
+    issueNumber: number;
+    issueUrl: string;
+    repoOwner: string;
+    repoName: string;
+}): TaskSpec;
+
+/** Parse an issue URL into owner, repo, and issue number */
+declare function parseIssueUrl(url: string): {
+    owner: string;
+    repo: string;
+    issueNumber: number;
+};
+/** Parse a PR URL into owner, repo, and PR number */
+declare function parsePRUrl(url: string): {
+    owner: string;
+    repo: string;
+    prNumber: number;
+};
+
+declare function runCodingAgent(params: {
+    taskSpec: TaskSpec;
+    repoConfig: ResolvedRepoConfig;
+    workingDir: string;
+    previousReview?: ReviewResult;
+    testFailures?: string;
+    commandFailures?: {
+        kind: string;
+        output: string;
+    };
+    sessionId?: string;
+    plan?: ImplementationPlan;
+    onProgress?: (message: string) => void;
+}): Promise<CodingResult>;
+
+declare function runReviewerAgent(params: {
+    taskSpec: TaskSpec;
+    diff: string;
+    repoConfig: ResolvedRepoConfig;
+    reviewCycle: number;
+}): Promise<ReviewResult>;
+
+declare function runPlanningAgent(params: {
+    taskSpec: TaskSpec;
+    repoConfig: ResolvedRepoConfig;
+    workingDir: string;
+    onProgress?: (message: string) => void;
+}): Promise<PlanningResult>;
+
+declare function runSecurityScanner(params: {
+    taskSpec: TaskSpec;
+    diff: string;
+    repoConfig: ResolvedRepoConfig;
+}): Promise<SecurityScanResult>;
+
+declare function isAutoMergeEligible(params: {
+    taskSpec: TaskSpec;
+    repoConfig: ResolvedRepoConfig;
+    securityReport?: SecurityReport;
+}): {
+    eligible: boolean;
+    reasons: string[];
+};
+
+/** Convert a completed PipelineState into a PipelineRunRecord */
+declare function buildRecordFromState(state: PipelineState, repoConfig: ResolvedRepoConfig): PipelineRunRecord;
+/** Append a pipeline run record to the JSONL history file */
+declare function appendRecord(record: PipelineRunRecord, basePath?: string): Promise<void>;
+interface CostFilter {
+    repo?: string;
+    since?: Date;
+    until?: Date;
+}
+/** Read pipeline run records from the JSONL history file */
+declare function readRecords(filter?: CostFilter, basePath?: string): Promise<PipelineRunRecord[]>;
+/** Compute summary statistics from a set of pipeline run records */
+declare function summarize(records: PipelineRunRecord[]): CostSummary;
+
+type JobStatus = "pending" | "running" | "completed" | "failed";
+interface Job {
+    id: string;
+    owner: string;
+    repo: string;
+    issueNumber: number;
+    issueUrl: string;
+    status: JobStatus;
+    result?: PipelineState;
+    error?: string;
+    enqueuedAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+interface QueueStatus {
+    active: Job | null;
+    pending: Job[];
+    completed: Job[];
+    totalProcessed: number;
+}
+interface QueueOptions {
+    maxSize: number;
+    historySize: number;
+}
+declare class JobQueue {
+    private pending;
+    private active;
+    private completed;
+    private totalProcessed;
+    private processing;
+    private readonly options;
+    private readonly processor;
+    constructor(processor: (job: Job) => Promise<PipelineState>, options?: Partial<QueueOptions>);
+    enqueue(params: {
+        owner: string;
+        repo: string;
+        issueNumber: number;
+        issueUrl: string;
+    }): Job;
+    getStatus(): QueueStatus;
+    getJob(id: string): Job | undefined;
+    get size(): number;
+    get isFull(): boolean;
+    private isDuplicateIn;
+    private processNext;
+}
+
+interface WebhookServerOptions {
+    port: number;
+    host: string;
+    secret: string;
+    maxQueueSize?: number;
+    historySize?: number;
+}
+interface WebhookServer {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getQueueStatus(): QueueStatus;
+    address(): {
+        host: string;
+        port: number;
+    } | null;
+}
+declare function createWebhookServer(config: XForceConfig, options: WebhookServerOptions): WebhookServer;
+
+type CommandKind = "lint" | "build" | "test" | "run";
+/** Run any shell command and capture output */
+declare function runCommand(params: {
+    workingDir: string;
+    command: string;
+    kind: CommandKind;
+    timeoutMs?: number;
+}): Promise<TestResult>;
+/** Run the target repo's test suite and capture output */
+declare function runTests(params: {
+    workingDir: string;
+    testCommand: string;
+    timeoutMs?: number;
+}): Promise<TestResult>;
+
+export { type AutoMergeRules, type CodingResult, type CommandKind, type CostSummary, type DefaultsConfig, type ImplementationPlan, type ImplementationStep, type Job, JobQueue, type JobStatus, type LabelsConfig, type MergeResult, type PipelineRunRecord, type PipelineState, type PipelineStatus, type PlanningResult, type QueueStatus, type RepoConfig, type ResolvedRepoConfig, type ReviewIssue, type ReviewResult, type RunPipelineParams, type SecurityFinding, type SecurityReport, type SecurityScanResult, type TaskSpec, type TestResult, type WebhookServer, type WebhookServerOptions, type XForceConfig, appendRecord, buildRecordFromState, createWebhookServer, isAutoMergeEligible, loadConfig, parseIssueBody, parseIssueUrl, parsePRUrl, readRecords, resolveRepoConfig, runCodingAgent, runCommand, runPipeline, runPlanningAgent, runReviewerAgent, runSecurityScanner, runTests, summarize };