@webpieces/pr-gate 0.4.692 → 0.4.693

package/src/scripts/workflow/build-gate-log.js

@@ -4,9 +4,9 @@ exports.BuildGateLog = exports.BuildLogHeartbeat = exports.BUILD_LOG_NAME = expo
 const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
 const fs = tslib_1.__importStar(require("fs"));
-const path = tslib_1.__importStar(require("path"));
-const rules_config_1 = require("@webpieces/rules-config");
 const inversify_1 = require("inversify");
+const gate_log_file_1 = require("./gate-log-file");
+const stage_output_log_1 = require("./stage-output-log");
 // ─── Why ───────────────────────────────────────────────────────────────────────────────────────────────
 // The build gate already builds everything. When the output only ever went to the CONSOLE, an agent that
 // wanted a different slice of it re-ran the WHOLE BUILD to get it: one measured session spent 23.9 minutes
@@ -28,6 +28,10 @@ const inversify_1 = require("inversify");
 // `spawnSync` blocks the event loop for the length of the build, so NOTHING can print while it runs — and
 // a silent terminal for 3–7 minutes is indistinguishable from a hang. The heartbeat is the reason this is
 // async, and it is why `run` returns a Promise and `BuildAffected.runBuildGate` is async with it.
+//
+// It is also the reason the heartbeat goes through `StageOutputLog.say` rather than `process.stdout` —
+// stage ② and stage ③ capture their own console output to a file, and a heartbeat captured into a file is
+// a heartbeat nobody can see. The 600-second watchdog that kills a silent command does not read files.
 /** How often the heartbeat reports the log's size. Hardcoded: a knob here would be a knob the PR gate's
  * own build never receives, and the two must stay the same command. */
 exports.HEARTBEAT_MS = 10_000;
@@ -44,7 +48,6 @@ exports.FINISH_STAGE = 'finish';
 exports.BUILD_STAGE = 'build';
 /** The one fixed log name — see BuildGateLog.fileNameFor for why only `wp-build` gets one. */
 exports.BUILD_LOG_NAME = 'build.log';
-const BACKUP_SUFFIX = '.bak';
 /**
  * The heartbeat's state: the line count reported on the PREVIOUS tick, so a tick that has not moved can
  * say so. Stateful per RUN, which is why it is constructed per run rather than injected.
@@ -54,49 +57,39 @@ const BACKUP_SUFFIX = '.bak';
  * BUILD from a stalled REPORTER.
  */
 class BuildLogHeartbeat {
+    files;
     logPath;
     displayPath;
     previous = null;
-    constructor(logPath, displayPath) {
+    constructor(files, logPath, displayPath) {
+        this.files = files;
         this.logPath = logPath;
         this.displayPath = displayPath;
     }
     /** One heartbeat line — `<path> size <n> lines`, plus ` still` when <n> has not moved. */
     tick() {
-        const count = this.lineCount();
+        const count = this.files.lineCount(this.logPath);
         const still = this.previous !== null && count === this.previous ? ' still' : '';
         this.previous = count;
         return `${this.displayPath} size ${count} lines${still}`;
     }
-    // Lines currently in the log. A log that does not exist yet is zero lines, not an error: the build may
-    // simply not have written its first byte, and a heartbeat may never be the reason a build stops.
-    lineCount() {
-        if (!fs.existsSync(this.logPath))
-            return 0;
-        const body = fs.readFileSync(this.logPath, 'utf8');
-        if (body === '')
-            return 0;
-        return body.split('\n').length - (body.endsWith('\n') ? 1 : 0);
-    }
 }
 exports.BuildLogHeartbeat = BuildLogHeartbeat;
 /**
  * Captures the build gate's full output to a file, reports progress while it runs, and renders the
  * pointer the caller is handed instead of a rebuild instruction.
  *
+ * WHERE the file goes, how the previous run is kept, and what the pointer reads like are `GateLogFile`'s
+ * — one mechanism, shared with the stage console log, so there is a single answer to "where is it?".
+ *
  * ─── Two naming schemes, one rule each ─────────────────────────────────────────────────────────────────
  *   • `wp-build` (BUILD_STAGE) writes ONE fixed path, `.webpieces/build.log`. It is fixed because a HUMAN
  *     OR AN AGENT TYPES IT — `grep -n error .webpieces/build.log` has to be writable from memory, and a
- *     name carrying a branch and a sha is not. History comes from the rotation below instead.
+ *     name carrying a branch and a sha is not. History comes from the rotation instead.
  *   • stage ② and stage ③ write `logs/build-gate-<stage>-<branch>-<shortSha>.log`, because those two
  *     gates CAN run against one commit and a failure message from one must not be pointing at a file the
  *     other overwrote. Nobody types those names; the failure message prints them.
  *
- * ─── Rotation, everywhere ──────────────────────────────────────────────────────────────────────────────
- * Every run moves an existing log to `<log>.bak` before writing, so the last TWO runs are always on disk.
- * One rule for every stage: no branch, and the previous run of a re-run at the same commit survives
- * instead of being truncated away.
- *
  * ─── Concurrency ───────────────────────────────────────────────────────────────────────────────────────
  * The DIRECTORY is `dotWebpieces.local()`-scoped — `<primary>/.webpieces/worktrees/<git worktree name>/`
  * in a linked worktree — so "N agents in N worktrees" is safe by construction rather than by naming. The
@@ -104,13 +97,17 @@ exports.BuildLogHeartbeat = BuildLogHeartbeat;
  * driving one git index.
  */
 let BuildGateLog = class BuildGateLog {
+    files;
+    stageConsole;
+    constructor(files, stageConsole) {
+        this.files = files;
+        this.stageConsole = stageConsole;
+    }
     /** Absolute path of the log for `stage` at the current HEAD, creating its directory. */
     pathFor(repoRoot, stage) {
-        const file = this.resolvePath(repoRoot, stage);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        return file;
+        return this.resolvePath(repoRoot, stage);
     }
-    /** The same path WITHOUT creating anything, and '' when no such log exists. Used by finish's skip path. */
+    /** The same path, and '' when no log has been WRITTEN there yet. Used by finish's skip path. */
     existingLogFor(repoRoot, stage) {
         const file = this.resolvePath(repoRoot, stage);
         return fs.existsSync(file) ? file : '';
@@ -123,31 +120,16 @@ let BuildGateLog = class BuildGateLog {
         const sha = this.slug(this.git(repoRoot, ['rev-parse', '--short', 'HEAD']));
         return `build-gate-${this.slug(stage)}-${branch === '' ? 'nobranch' : branch}-${sha === '' ? 'nosha' : sha}.log`;
     }
-    /** Where the PREVIOUS run of `logPath` is kept — always `<logPath>.bak`. */
-    backupPathFor(logPath) {
-        return `${logPath}${BACKUP_SUFFIX}`;
-    }
-    /**
-     * Move an existing log aside to `<log>.bak`, overwriting any previous backup. A missing log is the
-     * normal first-run state and is not an error.
-     */
-    rotate(logPath) {
-        fs.mkdirSync(path.dirname(logPath), { recursive: true });
-        if (!fs.existsSync(logPath))
-            return;
-        fs.rmSync(this.backupPathFor(logPath), { force: true });
-        fs.renameSync(logPath, this.backupPathFor(logPath));
-    }
     /**
      * Run `buildCommand` with its stdout AND stderr redirected in full to `logPath`, printing a heartbeat
-     * to the console every HEARTBEAT_MS so the caller can see it is alive. Returns the BUILD's exit code.
-     * Nothing is truncated and nothing is streamed.
+     * every HEARTBEAT_MS so the caller can see it is alive. Returns the BUILD's exit code. Nothing is
+     * truncated and nothing is streamed.
      */
     async run(repoRoot, buildCommand, logPath) {
-        this.rotate(logPath);
+        this.files.rotate(logPath);
         const fd = fs.openSync(logPath, 'w');
-        const heartbeat = new BuildLogHeartbeat(logPath, this.displayPath(repoRoot, logPath));
-        const timer = setInterval(() => { process.stdout.write(`${heartbeat.tick()}\n`); }, exports.HEARTBEAT_MS);
+        const heartbeat = new BuildLogHeartbeat(this.files, logPath, this.files.displayPath(repoRoot, logPath));
+        const timer = setInterval(() => { this.stageConsole.say(`${heartbeat.tick()}\n`); }, exports.HEARTBEAT_MS);
         // webpieces-disable no-unmanaged-exceptions -- chokepoint: the timer and the fd MUST be released
         // whatever the child does, and the exit code is returned rather than thrown so runBuildGate owns
         // the one CliExitError.
@@ -164,7 +146,7 @@ let BuildGateLog = class BuildGateLog {
      * The success summary: the caller is told WHERE the full output is, not handed the output.
      */
     successMessage(logPath) {
-        return `\nBuild success\n${this.logPointer(logPath)}`;
+        return `\nBuild success\n${this.files.pointer(logPath)}`;
     }
     /**
      * The ENTIRE message the caller gets on a failed build. It names the log, echoes the last
@@ -176,46 +158,11 @@ let BuildGateLog = class BuildGateLog {
      * agent guessing or rebuilding — so it is told to surface the contradiction to the human and stop.
      */
     failureMessage(buildCommand, logPath) {
-        return `\nBuild Failed: ${buildCommand}\n${this.logPointer(logPath)}\n` +
-            `Last ${exports.FAILURE_TAIL_LINES} lines of that log:\n${this.tail(logPath)}\n` +
+        return `\nBuild Failed: ${buildCommand}\n${this.files.pointer(logPath)}\n` +
+            `Last ${exports.FAILURE_TAIL_LINES} lines of that log:\n${this.files.tail(logPath, exports.FAILURE_TAIL_LINES)}\n` +
             `Read that FILE for the failures. Do NOT re-run the build to see them.\n` +
             `If you do not see failures in that log, report that to the user and stop.\n`;
     }
-    // The two lines that name the log, identical on success and failure so there is one thing to recognise.
-    // The backup line says what is TRUE RIGHT NOW: on the very first build in a tree there is no `.bak`
-    // yet, and pointing a reader at a file that does not exist is the small lie that costs a wasted `cat`.
-    logPointer(logPath) {
-        const name = path.basename(logPath);
-        const backedUp = fs.existsSync(this.backupPathFor(logPath))
-            ? `(${name} is backed up to ${name}${BACKUP_SUFFIX} every run so you have the last 2 builds of logs)`
-            : `(the previous ${name} is kept as ${name}${BACKUP_SUFFIX} on every run — this is the first, so there is none yet)`;
-        return `FullLog : ${logPath}\n${backedUp}\n`;
-    }
-    /**
-     * The log's last FAILURE_TAIL_LINES lines, or a plain statement of why there are none.
-     *
-     * A read that fails is REPORTED, never allowed to throw: this renders the message for a build that has
-     * ALREADY failed, so an I/O error escaping here would replace the real failure with the renderer's own
-     * — the caller would lose the build error and be handed a filesystem error instead. The full log is
-     * still named on the line above, so nothing is hidden by degrading to one line.
-     */
-    tail(logPath) {
-        if (!fs.existsSync(logPath))
-            return `    (no log file at ${logPath})\n`;
-        // webpieces-disable no-unmanaged-exceptions -- chokepoint: see above, the failure renderer may not
-        // replace the build's failure with its own.
-        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-        try {
-            const lines = fs.readFileSync(logPath, 'utf8').split('\n').filter((l) => l !== '');
-            if (lines.length === 0)
-                return '    (the log is empty)\n';
-            return lines.slice(-exports.FAILURE_TAIL_LINES).map((l) => `    ${l}\n`).join('');
-        }
-        catch (err) {
-            const error = (0, rules_config_1.toError)(err);
-            return `    (could not read ${logPath}: ${error.message})\n`;
-        }
-    }
     // Resolve, and wait for, the child's exit code. A spawn that never starts (a shell that is missing, a
     // cwd that vanished) fails CLOSED to 1 — calling a build that never ran green is the one outcome that
     // must be impossible — and the reason is APPENDED TO THE LOG, so the failure message's pointer still
@@ -229,17 +176,11 @@ let BuildGateLog = class BuildGateLog {
             child.on('close', (code) => { resolve(code ?? 1); });
         });
     }
-    // The path as the heartbeat shows it: relative to the repo when it sits inside it (a linked worktree's
-    // state lives under the PRIMARY clone, so it often does not), absolute otherwise.
-    displayPath(repoRoot, logPath) {
-        const relative = path.relative(repoRoot, logPath);
-        return relative === '' || relative.startsWith('..') || path.isAbsolute(relative) ? logPath : relative;
-    }
     resolvePath(repoRoot, stage) {
         const name = this.fileNameFor(repoRoot, stage);
         // `wp-build`'s log sits at the ROOT of the state dir, not under `logs/`, because it is the one log
         // path a person types from memory. Everything else keeps the per-commit names in `logs/`.
-        return stage === exports.BUILD_STAGE ? rules_config_1.dotWebpieces.localFile(repoRoot, name) : rules_config_1.dotWebpieces.logsFile(repoRoot, name);
+        return stage === exports.BUILD_STAGE ? this.files.localPath(repoRoot, name) : this.files.logsPath(repoRoot, name);
     }
     // Anything that is not a filename-safe character becomes '-', so `dean/feat` cannot create directories.
     slug(value) {
@@ -256,6 +197,8 @@ let BuildGateLog = class BuildGateLog {
 };
 exports.BuildGateLog = BuildGateLog;
 exports.BuildGateLog = BuildGateLog = tslib_1.__decorate([
-    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton),
+    tslib_1.__metadata("design:paramtypes", [gate_log_file_1.GateLogFile,
+        stage_output_log_1.StageOutputLog])
 ], BuildGateLog);
 //# sourceMappingURL=build-gate-log.js.map

package/src/scripts/workflow/build-gate-log.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-gate-log.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/build-gate-log.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn, spawnSync, ChildProcess } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { dotWebpieces, toError } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\n// ─── Why ───────────────────────────────────────────────────────────────────────────────────────────────\n// The build gate already builds everything. When the output only ever went to the CONSOLE, an agent that\n// wanted a different slice of it re-ran the WHOLE BUILD to get it: one measured session spent 23.9 minutes\n// across nine `nx affected` runs, five of them with NO code change in between — `| tail -50`, then\n// `> /tmp/file`, then `| grep`, then `| sed -n '1100,1230p'`. ~19 minutes spent re-reading a log.\n//\n// So the build's output is not streamed; it is REDIRECTED, in full, to a file whose path the caller is\n// handed on completion. Reading a different slice is then a `grep` of a FILE, not a second build.\n//\n// ─── Why a redirect and not `tee` ──────────────────────────────────────────────────────────────────────\n// An earlier cut of this used `cmd 2>&1 | tee log`, to keep the terminal byte-identical. That is what\n// makes the transcript expensive in the first place — an AI caller carries every line of it in context.\n// The redirect keeps the console to a handful of lines (a heartbeat, then a pointer at the file), which is\n// the entire productivity claim. Losing `tee` also deletes the `$?`-into-a-side-file dance it needed: in a\n// pipeline the shell reports TEE's status, which is 0 whether the build passed or failed, so the status\n// had to be smuggled out through a side file. With no pipe, the child's own exit code IS the answer.\n//\n// ─── Why async (`spawn`, not `spawnSync`) ──────────────────────────────────────────────────────────────\n// `spawnSync` blocks the event loop for the length of the build, so NOTHING can print while it runs — and\n// a silent terminal for 3–7 minutes is indistinguishable from a hang. The heartbeat is the reason this is\n// async, and it is why `run` returns a Promise and `BuildAffected.runBuildGate` is async with it.\n\n/** How often the heartbeat reports the log's size. Hardcoded: a knob here would be a knob the PR gate's\n * own build never receives, and the two must stay the same command. */\nexport const HEARTBEAT_MS = 10_000;\n\n/** How many trailing log lines the failure message echoes, so the immediate cause is visible without a\n * second command. Small on purpose — the FULL log is one grep away and the message must not become the\n * transcript it exists to replace. */\nexport const FAILURE_TAIL_LINES = 20;\n\n/**\n * Which stage's gate is being captured. The value decides the log FILENAME.\n */\nexport const REVIEW_STAGE = 'review';\nexport const FINISH_STAGE = 'finish';\n// `wp-build`, which is not a stage of the PR flow but runs the SAME gate (BuildAffected.runBuildGate).\nexport const BUILD_STAGE = 'build';\n\n/** The one fixed log name — see BuildGateLog.fileNameFor for why only `wp-build` gets one. */\nexport const BUILD_LOG_NAME = 'build.log';\nconst BACKUP_SUFFIX = '.bak';\n\n/**\n * The heartbeat's state: the line count reported on the PREVIOUS tick, so a tick that has not moved can\n * say so. Stateful per RUN, which is why it is constructed per run rather than injected.\n *\n * `still` is the load-bearing word. A build that is linking, or waiting on a cold nx cache, produces no\n * output for minutes; without `still` the caller sees the same number twice and cannot tell a stalled\n * BUILD from a stalled REPORTER.\n */\nexport class BuildLogHeartbeat {\n    private previous: number | null = null;\n\n    constructor(private readonly logPath: string, private readonly displayPath: string) {}\n\n    /** One heartbeat line — `<path> size <n> lines`, plus ` still` when <n> has not moved. */\n    tick(): string {\n        const count = this.lineCount();\n        const still = this.previous !== null && count === this.previous ? ' still' : '';\n        this.previous = count;\n        return `${this.displayPath} size ${count} lines${still}`;\n    }\n\n    // Lines currently in the log. A log that does not exist yet is zero lines, not an error: the build may\n    // simply not have written its first byte, and a heartbeat may never be the reason a build stops.\n    private lineCount(): number {\n        if (!fs.existsSync(this.logPath)) return 0;\n        const body = fs.readFileSync(this.logPath, 'utf8');\n        if (body === '') return 0;\n        return body.split('\\n').length - (body.endsWith('\\n') ? 1 : 0);\n    }\n}\n\n/**\n * Captures the build gate's full output to a file, reports progress while it runs, and renders the\n * pointer the caller is handed instead of a rebuild instruction.\n *\n * ─── Two naming schemes, one rule each ─────────────────────────────────────────────────────────────────\n *   • `wp-build` (BUILD_STAGE) writes ONE fixed path, `.webpieces/build.log`. It is fixed because a HUMAN\n *     OR AN AGENT TYPES IT — `grep -n error .webpieces/build.log` has to be writable from memory, and a\n *     name carrying a branch and a sha is not. History comes from the rotation below instead.\n *   • stage ② and stage ③ write `logs/build-gate-<stage>-<branch>-<shortSha>.log`, because those two\n *     gates CAN run against one commit and a failure message from one must not be pointing at a file the\n *     other overwrote. Nobody types those names; the failure message prints them.\n *\n * ─── Rotation, everywhere ──────────────────────────────────────────────────────────────────────────────\n * Every run moves an existing log to `<log>.bak` before writing, so the last TWO runs are always on disk.\n * One rule for every stage: no branch, and the previous run of a re-run at the same commit survives\n * instead of being truncated away.\n *\n * ─── Concurrency ───────────────────────────────────────────────────────────────────────────────────────\n * The DIRECTORY is `dotWebpieces.local()`-scoped — `<primary>/.webpieces/worktrees/<git worktree name>/`\n * in a linked worktree — so \"N agents in N worktrees\" is safe by construction rather than by naming. The\n * residual case is two builds in the SAME worktree at once, which is already unsupported: both would be\n * driving one git index.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class BuildGateLog {\n    /** Absolute path of the log for `stage` at the current HEAD, creating its directory. */\n    pathFor(repoRoot: string, stage: string): string {\n        const file = this.resolvePath(repoRoot, stage);\n        fs.mkdirSync(path.dirname(file), { recursive: true });\n        return file;\n    }\n\n    /** The same path WITHOUT creating anything, and '' when no such log exists. Used by finish's skip path. */\n    existingLogFor(repoRoot: string, stage: string): string {\n        const file = this.resolvePath(repoRoot, stage);\n        return fs.existsSync(file) ? file : '';\n    }\n\n    /** `build.log` for `wp-build`; `build-gate-<stage>-<branch>-<shortSha>.log` for the PR-flow stages. */\n    fileNameFor(repoRoot: string, stage: string): string {\n        if (stage === BUILD_STAGE) return BUILD_LOG_NAME;\n        const branch = this.slug(this.git(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD']));\n        const sha = this.slug(this.git(repoRoot, ['rev-parse', '--short', 'HEAD']));\n        return `build-gate-${this.slug(stage)}-${branch === '' ? 'nobranch' : branch}-${sha === '' ? 'nosha' : sha}.log`;\n    }\n\n    /** Where the PREVIOUS run of `logPath` is kept — always `<logPath>.bak`. */\n    backupPathFor(logPath: string): string {\n        return `${logPath}${BACKUP_SUFFIX}`;\n    }\n\n    /**\n     * Move an existing log aside to `<log>.bak`, overwriting any previous backup. A missing log is the\n     * normal first-run state and is not an error.\n     */\n    rotate(logPath: string): void {\n        fs.mkdirSync(path.dirname(logPath), { recursive: true });\n        if (!fs.existsSync(logPath)) return;\n        fs.rmSync(this.backupPathFor(logPath), { force: true });\n        fs.renameSync(logPath, this.backupPathFor(logPath));\n    }\n\n    /**\n     * Run `buildCommand` with its stdout AND stderr redirected in full to `logPath`, printing a heartbeat\n     * to the console every HEARTBEAT_MS so the caller can see it is alive. Returns the BUILD's exit code.\n     * Nothing is truncated and nothing is streamed.\n     */\n    async run(repoRoot: string, buildCommand: string, logPath: string): Promise<number> {\n        this.rotate(logPath);\n        const fd = fs.openSync(logPath, 'w');\n        const heartbeat = new BuildLogHeartbeat(logPath, this.displayPath(repoRoot, logPath));\n        const timer = setInterval((): void => { process.stdout.write(`${heartbeat.tick()}\\n`); }, HEARTBEAT_MS);\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the timer and the fd MUST be released\n        // whatever the child does, and the exit code is returned rather than thrown so runBuildGate owns\n        // the one CliExitError.\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return await this.awaitExit(spawn(buildCommand, { cwd: repoRoot, shell: true, stdio: ['ignore', fd, fd] }), fd);\n        } finally {\n            clearInterval(timer);\n            fs.closeSync(fd);\n        }\n    }\n\n    /**\n     * The success summary: the caller is told WHERE the full output is, not handed the output.\n     */\n    successMessage(logPath: string): string {\n        return `\\nBuild success\\n${this.logPointer(logPath)}`;\n    }\n\n    /**\n     * The ENTIRE message the caller gets on a failed build. It names the log, echoes the last\n     * FAILURE_TAIL_LINES lines so the immediate cause needs no second command, and forbids the rebuild\n     * this whole file exists to prevent.\n     *\n     * The last sentence is not filler. If the log holds no visible failure then something upstream is wrong\n     * (a runner that died without printing, a truncated redirect), and the worst possible response is an\n     * agent guessing or rebuilding — so it is told to surface the contradiction to the human and stop.\n     */\n    failureMessage(buildCommand: string, logPath: string): string {\n        return `\\nBuild Failed: ${buildCommand}\\n${this.logPointer(logPath)}\\n` +\n            `Last ${FAILURE_TAIL_LINES} lines of that log:\\n${this.tail(logPath)}\\n` +\n            `Read that FILE for the failures. Do NOT re-run the build to see them.\\n` +\n            `If you do not see failures in that log, report that to the user and stop.\\n`;\n    }\n\n    // The two lines that name the log, identical on success and failure so there is one thing to recognise.\n    // The backup line says what is TRUE RIGHT NOW: on the very first build in a tree there is no `.bak`\n    // yet, and pointing a reader at a file that does not exist is the small lie that costs a wasted `cat`.\n    private logPointer(logPath: string): string {\n        const name = path.basename(logPath);\n        const backedUp = fs.existsSync(this.backupPathFor(logPath))\n            ? `(${name} is backed up to ${name}${BACKUP_SUFFIX} every run so you have the last 2 builds of logs)`\n            : `(the previous ${name} is kept as ${name}${BACKUP_SUFFIX} on every run — this is the first, so there is none yet)`;\n        return `FullLog : ${logPath}\\n${backedUp}\\n`;\n    }\n\n    /**\n     * The log's last FAILURE_TAIL_LINES lines, or a plain statement of why there are none.\n     *\n     * A read that fails is REPORTED, never allowed to throw: this renders the message for a build that has\n     * ALREADY failed, so an I/O error escaping here would replace the real failure with the renderer's own\n     * — the caller would lose the build error and be handed a filesystem error instead. The full log is\n     * still named on the line above, so nothing is hidden by degrading to one line.\n     */\n    private tail(logPath: string): string {\n        if (!fs.existsSync(logPath)) return `    (no log file at ${logPath})\\n`;\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: see above, the failure renderer may not\n        // replace the build's failure with its own.\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const lines = fs.readFileSync(logPath, 'utf8').split('\\n').filter((l: string): boolean => l !== '');\n            if (lines.length === 0) return '    (the log is empty)\\n';\n            return lines.slice(-FAILURE_TAIL_LINES).map((l: string): string => `    ${l}\\n`).join('');\n        } catch (err: unknown) {\n            const error = toError(err);\n            return `    (could not read ${logPath}: ${error.message})\\n`;\n        }\n    }\n\n    // Resolve, and wait for, the child's exit code. A spawn that never starts (a shell that is missing, a\n    // cwd that vanished) fails CLOSED to 1 — calling a build that never ran green is the one outcome that\n    // must be impossible — and the reason is APPENDED TO THE LOG, so the failure message's pointer still\n    // leads to it rather than to an empty file.\n    private awaitExit(child: ChildProcess, fd: number): Promise<number> {\n        return new Promise<number>((resolve: (code: number) => void): void => {\n            child.on('error', (err: Error): void => {\n                fs.writeSync(fd, `\\nThe build command could not be started: ${err.message}\\n`);\n                resolve(1);\n            });\n            child.on('close', (code: number | null): void => { resolve(code ?? 1); });\n        });\n    }\n\n    // The path as the heartbeat shows it: relative to the repo when it sits inside it (a linked worktree's\n    // state lives under the PRIMARY clone, so it often does not), absolute otherwise.\n    private displayPath(repoRoot: string, logPath: string): string {\n        const relative = path.relative(repoRoot, logPath);\n        return relative === '' || relative.startsWith('..') || path.isAbsolute(relative) ? logPath : relative;\n    }\n\n    private resolvePath(repoRoot: string, stage: string): string {\n        const name = this.fileNameFor(repoRoot, stage);\n        // `wp-build`'s log sits at the ROOT of the state dir, not under `logs/`, because it is the one log\n        // path a person types from memory. Everything else keeps the per-commit names in `logs/`.\n        return stage === BUILD_STAGE ? dotWebpieces.localFile(repoRoot, name) : dotWebpieces.logsFile(repoRoot, name);\n    }\n\n    // Anything that is not a filename-safe character becomes '-', so `dean/feat` cannot create directories.\n    private slug(value: string): string {\n        return value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');\n    }\n\n    // One local git read. Fails SOFT to '' — a missing branch/sha degrades the FILENAME, and degrading a\n    // filename may never be the reason a build gate does not run.\n    private git(repoRoot: string, args: string[]): string {\n        const result = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8' });\n        if (result.status !== 0) return '';\n        return (result.stdout ?? '').trim();\n    }\n}\n"]}
+{"version":3,"file":"build-gate-log.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/build-gate-log.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn, spawnSync, ChildProcess } from 'child_process';\nimport * as fs from 'fs';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { GateLogFile } from './gate-log-file';\nimport { StageOutputLog } from './stage-output-log';\n\n// ─── Why ───────────────────────────────────────────────────────────────────────────────────────────────\n// The build gate already builds everything. When the output only ever went to the CONSOLE, an agent that\n// wanted a different slice of it re-ran the WHOLE BUILD to get it: one measured session spent 23.9 minutes\n// across nine `nx affected` runs, five of them with NO code change in between — `| tail -50`, then\n// `> /tmp/file`, then `| grep`, then `| sed -n '1100,1230p'`. ~19 minutes spent re-reading a log.\n//\n// So the build's output is not streamed; it is REDIRECTED, in full, to a file whose path the caller is\n// handed on completion. Reading a different slice is then a `grep` of a FILE, not a second build.\n//\n// ─── Why a redirect and not `tee` ──────────────────────────────────────────────────────────────────────\n// An earlier cut of this used `cmd 2>&1 | tee log`, to keep the terminal byte-identical. That is what\n// makes the transcript expensive in the first place — an AI caller carries every line of it in context.\n// The redirect keeps the console to a handful of lines (a heartbeat, then a pointer at the file), which is\n// the entire productivity claim. Losing `tee` also deletes the `$?`-into-a-side-file dance it needed: in a\n// pipeline the shell reports TEE's status, which is 0 whether the build passed or failed, so the status\n// had to be smuggled out through a side file. With no pipe, the child's own exit code IS the answer.\n//\n// ─── Why async (`spawn`, not `spawnSync`) ──────────────────────────────────────────────────────────────\n// `spawnSync` blocks the event loop for the length of the build, so NOTHING can print while it runs — and\n// a silent terminal for 3–7 minutes is indistinguishable from a hang. The heartbeat is the reason this is\n// async, and it is why `run` returns a Promise and `BuildAffected.runBuildGate` is async with it.\n//\n// It is also the reason the heartbeat goes through `StageOutputLog.say` rather than `process.stdout` —\n// stage ② and stage ③ capture their own console output to a file, and a heartbeat captured into a file is\n// a heartbeat nobody can see. The 600-second watchdog that kills a silent command does not read files.\n\n/** How often the heartbeat reports the log's size. Hardcoded: a knob here would be a knob the PR gate's\n * own build never receives, and the two must stay the same command. */\nexport const HEARTBEAT_MS = 10_000;\n\n/** How many trailing log lines the failure message echoes, so the immediate cause is visible without a\n * second command. Small on purpose — the FULL log is one grep away and the message must not become the\n * transcript it exists to replace. */\nexport const FAILURE_TAIL_LINES = 20;\n\n/**\n * Which stage's gate is being captured. The value decides the log FILENAME.\n */\nexport const REVIEW_STAGE = 'review';\nexport const FINISH_STAGE = 'finish';\n// `wp-build`, which is not a stage of the PR flow but runs the SAME gate (BuildAffected.runBuildGate).\nexport const BUILD_STAGE = 'build';\n\n/** The one fixed log name — see BuildGateLog.fileNameFor for why only `wp-build` gets one. */\nexport const BUILD_LOG_NAME = 'build.log';\n\n/**\n * The heartbeat's state: the line count reported on the PREVIOUS tick, so a tick that has not moved can\n * say so. Stateful per RUN, which is why it is constructed per run rather than injected.\n *\n * `still` is the load-bearing word. A build that is linking, or waiting on a cold nx cache, produces no\n * output for minutes; without `still` the caller sees the same number twice and cannot tell a stalled\n * BUILD from a stalled REPORTER.\n */\nexport class BuildLogHeartbeat {\n    private previous: number | null = null;\n\n    constructor(\n        private readonly files: GateLogFile,\n        private readonly logPath: string,\n        private readonly displayPath: string,\n    ) {}\n\n    /** One heartbeat line — `<path> size <n> lines`, plus ` still` when <n> has not moved. */\n    tick(): string {\n        const count = this.files.lineCount(this.logPath);\n        const still = this.previous !== null && count === this.previous ? ' still' : '';\n        this.previous = count;\n        return `${this.displayPath} size ${count} lines${still}`;\n    }\n}\n\n/**\n * Captures the build gate's full output to a file, reports progress while it runs, and renders the\n * pointer the caller is handed instead of a rebuild instruction.\n *\n * WHERE the file goes, how the previous run is kept, and what the pointer reads like are `GateLogFile`'s\n * — one mechanism, shared with the stage console log, so there is a single answer to \"where is it?\".\n *\n * ─── Two naming schemes, one rule each ─────────────────────────────────────────────────────────────────\n *   • `wp-build` (BUILD_STAGE) writes ONE fixed path, `.webpieces/build.log`. It is fixed because a HUMAN\n *     OR AN AGENT TYPES IT — `grep -n error .webpieces/build.log` has to be writable from memory, and a\n *     name carrying a branch and a sha is not. History comes from the rotation instead.\n *   • stage ② and stage ③ write `logs/build-gate-<stage>-<branch>-<shortSha>.log`, because those two\n *     gates CAN run against one commit and a failure message from one must not be pointing at a file the\n *     other overwrote. Nobody types those names; the failure message prints them.\n *\n * ─── Concurrency ───────────────────────────────────────────────────────────────────────────────────────\n * The DIRECTORY is `dotWebpieces.local()`-scoped — `<primary>/.webpieces/worktrees/<git worktree name>/`\n * in a linked worktree — so \"N agents in N worktrees\" is safe by construction rather than by naming. The\n * residual case is two builds in the SAME worktree at once, which is already unsupported: both would be\n * driving one git index.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class BuildGateLog {\n    constructor(\n        private readonly files: GateLogFile,\n        private readonly stageConsole: StageOutputLog,\n    ) {}\n\n    /** Absolute path of the log for `stage` at the current HEAD, creating its directory. */\n    pathFor(repoRoot: string, stage: string): string {\n        return this.resolvePath(repoRoot, stage);\n    }\n\n    /** The same path, and '' when no log has been WRITTEN there yet. Used by finish's skip path. */\n    existingLogFor(repoRoot: string, stage: string): string {\n        const file = this.resolvePath(repoRoot, stage);\n        return fs.existsSync(file) ? file : '';\n    }\n\n    /** `build.log` for `wp-build`; `build-gate-<stage>-<branch>-<shortSha>.log` for the PR-flow stages. */\n    fileNameFor(repoRoot: string, stage: string): string {\n        if (stage === BUILD_STAGE) return BUILD_LOG_NAME;\n        const branch = this.slug(this.git(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD']));\n        const sha = this.slug(this.git(repoRoot, ['rev-parse', '--short', 'HEAD']));\n        return `build-gate-${this.slug(stage)}-${branch === '' ? 'nobranch' : branch}-${sha === '' ? 'nosha' : sha}.log`;\n    }\n\n    /**\n     * Run `buildCommand` with its stdout AND stderr redirected in full to `logPath`, printing a heartbeat\n     * every HEARTBEAT_MS so the caller can see it is alive. Returns the BUILD's exit code. Nothing is\n     * truncated and nothing is streamed.\n     */\n    async run(repoRoot: string, buildCommand: string, logPath: string): Promise<number> {\n        this.files.rotate(logPath);\n        const fd = fs.openSync(logPath, 'w');\n        const heartbeat = new BuildLogHeartbeat(this.files, logPath, this.files.displayPath(repoRoot, logPath));\n        const timer = setInterval((): void => { this.stageConsole.say(`${heartbeat.tick()}\\n`); }, HEARTBEAT_MS);\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: the timer and the fd MUST be released\n        // whatever the child does, and the exit code is returned rather than thrown so runBuildGate owns\n        // the one CliExitError.\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return await this.awaitExit(spawn(buildCommand, { cwd: repoRoot, shell: true, stdio: ['ignore', fd, fd] }), fd);\n        } finally {\n            clearInterval(timer);\n            fs.closeSync(fd);\n        }\n    }\n\n    /**\n     * The success summary: the caller is told WHERE the full output is, not handed the output.\n     */\n    successMessage(logPath: string): string {\n        return `\\nBuild success\\n${this.files.pointer(logPath)}`;\n    }\n\n    /**\n     * The ENTIRE message the caller gets on a failed build. It names the log, echoes the last\n     * FAILURE_TAIL_LINES lines so the immediate cause needs no second command, and forbids the rebuild\n     * this whole file exists to prevent.\n     *\n     * The last sentence is not filler. If the log holds no visible failure then something upstream is wrong\n     * (a runner that died without printing, a truncated redirect), and the worst possible response is an\n     * agent guessing or rebuilding — so it is told to surface the contradiction to the human and stop.\n     */\n    failureMessage(buildCommand: string, logPath: string): string {\n        return `\\nBuild Failed: ${buildCommand}\\n${this.files.pointer(logPath)}\\n` +\n            `Last ${FAILURE_TAIL_LINES} lines of that log:\\n${this.files.tail(logPath, FAILURE_TAIL_LINES)}\\n` +\n            `Read that FILE for the failures. Do NOT re-run the build to see them.\\n` +\n            `If you do not see failures in that log, report that to the user and stop.\\n`;\n    }\n\n    // Resolve, and wait for, the child's exit code. A spawn that never starts (a shell that is missing, a\n    // cwd that vanished) fails CLOSED to 1 — calling a build that never ran green is the one outcome that\n    // must be impossible — and the reason is APPENDED TO THE LOG, so the failure message's pointer still\n    // leads to it rather than to an empty file.\n    private awaitExit(child: ChildProcess, fd: number): Promise<number> {\n        return new Promise<number>((resolve: (code: number) => void): void => {\n            child.on('error', (err: Error): void => {\n                fs.writeSync(fd, `\\nThe build command could not be started: ${err.message}\\n`);\n                resolve(1);\n            });\n            child.on('close', (code: number | null): void => { resolve(code ?? 1); });\n        });\n    }\n\n    private resolvePath(repoRoot: string, stage: string): string {\n        const name = this.fileNameFor(repoRoot, stage);\n        // `wp-build`'s log sits at the ROOT of the state dir, not under `logs/`, because it is the one log\n        // path a person types from memory. Everything else keeps the per-commit names in `logs/`.\n        return stage === BUILD_STAGE ? this.files.localPath(repoRoot, name) : this.files.logsPath(repoRoot, name);\n    }\n\n    // Anything that is not a filename-safe character becomes '-', so `dean/feat` cannot create directories.\n    private slug(value: string): string {\n        return value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');\n    }\n\n    // One local git read. Fails SOFT to '' — a missing branch/sha degrades the FILENAME, and degrading a\n    // filename may never be the reason a build gate does not run.\n    private git(repoRoot: string, args: string[]): string {\n        const result = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8' });\n        if (result.status !== 0) return '';\n        return (result.stdout ?? '').trim();\n    }\n}\n"]}

package/src/scripts/workflow/gate-log-file.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The file mechanics shared by every captured log in the PR gate: WHERE it goes, keeping the previous
+ * run, the pointer the caller prints instead of the output, and the failure tail.
+ *
+ * It knows nothing about builds, stages or console interception — its callers own all of that. Singleton
+ * because it is pure behaviour over paths; it holds no state.
+ */
+export declare class GateLogFile {
+    /**
+     * `<local()>/logs/<name>` — the ONE log directory, per worktree namespace. Creates the directory.
+     * Use for anything a MESSAGE points at; nobody types these names.
+     */
+    logsPath(repoRoot: string, name: string): string;
+    /**
+     * `<local()>/<name>` — the ROOT of the state dir, for the one log a PERSON types from memory
+     * (`.webpieces/build.log`). Creates the directory. Reach for `logsPath` unless the path itself has
+     * to be memorable.
+     */
+    localPath(repoRoot: string, name: string): string;
+    /** Where the PREVIOUS run of `logPath` is kept — always `<logPath>.bak`. */
+    backupPathFor(logPath: string): string;
+    /**
+     * Move an existing log aside to `<log>.bak`, overwriting any previous backup, so the last TWO runs
+     * are always on disk. A missing log is the normal first-run state and is not an error.
+     *
+     * ONE generation, everywhere: a re-run at the same commit does not truncate away the run before it,
+     * and a reader never has to work out which of N dated files is the one they want.
+     */
+    rotate(logPath: string): void;
+    /**
+     * The two lines that name a log — identical on success and on failure, so there is exactly one shape
+     * to recognise.
+     *
+     * The backup line states what is TRUE RIGHT NOW: on the very first run in a tree there is no `.bak`
+     * yet, and pointing a reader at a file that does not exist is the small lie that costs a wasted `cat`.
+     */
+    pointer(logPath: string): string;
+    /**
+     * The path as a progress line should show it: relative to the repo when it sits inside it (a linked
+     * worktree's state lives under the PRIMARY clone, so it usually does not), absolute otherwise.
+     */
+    displayPath(repoRoot: string, logPath: string): string;
+    /**
+     * The log's last `lines` lines, indented, or a plain statement of why there are none.
+     *
+     * A read that fails is REPORTED, never allowed to throw: this renders a message for something that
+     * has ALREADY failed, so an I/O error escaping here would replace the real failure with the
+     * renderer's own — the caller would lose the actual error and be handed a filesystem error instead.
+     * The full log is still named on the line above, so nothing is hidden by degrading to one line.
+     */
+    tail(logPath: string, lines: number): string;
+    /** How many lines the log holds right now. A log that does not exist yet is zero lines, not an error. */
+    lineCount(logPath: string): number;
+    private ensureDir;
+}

package/src/scripts/workflow/gate-log-file.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GateLogFile = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const rules_config_1 = require("@webpieces/rules-config");
+const inversify_1 = require("inversify");
+// ─── Why this class exists ─────────────────────────────────────────────────────────────────────────────
+// TWO things in this package write a big blob of output to a file and hand the caller a one-line pointer
+// instead of the blob: the BUILD (BuildGateLog) and the STAGE CONSOLE (StageOutputLog). They are different
+// subjects — one spawns a child and heartbeats, the other intercepts this process's own stdout — but the
+// FILE half is identical: where the file lands, how the previous run is kept, and what the pointer at it
+// reads like.
+//
+// That half lives here, once. Cloning it would have given the two logs two answers to "where is it?" and
+// two rotation policies, and the whole value of the pointer is that a reader recognises it instantly and
+// can `grep` it without first working out which subsystem wrote it.
+//
+// ─── WHERE the files land, and why that shape ──────────────────────────────────────────────────────────
+// Through `dotWebpieces` — never `path.join(repoRoot, '.webpieces')`. In a LINKED WORKTREE `local()`
+// resolves to `<primary>/.webpieces/worktrees/<git worktree name>/`, so:
+//   • N agents in N worktrees never write one another's log, by construction rather than by naming;
+//   • the history OUTLIVES the worktree — `wp-cleanup` reaps a tree's directory and the logs it wrote are
+//     still there under the primary clone, which is exactly when you want them;
+//   • it self-limits, because `.webpieces/worktrees/**` is already swept once a namespace goes stale.
+//     Nothing here needs a retention policy of its own.
+/** The suffix of the ONE previous generation kept beside a log. */
+const BACKUP_SUFFIX = '.bak';
+/**
+ * The file mechanics shared by every captured log in the PR gate: WHERE it goes, keeping the previous
+ * run, the pointer the caller prints instead of the output, and the failure tail.
+ *
+ * It knows nothing about builds, stages or console interception — its callers own all of that. Singleton
+ * because it is pure behaviour over paths; it holds no state.
+ */
+let GateLogFile = class GateLogFile {
+    /**
+     * `<local()>/logs/<name>` — the ONE log directory, per worktree namespace. Creates the directory.
+     * Use for anything a MESSAGE points at; nobody types these names.
+     */
+    logsPath(repoRoot, name) {
+        return this.ensureDir(rules_config_1.dotWebpieces.logsFile(repoRoot, name));
+    }
+    /**
+     * `<local()>/<name>` — the ROOT of the state dir, for the one log a PERSON types from memory
+     * (`.webpieces/build.log`). Creates the directory. Reach for `logsPath` unless the path itself has
+     * to be memorable.
+     */
+    localPath(repoRoot, name) {
+        return this.ensureDir(rules_config_1.dotWebpieces.localFile(repoRoot, name));
+    }
+    /** Where the PREVIOUS run of `logPath` is kept — always `<logPath>.bak`. */
+    backupPathFor(logPath) {
+        return `${logPath}${BACKUP_SUFFIX}`;
+    }
+    /**
+     * Move an existing log aside to `<log>.bak`, overwriting any previous backup, so the last TWO runs
+     * are always on disk. A missing log is the normal first-run state and is not an error.
+     *
+     * ONE generation, everywhere: a re-run at the same commit does not truncate away the run before it,
+     * and a reader never has to work out which of N dated files is the one they want.
+     */
+    rotate(logPath) {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        if (!fs.existsSync(logPath))
+            return;
+        fs.rmSync(this.backupPathFor(logPath), { force: true });
+        fs.renameSync(logPath, this.backupPathFor(logPath));
+    }
+    /**
+     * The two lines that name a log — identical on success and on failure, so there is exactly one shape
+     * to recognise.
+     *
+     * The backup line states what is TRUE RIGHT NOW: on the very first run in a tree there is no `.bak`
+     * yet, and pointing a reader at a file that does not exist is the small lie that costs a wasted `cat`.
+     */
+    pointer(logPath) {
+        const name = path.basename(logPath);
+        const backedUp = fs.existsSync(this.backupPathFor(logPath))
+            ? `(${name} is backed up to ${name}${BACKUP_SUFFIX} every run so you have the last 2 runs of logs)`
+            : `(the previous ${name} is kept as ${name}${BACKUP_SUFFIX} on every run — this is the first, so there is none yet)`;
+        return `FullLog : ${logPath}\n${backedUp}\n`;
+    }
+    /**
+     * The path as a progress line should show it: relative to the repo when it sits inside it (a linked
+     * worktree's state lives under the PRIMARY clone, so it usually does not), absolute otherwise.
+     */
+    displayPath(repoRoot, logPath) {
+        const relative = path.relative(repoRoot, logPath);
+        return relative === '' || relative.startsWith('..') || path.isAbsolute(relative) ? logPath : relative;
+    }
+    /**
+     * The log's last `lines` lines, indented, or a plain statement of why there are none.
+     *
+     * A read that fails is REPORTED, never allowed to throw: this renders a message for something that
+     * has ALREADY failed, so an I/O error escaping here would replace the real failure with the
+     * renderer's own — the caller would lose the actual error and be handed a filesystem error instead.
+     * The full log is still named on the line above, so nothing is hidden by degrading to one line.
+     */
+    tail(logPath, lines) {
+        if (!fs.existsSync(logPath))
+            return `    (no log file at ${logPath})\n`;
+        // webpieces-disable no-unmanaged-exceptions -- chokepoint: see above, the failure renderer may not
+        // replace the caller's failure with its own.
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const all = fs.readFileSync(logPath, 'utf8').split('\n').filter((l) => l !== '');
+            if (all.length === 0)
+                return '    (the log is empty)\n';
+            return all.slice(-lines).map((l) => `    ${l}\n`).join('');
+        }
+        catch (err) {
+            const error = (0, rules_config_1.toError)(err);
+            return `    (could not read ${logPath}: ${error.message})\n`;
+        }
+    }
+    /** How many lines the log holds right now. A log that does not exist yet is zero lines, not an error. */
+    lineCount(logPath) {
+        if (!fs.existsSync(logPath))
+            return 0;
+        const body = fs.readFileSync(logPath, 'utf8');
+        if (body === '')
+            return 0;
+        return body.split('\n').length - (body.endsWith('\n') ? 1 : 0);
+    }
+    ensureDir(file) {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        return file;
+    }
+};
+exports.GateLogFile = GateLogFile;
+exports.GateLogFile = GateLogFile = tslib_1.__decorate([
+    (0, inversify_1.injectable)(inversify_1.bindingScopeValues.Singleton)
+], GateLogFile);
+//# sourceMappingURL=gate-log-file.js.map

package/src/scripts/workflow/gate-log-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-log-file.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/pr-gate/src/scripts/workflow/gate-log-file.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as path from 'path';\nimport { dotWebpieces, toError } from '@webpieces/rules-config';\nimport { injectable, bindingScopeValues } from 'inversify';\n\n// ─── Why this class exists ─────────────────────────────────────────────────────────────────────────────\n// TWO things in this package write a big blob of output to a file and hand the caller a one-line pointer\n// instead of the blob: the BUILD (BuildGateLog) and the STAGE CONSOLE (StageOutputLog). They are different\n// subjects — one spawns a child and heartbeats, the other intercepts this process's own stdout — but the\n// FILE half is identical: where the file lands, how the previous run is kept, and what the pointer at it\n// reads like.\n//\n// That half lives here, once. Cloning it would have given the two logs two answers to \"where is it?\" and\n// two rotation policies, and the whole value of the pointer is that a reader recognises it instantly and\n// can `grep` it without first working out which subsystem wrote it.\n//\n// ─── WHERE the files land, and why that shape ──────────────────────────────────────────────────────────\n// Through `dotWebpieces` — never `path.join(repoRoot, '.webpieces')`. In a LINKED WORKTREE `local()`\n// resolves to `<primary>/.webpieces/worktrees/<git worktree name>/`, so:\n//   • N agents in N worktrees never write one another's log, by construction rather than by naming;\n//   • the history OUTLIVES the worktree — `wp-cleanup` reaps a tree's directory and the logs it wrote are\n//     still there under the primary clone, which is exactly when you want them;\n//   • it self-limits, because `.webpieces/worktrees/**` is already swept once a namespace goes stale.\n//     Nothing here needs a retention policy of its own.\n\n/** The suffix of the ONE previous generation kept beside a log. */\nconst BACKUP_SUFFIX = '.bak';\n\n/**\n * The file mechanics shared by every captured log in the PR gate: WHERE it goes, keeping the previous\n * run, the pointer the caller prints instead of the output, and the failure tail.\n *\n * It knows nothing about builds, stages or console interception — its callers own all of that. Singleton\n * because it is pure behaviour over paths; it holds no state.\n */\n@injectable(bindingScopeValues.Singleton)\nexport class GateLogFile {\n    /**\n     * `<local()>/logs/<name>` — the ONE log directory, per worktree namespace. Creates the directory.\n     * Use for anything a MESSAGE points at; nobody types these names.\n     */\n    logsPath(repoRoot: string, name: string): string {\n        return this.ensureDir(dotWebpieces.logsFile(repoRoot, name));\n    }\n\n    /**\n     * `<local()>/<name>` — the ROOT of the state dir, for the one log a PERSON types from memory\n     * (`.webpieces/build.log`). Creates the directory. Reach for `logsPath` unless the path itself has\n     * to be memorable.\n     */\n    localPath(repoRoot: string, name: string): string {\n        return this.ensureDir(dotWebpieces.localFile(repoRoot, name));\n    }\n\n    /** Where the PREVIOUS run of `logPath` is kept — always `<logPath>.bak`. */\n    backupPathFor(logPath: string): string {\n        return `${logPath}${BACKUP_SUFFIX}`;\n    }\n\n    /**\n     * Move an existing log aside to `<log>.bak`, overwriting any previous backup, so the last TWO runs\n     * are always on disk. A missing log is the normal first-run state and is not an error.\n     *\n     * ONE generation, everywhere: a re-run at the same commit does not truncate away the run before it,\n     * and a reader never has to work out which of N dated files is the one they want.\n     */\n    rotate(logPath: string): void {\n        fs.mkdirSync(path.dirname(logPath), { recursive: true });\n        if (!fs.existsSync(logPath)) return;\n        fs.rmSync(this.backupPathFor(logPath), { force: true });\n        fs.renameSync(logPath, this.backupPathFor(logPath));\n    }\n\n    /**\n     * The two lines that name a log — identical on success and on failure, so there is exactly one shape\n     * to recognise.\n     *\n     * The backup line states what is TRUE RIGHT NOW: on the very first run in a tree there is no `.bak`\n     * yet, and pointing a reader at a file that does not exist is the small lie that costs a wasted `cat`.\n     */\n    pointer(logPath: string): string {\n        const name = path.basename(logPath);\n        const backedUp = fs.existsSync(this.backupPathFor(logPath))\n            ? `(${name} is backed up to ${name}${BACKUP_SUFFIX} every run so you have the last 2 runs of logs)`\n            : `(the previous ${name} is kept as ${name}${BACKUP_SUFFIX} on every run — this is the first, so there is none yet)`;\n        return `FullLog : ${logPath}\\n${backedUp}\\n`;\n    }\n\n    /**\n     * The path as a progress line should show it: relative to the repo when it sits inside it (a linked\n     * worktree's state lives under the PRIMARY clone, so it usually does not), absolute otherwise.\n     */\n    displayPath(repoRoot: string, logPath: string): string {\n        const relative = path.relative(repoRoot, logPath);\n        return relative === '' || relative.startsWith('..') || path.isAbsolute(relative) ? logPath : relative;\n    }\n\n    /**\n     * The log's last `lines` lines, indented, or a plain statement of why there are none.\n     *\n     * A read that fails is REPORTED, never allowed to throw: this renders a message for something that\n     * has ALREADY failed, so an I/O error escaping here would replace the real failure with the\n     * renderer's own — the caller would lose the actual error and be handed a filesystem error instead.\n     * The full log is still named on the line above, so nothing is hidden by degrading to one line.\n     */\n    tail(logPath: string, lines: number): string {\n        if (!fs.existsSync(logPath)) return `    (no log file at ${logPath})\\n`;\n        // webpieces-disable no-unmanaged-exceptions -- chokepoint: see above, the failure renderer may not\n        // replace the caller's failure with its own.\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const all = fs.readFileSync(logPath, 'utf8').split('\\n').filter((l: string): boolean => l !== '');\n            if (all.length === 0) return '    (the log is empty)\\n';\n            return all.slice(-lines).map((l: string): string => `    ${l}\\n`).join('');\n        } catch (err: unknown) {\n            const error = toError(err);\n            return `    (could not read ${logPath}: ${error.message})\\n`;\n        }\n    }\n\n    /** How many lines the log holds right now. A log that does not exist yet is zero lines, not an error. */\n    lineCount(logPath: string): number {\n        if (!fs.existsSync(logPath)) return 0;\n        const body = fs.readFileSync(logPath, 'utf8');\n        if (body === '') return 0;\n        return body.split('\\n').length - (body.endsWith('\\n') ? 1 : 0);\n    }\n\n    private ensureDir(file: string): string {\n        fs.mkdirSync(path.dirname(file), { recursive: true });\n        return file;\n    }\n}\n"]}

package/src/scripts/workflow/stage-output-log.d.ts

@@ -0,0 +1,40 @@
+import { GateLogFile } from './gate-log-file';
+/** Stage ②'s console log. Named for the command, because that is what a reader is looking for. */
+export declare const REVIEW_CONSOLE_LOG = "wp-review-upsert-pr.log";
+/** Stage ③'s console log. */
+export declare const FINISH_CONSOLE_LOG = "wp-finish-upsert-pr.log";
+/**
+ * Captures a stage's verbose console output to a file, keeps the handful of lines the caller must act on
+ * immediately on the terminal, and hands back the one-line pointer at the file.
+ *
+ * Singleton, and stateful FOR THE DURATION OF ONE `withCapture` call: a bin runs exactly one stage.
+ * Re-entering it is a programming error, not a supported mode, and it throws rather than silently
+ * capturing into the inner file and restoring the outer one.
+ */
+export declare class StageOutputLog {
+    private readonly files;
+    constructor(files: GateLogFile);
+    private logPath;
+    private fd;
+    private original;
+    /**
+     * Run `body` with this process's stdout captured to `<logs>/<fileName>`, then restore stdout and
+     * print the pointer at the file.
+     *
+     * The pointer is printed in a `finally`, so it is there on the FAILURE path too — which is the path
+     * where a reader most needs it, and the one where an uncaptured stage would have scrolled the cause
+     * off the top of the terminal.
+     */
+    withCapture<T>(repoRoot: string, fileName: string, body: () => Promise<T>): Promise<T>;
+    /**
+     * Print `text` to the TERMINAL as well as the log — for the few things a caller must act on before it
+     * can do anything else: the build heartbeat (a silent command is a killed command), the build result,
+     * the review instructions, the PR link, and anything naming a file to read.
+     *
+     * Outside a capture this is an ordinary write, so a class that calls it is not coupled to the stage.
+     */
+    say(text: string): void;
+    private intercept;
+    private release;
+    private appendToLog;
+}