ai-foreman 1.3.1 → 1.5.0

package/dist/interviews.d.ts

@@ -0,0 +1,68 @@
+export declare const INTERVIEW_STATE_VERSION = 1;
+export declare const INTERVIEW_DIRECTORY = ".rafi/interviews";
+export type InterviewWorkflow = "create" | "plan" | "tickets-setup-init" | "tickets-setup-update";
+export type InterviewStatus = "in_progress" | "needs_review" | "completed" | "incompatible";
+export interface InterviewRuntimeState {
+    runtime?: "claude" | "codex";
+    model?: string;
+    sessionId?: string;
+    /** True when a session id could not be resumed and a fresh session is needed. */
+    continuityLost?: boolean;
+}
+export interface InterviewOutputFingerprint {
+    path: string;
+    sha256: string | null;
+}
+export interface InterviewFailure {
+    checkpoint: string;
+    summary: string;
+    at: string;
+}
+export interface InterviewRecord {
+    version: number;
+    id: string;
+    workflow: InterviewWorkflow;
+    status: InterviewStatus;
+    /** Arguments/context required to re-enter the runner. No environment secrets. */
+    invocation: Record<string, unknown>;
+    answers: Record<string, unknown>;
+    checkpoint: string;
+    runtime: InterviewRuntimeState;
+    outputs: InterviewOutputFingerprint[];
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    failure?: InterviewFailure;
+}
+export interface InterviewRecordProblem {
+    path: string;
+    reason: string;
+}
+export interface InterviewReadResult {
+    records: InterviewRecord[];
+    problems: InterviewRecordProblem[];
+}
+export declare function interviewDirectory(projectDir: string): string;
+export declare function createInterviewRecord(input: {
+    workflow: InterviewWorkflow;
+    invocation: Record<string, unknown>;
+    answers?: Record<string, unknown>;
+    checkpoint: string;
+    outputs?: string[];
+    now?: Date;
+}): InterviewRecord;
+/** Ensure ignored local state exists without modifying unrelated gitignore text. */
+export declare function ensureInterviewGitignore(projectDir: string): void;
+export declare function saveInterviewRecord(projectDir: string, record: InterviewRecord, now?: Date): InterviewRecord;
+export declare function checkpointInterview(projectDir: string, record: InterviewRecord, update: Partial<Pick<InterviewRecord, "answers" | "checkpoint" | "runtime" | "outputs" | "invocation" | "status">>): InterviewRecord;
+export declare function failInterview(projectDir: string, record: InterviewRecord, checkpoint: string, error: unknown): InterviewRecord;
+export declare function completeInterview(projectDir: string, record: InterviewRecord, now?: Date): InterviewRecord;
+export declare function readInterviewRecords(projectDir: string): InterviewReadResult;
+export declare function unfinishedInterviews(projectDir: string): InterviewRecord[];
+export declare function findInterviewRecord(projectDir: string, id: string): InterviewRecord | undefined;
+export declare function discardInterview(projectDir: string, id: string): boolean;
+/** Remove only completed records past retention; malformed/incompatible files stay for explicit discard. */
+export declare function pruneCompletedInterviews(projectDir: string, now?: Date): string[];
+export declare function fingerprintOutputs(projectDir: string, paths: string[]): InterviewOutputFingerprint[];
+export declare function outputsChanged(projectDir: string, fingerprints: InterviewOutputFingerprint[]): string[];
+export declare function redactFailure(error: unknown): string;

package/dist/interviews.js

@@ -0,0 +1,184 @@
+/**
+ * Durable, local state for commands that ask a human questions.  This lives in
+ * ai-foreman (rather than a CLI package) because `rafi tickets` is implemented
+ * there too.  Records deliberately contain decisions and small diagnostics,
+ * never a transcript or command output.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join, relative, resolve } from "node:path";
+export const INTERVIEW_STATE_VERSION = 1;
+export const INTERVIEW_DIRECTORY = ".rafi/interviews";
+const MAX_FAILURE_LENGTH = 1_000;
+const COMPLETE_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
+export function interviewDirectory(projectDir) {
+    return join(resolve(projectDir), INTERVIEW_DIRECTORY);
+}
+export function createInterviewRecord(input) {
+    const stamp = (input.now ?? new Date()).toISOString();
+    return {
+        version: INTERVIEW_STATE_VERSION,
+        id: randomUUID(),
+        workflow: input.workflow,
+        status: "in_progress",
+        invocation: { ...input.invocation },
+        answers: { ...(input.answers ?? {}) },
+        checkpoint: input.checkpoint,
+        runtime: {},
+        outputs: fingerprintOutputs(String(input.invocation.projectDir ?? ""), input.outputs ?? []),
+        createdAt: stamp,
+        updatedAt: stamp,
+    };
+}
+/** Ensure ignored local state exists without modifying unrelated gitignore text. */
+export function ensureInterviewGitignore(projectDir) {
+    const root = resolve(projectDir);
+    const path = join(root, ".gitignore");
+    const line = ".rafi/interviews/";
+    const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (current.split(/\r?\n/).some((entry) => entry.trim() === line))
+        return;
+    const prefix = current && !current.endsWith("\n") ? "\n" : "";
+    writeFileSync(path, `${current}${prefix}${line}\n`, "utf8");
+}
+export function saveInterviewRecord(projectDir, record, now = new Date()) {
+    validateRecord(record);
+    const directory = interviewDirectory(projectDir);
+    mkdirSync(directory, { recursive: true });
+    ensureInterviewGitignore(projectDir);
+    const next = { ...record, updatedAt: now.toISOString() };
+    const path = interviewRecordPath(projectDir, next.id);
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    renameSync(temp, path);
+    return next;
+}
+export function checkpointInterview(projectDir, record, update) {
+    const next = {
+        ...record,
+        ...update,
+        answers: update.answers ? { ...update.answers } : record.answers,
+        runtime: update.runtime ? { ...update.runtime } : record.runtime,
+        invocation: update.invocation ? { ...update.invocation } : record.invocation,
+        outputs: update.outputs ? update.outputs.map((output) => ({ ...output })) : record.outputs,
+    };
+    return saveInterviewRecord(projectDir, next);
+}
+export function failInterview(projectDir, record, checkpoint, error) {
+    const at = new Date().toISOString();
+    return saveInterviewRecord(projectDir, {
+        ...record,
+        status: record.status === "needs_review" ? "needs_review" : "in_progress",
+        checkpoint,
+        failure: { checkpoint, at, summary: redactFailure(error) },
+    });
+}
+export function completeInterview(projectDir, record, now = new Date()) {
+    const stamp = now.toISOString();
+    return saveInterviewRecord(projectDir, {
+        ...record,
+        status: "completed",
+        completedAt: stamp,
+        failure: undefined,
+    }, now);
+}
+export function readInterviewRecords(projectDir) {
+    const directory = interviewDirectory(projectDir);
+    if (!existsSync(directory))
+        return { records: [], problems: [] };
+    const records = [];
+    const problems = [];
+    for (const name of readFileNames(directory)) {
+        const path = join(directory, name);
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            const record = parseInterviewRecord(parsed);
+            records.push(record);
+        }
+        catch (error) {
+            problems.push({ path, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    records.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    return { records, problems };
+}
+export function unfinishedInterviews(projectDir) {
+    return readInterviewRecords(projectDir).records.filter((record) => record.status === "in_progress" || record.status === "needs_review" || record.status === "incompatible");
+}
+export function findInterviewRecord(projectDir, id) {
+    return readInterviewRecords(projectDir).records.find((record) => record.id === id || record.id.startsWith(id));
+}
+export function discardInterview(projectDir, id) {
+    const record = findInterviewRecord(projectDir, id);
+    if (!record)
+        return false;
+    rmSync(interviewRecordPath(projectDir, record.id));
+    return true;
+}
+/** Remove only completed records past retention; malformed/incompatible files stay for explicit discard. */
+export function pruneCompletedInterviews(projectDir, now = new Date()) {
+    const removed = [];
+    for (const record of readInterviewRecords(projectDir).records) {
+        if (record.status !== "completed" || !record.completedAt)
+            continue;
+        if (now.getTime() - new Date(record.completedAt).getTime() <= COMPLETE_RETENTION_MS)
+            continue;
+        rmSync(interviewRecordPath(projectDir, record.id));
+        removed.push(record.id);
+    }
+    return removed;
+}
+export function fingerprintOutputs(projectDir, paths) {
+    if (!projectDir)
+        return paths.map((path) => ({ path, sha256: null }));
+    return paths.map((path) => ({ path, sha256: fingerprintFile(projectDir, path) }));
+}
+export function outputsChanged(projectDir, fingerprints) {
+    return fingerprints
+        .filter((fingerprint) => fingerprintFile(projectDir, fingerprint.path) !== fingerprint.sha256)
+        .map((fingerprint) => fingerprint.path);
+}
+export function redactFailure(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw
+        .replace(/((?:api[_-]?key|token|password|secret)\s*[=:])\s*[^\s,;]+/gi, "$1<redacted>")
+        .replace(/\b(?:sk|rk|ghp|github_pat)_[A-Za-z0-9_-]+\b/g, "<redacted>")
+        .replace(/\s+/g, " ")
+        .slice(0, MAX_FAILURE_LENGTH);
+}
+function interviewRecordPath(projectDir, id) {
+    return join(interviewDirectory(projectDir), `${id}.json`);
+}
+function readFileNames(directory) {
+    return readdirSync(directory).filter((name) => name.endsWith(".json"));
+}
+function fingerprintFile(projectDir, path) {
+    const root = resolve(projectDir);
+    const absolute = resolve(root, path);
+    if (relative(root, absolute).startsWith(".."))
+        return null;
+    if (!existsSync(absolute))
+        return null;
+    return createHash("sha256").update(readFileSync(absolute)).digest("hex");
+}
+function parseInterviewRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid interview record");
+    const record = value;
+    if (record.version !== INTERVIEW_STATE_VERSION) {
+        // Preserve it on disk. The caller can show it and require an explicit discard.
+        if (typeof record.id === "string" && typeof record.workflow === "string") {
+            return { ...record, status: "incompatible" };
+        }
+        throw new Error(`unsupported interview record version: ${String(record.version)}`);
+    }
+    validateRecord(record);
+    return record;
+}
+function validateRecord(record) {
+    if (record.version !== INTERVIEW_STATE_VERSION)
+        throw new Error("unsupported interview record version");
+    if (!record.id || !record.workflow || !record.checkpoint || !record.createdAt || !record.updatedAt) {
+        throw new Error("invalid interview record");
+    }
+}

package/dist/log.d.ts

@@ -1,7 +1,7 @@
 /** A single structured log record. */
 export interface LogRecord {
     ts: string;
-    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "qa" | "qa-fix" | "error";
+    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "gitlab-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "pr-auto-merge-enabled" | "pr-auto-merge-failed" | "mr-created" | "mr-existing" | "mr-failed" | "mr-auto-merge-enabled" | "mr-auto-merge-failed" | "branch-auto-merge-wait" | "branch-direct-merge" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "qa" | "qa-fix" | "error";
     [key: string]: unknown;
 }
 /** Append-only JSONL logger. One line per record, plus an echo to the console. */

package/dist/runtimeAuth.js

@@ -25,7 +25,7 @@ export function checkRuntimeReady(projectDir, runtime) {
             });
         }
         else {
-            execFileSync("codex", ["exec", "-C", projectDir, "Return exactly OK"], {
+            execFileSync("codex", ["exec", "--skip-git-repo-check", "-C", projectDir, "Return exactly OK"], {
                 cwd: projectDir,
                 encoding: "utf8",
                 stdio: ["ignore", "pipe", "pipe"],

package/dist/tickets/commands.d.ts

@@ -3,6 +3,7 @@ import type { ValidationResult } from "./stateDb.js";
 import { type TicketsConfig, resolveTicketPaths } from "./config.js";
 import { StateDb } from "./stateDb.js";
 import { runAllValidation } from "./validate.js";
+import { type ReviewCommandOptions, type ReviewCommandResult } from "./recommendations.js";
 export interface TicketContext {
     config: TicketsConfig;
     projectDir: string;
@@ -92,3 +93,4 @@ export declare function cmdImplementationQueue(projectDir: string): import("./qu
 export declare function cmdArchive(projectDir: string, _opts: {
     olderThanDays?: number;
 }): void;
+export declare function cmdReview(projectDir: string, opts?: ReviewCommandOptions): ReviewCommandResult;

package/dist/tickets/commands.js

@@ -8,6 +8,7 @@ import { nowTimestamp, logEvent } from "./events.js";
 import { renderAndWrite, renderTrackerRules } from "./renderMarkdown.js";
 import { runAllValidation } from "./validate.js";
 import { buildNextQueue } from "./queue.js";
+import { cmdReviewRecommendations } from "./recommendations.js";
 export function openContext(projectDir) {
     const config = loadTicketsConfig(projectDir);
     const paths = resolveTicketPaths(config, projectDir);
@@ -78,6 +79,14 @@ export function cmdInit(projectDir, opts) {
     };
     writeFileSync(join(ticketsDir, "config.yaml"), stringify(config, { lineWidth: 80 }), "utf8");
     writeFileSync(join(ticketsDir, "tickets.yaml"), "tickets: []\n", "utf8");
+    writeFileSync(join(ticketsDir, ".gitignore"), [
+        "imports/",
+        "ticket-state.sqlite",
+        "ticket-state.sqlite-shm",
+        "ticket-state.sqlite-wal",
+        "backups/",
+        "",
+    ].join("\n"), "utf8");
     writeFileSync(join(ticketsDir, "tracker-rules.md"), renderTrackerRules(progressDoc), "utf8");
     const ticketSchema = {
         $schema: "http://json-schema.org/draft-07/schema#",
@@ -100,6 +109,20 @@ export function cmdInit(projectDir, opts) {
             likely_files: { type: "array", items: { type: "string" } },
             rollback: { type: ["string", "null"] },
             notes: { type: ["string", "null"] },
+            external_refs: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["provider", "id"],
+                    additionalProperties: true,
+                    properties: {
+                        provider: { type: "string", minLength: 1 },
+                        id: { type: "string", minLength: 1 },
+                        key: { type: ["string", "null"] },
+                        url: { type: ["string", "null"] },
+                    },
+                },
+            },
         },
     };
     writeFileSync(join(ticketsDir, "schema", "tickets.schema.json"), JSON.stringify(ticketSchema, null, 2), "utf8");
@@ -453,3 +476,7 @@ export function cmdArchive(projectDir, _opts) {
         renderAfterUpdate(ctx);
     });
 }
+// ── review recommendations ──────────────────────────────────────────────────
+export function cmdReview(projectDir, opts = {}) {
+    return cmdReviewRecommendations(projectDir, opts);
+}

package/dist/tickets/importer.d.ts

@@ -1 +1,56 @@
+import type { TicketDef } from "./ticketSchema.js";
+import type { TicketSourceConfig } from "./setupConfig.js";
 export declare function importFromMarkdown(_progressDocPath: string): never;
+export interface ImportedTicketItem {
+    provider: "linear" | "jira";
+    providerId: string;
+    key?: string | null;
+    url?: string | null;
+    title: string;
+    description?: string | null;
+    area?: string | null;
+    priority?: string | number | null;
+    size?: string | number | null;
+    status?: string | null;
+    statusCategory?: string | null;
+    labels?: string[];
+    comments?: ImportedComment[];
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    raw: unknown;
+}
+export interface ImportedComment {
+    author?: string | null;
+    body: string;
+    createdAt?: string | null;
+}
+export interface ExternalImportOptions {
+    importCap: number;
+    commentLimit: number;
+    recommendSplitForXl?: boolean;
+}
+export interface ExternalImportResult {
+    provider: "linear" | "jira";
+    sourceLabel: string;
+    fetched: number;
+    created: number;
+    updated: number;
+    snapshotPath: string;
+}
+export declare function importExternalSources(projectDir: string, sources: Extract<TicketSourceConfig, {
+    type: "linear" | "jira";
+}>[], opts: ExternalImportOptions): Promise<ExternalImportResult[]>;
+export declare function validateExternalSourceAccess(source: Extract<TicketSourceConfig, {
+    type: "linear" | "jira";
+}>): Promise<void>;
+export declare function fetchLinearIssues(source: Extract<TicketSourceConfig, {
+    type: "linear";
+}>, opts: ExternalImportOptions): Promise<ImportedTicketItem[]>;
+export declare function fetchJiraIssues(source: Extract<TicketSourceConfig, {
+    type: "jira";
+}>, opts: ExternalImportOptions): Promise<ImportedTicketItem[]>;
+export declare function applyImportedItems(projectDir: string, items: ImportedTicketItem[]): {
+    created: number;
+    updated: number;
+    tickets: TicketDef[];
+};