@webpieces/rules-config 0.4.686 → 0.4.688

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/rules-config",
-  "version": "0.4.686",
+  "version": "0.4.688",
   "description": "Shared webpieces.config.json loader. Single source of truth for validation rule configuration consumed by @webpieces/ai-hook-rules, @webpieces/code-rules, and @webpieces/nx-webpieces-rules.",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/builds-log.d.ts

@@ -0,0 +1,193 @@
+import { DotWebpieces } from './state-dir';
+/**
+ * `~/.webpieces/builds.log` — the MACHINE-WIDE, append-only ledger of every build this box has started.
+ *
+ * ─── WHY THIS ONE FILE LIVES OUTSIDE THE REPO ─────────────────────────────────────────────────────────
+ * `no-machine-global-state.spec.ts` records the standing rule: webpieces writes state under
+ * `{repo}/.webpieces` and nowhere else. This is the ONE carve-out, and the argument is written out in
+ * `decisions/0006-the-build-ledger-is-machine-global.md`. In short:
+ *
+ *   • The FACT is machine-scoped. "How many builds are burning this box's CPU right now" is not a
+ *     property of any repo; it is a property of the machine. A per-repo ledger cannot answer it — every
+ *     linked worktree has its OWN `.webpieces/`, so it would be blind to the sibling worktree it is
+ *     actually contending with, never mind the four other repos on the disk.
+ *   • It is NOT A CACHE. The retired `PrBodyStore` that the no-machine-global rule was written for was a
+ *     local copy of a fact GitHub owned, so it could be stale, missing, or on the wrong computer. There
+ *     is no remote copy of this. The file IS the fact.
+ *   • Its key is an ABSOLUTE LOCAL PATH, which is stable precisely because it never leaves the machine —
+ *     the instability that killed `PrBodyStore`'s `<host>/<owner>/<repo>` key cannot arise here.
+ *
+ * ─── WHY IT IS SAFE TO WRITE CONCURRENTLY ─────────────────────────────────────────────────────────────
+ * Rows are deliberately kept under `MAX_ROW_BYTES` (512, macOS `PIPE_BUF`). A single `O_APPEND`
+ * `write(2)` at or below that size is indivisible, so two builds appending at the same instant cannot
+ * interleave halves of a line. The lock is therefore belt-and-braces for the APPEND and genuinely
+ * load-bearing for ROTATION, where a rename-and-reopen really does race.
+ *
+ * ─── IT MAY NEVER FAIL A BUILD ────────────────────────────────────────────────────────────────────────
+ * Every method here is best-effort and swallows its own errors. A build must never die because a log
+ * file was busy, unwritable, or on a full disk. Lock acquisition retries and then gives up and appends
+ * anyway — which the row-size invariant above makes safe.
+ */
+export declare const BUILDS_LOG_FILE = "builds.log";
+export declare const BUILDS_LOCK_FILE = "builds.log.lock";
+/** START, and the two terminal kinds. `DONE-` is the greppable prefix that pairs with a START. */
+export declare const BUILD_START = "START";
+export declare const BUILD_DONE_SUCCESS = "DONE-SUCCESS";
+export declare const BUILD_DONE_FAIL = "DONE-FAIL";
+/** Rotate at 1 MB, keeping five generations (`.1` … `.5`); the old `.5` is dropped. */
+export declare const MAX_BUILDS_LOG_BYTES: number;
+export declare const BUILDS_LOG_GENERATIONS = 5;
+/**
+ * macOS `PIPE_BUF`. A row at or under this size is written by ONE indivisible `write(2)`, which is what
+ * makes a lost lock a non-event rather than a corrupted file. Long paths are clipped to hold the line
+ * under it — see `clip`.
+ */
+export declare const MAX_ROW_BYTES = 512;
+/**
+ * The handle a START row hands back, and the ONLY thing `finish()` accepts. Data-only (a class, per
+ * CLAUDE.md), carrying exactly the fields the DONE row needs to pair itself with its START: the uuid,
+ * the caller, the repo, and when it began (so `took=` is computed from one clock, not two).
+ */
+export declare class BuildTicket {
+    id: string;
+    by: string;
+    repo: string;
+    startedMs: number;
+    constructor(id: string, by: string, repo: string, startedMs: number);
+}
+/**
+ * One build that is STILL RUNNING — a START row with no matching `DONE-`, whose pid is still alive.
+ * Data-only. This is what the refusal message renders, so it carries the three things a reader needs to
+ * recognise the build in question: where it is, which tree, and how old it is.
+ */
+export declare class RunningBuild {
+    id: string;
+    by: string;
+    repo: string;
+    tree: string;
+    cwd: string;
+    branch: string;
+    pid: number;
+    startedMs: number;
+    constructor(id: string, by: string, repo: string, tree: string, cwd: string, branch: string, pid: number, startedMs: number);
+}
+/**
+ * The ledger. See the file docblock for why it is machine-global and why every operation swallows its
+ * own errors.
+ *
+ * `homeDir` is a parameter on every public method, defaulted to `os.homedir()`, for exactly the reason
+ * `HomeConfigService.configPath` takes one: a spec must be able to exercise the real code against a temp
+ * directory and must never touch the developer's actual `~/.webpieces`.
+ */
+export declare class BuildsLog {
+    private readonly dotDir;
+    constructor(dotDir: DotWebpieces);
+    /** `~/.webpieces/builds.log`. */
+    logPath(homeDir?: string): string;
+    /** `~/.webpieces/builds.log.lock` — `{"pid":N,"started":<epochMs>}`. */
+    lockPath(homeDir?: string): string;
+    /** `~/.webpieces/builds.log.<n>` — generation `n`, 1 being the most recent. */
+    rotatedPath(generation: number, homeDir?: string): string;
+    /**
+     * Record that a build is starting, and hand back the ticket its DONE row will need.
+     *
+     * `by` is the CALLER — `BuildGateOptions.stage`, i.e. `build` | `review` | `finish`. There is no
+     * second "caller" concept anywhere: the stage id already is one, and a second spelling of it would
+     * be the shim CLAUDE.md rejects.
+     *
+     * Returns a ticket even when the append failed. A build whose START row never landed still has to be
+     * able to call `finish()`; the alternative is a nullable return that every call site must branch on
+     * for a logging failure that is, by policy, not an error.
+     */
+    start(by: string, startDir: string, homeDir?: string): BuildTicket;
+    /**
+     * Record that the build behind `ticket` has ended. `exitCode` 0 writes `DONE-SUCCESS`; anything else
+     * writes `DONE-FAIL` carrying the code, so `grep DONE-FAIL` lists every red build on the machine.
+     */
+    finish(ticket: BuildTicket, exitCode: number, homeDir?: string): void;
+    /**
+     * Every build that is still live: a `START` with no matching `DONE-` row, whose pid is still alive.
+     *
+     * The pid filter is not an optimisation, it is what keeps the ledger from wedging the machine. A
+     * build killed with SIGKILL — an agent cancelled mid-run, a terminal closed — writes no DONE row, so
+     * without the liveness test its START would count forever and the fourth build would be refused for
+     * the rest of the machine's life. The uuid answers "which build"; the pid answers "is it still real".
+     *
+     * Only the CURRENT generation is read. A rotated-away START is by definition at least 1 MB of rows
+     * old and is not a build anyone is contending with.
+     */
+    running(homeDir?: string): RunningBuild[];
+    /**
+     * The `@webpieces` release ACTUALLY EXECUTING — found by walking UP from this module's own directory
+     * to the nearest enclosing `node_modules/@webpieces/<pkg>/package.json`. `''` when this code is
+     * running from source rather than from an installed package (which is the state in this repo's own
+     * specs, and a perfectly ordinary answer).
+     *
+     * ─── WHY THIS IS NOT `WebpiecesVersions.readInstalled(root)` ──────────────────────────────────────
+     * They answer DIFFERENT QUESTIONS and merging them would break the older one. `readInstalled` joins
+     * `<root>/node_modules/@webpieces/...` at a FIXED tree root ON PURPOSE: its whole job is to detect
+     * DRIFT between what a tree PINS and what some other tree pins, and a walk-up would silently resolve
+     * a worktree with no install of its own to the primary clone's copy — hiding exactly the skew that
+     * guard exists to catch. This question is the opposite one: "whichever copy is running, name it", and
+     * for that the walk-up is the only correct answer. Do not fold them together.
+     */
+    executingVersion(): string;
+    private versionOfEnclosingPackage;
+    private startRow;
+    private doneRow;
+    /**
+     * Hold a long path down to `max` characters by keeping its TAIL, which is the half that identifies
+     * the tree; a clipped value is marked with a leading `…` so nobody mistakes it for a real path.
+     *
+     * This is what keeps a row under `MAX_ROW_BYTES` — see the file docblock. `append` re-checks the
+     * assembled line as a backstop, because three clipped fields plus a long branch name can still add up.
+     */
+    private clip;
+    /** The value of `<name>=` on a TSV row, or '' when the row does not carry it. */
+    private field;
+    private toRunningBuild;
+    /**
+     * Is `pid` still addressable? `process.kill(pid, 0)` sends no signal — it only asks the kernel. ESRCH
+     * is the ONE answer that proves death; EPERM proves the opposite (it exists, it is somebody else's).
+     * Same test, same reasoning, as `AgentWorktreeLockReader.isRunning`, including the accepted
+     * imprecision of pid reuse: being wrong in the "still running" direction costs one extra refusal,
+     * being wrong the other way lets a fourth build start.
+     */
+    private isAlive;
+    /**
+     * Append one row, best-effort. Takes the lock so rotation cannot race, and appends ANYWAY when the
+     * lock cannot be had within `LOCK_TIMEOUT_MS` — the row is under `PIPE_BUF`, so an unlocked
+     * `O_APPEND` write is still indivisible, and a build must never die because a log file was busy.
+     */
+    private append;
+    private truncateToRowLimit;
+    /**
+     * Take the ledger lock, retrying every `LOCK_RETRY_MS` until `LOCK_TIMEOUT_MS`. False means "carry on
+     * without it" — never an error, and never a reason to skip the append.
+     *
+     * The mechanism is `MainSyncStatusService.tryAcquireMainSyncLock`'s, proven and deliberately copied
+     * rather than re-invented: an `wx` (O_CREAT|O_EXCL) create so exactly one of N racers wins, a payload
+     * carrying pid + started so a dead holder is identifiable, stale reclaim gated on pid liveness, and a
+     * re-read afterwards to confirm the entry on disk is OURS (a simultaneous reclaimer could have
+     * unlinked ours and written its own between the two calls).
+     */
+    private tryAcquireLock;
+    private releaseLock;
+    private createExclusive;
+    private lockHolderPid;
+    private isHolderAlive;
+    private holderIsUs;
+    /**
+     * `.4→.5, .3→.4, … .log→.1`, dropping the old `.5`. Runs INSIDE the lock, which is the one place the
+     * lock is genuinely load-bearing: a rename-and-reopen really does race, and a writer that opened the
+     * old inode mid-shift would append into a file nobody reads again.
+     */
+    private rotateIfLarge;
+    private ensureDir;
+    private unlinkQuietly;
+    private renameQuietly;
+    private readTextOrEmpty;
+    private readLines;
+    private sleep;
+    private gitBranch;
+}