@cjvana/claude-auto 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1137 @@
+import { Document } from 'yaml';
+import { z } from 'zod';
+import Database from 'better-sqlite3';
+
+type CliCommand = "create" | "check-repo" | "list" | "logs" | "report" | "pause" | "resume" | "remove" | "edit" | "cost" | "dashboard" | "help";
+interface ParsedCommand {
+    command: CliCommand;
+    args: Record<string, string | number | boolean | undefined>;
+}
+type CommandHandler = (args: ParsedCommand["args"]) => Promise<void>;
+declare const COMMANDS: Record<string, string>;
+
+/**
+ * Check if a path is a valid git repository.
+ * Outputs JSON for the setup wizard to consume.
+ */
+declare function checkRepoCommand(args: ParsedCommand["args"]): Promise<void>;
+
+/**
+ * CLI command handler for `claude-auto cost`.
+ *
+ * Without a jobId: displays per-job cost summary table.
+ * With a jobId: displays per-day cost breakdown for that job.
+ * With --json flag: outputs JSON array instead of formatted table.
+ *
+ * @param args - Parsed CLI arguments (jobId?: string, json?: boolean)
+ */
+declare function costCommand(args: Record<string, string | number | boolean | undefined>): Promise<void>;
+
+/**
+ * Create a new autonomous cron job. Validates all inputs, optionally clones the repo,
+ * creates the job config, and registers with the system scheduler.
+ */
+declare function createCommand(args: ParsedCommand["args"]): Promise<void>;
+
+/**
+ * Edit a job's configuration fields. Re-validates and re-registers with scheduler
+ * if schedule or timezone changes. Supports multiple flags in one invocation.
+ */
+declare function editCommand(args: ParsedCommand["args"]): Promise<void>;
+
+/**
+ * List all configured jobs with enriched status info:
+ * ID, Name, Status, Repo, Schedule, Last Run, Next Run.
+ *
+ * Satisfies JOB-01 (list with status/schedule/last run/next run)
+ * and JOB-05 (multiple jobs visible as separate entries).
+ */
+declare function listCommand(args: ParsedCommand["args"]): Promise<void>;
+
+/**
+ * Show recent run history for a specific job.
+ * Displays a table of: Run ID, Status, Started, Duration, PR URL, Error.
+ */
+declare function logsCommand(args: ParsedCommand["args"]): Promise<void>;
+
+/**
+ * Pause a running job: sets enabled=false and unregisters from scheduler.
+ * Idempotent: pausing an already-paused job prints a message and exits cleanly.
+ */
+declare function pauseCommand(args: ParsedCommand["args"]): Promise<void>;
+
+/**
+ * Remove a job: unregisters from scheduler and deletes job directory.
+ * With --keep-logs: archives run logs before deleting.
+ */
+declare function removeCommand(args: ParsedCommand["args"]): Promise<void>;
+
+/**
+ * Show aggregate run summary for a single job or across all jobs.
+ * Satisfies REPT-02 (aggregate run summary reports).
+ */
+declare function reportCommand(args: ParsedCommand["args"]): Promise<void>;
+
+/**
+ * Resume a paused job: sets enabled=true and re-registers with scheduler.
+ * Idempotent: resuming an already-active job prints a message and exits cleanly.
+ */
+declare function resumeCommand(args: ParsedCommand["args"]): Promise<void>;
+
+/**
+ * Convert milliseconds to human-readable duration.
+ * Omits zero-value leading parts. For hours+, shows "Xh Ym" (omits seconds).
+ * For minutes+, shows "Xm Ys". For <1m, shows "Xs".
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Format a date as a relative time string: "just now", "5 minutes ago", "2 hours ago", etc.
+ * Pure math, no library dependencies.
+ */
+declare function formatRelativeTime(date: Date): string;
+/**
+ * Format data as an aligned text table.
+ * Returns an empty string when there are no rows.
+ */
+declare function formatTable(headers: string[], rows: string[][]): string;
+/**
+ * Returns a text badge for a status string: "active" -> "[active]".
+ */
+declare function statusBadge(status: string): string;
+
+/**
+ * Parse CLI argv (process.argv.slice(2)) into a structured command.
+ * Extracts the subcommand from argv[0], then parses remaining args.
+ */
+declare function parseCommand(argv: string[]): ParsedCommand;
+/**
+ * Main CLI entry point. Parses argv and dispatches to the appropriate command handler.
+ */
+declare function runCli(argv: string[]): Promise<void>;
+
+declare const JobConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    repo: z.ZodObject<{
+        path: z.ZodString;
+        branch: z.ZodDefault<z.ZodString>;
+        remote: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    schedule: z.ZodObject<{
+        cron: z.ZodString;
+        timezone: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    focus: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "open-issues": "open-issues";
+        "bug-discovery": "bug-discovery";
+        features: "features";
+        documentation: "documentation";
+    }>>>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    guardrails: z.ZodDefault<z.ZodObject<{
+        maxTurns: z.ZodDefault<z.ZodNumber>;
+        maxBudgetUsd: z.ZodDefault<z.ZodNumber>;
+        noNewDependencies: z.ZodDefault<z.ZodBoolean>;
+        noArchitectureChanges: z.ZodDefault<z.ZodBoolean>;
+        bugFixOnly: z.ZodDefault<z.ZodBoolean>;
+        restrictToPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    notifications: z.ZodDefault<z.ZodObject<{
+        discord: z.ZodOptional<z.ZodObject<{
+            webhookUrl: z.ZodString;
+            onSuccess: z.ZodDefault<z.ZodBoolean>;
+            onFailure: z.ZodDefault<z.ZodBoolean>;
+            onNoChanges: z.ZodDefault<z.ZodBoolean>;
+            onLocked: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        slack: z.ZodOptional<z.ZodObject<{
+            webhookUrl: z.ZodString;
+            onSuccess: z.ZodDefault<z.ZodBoolean>;
+            onFailure: z.ZodDefault<z.ZodBoolean>;
+            onNoChanges: z.ZodDefault<z.ZodBoolean>;
+            onLocked: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        telegram: z.ZodOptional<z.ZodObject<{
+            botToken: z.ZodString;
+            chatId: z.ZodString;
+            onSuccess: z.ZodDefault<z.ZodBoolean>;
+            onFailure: z.ZodDefault<z.ZodBoolean>;
+            onNoChanges: z.ZodDefault<z.ZodBoolean>;
+            onLocked: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    model: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        default: "default";
+        sonnet: "sonnet";
+        opus: "opus";
+        haiku: "haiku";
+        opusplan: "opusplan";
+    }>, z.ZodString]>>;
+    budget: z.ZodOptional<z.ZodObject<{
+        dailyUsd: z.ZodOptional<z.ZodNumber>;
+        weeklyUsd: z.ZodOptional<z.ZodNumber>;
+        monthlyUsd: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    maxFeedbackRounds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    pipeline: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        planModel: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+            default: "default";
+            sonnet: "sonnet";
+            opus: "opus";
+            haiku: "haiku";
+            opusplan: "opusplan";
+        }>, z.ZodString]>>;
+        implementModel: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+            default: "default";
+            sonnet: "sonnet";
+            opus: "opus";
+            haiku: "haiku";
+            opusplan: "opusplan";
+        }>, z.ZodString]>>;
+        reviewModel: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+            default: "default";
+            sonnet: "sonnet";
+            opus: "opus";
+            haiku: "haiku";
+            opusplan: "opusplan";
+        }>, z.ZodString]>>;
+        maxReviewRounds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type JobConfig = z.infer<typeof JobConfigSchema>;
+interface ScheduleInfo {
+    cron: string;
+    timezone: string;
+    humanReadable: string;
+    nextRuns: Date[];
+}
+
+/**
+ * Read a YAML config file and return the parsed Document (preserves comments).
+ * Throws ConfigParseError if the YAML syntax is invalid.
+ */
+declare function readConfigDocument(filePath: string): Promise<Document>;
+/**
+ * Validate a parsed YAML Document against the JobConfigSchema.
+ * Returns the validated and typed JobConfig.
+ * Throws ConfigValidationError if validation fails.
+ */
+declare function validateConfig(filePath: string, doc: Document): JobConfig;
+/**
+ * Load a job config from a YAML file, validating it against the schema.
+ * Combines readConfigDocument + validateConfig.
+ */
+declare function loadJobConfig(filePath: string): Promise<JobConfig>;
+/**
+ * Save a JobConfig to a YAML file using atomic writes.
+ * Multiline systemPrompt values use YAML block literal style (|).
+ */
+declare function saveJobConfig(filePath: string, config: JobConfig): Promise<void>;
+/**
+ * Update a field in a YAML Document by path, preserving comments.
+ */
+declare function updateConfigField(doc: Document, path: (string | number)[], value: unknown): void;
+/**
+ * Write a YAML Document to a file using atomic writes, preserving comments.
+ */
+declare function writeConfigDocument(filePath: string, doc: Document): Promise<void>;
+
+/**
+ * Get or create the SQLite database singleton.
+ * On first call, opens the database, sets pragmas (WAL mode, synchronous=normal,
+ * foreign_keys=ON), and runs schema migrations.
+ *
+ * @param dbPath - Optional path override for testing (e.g., ":memory:")
+ * @returns The singleton Database instance
+ */
+declare function getDatabase(dbPath?: string): Database.Database;
+/**
+ * Close the database connection and reset the singleton.
+ * Safe to call multiple times. After calling, the next getDatabase()
+ * call will open a fresh connection.
+ */
+declare function closeDatabase(): void;
+
+/**
+ * Create a new job with a generated nanoid(12) identifier.
+ * Writes the config to disk and returns the complete JobConfig.
+ */
+declare function createJob(input: Omit<JobConfig, "id">): Promise<JobConfig>;
+/**
+ * Read and validate a job config by its ID.
+ * Throws if the job doesn't exist (ENOENT) or config is invalid.
+ */
+declare function readJob(jobId: string): Promise<JobConfig>;
+/**
+ * Update specified fields of a job config while preserving YAML comments.
+ * Validates the result before writing. Rejects invalid updates.
+ */
+declare function updateJob(jobId: string, updates: Partial<Omit<JobConfig, "id">>): Promise<JobConfig>;
+/**
+ * Delete a job and its entire directory.
+ * Idempotent: does not throw if the job doesn't exist.
+ */
+declare function deleteJob(jobId: string): Promise<void>;
+/**
+ * List all valid job configs.
+ * Skips invalid directories/configs. Returns empty array if no jobs directory exists.
+ */
+declare function listJobs(): Promise<JobConfig[]>;
+
+/**
+ * Validate a cron expression. Throws CronValidationError if invalid.
+ * Only accepts standard 5-field cron expressions.
+ */
+declare function validateCronExpression(cronExpr: string): void;
+/**
+ * Get a human-readable description of a cron expression.
+ * Example: "0 *​/6 * * *" -> "Every 6 hours"
+ */
+declare function describeSchedule(cronExpr: string): string;
+/**
+ * Compute the next N run times for a cron expression in the given IANA timezone.
+ */
+declare function getNextRuns(cronExpr: string, timezone: string, count?: number): Date[];
+/**
+ * Validate a cron expression and return complete schedule info
+ * including human-readable description and next run times.
+ */
+declare function validateAndDescribeSchedule(cronExpr: string, timezone: string): ScheduleInfo;
+
+interface SpawnOptions {
+    cwd: string;
+    prompt: string;
+    maxTurns: number;
+    maxBudgetUsd: number;
+    allowedTools: string[];
+    appendSystemPrompt?: string;
+    model?: string;
+    env?: Record<string, string>;
+}
+interface SpawnResult {
+    success: boolean;
+    result: string;
+    summary: string;
+    sessionId: string;
+    costUsd: number;
+    numTurns: number;
+    durationMs: number;
+    isError: boolean;
+    subtype: string;
+    errors?: string[];
+}
+type RunStatus = "success" | "no-changes" | "error" | "locked" | "git-error" | "paused" | "budget-exceeded" | "needs-human-review" | "merge-conflict";
+interface RunResult {
+    status: RunStatus;
+    jobId: string;
+    runId: string;
+    startedAt: string;
+    completedAt: string;
+    durationMs: number;
+    prUrl?: string;
+    summary?: string;
+    costUsd?: number;
+    numTurns?: number;
+    sessionId?: string;
+    error?: string;
+    branchName?: string;
+    issueNumber?: number;
+    model?: string;
+    feedbackRound?: number;
+    prNumber?: number;
+    pipelineStages?: Array<{
+        stage: string;
+        costUsd: number;
+        durationMs: number;
+        numTurns: number;
+    }>;
+}
+interface RunLogEntry extends RunResult {
+}
+interface ReviewThread {
+    id: string;
+    isResolved: boolean;
+    comments: Array<{
+        body: string;
+        author: {
+            login: string;
+        };
+    }>;
+}
+interface PRFeedbackContext {
+    number: number;
+    title: string;
+    headRefName: string;
+    url: string;
+    reviewDecision: string;
+    unresolvedThreads: ReviewThread[];
+    currentRound: number;
+}
+interface PipelineStageResult {
+    stage: "plan" | "implement" | "review" | "fix";
+    spawnResult: SpawnResult;
+}
+interface PipelineResult {
+    stages: PipelineStageResult[];
+    reviewVerdict: "pass" | "fail" | "skipped";
+    totalCostUsd: number;
+    totalDurationMs: number;
+    summary: string;
+}
+interface RebaseResult {
+    diverged: boolean;
+    rebased: boolean;
+    conflicts: string[];
+}
+
+/**
+ * Send notifications to all configured providers for a completed run.
+ *
+ * Best-effort: failures are logged as warnings but never thrown.
+ * All providers are called in parallel via Promise.allSettled.
+ */
+declare function sendNotifications(config: JobConfig, result: RunResult): Promise<void>;
+
+type NotificationEvent = "success" | "no-changes" | "error" | "locked" | "git-error" | "budget-exceeded" | "merge-conflict" | "needs-human-review";
+interface NotificationPayload {
+    event: NotificationEvent;
+    jobId: string;
+    jobName: string;
+    runId: string;
+    repoPath: string;
+    branch: string;
+    startedAt: string;
+    completedAt: string;
+    durationMs: number;
+    prUrl?: string;
+    summary?: string;
+    costUsd?: number;
+    numTurns?: number;
+    error?: string;
+    branchName?: string;
+}
+interface EventTriggers {
+    onSuccess?: boolean;
+    onFailure?: boolean;
+    onNoChanges?: boolean;
+    onLocked?: boolean;
+}
+/**
+ * Determines whether a notification should be sent for a given run status
+ * and provider trigger configuration.
+ *
+ * Defaults:
+ * - onSuccess: true (backward compat -- always notify on PR created)
+ * - onFailure: true (always notify on errors)
+ * - onNoChanges: false (avoid noise)
+ * - onLocked: false (avoid noise)
+ */
+declare function shouldNotify(status: RunStatus, triggers: EventTriggers): boolean;
+/**
+ * Build a NotificationPayload from job config and run result.
+ * Maps RunResult + JobConfig into the shape formatters consume.
+ */
+declare function buildPayload(config: JobConfig, result: RunResult): NotificationPayload;
+
+/**
+ * Format a notification payload for Discord webhook API.
+ * Returns a JSON-serializable object with Discord embeds.
+ */
+declare function formatDiscord(payload: NotificationPayload): object;
+/**
+ * Format a notification payload for Slack incoming webhook API.
+ * Returns a JSON-serializable object with Slack blocks.
+ */
+declare function formatSlack(payload: NotificationPayload): object;
+/**
+ * Format a notification payload for Telegram Bot API (sendMessage).
+ * Returns a JSON-serializable object with chat_id, text, and parse_mode.
+ */
+declare function formatTelegram(payload: NotificationPayload, chatId: string): object;
+
+/**
+ * Extract a GitHub issue number from text.
+ * Looks for patterns like: #42, fixes #7, closes #123, resolves #99
+ * Returns the first matched issue number, or undefined if none found.
+ */
+declare function extractIssueNumber(text: string): number | undefined;
+interface PostIssueCommentOptions {
+    repoPath: string;
+    issueNumber: number;
+    status: RunStatus;
+    prUrl?: string;
+    summary?: string;
+    error?: string;
+    jobName: string;
+}
+/**
+ * Post a comment on a GitHub issue about the run result.
+ *
+ * Best-effort: failures are logged as warnings but never thrown.
+ * Skips posting for "locked" status (no value in commenting on skipped runs).
+ */
+declare function postIssueComment(options: PostIssueCommentOptions): Promise<void>;
+
+interface RegisteredJob {
+    jobId: string;
+    schedule: string;
+    command: string;
+}
+interface Scheduler {
+    register(job: JobConfig, env?: Record<string, string>): Promise<void>;
+    unregister(jobId: string): Promise<void>;
+    isRegistered(jobId: string): Promise<boolean>;
+    list(): Promise<RegisteredJob[]>;
+}
+/**
+ * Factory function that returns the correct Scheduler implementation
+ * for the current platform: CrontabScheduler on Linux, LaunchdScheduler on macOS,
+ * SchtasksScheduler on Windows.
+ */
+declare function createScheduler(): Promise<Scheduler>;
+
+/**
+ * CrontabScheduler implements the Scheduler interface for Linux systems.
+ * Uses comment-tagged crontab entries for identification and CRUD.
+ */
+declare class CrontabScheduler implements Scheduler {
+    register(job: JobConfig, _env?: Record<string, string>): Promise<void>;
+    unregister(jobId: string): Promise<void>;
+    isRegistered(jobId: string): Promise<boolean>;
+    list(): Promise<RegisteredJob[]>;
+}
+
+type Platform = "linux" | "darwin" | "win32";
+/**
+ * Detect the current platform. Returns "linux", "darwin", or "win32".
+ * Throws SchedulerError for unsupported platforms.
+ */
+declare function detectPlatform(): Platform;
+
+interface CalendarInterval {
+    Month?: number;
+    Day?: number;
+    Weekday?: number;
+    Hour?: number;
+    Minute?: number;
+}
+/**
+ * Convert a 5-field cron expression to launchd scheduling config.
+ *
+ * For high-frequency "every N minutes" patterns, returns { startInterval: seconds }.
+ * For specific times, returns { calendarIntervals: CalendarInterval[] }.
+ *
+ * Throws if the expression would produce more than 50 calendar intervals.
+ */
+declare function cronToCalendarIntervals(cronExpr: string): {
+    calendarIntervals?: CalendarInterval[];
+    startInterval?: number;
+};
+/**
+ * LaunchdScheduler implements the Scheduler interface for macOS.
+ * Uses plist files in ~/Library/LaunchAgents/ and modern launchctl bootstrap/bootout.
+ */
+declare class LaunchdScheduler implements Scheduler {
+    register(job: JobConfig, env?: Record<string, string>): Promise<void>;
+    unregister(jobId: string): Promise<void>;
+    isRegistered(jobId: string): Promise<boolean>;
+    list(): Promise<RegisteredJob[]>;
+}
+
+interface SchtasksSchedule {
+    args: string[];
+    description: string;
+}
+/**
+ * Translate a 5-field cron expression into schtasks /SC schedule parameters.
+ *
+ * Supports:
+ * - Every N minutes (e.g., *\/30 * * * *)
+ * - Every N hours at minute M (e.g., 0 *\/6 * * *)
+ * - Daily at specific time (e.g., 0 9 * * *)
+ * - Specific days of week (e.g., 0 9 * * 1-5)
+ * - Monthly on a single day (e.g., 0 9 15 * *)
+ *
+ * Throws SchedulerError for patterns that cannot be represented as a single
+ * Windows Task Scheduler entry.
+ */
+declare function cronToSchtasks(cronExpr: string): SchtasksSchedule;
+/**
+ * SchtasksScheduler implements the Scheduler interface for Windows systems.
+ * Uses `schtasks.exe` to create, query, and delete tasks in Windows Task Scheduler.
+ *
+ * Task name format: `claude-auto-{jobId}`
+ */
+declare class SchtasksScheduler implements Scheduler {
+    register(job: JobConfig, _env?: Record<string, string>): Promise<void>;
+    unregister(jobId: string): Promise<void>;
+    isRegistered(jobId: string): Promise<boolean>;
+    list(): Promise<RegisteredJob[]>;
+}
+
+/**
+ * Structured context from a prior run, containing only verifiable facts
+ * (issue numbers, PR URLs, branch names) -- never raw narrative summaries.
+ */
+interface RunContext {
+    id: string;
+    status: string;
+    pr_url: string | null;
+    branch_name: string | null;
+    issue_number: number | null;
+    summary: string | null;
+    started_at: string;
+}
+/**
+ * Persist a run log entry to the SQLite database.
+ * Maps RunLogEntry camelCase fields to snake_case columns.
+ *
+ * @param entry - The run log entry to save
+ */
+declare function saveRunContext(entry: RunLogEntry): void;
+/**
+ * Load recent run context for a job from SQLite.
+ * Only returns runs with status "success" or "no-changes" (not errors, locked, etc.)
+ * to avoid injecting failure context into Claude's prompt.
+ *
+ * @param jobId - The job identifier
+ * @param limit - Maximum number of recent runs to return (default: 5)
+ * @returns Array of RunContext sorted by started_at descending
+ */
+declare function loadRunContext(jobId: string, limit?: number): RunContext[];
+/**
+ * Format run context as a structured "Previous Work" prompt section.
+ * Only includes verifiable facts (issue numbers, PR URLs, branch names)
+ * to avoid hallucination amplification from raw narrative summaries.
+ *
+ * @param context - Array of RunContext from loadRunContext
+ * @returns Formatted string for prompt injection, or empty string if no context
+ */
+declare function formatContextWindow(context: RunContext[]): string;
+
+/**
+ * Budget configuration with optional caps per time period.
+ * When a cap is set, cumulative cost within that period is checked
+ * before spawning a new run.
+ */
+interface BudgetConfig {
+    dailyUsd?: number;
+    weeklyUsd?: number;
+    monthlyUsd?: number;
+}
+/**
+ * Per-job cost summary row returned by getCostSummary() when no jobId is specified.
+ */
+interface CostSummaryRow {
+    job_id: string;
+    runs: number;
+    total_cost: number;
+    avg_cost: number;
+    total_turns: number;
+}
+/**
+ * Per-day cost breakdown row returned by getCostSummary(jobId).
+ */
+interface DailyCostRow {
+    day: string;
+    runs: number;
+    total_cost: number;
+    total_turns: number;
+}
+/**
+ * Check whether cumulative cost for a job exceeds any configured budget cap.
+ *
+ * Queries the runs table for cost accrued within each budget period (daily, weekly, monthly),
+ * excluding non-spending statuses (locked, paused, budget-exceeded).
+ *
+ * @param jobId - The job identifier to check
+ * @param budget - Budget configuration with optional period caps
+ * @param dbPath - Optional database path override for testing
+ * @returns true if any budget cap is met or exceeded, false otherwise
+ */
+declare function checkBudget(jobId: string, budget: BudgetConfig, dbPath?: string): boolean;
+/**
+ * Get cost summary data from the runs table.
+ *
+ * When jobId is provided, returns per-day cost breakdown for that job (last 30 days).
+ * When no jobId is provided, returns per-job aggregate cost totals across all jobs.
+ *
+ * @param jobId - Optional job identifier for per-day breakdown
+ * @param dbPath - Optional database path override for testing
+ * @returns Array of CostSummaryRow (no jobId) or DailyCostRow (with jobId)
+ */
+declare function getCostSummary(jobId?: string, dbPath?: string): CostSummaryRow[] | DailyCostRow[];
+
+/**
+ * Pull latest changes from remote branch.
+ * Runs: git fetch, git checkout, git pull --ff-only (in order).
+ */
+declare function pullLatest(repoPath: string, branch: string, remote: string): Promise<void>;
+/**
+ * Create a new branch for this run.
+ * Branch name format: claude-auto/{jobId}/{ISO-timestamp}
+ */
+declare function createBranch(repoPath: string, jobId: string): Promise<string>;
+/**
+ * Check if the working tree has uncommitted changes.
+ */
+declare function hasChanges(repoPath: string): Promise<boolean>;
+/**
+ * Push branch to origin with upstream tracking.
+ * Safety: only uses -u flag, no destructive push flags.
+ */
+declare function pushBranch(repoPath: string, branchName: string): Promise<void>;
+/**
+ * Checkout an existing branch (e.g., a PR branch) and reset to match remote.
+ * Used for PR feedback iteration -- safely switches to the existing PR branch.
+ *
+ * Steps:
+ * 1. Fetch the latest state of the branch from origin
+ * 2. Checkout the branch (may already exist locally or be created from remote tracking)
+ * 3. Hard reset to match origin exactly (safe because claude-auto never has local-only state)
+ */
+declare function checkoutExistingBranch(repoPath: string, branchName: string): Promise<void>;
+/**
+ * Create a pull request via GitHub CLI.
+ * Returns the PR URL.
+ */
+declare function createPR(repoPath: string, branchName: string, baseBranch: string, title: string, body: string): Promise<string>;
+/**
+ * Check if the target branch has diverged from the current branch.
+ * Fetches the remote base branch first, then uses git merge-base --is-ancestor
+ * to determine if the remote base is still an ancestor of HEAD.
+ *
+ * @returns true if diverged (remote base has commits not in current branch), false otherwise
+ */
+declare function checkDivergence(repoPath: string, baseBranch: string, remote: string): Promise<boolean>;
+/**
+ * Attempt to rebase the current branch onto the remote base branch.
+ * First checks for divergence; if not diverged, returns early.
+ * If diverged, attempts rebase. On conflict, aborts cleanly and returns conflict list.
+ */
+declare function attemptRebase(repoPath: string, baseBranch: string, remote: string): Promise<RebaseResult>;
+/**
+ * Get the diff between the base branch and HEAD.
+ * Best-effort: returns empty string on error.
+ */
+declare function getDiffFromBase(repoPath: string, baseBranch: string): Promise<string>;
+
+/**
+ * A scored and filtered GitHub issue ready for presentation to Claude.
+ * Body is truncated to 1000 chars to reduce token usage.
+ */
+interface ScoredIssue {
+    number: number;
+    title: string;
+    body: string;
+    labels: string[];
+    score: number;
+    skipReason?: string;
+}
+/**
+ * Triage GitHub issues for a repository by scoring and filtering them
+ * before presenting to Claude. This reduces token usage and improves
+ * work selection quality.
+ *
+ * Scoring rubric:
+ * - Base score: 50
+ * - Label boosts: good first issue (+30), bug (+20), enhancement (+10), documentation (+5)
+ * - Body quality: < 20 chars (-30), > 100 chars (+10), > 500 chars (+5 additional)
+ *
+ * Skip reasons:
+ * - already-attempted: issue was worked on in a previous run
+ * - assigned: issue has assignees
+ * - negative-label: issue has wontfix or duplicate label
+ * - requires-human: issue has question or discussion label
+ *
+ * @param repoPath - Path to the repository (used as cwd for gh CLI)
+ * @param previousIssues - Issue numbers already attempted in prior runs
+ * @returns Scored issues sorted by score descending, with skipped issues excluded
+ */
+declare function triageIssues(repoPath: string, previousIssues: number[]): Promise<ScoredIssue[]>;
+
+/** Stale lock threshold: 45 minutes in milliseconds */
+declare const STALE_THRESHOLD: number;
+/**
+ * Acquire a file-based lock for a job.
+ * Returns a release function on success, or null if the lock is already held.
+ * Uses proper-lockfile for cross-process safety with stale detection.
+ */
+declare function acquireLock(jobId: string): Promise<(() => Promise<void>) | null>;
+
+/**
+ * Write a run log entry as a JSON file for a specific job run.
+ * Creates the runs directory if it doesn't exist (via writeFileSafe).
+ *
+ * @param jobId - The job identifier
+ * @param entry - The run log entry to write
+ */
+declare function writeRunLog(jobId: string, entry: RunLogEntry): Promise<void>;
+/**
+ * Read and parse a specific run log entry.
+ *
+ * @param jobId - The job identifier
+ * @param runId - The run identifier
+ * @returns Parsed RunLogEntry
+ * @throws When the log file doesn't exist (ENOENT)
+ */
+declare function readRunLog(jobId: string, runId: string): Promise<RunLogEntry>;
+/**
+ * List all run logs for a job, sorted by startedAt descending (newest first).
+ * Returns an empty array when the runs directory doesn't exist.
+ * Skips files that fail to parse (logs warning but doesn't throw).
+ *
+ * @param jobId - The job identifier
+ * @returns Array of RunLogEntry sorted by startedAt descending
+ */
+declare function listRunLogs(jobId: string): Promise<RunLogEntry[]>;
+
+/**
+ * Execute a full autonomous run cycle for a job.
+ *
+ * Sequence: lock -> config -> enabled check -> budget check -> pullLatest ->
+ * check PR feedback (priority) -> if feedback: iterate on PR -> else: triage issues ->
+ * create branch -> spawn Claude -> check changes -> push/PR -> log -> unlock
+ *
+ * @param jobId - The job identifier to run
+ * @returns RunResult with status indicating outcome
+ */
+declare function executeRun(jobId: string): Promise<RunResult>;
+
+/**
+ * Run the multi-stage pipeline: plan -> implement -> review -> optional fix.
+ *
+ * Each stage spawns a separate Claude instance via spawnClaude with its
+ * configured model, budget slice, and prompt. The review stage verdict
+ * determines whether a fix stage runs.
+ *
+ * When maxReviewRounds > 1, the review+fix cycle repeats up to N times.
+ * On the last round, if review fails, the fix stage still runs once but
+ * no re-review occurs.
+ *
+ * @param config - Job configuration with pipeline settings
+ * @param repoPath - Path to the repository
+ * @param branchName - Current work branch name
+ * @param runContext - Prior run context for duplicate avoidance
+ * @param triaged - Pre-scored issues from triage
+ * @returns PipelineResult with all stage results aggregated
+ */
+declare function runPipeline(config: JobConfig, repoPath: string, _branchName: string, runContext: RunContext[], triaged: ScoredIssue[]): Promise<PipelineResult>;
+
+/**
+ * Build a read-only tool set for plan and review stages.
+ * Excludes Edit, Write, and git mutation tools (add, commit).
+ * Includes read-only tools: file reading, search, git inspection, issue viewing, test running.
+ *
+ * @param _config - Job configuration (reserved for future guardrail-based filtering)
+ * @returns Array of allowed tool strings for read-only stages
+ */
+declare function buildReadOnlyTools(_config: JobConfig): string[];
+/**
+ * Build the work prompt for the PLAN stage of the pipeline.
+ * Instructs Claude to research the codebase and produce a concrete,
+ * actionable implementation plan without making any changes.
+ *
+ * @param config - Job configuration with focus areas
+ * @param triaged - Pre-scored issues from triage (may be empty)
+ * @param context - Prior run context for duplicate avoidance
+ * @returns Multi-section plan prompt string
+ */
+declare function buildPlanPrompt(config: JobConfig, triaged: ScoredIssue[], context: RunContext[]): string;
+/**
+ * Build the system prompt for the PLAN stage.
+ *
+ * @param config - Job configuration with optional systemPrompt
+ * @returns System prompt string for the planning stage
+ */
+declare function buildPlanSystemPrompt(config: JobConfig): string;
+/**
+ * Build the work prompt for the IMPLEMENT stage of the pipeline.
+ * Includes the plan output, focus areas, guardrails, git safety rules,
+ * and completion instructions.
+ *
+ * @param config - Job configuration with guardrails and focus areas
+ * @param planResult - SpawnResult from the plan stage
+ * @param context - Prior run context for duplicate avoidance
+ * @returns Multi-section implement prompt string
+ */
+declare function buildImplementPrompt(config: JobConfig, planResult: SpawnResult, context: RunContext[]): string;
+/**
+ * Build the system prompt for the IMPLEMENT stage.
+ *
+ * @param config - Job configuration with optional systemPrompt
+ * @returns System prompt string for the implementation stage
+ */
+declare function buildImplementSystemPrompt(config: JobConfig): string;
+/**
+ * Build the work prompt for the REVIEW stage of the pipeline.
+ * Includes the original plan, the implementation diff, and verdict instructions.
+ *
+ * @param config - Job configuration
+ * @param planText - The plan stage output text
+ * @param diffOutput - Git diff of implementation changes
+ * @returns Multi-section review prompt string
+ */
+declare function buildReviewPrompt(_config: JobConfig, planText: string, diffOutput: string): string;
+/**
+ * Build the system prompt for the REVIEW stage.
+ *
+ * @param config - Job configuration with optional systemPrompt
+ * @returns System prompt string for the review stage
+ */
+declare function buildReviewSystemPrompt(config: JobConfig): string;
+/**
+ * Build the work prompt for the FIX stage of the pipeline.
+ * Includes the review feedback and git safety rules.
+ *
+ * @param config - Job configuration
+ * @param reviewText - The review stage output text with issues to fix
+ * @returns Multi-section fix prompt string
+ */
+declare function buildFixPrompt(_config: JobConfig, reviewText: string): string;
+/**
+ * Build the system prompt for the FIX stage.
+ *
+ * @param config - Job configuration with optional systemPrompt
+ * @returns System prompt string for the fix stage
+ */
+declare function buildFixSystemPrompt(config: JobConfig): string;
+/**
+ * Parse the review stage output to determine the verdict.
+ * Searches for "VERDICT: PASS" or "VERDICT: FAIL" markers.
+ * If both exist, FAIL takes priority (safer).
+ * Defaults to "fail" when no verdict marker is found (safer to run fix stage unnecessarily).
+ *
+ * @param reviewResult - SpawnResult from the review stage
+ * @returns "pass" or "fail"
+ */
+declare function parseReviewVerdict(reviewResult: SpawnResult): "pass" | "fail";
+
+/**
+ * Internal interface for PR data from `gh pr list --json`.
+ * Not exported -- external consumers use PRFeedbackContext.
+ */
+interface PRWithFeedback {
+    number: number;
+    title: string;
+    headRefName: string;
+    reviewDecision: string;
+    url: string;
+}
+/**
+ * List open PRs authored by the current user that match this job's branch prefix.
+ * Uses `gh pr list` with JSON output for structured data.
+ *
+ * @param repoPath - Path to the git repository
+ * @param jobId - Job identifier used to filter branches by prefix
+ * @returns Array of PRs matching the claude-auto/{jobId}/ branch prefix
+ */
+declare function listOpenPRsWithFeedback(repoPath: string, jobId: string): Promise<PRWithFeedback[]>;
+/**
+ * Get the owner and name of the repository from `gh repo view`.
+ *
+ * @param repoPath - Path to the git repository
+ * @returns Object with owner (login) and name of the repository
+ */
+declare function getRepoOwnerName(repoPath: string): Promise<{
+    owner: string;
+    name: string;
+}>;
+/**
+ * Fetch unresolved review threads for a PR using the GitHub GraphQL API.
+ * This is necessary because the REST API does not expose the `isResolved` field.
+ *
+ * Filters out:
+ * - Resolved threads (isResolved: true)
+ * - Threads where ALL comments are from bot authors (login ending with "[bot]")
+ *
+ * @param repoPath - Path to the git repository
+ * @param prNumber - PR number to query
+ * @returns Array of unresolved ReviewThread objects with human comments
+ */
+declare function getUnresolvedThreads(repoPath: string, prNumber: number): Promise<ReviewThread[]>;
+/**
+ * Post a comment on a PR using `gh pr comment`.
+ * Best-effort: failures are logged as warnings but never thrown.
+ *
+ * @param repoPath - Path to the git repository
+ * @param prNumber - PR number to comment on
+ * @param body - Comment body text
+ */
+declare function postPRComment(repoPath: string, prNumber: number, body: string): Promise<void>;
+/**
+ * Get the current feedback round count for a PR from the SQLite database.
+ * Counts the number of prior runs with a matching pr_number and non-null feedback_round.
+ *
+ * @param jobId - Job identifier
+ * @param prNumber - PR number
+ * @returns Number of prior feedback rounds (0 if none)
+ */
+declare function getFeedbackRound(jobId: string, prNumber: number): number;
+/**
+ * Check for open PRs with actionable feedback that should be iterated on.
+ *
+ * Orchestration flow:
+ * 1. List open PRs for this job
+ * 2. Filter to PRs with CHANGES_REQUESTED review decision
+ * 3. For each candidate, fetch unresolved review threads
+ * 4. Check feedback round count against max rounds
+ * 5. Return PRFeedbackContext if actionable, null otherwise
+ *
+ * @param repoPath - Path to the git repository
+ * @param jobId - Job identifier
+ * @param maxRounds - Maximum number of feedback rounds allowed
+ * @returns PRFeedbackContext if there's actionable feedback, null otherwise
+ */
+declare function checkPendingPRFeedback(repoPath: string, jobId: string, maxRounds: number): Promise<PRFeedbackContext | null>;
+
+/**
+ * Build the system prompt for Claude, including research instructions
+ * and an optional user-provided system prompt.
+ *
+ * @param config - Job configuration with optional systemPrompt
+ * @returns Combined system prompt string
+ */
+declare function buildSystemPrompt(config: JobConfig): string;
+/**
+ * Build the work prompt for Claude, containing priority chain, focus areas,
+ * conditional guardrails, git safety rules, documentation requirements,
+ * completion instructions, and optionally a "Previous Work" context section.
+ *
+ * @param config - Job configuration with guardrails and focus areas
+ * @param context - Optional array of prior run context for duplicate avoidance
+ * @returns Multi-section work prompt string
+ */
+declare function buildWorkPrompt(config: JobConfig, context?: RunContext[]): string;
+/**
+ * Build a prompt for Claude to address PR review feedback.
+ *
+ * The prompt includes:
+ * 1. Task framing with round/iteration info
+ * 2. Sanitized review comments in XML tags (truncated to 2000 chars each)
+ * 3. Git safety rules
+ * 4. Completion instructions
+ * 5. Previous work context (if provided)
+ *
+ * @param config - Job configuration
+ * @param feedback - PR feedback context with unresolved review threads
+ * @param context - Optional array of prior run context
+ * @returns Multi-section feedback prompt string
+ */
+declare function buildFeedbackPrompt(config: JobConfig, feedback: PRFeedbackContext, context?: RunContext[]): string;
+/**
+ * Build a work prompt enhanced with pre-triaged issue candidates.
+ *
+ * When triaged issues are provided, replaces the generic "check gh issue list"
+ * section with a ranked list of pre-scored candidates. Falls back to the
+ * standard buildWorkPrompt when no triaged issues are available.
+ *
+ * @param config - Job configuration
+ * @param triaged - Array of scored issues from triage (may be empty)
+ * @param context - Optional array of prior run context
+ * @returns Multi-section work prompt string
+ */
+declare function buildTriagedWorkPrompt(config: JobConfig, triaged: ScoredIssue[], context?: RunContext[]): string;
+
+/**
+ * Build the list of allowed tools for Claude based on job config guardrails.
+ * Always includes core tools (Read, Edit, Write, Glob, Grep), git tools,
+ * GitHub CLI tools, and npm test/lint/typecheck tools. Conditionally includes
+ * npm install/add when noNewDependencies is false (default).
+ */
+declare function buildAllowedTools(config: JobConfig): string[];
+/**
+ * Spawn Claude Code CLI in headless mode with JSON output parsing.
+ * Invokes `claude -p` with --output-format json, --max-turns, --max-budget-usd,
+ * --dangerously-skip-permissions, and optional --append-system-prompt and --allowedTools.
+ *
+ * @param options - Spawn configuration including cwd, prompt, limits, and tools
+ * @returns SpawnResult with parsed JSON output fields
+ * @throws SpawnError when process exits non-zero and JSON parsing fails
+ */
+declare function spawnClaude(options: SpawnOptions): Promise<SpawnResult>;
+
+/**
+ * Launch the interactive TUI dashboard.
+ * Renders the App component via ink and blocks until the user quits.
+ */
+declare function launchDashboard(): Promise<void>;
+
+declare class ConfigParseError extends Error {
+    readonly filePath: string;
+    readonly parseErrors: Array<{
+        message: string;
+    }>;
+    name: "ConfigParseError";
+    constructor(filePath: string, parseErrors: Array<{
+        message: string;
+    }>);
+}
+declare class ConfigValidationError extends Error {
+    readonly filePath: string;
+    readonly validationMessage: string;
+    name: "ConfigValidationError";
+    constructor(filePath: string, validationMessage: string);
+}
+declare class SchedulerError extends Error {
+    readonly platform: string;
+    readonly cause?: Error | undefined;
+    name: "SchedulerError";
+    constructor(platform: string, message: string, cause?: Error | undefined);
+}
+declare class CronValidationError extends Error {
+    readonly expression: string;
+    name: "CronValidationError";
+    constructor(expression: string, message: string);
+}
+declare class GitOpsError extends Error {
+    readonly operation: string;
+    readonly repoPath: string;
+    readonly cause?: Error | undefined;
+    name: "GitOpsError";
+    constructor(operation: string, repoPath: string, message: string, cause?: Error | undefined);
+}
+declare class LockError extends Error {
+    readonly jobId: string;
+    name: "LockError";
+    constructor(jobId: string, message: string);
+}
+declare class SpawnError extends Error {
+    readonly exitCode?: number | undefined;
+    name: "SpawnError";
+    constructor(message: string, exitCode?: number | undefined);
+}
+
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Execute a command and return stdout/stderr.
+ * Throws if the command exits with non-zero status.
+ */
+declare function execCommand(command: string, args: string[], options?: {
+    stdin?: string;
+    cwd?: string;
+}): Promise<ExecResult>;
+
+declare function writeFileSafe(filePath: string, content: string): Promise<void>;
+
+declare const paths: {
+    readonly base: string;
+    readonly jobs: string;
+    readonly jobDir: (jobId: string) => string;
+    readonly jobConfig: (jobId: string) => string;
+    readonly logs: string;
+    readonly jobLogs: (jobId: string) => string;
+    readonly jobLog: (jobId: string, runId: string) => string;
+    readonly jobLock: (jobId: string) => string;
+    readonly plistDir: string;
+    readonly plistPath: (jobId: string) => string;
+    readonly crontabLock: string;
+    readonly database: string;
+};
+
+export { type BudgetConfig, COMMANDS, type CalendarInterval, type CliCommand, type CommandHandler, ConfigParseError, ConfigValidationError, type CostSummaryRow, CronValidationError, CrontabScheduler, type DailyCostRow, type EventTriggers, GitOpsError, type JobConfig, JobConfigSchema, LaunchdScheduler, LockError, type NotificationEvent, type NotificationPayload, type PRFeedbackContext, type ParsedCommand, type PipelineResult, type PipelineStageResult, type Platform, type RebaseResult, type RegisteredJob, type ReviewThread, type RunContext, type RunLogEntry, type RunResult, type RunStatus, STALE_THRESHOLD, type ScheduleInfo, type Scheduler, SchedulerError, SchtasksScheduler, type ScoredIssue, SpawnError, type SpawnOptions, type SpawnResult, acquireLock, attemptRebase, buildAllowedTools, buildFeedbackPrompt, buildFixPrompt, buildFixSystemPrompt, buildImplementPrompt, buildImplementSystemPrompt, buildPayload, buildPlanPrompt, buildPlanSystemPrompt, buildReadOnlyTools, buildReviewPrompt, buildReviewSystemPrompt, buildSystemPrompt, buildTriagedWorkPrompt, buildWorkPrompt, checkBudget, checkDivergence, checkPendingPRFeedback, checkRepoCommand, checkoutExistingBranch, closeDatabase, costCommand, createBranch, createCommand, createJob, createPR, createScheduler, cronToCalendarIntervals, cronToSchtasks, deleteJob, describeSchedule, detectPlatform, editCommand, execCommand, executeRun, extractIssueNumber, formatContextWindow, formatDiscord, formatDuration, formatRelativeTime, formatSlack, formatTable, formatTelegram, getCostSummary, getDatabase, getDiffFromBase, getFeedbackRound, getNextRuns, getRepoOwnerName, getUnresolvedThreads, hasChanges, launchDashboard, listCommand, listJobs, listOpenPRsWithFeedback, listRunLogs, loadJobConfig, loadRunContext, logsCommand, parseCommand, parseReviewVerdict, paths, pauseCommand, postIssueComment, postPRComment, pullLatest, pushBranch, readConfigDocument, readJob, readRunLog, removeCommand, reportCommand, resumeCommand, runCli, runPipeline, saveJobConfig, saveRunContext, sendNotifications, shouldNotify, spawnClaude, statusBadge, triageIssues, updateConfigField, updateJob, validateAndDescribeSchedule, validateConfig, validateCronExpression, writeConfigDocument, writeFileSafe, writeRunLog };