@cat-factory/executor-harness 1.31.0

package/dist/follow-ups.js

@@ -0,0 +1,103 @@
+import { readFile } from 'node:fs/promises';
+import { log } from './logger.js';
+// The Coder's forward-looking side channel. As the implementer works it appends one
+// JSON line per item to a sentinel file in its working directory; the harness tails
+// that file and streams the new items OUT on the job view (drain-on-read), so the
+// backend lifts them onto the run's step and the "Follow-up companion" lights up
+// while the container is still running. This is the OUT-bound half only — there is no
+// in-bound path back into a running container (an answer reaches the Coder via a
+// backend-driven re-run, not by resuming the live process).
+/** The sentinel file the Coder appends items to, relative to its working directory. */
+export const FOLLOW_UPS_FILENAME = '.cat-follow-ups.jsonl';
+/** Coerce one parsed JSON line into a {@link FollowUpLine}, or null when unusable. */
+function coerceLine(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const o = value;
+    const title = typeof o.title === 'string' ? o.title.trim() : '';
+    if (!title)
+        return null;
+    const kind = o.kind === 'question' ? 'question' : 'follow_up';
+    const detail = typeof o.detail === 'string' ? o.detail : '';
+    const suggestedAction = typeof o.suggestedAction === 'string' && o.suggestedAction.trim()
+        ? o.suggestedAction.trim()
+        : undefined;
+    return {
+        kind,
+        title: title.slice(0, 300),
+        detail,
+        ...(suggestedAction ? { suggestedAction } : {}),
+    };
+}
+/**
+ * Tails an append-only JSONL sentinel file, yielding only the NEW complete lines on each
+ * {@link poll}. Tracks how many characters have been consumed so a partially-written
+ * trailing line (no newline yet) is held back until it completes. Tolerant: a malformed
+ * line is skipped, a missing file yields nothing — surfacing follow-ups must never
+ * disturb the coding run.
+ */
+export class FollowUpTailer {
+    filePath;
+    onItems;
+    logger;
+    consumed = 0;
+    /** Running count of complete-but-unparsable lines, so silent drops become visible. */
+    skipped = 0;
+    constructor(filePath, onItems, logger = log) {
+        this.filePath = filePath;
+        this.onItems = onItems;
+        this.logger = logger;
+    }
+    /** Read any new complete lines and emit the coerced items. Best-effort; never throws. */
+    async poll() {
+        let content;
+        try {
+            content = await readFile(this.filePath, 'utf8');
+        }
+        catch {
+            // Not created yet (or vanished): nothing to surface.
+            return;
+        }
+        if (content.length <= this.consumed)
+            return;
+        const fresh = content.slice(this.consumed);
+        // Only consume up to the last newline; hold any trailing partial line for next poll.
+        const lastNewline = fresh.lastIndexOf('\n');
+        if (lastNewline === -1)
+            return;
+        this.consumed += lastNewline + 1;
+        const items = [];
+        let skippedThisPoll = 0;
+        for (const raw of fresh.slice(0, lastNewline).split('\n')) {
+            const line = raw.trim();
+            if (!line)
+                continue;
+            try {
+                const coerced = coerceLine(JSON.parse(line));
+                if (coerced)
+                    items.push(coerced);
+                else
+                    skippedThisPoll++;
+            }
+            catch {
+                // A non-JSON / half-written line — skip it (a later poll re-reads from `consumed`,
+                // which only advanced past complete newline-terminated lines).
+                skippedThisPoll++;
+            }
+        }
+        if (skippedThisPoll > 0) {
+            // A complete line that didn't yield an item is dropped for good (consumed past it).
+            // Surface it at warn with a running total rather than swallowing it silently — a
+            // steadily-growing count points at a malformed-emitter bug, not a transient race.
+            this.skipped += skippedThisPoll;
+            this.logger.warn('follow-ups: skipped malformed lines', {
+                skipped: skippedThisPoll,
+                skippedTotal: this.skipped,
+            });
+        }
+        if (items.length > 0) {
+            this.logger.info('follow-ups: surfaced items', { count: items.length });
+            this.onItems(items);
+        }
+    }
+}

package/dist/frontend-infra.js

@@ -0,0 +1,283 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { killChildProcess } from './process.js';
+import { pathExists } from './fs-utils.js';
+import { captureRedactedOutput, redactSecrets } from './redact.js';
+import { log } from './logger.js';
+const exec = promisify(execFile);
+// The self-contained frontend UI-test stand-up (the `tester-ui` flow). In ONE container we
+// build the frontend, stand WireMock up for its mocked upstreams, serve the built app, and
+// point the agent at it — all as localhost PROCESSES (no Docker-in-Docker), so it works on
+// Cloudflare and Apple `container` too. The backend has already resolved every upstream to a
+// concrete URL and handed them in `infra.env`; this file only builds/serves/mocks. WireMock
+// standalone (the jar at `$WIREMOCK_JAR`) and a static file server (`serve`) plus the package
+// managers are provided by the UI image (Dockerfile.ui).
+/** Where the WireMock standalone jar lives in the image (overridable for tests). */
+const WIREMOCK_JAR = process.env.WIREMOCK_JAR ?? '/opt/wiremock/wiremock-standalone.jar';
+/** Defaults the backend may omit; kept here so the harness owns the runtime shape. */
+const DEFAULTS = {
+    packageManager: 'pnpm',
+    buildScript: 'build',
+    outputDir: 'dist',
+    serveMode: 'static',
+    servePort: 4173,
+    envInjection: 'build',
+    mockMappingsPath: 'mocks/',
+    wiremockPort: 8089,
+};
+/** The install command for a package manager (an explicit `install` overrides this). */
+export function installCommand(spec) {
+    if (spec.install)
+        return spec.install.split(/\s+/).filter(Boolean);
+    const pm = spec.packageManager ?? DEFAULTS.packageManager;
+    return [pm, 'install'];
+}
+/**
+ * Attach an `'error'` listener to a spawned background process. A `ChildProcess` is an
+ * EventEmitter, and an `'error'` event with NO listener (an ENOENT for a missing binary, an
+ * EAGAIN/ENOMEM under the container's memory limit) is re-thrown by Node as an UNCAUGHT
+ * exception that would kill the whole harness job server. The frontend stand-up is
+ * best-effort, so we swallow the error into the log instead — a dead WireMock / server is
+ * then caught by the health-check and surfaced as a prompt note, not a container crash.
+ */
+function guardProcess(child, label, logger) {
+    child.on('error', (err) => {
+        logger.warn(`agent(frontend): ${label} process error`, {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    });
+    return child;
+}
+/**
+ * Build the frontend, start WireMock, serve the built app and health-check both. Best-effort,
+ * like the docker-compose stand-up: a failed build / server that never binds is surfaced to
+ * the agent as a prompt note (and captured on the record) rather than failing the job — the
+ * agent then reports the gap as a concern. Every path returns the processes to tear down.
+ */
+export async function standUpFrontend(dir, infra, signal, onActivity, logger = log) {
+    const startedAt = Date.now();
+    const processes = [];
+    // Keep the run's inactivity watchdog fed while the (activity-silent) install → build → serve
+    // stand-up runs. A real frontend's `install` + `build` can exceed the harness inactivity
+    // window (default 10 min, JOB_INACTIVITY_MS) — and unlike the Pi phase this stand-up emits
+    // no activity events of its own — so without this heartbeat the watchdog would abort the job
+    // MID-BUILD with a misleading "likely hung". `unref()` so it never itself holds the loop open.
+    const heartbeat = setInterval(() => onActivity?.(), 30_000);
+    if (typeof heartbeat.unref === 'function')
+        heartbeat.unref();
+    const servePort = infra.servePort ?? DEFAULTS.servePort;
+    const wiremockPort = infra.wiremockPort ?? DEFAULTS.wiremockPort;
+    const serveUrl = `http://localhost:${servePort}`;
+    // Raw (un-redacted) stage output; redacted+bounded ONCE when a record is built.
+    const rawOutput = [];
+    const pushOutput = (stdout, stderr) => {
+        const merged = [String(stdout ?? ''), String(stderr ?? '')]
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .join('\n');
+        if (merged)
+            rawOutput.push(merged);
+    };
+    const record = (extra) => {
+        const logs = rawOutput.length ? captureRedactedOutput(rawOutput.join('\n'), '') : undefined;
+        return {
+            started: false,
+            at: Date.now(),
+            durationMs: Date.now() - startedAt,
+            ...(logs ? { logs } : {}),
+            ...extra,
+        };
+    };
+    const buildEnv = (infra.envInjection ?? DEFAULTS.envInjection) === 'build' ? (infra.env ?? {}) : {};
+    try {
+        // 1) Install dependencies.
+        const install = installCommand(infra);
+        logger.info('agent(frontend): installing', { command: install.join(' ') });
+        const installed = await exec(install[0], install.slice(1), {
+            cwd: dir,
+            signal,
+            timeout: 8 * 60_000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        pushOutput(installed.stdout, installed.stderr);
+        // 2) Build (build-time env injected here; runtime injection writes a shim after).
+        const pm = infra.packageManager ?? DEFAULTS.packageManager;
+        const buildScript = infra.buildScript ?? DEFAULTS.buildScript;
+        logger.info('agent(frontend): building', { buildScript });
+        const built = await exec(pm, ['run', buildScript], {
+            cwd: dir,
+            signal,
+            timeout: 12 * 60_000,
+            maxBuffer: 16 * 1024 * 1024,
+            env: { ...process.env, ...buildEnv },
+        });
+        pushOutput(built.stdout, built.stderr);
+        // Runtime injection: write a `window.env` shim into the build output the app can load
+        // (`<outputDir>/env.js`). Best-effort — the app must reference it; a build-time app ignores it.
+        const outputDir = infra.outputDir ?? DEFAULTS.outputDir;
+        if ((infra.envInjection ?? DEFAULTS.envInjection) === 'runtime' && infra.env) {
+            // The shim is written under `outputDir`, which the STATIC server serves as its root. A
+            // `serveMode: 'command'` dev/preview server serves from its OWN root, so it won't expose
+            // `<outputDir>/env.js` — the shim is then inert. Warn rather than silently no-op, and the
+            // `env` is ALSO forwarded to the serve process (see startServe) so a runtime-reading
+            // server can still pick the URLs up from the environment.
+            if ((infra.serveMode ?? DEFAULTS.serveMode) === 'command') {
+                logger.warn('agent(frontend): runtime env injection with serveMode:command — the window.env shim ' +
+                    'is only served in static mode; relying on the forwarded env instead', { outputDir });
+            }
+            const shim = `window.env = ${JSON.stringify(infra.env)};\n`;
+            await writeFile(join(dir, outputDir, 'env.js'), shim, 'utf8').catch((err) => {
+                // Best-effort, but no longer silent: a missing/renamed output dir would drop the shim
+                // and the app would read no URLs, so surface it in the log for diagnosis.
+                logger.warn('agent(frontend): could not write runtime env shim', {
+                    path: join(outputDir, 'env.js'),
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
+        // 3) WireMock for the mocked upstreams. Seeded from the FE repo's mappings dir when present;
+        // otherwise it still binds the port (unmatched requests 404, gentler than ECONNREFUSED).
+        processes.push(await startWireMock(dir, infra, wiremockPort, logger));
+        // 4) Serve the built app.
+        processes.push(startServe(dir, infra, servePort, outputDir, logger));
+        // 5) Health-check the served app AND WireMock before handing off, concurrently (WireMock is
+        // a JVM that cold-starts slower than the static server). A dead WireMock would otherwise let
+        // the agent start and hit ECONNREFUSED on the app's first mocked-upstream call.
+        const wiremockUrl = `http://localhost:${wiremockPort}/__admin/`;
+        const [appHealthy, wiremockHealthy] = await Promise.all([
+            waitForHttp(serveUrl, signal, logger),
+            waitForHttp(wiremockUrl, signal, logger),
+        ]);
+        if (!appHealthy) {
+            return {
+                processes,
+                note: `the frontend was built but its server never became reachable at ${serveUrl}`,
+                record: record({ error: `frontend server did not become reachable at ${serveUrl}` }),
+            };
+        }
+        if (!wiremockHealthy) {
+            // The app is up but the mock upstream isn't — the agent can still smoke-test the app;
+            // flag that mocked-backend calls may fail so it reports the gap rather than treating a
+            // mock ECONNREFUSED as a real defect.
+            return {
+                processes,
+                serveUrl,
+                note: `the frontend is served at ${serveUrl}, but WireMock (the mock for its other backend ` +
+                    `upstreams) never became reachable on port ${wiremockPort}, so calls to mocked ` +
+                    `upstreams may fail — flag any such failures as an infra gap, not an app defect`,
+                record: record({
+                    started: true,
+                    error: `WireMock did not become reachable on port ${wiremockPort}`,
+                }),
+            };
+        }
+        logger.info('agent(frontend): app is serving', { serveUrl, wiremockPort });
+        return {
+            processes,
+            serveUrl,
+            record: record({ started: true }),
+        };
+    }
+    catch (err) {
+        const note = err instanceof Error ? err.message : String(err);
+        logger.warn('agent(frontend): stand-up failed', { error: note });
+        const e = err;
+        pushOutput(e.stdout, e.stderr);
+        return { processes, note, record: record({ error: redactSecrets(note) }) };
+    }
+    finally {
+        // The stand-up is done (handed off, or failed) — the Pi phase feeds the watchdog from here.
+        clearInterval(heartbeat);
+    }
+}
+/** Terminate the frontend stand-up's processes (WireMock + the served app). Best-effort. */
+export async function tearDownFrontend(processes, logger = log) {
+    for (const child of processes) {
+        try {
+            killChildProcess(child, undefined, logger);
+        }
+        catch {
+            // The container is ephemeral and torn down with the run anyway — ignore.
+        }
+    }
+}
+/**
+ * Start WireMock standalone as a background process on `wiremockPort`, seeded from the FE
+ * repo's mappings dir (`mockMappingsPath`, passed verbatim as WireMock's `--root-dir`) when it
+ * exists. WireMock reads stub JSON from a `mappings/` subdirectory (and bodies from `__files/`)
+ * UNDER that root — so the default `mocks/` means `mocks/mappings/*.json`. A missing jar / JRE
+ * surfaces asynchronously as a process `'error'` (swallowed by {@link guardProcess}) and is then
+ * caught by the caller's WireMock health-check; a missing root dir is non-fatal (WireMock still
+ * binds the port and 404s unmatched requests).
+ */
+async function startWireMock(dir, infra, wiremockPort, logger) {
+    const mappingsPath = infra.wiremockMappingsPath ?? DEFAULTS.mockMappingsPath;
+    const rootDir = join(dir, mappingsPath);
+    const hasMappings = await pathExists(rootDir);
+    const args = ['-jar', WIREMOCK_JAR, '--port', String(wiremockPort), '--disable-banner'];
+    if (hasMappings)
+        args.push('--root-dir', rootDir);
+    else
+        logger.warn('agent(frontend): no WireMock mappings dir, starting empty', { mappingsPath });
+    logger.info('agent(frontend): starting WireMock', { wiremockPort, hasMappings });
+    return guardProcess(spawn('java', args, { cwd: dir, stdio: 'ignore' }), 'WireMock', logger);
+}
+/**
+ * Serve the built app on `servePort`: a static file server of `outputDir` (`static` mode), or
+ * the FE's own serve script (`command` mode, e.g. `preview`). In `command` mode the port is
+ * passed as the `PORT` env var, so the script MUST honour it (else it binds its own default
+ * port and the health-check — which polls `servePort` — never sees it), and the resolved
+ * backend URLs (`infra.env`) are ALSO forwarded so a runtime-reading dev/preview server sees
+ * them (a static server needs no env — build/runtime injection already baked/shim'd the URLs
+ * into the output it serves). Returns the background process; the static server (`serve`) is
+ * provided by the UI image.
+ */
+function startServe(dir, infra, servePort, outputDir, logger) {
+    const mode = infra.serveMode ?? DEFAULTS.serveMode;
+    if (mode === 'command' && infra.serveScript) {
+        const pm = infra.packageManager ?? DEFAULTS.packageManager;
+        logger.info('agent(frontend): serving via script', {
+            serveScript: infra.serveScript,
+            servePort,
+        });
+        return guardProcess(spawn(pm, ['run', infra.serveScript], {
+            cwd: dir,
+            stdio: 'ignore',
+            // Reserved names were already filtered from `infra.env` at parse; PORT wins last so
+            // the health-check's port is authoritative even if a binding tried to set it.
+            // (Spreading an undefined `infra.env` is a no-op, so no `?? {}` fallback is needed.)
+            env: { ...process.env, ...infra.env, PORT: String(servePort) },
+        }), 'serve', logger);
+    }
+    logger.info('agent(frontend): serving static output', { outputDir, servePort });
+    // `serve -s` single-page fallback so a client-routed SPA resolves deep links to index.html.
+    return guardProcess(spawn('serve', ['-s', outputDir, '-l', String(servePort)], { cwd: dir, stdio: 'ignore' }), 'serve', logger);
+}
+/** Poll a URL until it answers (any HTTP status) or the timeout elapses. */
+async function waitForHttp(url, signal, logger, timeoutMs = 90_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (signal?.aborted)
+            return false;
+        try {
+            // Abort a hung probe on the per-attempt 5s timeout AND on the run's own signal, so an
+            // aborted run doesn't wait out an in-flight fetch (the top-of-loop check only catches an
+            // abort BETWEEN attempts).
+            const attemptSignal = signal
+                ? AbortSignal.any([signal, AbortSignal.timeout(5_000)])
+                : AbortSignal.timeout(5_000);
+            const res = await fetch(url, { signal: attemptSignal });
+            // Any response (even a 404) means the server is up and accepting connections.
+            if (res.status > 0)
+                return true;
+        }
+        catch {
+            // Not up yet — back off and retry.
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1_000));
+    }
+    logger.warn('agent(frontend): health-check timed out', { url, timeoutMs });
+    return false;
+}

package/dist/fs-utils.js

@@ -0,0 +1,11 @@
+import { stat } from 'node:fs/promises';
+/** Whether `path` exists (a file or directory), swallowing ENOENT (and any stat error). */
+export async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}