ai-foreman 1.7.4 → 1.7.5

package/dist/qaReview.js

@@ -1,9 +1,10 @@
+import { currentActivity, withActivityPhase } from "./activity.js";
 import { buildQaFixInstruction, buildQaInstruction, parseStepStatus } from "./foreman.js";
-import { createDisposableQaSnapshot } from "./qaSnapshot.js";
+import { createDisposableQaSnapshotAsync } from "./qaSnapshot.js";
 export async function runIsolatedQa(opts) {
     const history = [];
     for (let cycle = 1; cycle <= opts.maxCycles; cycle++) {
-        const review = await oneReview(opts, cycle);
+        const review = await withActivityPhase(`running QA cycle ${cycle}/${opts.maxCycles}`, () => oneReview(opts, cycle));
         if (review.outcome === "retry-modification") {
             cycle -= 1;
             continue;
@@ -15,7 +16,7 @@ export async function runIsolatedQa(opts) {
         history.push({ cycle, outcome: "qa_fail", detail: review.detail });
         if (cycle === opts.maxCycles)
             break;
-        const fix = await opts.fix(review.detail ?? "QA reported unspecified issues");
+        const fix = await withActivityPhase("applying QA fixes", () => opts.fix(review.detail ?? "QA reported unspecified issues"));
         if (!fix.ok)
             return { outcome: "blocked", detail: fix.detail ?? "Builder QA fix failed" };
     }
@@ -30,19 +31,20 @@ export async function runIsolatedQa(opts) {
     const issues = decision.action === "remediate" ? decision.remediation : history.at(-1)?.detail;
     if (!issues)
         return { outcome: "nonconverged", detail: "Planner remediation did not produce approved fix instructions" };
-    const fix = await opts.fix(issues);
+    const fix = await withActivityPhase("applying QA remediation", () => opts.fix(issues));
     if (!fix.ok)
         return { outcome: "blocked", detail: fix.detail ?? "Builder QA fix failed" };
     return runIsolatedQa(opts);
 }
 async function oneReview(opts, cycle) {
-    const snapshot = createDisposableQaSnapshot(opts.builderWorktree);
+    const progress = (state, detail) => currentActivity()?.update(state, detail);
+    const snapshot = await withActivityPhase("preparing disposable QA snapshot", () => createDisposableQaSnapshotAsync(opts.builderWorktree, progress));
     let qa;
     try {
         const resume = opts.qaStrategy === "compact" && opts.state.modificationViolations === 0 ? opts.state.sessionId : undefined;
         qa = await opts.createQa(snapshot.path, resume);
         if (opts.qaStrategy === "compact" && opts.state.reviews > 0 && resume) {
-            const compacted = await compactWithRetry(qa);
+            const compacted = await withActivityPhase("compacting QA session", () => compactWithRetry(qa));
             if (!compacted.ok) {
                 await qa.close();
                 qa = await opts.createQa(snapshot.path);
@@ -59,7 +61,7 @@ async function oneReview(opts, cycle) {
         const status = parseStepStatus(turn.text);
         opts.state.reviews += 1;
         opts.state.sessionId = qa.sessionId();
-        const changes = snapshot.qaChanges();
+        const changes = await withActivityPhase("checking QA file changes", () => snapshot.qaChanges());
         if (changes.length) {
             opts.state.modificationViolations += 1;
             opts.evidence?.({ cycle, outcome: "qa_file_modification", detail: "QA modified the disposable review copy", qaDiff: changes });
@@ -82,8 +84,9 @@ async function oneReview(opts, cycle) {
         return { outcome: "needs-human", detail: status.error ?? `QA returned ${status.kind}` };
     }
     finally {
-        await qa?.close().catch(() => { });
-        snapshot.remove();
+        if (qa)
+            await withActivityPhase("closing QA session", () => qa.close().catch(() => { }));
+        await withActivityPhase("cleaning up disposable QA snapshot", () => snapshot.remove());
     }
 }
 export async function compactWithRetry(adapter) {

package/dist/qaSnapshot.d.ts

@@ -14,6 +14,20 @@ export interface DisposableQaSnapshot {
     qaChanges(): string[];
     remove(): void;
 }
+export interface AsyncDisposableQaSnapshot {
+    path: string;
+    manifest: QaChangeManifest;
+    verify(): Promise<void>;
+    qaChanges(): Promise<string[]>;
+    remove(): Promise<void>;
+}
+export type QaSnapshotProgress = (state: string, detail?: string) => void;
 /** Reproduce the Builder's exact change set in a detached disposable worktree. */
 export declare function createDisposableQaSnapshot(builderWorktree: string): DisposableQaSnapshot;
+/**
+ * Async form used by the live CLI. Git and filesystem work yields to the event
+ * loop so the activity reporter can keep animating during large snapshots.
+ */
+export declare function createDisposableQaSnapshotAsync(builderWorktree: string, progress?: QaSnapshotProgress): Promise<AsyncDisposableQaSnapshot>;
 export declare function changeManifest(worktree: string): QaChangeManifest;
+export declare function changeManifestAsync(worktree: string, progress?: QaSnapshotProgress, state?: string): Promise<QaChangeManifest>;

package/dist/qaSnapshot.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
+import { cp, lstat, mkdir, mkdtemp, readFile, readlink, rm, symlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 /** Reproduce the Builder's exact change set in a detached disposable worktree. */
 export function createDisposableQaSnapshot(builderWorktree) {
     const source = resolve(builderWorktree);
@@ -47,6 +48,69 @@ export function createDisposableQaSnapshot(builderWorktree) {
         throw error;
     }
 }
+/**
+ * Async form used by the live CLI. Git and filesystem work yields to the event
+ * loop so the activity reporter can keep animating during large snapshots.
+ */
+export async function createDisposableQaSnapshotAsync(builderWorktree, progress = () => { }) {
+    const source = resolve(builderWorktree);
+    progress("preparing disposable QA snapshot", "locating Builder worktree");
+    const root = (await runGit(source, ["rev-parse", "--show-toplevel"])).toString().trim();
+    const tempRoot = await mkdtemp(join(tmpdir(), "rafi-qa-"));
+    const review = join(tempRoot, "review");
+    const head = (await runGit(source, ["rev-parse", "HEAD"])).toString().trim();
+    progress("preparing disposable QA snapshot", "creating detached review worktree");
+    try {
+        await runGit(root, ["worktree", "add", "--detach", review, head]);
+    }
+    catch (error) {
+        await rm(tempRoot, { recursive: true, force: true });
+        throw new Error(`cannot create disposable QA worktree: ${errorMessage(error)}`);
+    }
+    try {
+        progress("preparing disposable QA snapshot", "copying tracked Builder changes");
+        const diff = await runGit(source, ["diff", "--binary", "HEAD"]);
+        if (diff.length) {
+            try {
+                await runGit(review, ["apply", "--index", "--binary", "--whitespace=nowarn", "-"], diff);
+            }
+            catch (error) {
+                throw new Error(`cannot apply Builder diff to QA worktree: ${errorMessage(error)}`);
+            }
+        }
+        const paths = await untrackedPathsAsync(source);
+        for (let index = 0; index < paths.length; index++) {
+            progress("preparing disposable QA snapshot", `copying untracked files ${index + 1}/${paths.length}`);
+            await copyUntrackedAsync(source, review, paths[index]);
+        }
+        progress("preparing disposable QA snapshot", "recording Builder change manifest");
+        const manifest = await changeManifestAsync(source, progress, "preparing disposable QA snapshot");
+        const snapshot = {
+            path: review,
+            manifest,
+            verify: async () => {
+                const actual = await changeManifestAsync(review, progress, "preparing disposable QA snapshot");
+                if (JSON.stringify(actual) !== JSON.stringify(manifest)) {
+                    throw new Error(`disposable QA snapshot does not match Builder change manifest: expected ${JSON.stringify(manifest)}, got ${JSON.stringify(actual)}`);
+                }
+            },
+            qaChanges: async () => manifestDifference(manifest, await changeManifestAsync(review, progress)),
+            remove: async () => {
+                progress("cleaning up disposable QA snapshot", "removing detached review worktree");
+                await runGit(root, ["worktree", "remove", "--force", review]).catch(() => { });
+                await rm(tempRoot, { recursive: true, force: true });
+            },
+        };
+        progress("preparing disposable QA snapshot", "verifying review copy");
+        await snapshot.verify();
+        return snapshot;
+    }
+    catch (error) {
+        await runGit(root, ["worktree", "remove", "--force", review]).catch(() => { });
+        await rm(tempRoot, { recursive: true, force: true });
+        throw error;
+    }
+}
 export function changeManifest(worktree) {
     const diff = execFileSync("git", ["-C", worktree, "diff", "--binary", "HEAD"], { encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
     const untracked = untrackedPaths(worktree).map((path) => {
@@ -58,10 +122,29 @@ export function changeManifest(worktree) {
     });
     return { diffDigest: createHash("sha256").update(diff).digest("hex"), untracked };
 }
+export async function changeManifestAsync(worktree, progress = () => { }, state = "checking QA file changes") {
+    const diff = await runGit(worktree, ["diff", "--binary", "HEAD"]);
+    const paths = await untrackedPathsAsync(worktree);
+    const untracked = [];
+    for (let index = 0; index < paths.length; index++) {
+        const path = paths[index];
+        progress(state, `hashing untracked files ${index + 1}/${paths.length}`);
+        const absolute = join(worktree, path);
+        const stat = await lstat(absolute);
+        const kind = stat.isSymbolicLink() ? "symlink" : "file";
+        const bytes = kind === "symlink" ? Buffer.from(await readlink(absolute)) : await readFile(absolute);
+        untracked.push({ path, kind, mode: stat.mode & 0o7777, digest: createHash("sha256").update(bytes).digest("hex") });
+    }
+    return { diffDigest: createHash("sha256").update(diff).digest("hex"), untracked };
+}
 function untrackedPaths(worktree) {
     const raw = execFileSync("git", ["-C", worktree, "ls-files", "--others", "--exclude-standard", "-z"], { encoding: "buffer" });
     return raw.toString().split("\0").filter(Boolean).sort();
 }
+async function untrackedPathsAsync(worktree) {
+    const raw = await runGit(worktree, ["ls-files", "--others", "--exclude-standard", "-z"]);
+    return raw.toString().split("\0").filter(Boolean).sort();
+}
 function copyUntracked(source, target, path) {
     const from = join(source, path);
     const to = join(target, path);
@@ -75,6 +158,39 @@ function copyUntracked(source, target, path) {
     else
         cpSync(from, to, { preserveTimestamps: true });
 }
+async function copyUntrackedAsync(source, target, path) {
+    const from = join(source, path);
+    const to = join(target, path);
+    await mkdir(dirname(to), { recursive: true });
+    const stat = await lstat(from);
+    if (stat.isSymbolicLink()) {
+        await rm(to, { force: true });
+        await symlink(await readlink(from), to);
+    }
+    else {
+        await cp(from, to, { preserveTimestamps: true });
+    }
+}
+function runGit(cwd, args, input) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn("git", ["-C", cwd, ...args], { stdio: ["pipe", "pipe", "pipe"] });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolvePromise(Buffer.concat(stdout));
+            else
+                reject(new Error(Buffer.concat(stderr).toString().trim() || `git exited with status ${code ?? "unknown"}`));
+        });
+        child.stdin.end(input);
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function manifestDifference(before, after) {
     const changes = [];
     if (before.diffDigest !== after.diffDigest)

package/dist/runtimeReadiness.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
 import { delimiter, isAbsolute, resolve } from "node:path";
+import { currentActivity, withActivityPhase } from "./activity.js";
 export const RUNTIME_PROBE_TIMEOUT_MS = 30_000;
 export const RUNTIME_DIAGNOSTIC_LIMIT = 8 * 1024;
 const RELEVANT_ENV = /^(ANTHROPIC|CLAUDE|CODEX|OPENAI|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|SSL_CERT_FILE|NODE_EXTRA_CA_CERTS)(_|$)/i;
@@ -52,6 +53,9 @@ function isRunnableFile(path, platform) {
     }
 }
 export async function probeRuntime(cwd, runtime, opts = {}) {
+    return withActivityPhase(`checking ${runtime} runtime`, () => probeRuntimeInternal(cwd, runtime, opts));
+}
+async function probeRuntimeInternal(cwd, runtime, opts) {
     const env = opts.env ?? process.env;
     const command = runtime === "claude" ? "claude" : "codex";
     const executable = resolveExecutablePath(command, env) ?? command;
@@ -68,6 +72,7 @@ export async function probeRuntime(cwd, runtime, opts = {}) {
         const spawnOpts = { cwd, env, stdio: ["ignore", "pipe", "pipe"] };
         const child = spawn(executable, args, spawnOpts);
         const append = (chunk) => {
+            currentActivity()?.pulse(`${runtime} runtime responded`);
             if (output.length >= limit)
                 return;
             const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);

package/dist/sources/sourceRegistry.js

@@ -1,10 +1,13 @@
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse, stringify } from "yaml";
 import { fetchAndSnapshotUrl, normalizePublicHttpUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
 import { fetchJiraIssues, fetchLinearIssues } from "../tickets/importer.js";
+import { withActivityPhase } from "../activity.js";
+const execFileAsync = promisify(execFile);
 export const SOURCE_REQUEST_START = "RAFI_SOURCE_REQUEST_START";
 export const SOURCE_REQUEST_END = "RAFI_SOURCE_REQUEST_END";
 const CONFIG_FILE = "rafi-config.yaml";
@@ -148,9 +151,12 @@ export function sourceRequestFromAnswer(answer, projectDir) {
     if (/^https?:\/\/\S+$/i.test(value))
         return requestFromUrl(value);
     const candidate = resolve(projectDir, value);
-    if (value && existsSync(candidate))
-        return { type: "local", label: basename(candidate), locator: { path: normalizeLocalPath(projectDir, candidate) } };
-    if (hasGlobMagic(value) || /^(?:\.{0,2}\/|\/)/.test(value) || /[\\/][^\\/]+\.[A-Za-z0-9]{1,12}$/.test(value))
+    if (value && existsSync(candidate)) {
+        const rel = relative(resolve(projectDir), candidate);
+        const path = !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel) ? rel || "." : candidate;
+        return { type: "local", label: basename(candidate), locator: { path } };
+    }
+    if (hasGlobMagic(value) || /^(?:\.{0,2}\/|\/)/.test(value) || /^[^\s]+[\\/][^\\/]+\.[A-Za-z0-9]{1,12}$/.test(value))
         return { type: "local", label: basename(value), locator: { path: value } };
     if (/^(?:open\s+)?issues\s+for\s+(?:this|the)\s+repo(?:sitory)?$/i.test(value))
         return { type: inferOriginProvider(projectDir), label: "Open repository issues", locator: { repository: inferOriginRepository(projectDir), mode: "issues", filters: { state: "open" } } };
@@ -272,7 +278,7 @@ async function captureUrl(projectDir, entry, storage) {
     rmSync(resolve(projectDir, fetched.metadataPath), { force: true });
     return version;
 }
-function captureCliProvider(projectDir, entry, storage) {
+async function captureCliProvider(projectDir, entry, storage) {
     const repository = entry.locator.repository || inferOriginRepository(projectDir);
     const mode = entry.locator.mode ?? "issues";
     let command;
@@ -309,7 +315,8 @@ function captureCliProvider(projectDir, entry, storage) {
     }
     let text;
     try {
-        text = execFileSync(command, args, { cwd: projectDir, encoding: "utf8", maxBuffer: 20 * 1024 * 1024 });
+        const result = await withActivityPhase(`fetching ${entry.type} source`, () => execFileAsync(command, args, { cwd: projectDir, encoding: "utf8", maxBuffer: 20 * 1024 * 1024 }));
+        text = result.stdout;
     }
     catch (error) {
         throw new Error(`${entry.type} source ${entry.label} could not be retrieved with authenticated ${command}: ${error instanceof Error ? error.message : String(error)}`);

package/dist/tickets/importer.js

@@ -5,6 +5,7 @@ import { StateDb } from "./stateDb.js";
 import { nowTimestamp } from "./events.js";
 import { loadTicketsConfig, resolveTicketPaths } from "./config.js";
 import { insertXlSplitRecommendations } from "./recommendations.js";
+import { currentActivity, withActivityPhase } from "../activity.js";
 export function importFromMarkdown(_progressDocPath) {
     throw new Error("foreman tickets import is not yet implemented.\n\n" +
         "To start fresh:\n" +
@@ -19,9 +20,9 @@ export function importFromMarkdown(_progressDocPath) {
 export async function importExternalSources(projectDir, sources, opts) {
     const results = [];
     for (const source of sources) {
-        const items = source.type === "linear"
-            ? await fetchLinearIssues(source, opts)
-            : await fetchJiraIssues(source, opts);
+        const items = await withActivityPhase(`importing ${source.type} tickets`, () => source.type === "linear"
+            ? fetchLinearIssues(source, opts)
+            : fetchJiraIssues(source, opts));
         const snapshotPath = writeImportSnapshot(projectDir, source.type, {
             source: redactSource(source),
             fetched_at: new Date().toISOString(),
@@ -42,11 +43,13 @@ export async function importExternalSources(projectDir, sources, opts) {
     return results;
 }
 export async function validateExternalSourceAccess(source) {
-    if (source.type === "linear") {
-        await fetchLinearIssues(source, { importCap: 1, commentLimit: 0 });
-        return;
-    }
-    await fetchJiraIssues(source, { importCap: 1, commentLimit: 0 });
+    await withActivityPhase(`checking ${source.type} access`, async () => {
+        if (source.type === "linear") {
+            await fetchLinearIssues(source, { importCap: 1, commentLimit: 0 });
+            return;
+        }
+        await fetchJiraIssues(source, { importCap: 1, commentLimit: 0 });
+    });
 }
 export async function fetchLinearIssues(source, opts) {
     const apiKey = process.env[source.api_key_env];
@@ -84,6 +87,7 @@ export async function fetchLinearIssues(source, opts) {
             if (items.length >= opts.importCap)
                 break;
         }
+        currentActivity()?.update("importing Linear tickets", `fetched ${items.length}`);
         if (!issues?.pageInfo?.hasNextPage || !issues.pageInfo.endCursor || nodes.length === 0)
             break;
         after = issues.pageInfo.endCursor;
@@ -137,6 +141,7 @@ export async function fetchJiraIssues(source, opts) {
             if (items.length >= opts.importCap)
                 break;
         }
+        currentActivity()?.update("importing Jira tickets", `fetched ${items.length}`);
         nextPageToken = typeof json.nextPageToken === "string" ? json.nextPageToken : undefined;
         if (!nextPageToken || issues.length === 0 || json.isLast === true)
             break;

package/dist/tickets/sourceFetch.js

@@ -5,12 +5,22 @@ import { isIP } from "node:net";
 import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { readdirSync } from "node:fs";
 import { parse as parseHtml } from "parse5";
+import { currentActivity, withActivityPhase } from "../activity.js";
 export const DEFAULT_SOURCE_FETCH_LIMITS = {
     timeoutMs: 15_000,
     maxBytes: 10 * 1024 * 1024,
     maxRedirects: 5,
 };
 export async function fetchAndSnapshotUrl(projectDir, input, limits = {}) {
+    const label = (() => { try {
+        return `fetching source ${new URL(input).hostname}`;
+    }
+    catch {
+        return "fetching URL source";
+    } })();
+    return withActivityPhase(label, () => fetchAndSnapshotUrlInternal(projectDir, input, limits));
+}
+async function fetchAndSnapshotUrlInternal(projectDir, input, limits) {
     const effective = { ...DEFAULT_SOURCE_FETCH_LIMITS, ...limits };
     const requested = normalizePublicHttpUrl(input);
     let current = requested;
@@ -126,6 +136,7 @@ async function readLimitedBody(response, maxBytes) {
         if (done)
             break;
         total += value.length;
+        currentActivity()?.pulse(`downloaded ${formatBytes(total)}`);
         if (total > maxBytes) {
             await reader.cancel();
             throw new Error(`URL content exceeds ${maxBytes} byte limit`);
@@ -174,6 +185,7 @@ async function extractSourceText(kind, bytes) {
         const document = await pdfjs.getDocument({ data: bytes, useWorkerFetch: false, isEvalSupported: false }).promise;
         const pages = [];
         for (let pageNumber = 1; pageNumber <= document.numPages; pageNumber++) {
+            currentActivity()?.update("extracting PDF source", `page ${pageNumber}/${document.numPages}`);
             const page = await document.getPage(pageNumber);
             const content = await page.getTextContent();
             pages.push(content.items.map((item) => "str" in item ? item.str : "").join(" "));
@@ -185,6 +197,13 @@ async function extractSourceText(kind, bytes) {
     const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
     return kind === "html" ? htmlToText(decoded) : decoded;
 }
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
 export function htmlToText(html) {
     const doc = parseHtml(html);
     const blocks = new Set(["address", "article", "aside", "blockquote", "br", "div", "footer", "h1", "h2", "h3", "h4", "h5", "h6", "header", "li", "main", "p", "section", "table", "tr"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "description": "An orchestrator that keeps Codex CLI / Claude Code builders moving through their step list unattended. Part of Rafi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -17,6 +17,10 @@
     "ai-foreman": "dist/index.js"
   },
   "exports": {
+    "./activity.js": {
+      "types": "./dist/activity.d.ts",
+      "default": "./dist/activity.js"
+    },
     "./agent-run.js": {
       "types": "./dist/agentRun.d.ts",
       "default": "./dist/agentRun.js"
@@ -25,6 +29,10 @@
       "types": "./dist/interviews.d.ts",
       "default": "./dist/interviews.js"
     },
+    "./provider-questions.js": {
+      "types": "./dist/providerQuestions.d.ts",
+      "default": "./dist/providerQuestions.js"
+    },
     "./runtime-readiness.js": {
       "types": "./dist/runtimeReadiness.d.ts",
       "default": "./dist/runtimeReadiness.js"
@@ -118,8 +126,8 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.148"
   },
   "dependencies": {
-    "special-agents": "0.8.2",
-    "rafi-spec": "0.8.2",
+    "special-agents": "0.8.3",
+    "rafi-spec": "0.8.3",
     "@clack/prompts": "^1.4.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",