@reticlehq/server 2.14.0 → 3.2.0

package/dist/daemon/heartbeat.js

@@ -1,141 +0,0 @@
-/**
- * A regular beat, so SILENCE in the daemon log becomes evidence.
- *
- * `installExitTrace` hooks `'exit'`, which a SIGKILL never fires. So a daemon that is killed —
- * crashed, OOM-ed, swept by another project, `kill -9`'d by the recipe in every troubleshooting
- * thread — leaves no trace at all, and the last line before its port goes dark is whatever it
- * happened to be doing. Worse, a daemon that DID exit logs `code: 0`, so a tidy shutdown and a
- * violent death are the same shape to anyone reading the file.
- *
- * Measured cost of that: a correct SvelteKit install was written up as an install failure, because
- * the daemon had died 21 seconds earlier and nothing in the log said so. The fixture was named in the
- * report; the daemon was not.
- *
- * Two halves, and the second is what makes the first worth having:
- *   - DaemonHeartbeat emits `reticle_daemon_alive` on a fixed cadence, unconditionally.
- *   - classifyDaemonLife reads a log back and says which way the daemon ended.
- *
- * A heartbeat nobody interprets is just log volume.
- */
-/** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
-export const DAEMON_HEARTBEAT_EVENT = 'reticle_daemon_alive';
-/** Written by installExitTrace when the process exits through Node. */
-const DAEMON_EXIT_EVENT = 'reticle_daemon_exiting';
-/** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
-const DAEMON_SIGNAL_EVENT = 'reticle_daemon_signalled';
-/**
- * How often a live daemon says so.
- *
- * The median daemon lives 28 minutes, so at 30s that is ~56 lines — readable, and small against a log
- * that already rotates. Shorter would make the gap sharper and the file noisier; the gap only needs
- * to be legible against a connect window, which is measured in seconds.
- */
-export const DAEMON_HEARTBEAT_MS = 30_000;
-/**
- * How many beats may be missed before a reader calls it dead.
- *
- * Timers slip under load — the battery boots three servers and a browser — and a reader that cries
- * death on one late beat is a reader people learn to ignore. Two intervals plus a margin.
- */
-const MISSED_BEATS_TOLERATED = 2;
-/**
- * The cadence, from the environment. Same shape as `resolveIdleCheckMs`: a bad value falls back
- * rather than throwing, and 0 or negative is not a legal cadence — it would spin.
- */
-export function resolveHeartbeatMs(raw) {
-    if (raw === undefined || '' === raw.trim())
-        return DAEMON_HEARTBEAT_MS;
-    const n = Number(raw);
-    if (!Number.isFinite(n) || n <= 0)
-        return DAEMON_HEARTBEAT_MS;
-    return Math.floor(n);
-}
-export class DaemonHeartbeat {
-    #log;
-    #facts;
-    #intervalMs;
-    #clock;
-    #startedAt;
-    #timer;
-    constructor(opts) {
-        this.#log = opts.log;
-        this.#facts = opts.facts;
-        this.#intervalMs = opts.intervalMs ?? DAEMON_HEARTBEAT_MS;
-        this.#clock = opts.clock ?? (() => Date.now());
-        this.#startedAt = this.#clock();
-    }
-    /**
-     * One beat. Exposed so a test can drive it with an injected clock rather than waiting.
-     *
-     * Unconditional on purpose. Skipping the beat when nothing happened is the obvious optimisation and
-     * it destroys the signal: silence would then mean "idle" OR "dead", which is precisely the
-     * ambiguity this exists to remove.
-     */
-    beat() {
-        const facts = this.#facts();
-        this.#log(DAEMON_HEARTBEAT_EVENT, {
-            uptimeMs: this.#clock() - this.#startedAt,
-            // The cadence travels WITH the beat so a reader never hard-codes it. Hard-coding is how the
-            // reader and the emitter drift apart the first time the interval is tuned.
-            everyMs: this.#intervalMs,
-            sessions: facts.sessions,
-            served: facts.served,
-        });
-    }
-    start() {
-        if (this.#timer !== undefined)
-            return;
-        this.#timer = setInterval(() => this.beat(), this.#intervalMs);
-        // Never the reason a process stays alive — this is a diagnostic, not a workload.
-        this.#timer.unref();
-    }
-    stop() {
-        if (this.#timer === undefined)
-            return;
-        clearInterval(this.#timer);
-        this.#timer = undefined;
-    }
-}
-/** How a daemon's life ended, as far as its own log can say. */
-export const DaemonEnd = {
-    /** Still beating within tolerance. */
-    ALIVE: 'alive',
-    /** Logged its own exit, with no signal before it. */
-    CLEAN: 'clean',
-    /** A signal arrived — the cause an exit line with `code: 0` does not carry. */
-    SIGNALLED: 'signalled',
-    /** The beat simply stopped. No exit, no signal: killed, crashed, or swept. */
-    DIED_SILENTLY: 'died_silently',
-    /** No beat was ever emitted, so this log cannot answer the question. */
-    UNKNOWN: 'unknown',
-};
-/**
- * Read a daemon log back and say how it ended.
- *
- * UNKNOWN rather than ALIVE when there is no heartbeat at all — every log written before this
- * existed, and any file the reader was pointed at by mistake. Inferring health from the absence of a
- * signal we never sent is the same confident-wrong this module replaces.
- */
-export function classifyDaemonLife(lines, nowMs) {
-    const beats = lines.filter((l) => l.event === DAEMON_HEARTBEAT_EVENT);
-    const exit = lines.findLast((l) => l.event === DAEMON_EXIT_EVENT);
-    const signal = lines.findLast((l) => l.event === DAEMON_SIGNAL_EVENT);
-    if (exit !== undefined) {
-        // A signal is the CAUSE; the exit line only says it happened. Reporting `clean` for a SIGTERMed
-        // daemon is how "shut down tidily" and "the bridge every app needs is gone" became one sentence.
-        return signal === undefined
-            ? { end: DaemonEnd.CLEAN }
-            : {
-                end: DaemonEnd.SIGNALLED,
-                ...('string' === typeof signal.signal ? { signal: signal.signal } : {}),
-            };
-    }
-    const last = beats.at(-1);
-    if (last === undefined)
-        return { end: DaemonEnd.UNKNOWN };
-    const everyMs = 'number' === typeof last.everyMs ? last.everyMs : DAEMON_HEARTBEAT_MS;
-    const silentForMs = nowMs - last.t;
-    return silentForMs > everyMs * MISSED_BEATS_TOLERATED
-        ? { end: DaemonEnd.DIED_SILENTLY, lastBeatMs: last.t, silentForMs }
-        : { end: DaemonEnd.ALIVE, lastBeatMs: last.t };
-}

package/dist/daemon/idle-grace.d.ts

@@ -1,32 +0,0 @@
-/**
- * How long an idle daemon is given before it shuts itself down.
- *
- * It used to be one number for every case, and at 5 minutes that number killed live runs: 187
- * `reticle_daemon_idle_shutdown` lines on one user's machine, with their editor's Reticle
- * disconnecting each time; and in the fixtures gate it fired during long dependency installs, so apps
- * that booted afterwards hit ERR_CONNECTION_REFUSED and were scored as install failures when nothing
- * was wrong with their install.
- *
- * Reverting is not an option. Daemons used to sit idle a median of 28 minutes at a 0.04% duty cycle
- * because "an agent is attached" alone kept one alive for a whole editor session, and the widened
- * rule is what fixed that.
- *
- * The distinction is TIME, not state. Mid-install an attached daemon is state-identical to one in an
- * empty directory — nothing has been asked of either. What differs is how long it is reasonable to
- * wait: quiet with a client attached means the human is thinking or the install is slow; the same
- * quiet with nobody attached means the daemon is unwanted. Both still exit.
- */
-/**
- * An attached daemon waits this many times the base grace. Six is chosen against the two measurements
- * that matter: the default base is 5 minutes, so an attached daemon survives 30 — comfortably past
- * the slow installs that were killing runs, and comfortably short of the 28-minute median idle the
- * shorter rule was introduced to end.
- */
-export declare const ATTACHED_GRACE_MULTIPLIER = 6;
-/**
- * @param overrideMs an explicit attached grace (RETICLE_IDLE_ATTACHED_MS). Derived from the base when
- * absent — but the derived value is arithmetic on a number the caller also controls, and a test that
- * has to reason about both is a test that breaks for the wrong reason. Configuring it directly is
- * what lets the e2e spec assert the BEHAVIOUR (an attached daemon exits) without racing a product.
- */
-export declare function idleGraceMs(baseMs: number, agentAttached: boolean, overrideMs?: number): number;

package/dist/daemon/idle-grace.js

@@ -1,41 +0,0 @@
-/**
- * How long an idle daemon is given before it shuts itself down.
- *
- * It used to be one number for every case, and at 5 minutes that number killed live runs: 187
- * `reticle_daemon_idle_shutdown` lines on one user's machine, with their editor's Reticle
- * disconnecting each time; and in the fixtures gate it fired during long dependency installs, so apps
- * that booted afterwards hit ERR_CONNECTION_REFUSED and were scored as install failures when nothing
- * was wrong with their install.
- *
- * Reverting is not an option. Daemons used to sit idle a median of 28 minutes at a 0.04% duty cycle
- * because "an agent is attached" alone kept one alive for a whole editor session, and the widened
- * rule is what fixed that.
- *
- * The distinction is TIME, not state. Mid-install an attached daemon is state-identical to one in an
- * empty directory — nothing has been asked of either. What differs is how long it is reasonable to
- * wait: quiet with a client attached means the human is thinking or the install is slow; the same
- * quiet with nobody attached means the daemon is unwanted. Both still exit.
- */
-/**
- * An attached daemon waits this many times the base grace. Six is chosen against the two measurements
- * that matter: the default base is 5 minutes, so an attached daemon survives 30 — comfortably past
- * the slow installs that were killing runs, and comfortably short of the 28-minute median idle the
- * shorter rule was introduced to end.
- */
-export const ATTACHED_GRACE_MULTIPLIER = 6;
-/**
- * @param overrideMs an explicit attached grace (RETICLE_IDLE_ATTACHED_MS). Derived from the base when
- * absent — but the derived value is arithmetic on a number the caller also controls, and a test that
- * has to reason about both is a test that breaks for the wrong reason. Configuring it directly is
- * what lets the e2e spec assert the BEHAVIOUR (an attached daemon exits) without racing a product.
- */
-export function idleGraceMs(baseMs, agentAttached, overrideMs) {
-    // A non-positive base means the watcher is disabled; multiplying must not resurrect it.
-    if (baseMs <= 0)
-        return baseMs;
-    if (!agentAttached)
-        return baseMs;
-    return overrideMs !== undefined && overrideMs > 0
-        ? overrideMs
-        : baseMs * ATTACHED_GRACE_MULTIPLIER;
-}

package/dist/daemon/idle-shutdown.d.ts

@@ -1,54 +0,0 @@
-export interface IdleShutdownOptions {
-    /** True when nothing is using the daemon: no agent connected, no browser session, no pool lease. */
-    isIdle: () => boolean;
-    /** Clean teardown + process exit. Called at most once. */
-    onShutdown: () => void;
-    /** Continuous-idle window before shutdown. `0` (or negative) disables the watcher entirely. */
-    graceMs: number;
-    /**
-     * Is an agent's MCP client attached right now? An attached daemon gets a much longer grace — quiet
-     * with a client present means a slow install or a thinking human, not an unwanted daemon. It still
-     * exits. See idle-grace.
-     */
-    agentAttached?: () => boolean;
-    /** Explicit attached grace (RETICLE_IDLE_ATTACHED_MS); derived from graceMs when absent. */
-    attachedGraceMs?: number;
-    /** How often to re-check idleness. */
-    checkIntervalMs?: number;
-    /** Injected clock — never read wall-clock time in logic (repo rule). */
-    clock?: () => number;
-}
-/**
- * Self-terminates an idle daemon so Reticle never lingers eating a user's resources (the daemon process,
- * any headless Chromium the pool launched, and the bound port) after the editor closes. The `reticle mcp`
- * proxy spawns the daemon DETACHED so it survives between turns — which means nothing else will ever
- * stop it; this watcher is that missing stop. Idle = `isIdle` true continuously for `graceMs` (long
- * enough to ride out brief agent reconnects between turns). On fire it calls `onShutdown` exactly once.
- * The interval is `unref`'d, so it never keeps the process alive on its own; `start` is idempotent.
- */
-export declare class IdleShutdown {
-    #private;
-    constructor(opts: IdleShutdownOptions);
-    /** Run one idle check. Exposed so a test can drive it deterministically with an injected clock. */
-    check(): void;
-    start(): void;
-    stop(): void;
-}
-/**
- * The idle re-check cadence, from the environment. Same shape as the grace resolver, with one
- * deliberate difference: `0` is not a legal cadence here (it would spin), so `<= 0` falls back to
- * the default rather than meaning anything.
- */
-export declare function resolveIdleCheckMs(raw: string | undefined): number;
-/**
- * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of
- * milliseconds, `0` to disable. Anything missing or invalid falls back to the default. Pure.
- *
- * The disable is NOT implemented here — 0 is passed through as 0, and `IdleShutdown` treats
- * `graceMs <= 0` as "never self-shut-down" in both `start()` and `check()`. Said out loud because
- * this docblock had drifted onto the function above it, leaving this one undocumented next to a
- * bare `Math.floor`: a reviewer driving 2.5.0 read it as a documented option with no branch
- * implementing it and filed the gate that depends on it as inverted. The behaviour was correct in
- * every build; only the code was readable as broken.
- */
-export declare function resolveIdleShutdownMs(raw: string | undefined): number;

package/dist/daemon/idle-shutdown.js

@@ -1,98 +0,0 @@
-import { SESSION_LIFECYCLE } from '@reticlehq/core';
-import { idleGraceMs } from './idle-grace.js';
-import { log } from '../log.js';
-/**
- * Self-terminates an idle daemon so Reticle never lingers eating a user's resources (the daemon process,
- * any headless Chromium the pool launched, and the bound port) after the editor closes. The `reticle mcp`
- * proxy spawns the daemon DETACHED so it survives between turns — which means nothing else will ever
- * stop it; this watcher is that missing stop. Idle = `isIdle` true continuously for `graceMs` (long
- * enough to ride out brief agent reconnects between turns). On fire it calls `onShutdown` exactly once.
- * The interval is `unref`'d, so it never keeps the process alive on its own; `start` is idempotent.
- */
-export class IdleShutdown {
-    #timer;
-    #idleSince = null;
-    #fired = false;
-    #isIdle;
-    #onShutdown;
-    #graceMs;
-    #agentAttached;
-    #attachedGraceMs;
-    #checkMs;
-    #clock;
-    constructor(opts) {
-        this.#isIdle = opts.isIdle;
-        this.#onShutdown = opts.onShutdown;
-        this.#graceMs = opts.graceMs;
-        this.#agentAttached = opts.agentAttached;
-        this.#attachedGraceMs = opts.attachedGraceMs;
-        this.#checkMs = opts.checkIntervalMs ?? SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
-        this.#clock = opts.clock ?? (() => Date.now());
-    }
-    /** Run one idle check. Exposed so a test can drive it deterministically with an injected clock. */
-    check() {
-        if (this.#fired || this.#graceMs <= 0)
-            return; // graceMs <= 0 ⇒ disabled (never self-shut-down)
-        if (!this.#isIdle()) {
-            this.#idleSince = null;
-            return;
-        }
-        const now = this.#clock();
-        this.#idleSince ??= now;
-        // Read per CHECK, not at construction: a client attaches and detaches during a daemon's life, and
-        // the question "how long should this quiet be tolerated" is only answerable now. See idle-grace.
-        const grace = idleGraceMs(this.#graceMs, this.#agentAttached?.() ?? false, this.#attachedGraceMs);
-        if (now - this.#idleSince >= grace) {
-            this.#fired = true;
-            log('reticle_daemon_idle_shutdown', {
-                idleMs: now - this.#idleSince,
-                attached: this.#agentAttached?.() ?? false,
-            });
-            this.#onShutdown();
-        }
-    }
-    start() {
-        if (this.#graceMs <= 0 || this.#timer !== undefined)
-            return; // 0 = disabled
-        this.#timer = setInterval(() => this.check(), this.#checkMs);
-        this.#timer.unref();
-    }
-    stop() {
-        if (this.#timer === undefined)
-            return;
-        clearInterval(this.#timer);
-        this.#timer = undefined;
-    }
-}
-/**
- * The idle re-check cadence, from the environment. Same shape as the grace resolver, with one
- * deliberate difference: `0` is not a legal cadence here (it would spin), so `<= 0` falls back to
- * the default rather than meaning anything.
- */
-export function resolveIdleCheckMs(raw) {
-    if (raw === undefined || '' === raw.trim())
-        return SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
-    const n = Number(raw);
-    if (!Number.isFinite(n) || n <= 0)
-        return SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
-    return Math.floor(n);
-}
-/**
- * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of
- * milliseconds, `0` to disable. Anything missing or invalid falls back to the default. Pure.
- *
- * The disable is NOT implemented here — 0 is passed through as 0, and `IdleShutdown` treats
- * `graceMs <= 0` as "never self-shut-down" in both `start()` and `check()`. Said out loud because
- * this docblock had drifted onto the function above it, leaving this one undocumented next to a
- * bare `Math.floor`: a reviewer driving 2.5.0 read it as a documented option with no branch
- * implementing it and filed the gate that depends on it as inverted. The behaviour was correct in
- * every build; only the code was readable as broken.
- */
-export function resolveIdleShutdownMs(raw) {
-    if (raw === undefined || '' === raw.trim())
-        return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
-    const n = Number(raw);
-    if (!Number.isFinite(n) || n < 0)
-        return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
-    return Math.floor(n);
-}

package/dist/daemon/state-dir.js

@@ -1,59 +0,0 @@
-/**
- * Can Reticle write the directory it keeps everything in?
- *
- * `~/.reticle` holds the pid files, the daemon logs, the telemetry id and outbox, and every saved
- * flow. A daemon that cannot write it does not start — and until now said nothing useful about why.
- *
- * Measured on 2.6.0 with `chmod 555 ~/.reticle`:
- *
- *   the daemon did not come up on :4415 — nothing is listening on :4415 — no daemon is running
- *   see /…/.reticle/daemon-4415.log
- *
- * The first line restates the symptom. The second points at a log **inside the unwritable
- * directory**, so the one diagnostic offered cannot exist. Someone hitting this — a locked-down home
- * directory, a container with a read-only mount, a managed corporate profile — has nothing to go on.
- *
- * Deliberately a PROBE, not a permission-bit read: `stat` says what the mode claims, and an ACL, a
- * read-only mount, SELinux or a full disk all produce a writable-looking mode and a failing write.
- * The only honest test of "can I write here" is writing.
- */
-import { mkdirSync, existsSync, writeFileSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
-/** Probe filename. Distinctive so a leftover is obviously ours, and unlinked immediately either way. */
-const PROBE = '.reticle-write-probe';
-/**
- * A sentence naming the problem, or `undefined` when the directory is usable.
- *
- * A directory that does not exist yet is NOT a problem: the daemon creates it, and the creation
- * failing is caught by the same probe on the parent path.
- */
-export function stateDirProblem(dir) {
-    if (!existsSync(dir)) {
-        // Not yet created is the ordinary first-run state. Only report if we cannot create it.
-        try {
-            mkdirSync(dir, { recursive: true });
-        }
-        catch {
-            return (`Reticle cannot create its state directory at ${dir}. Everything it keeps — the daemon ` +
-                'log, the pid file, saved flows — lives there, so the daemon cannot start. Check the ' +
-                'permissions on the parent directory, or point Reticle elsewhere with HOME.');
-        }
-        return undefined;
-    }
-    const probe = join(dir, PROBE);
-    try {
-        writeFileSync(probe, '', 'utf8');
-    }
-    catch {
-        return (`Reticle cannot write to its state directory at ${dir}. Everything it keeps — the daemon ` +
-            'log, the pid file, saved flows — lives there, so the daemon cannot start. Make it writable ' +
-            '(`chmod u+w`), or point Reticle elsewhere with HOME.');
-    }
-    try {
-        unlinkSync(probe);
-    }
-    catch {
-        /* wrote but could not clean up: the directory IS writable, which is the question asked */
-    }
-    return undefined;
-}

package/dist/daemon/wake-decision.d.ts

@@ -1,32 +0,0 @@
-/**
- * What a woken MCP proxy may do with whatever is sitting on its port.
- *
- * Pulled out as a pure function because the wake path lives inside a long side-effecting closure in
- * `mcp-command.ts`, and the decision it was getting wrong is three lines of reasoning that deserve a
- * test of their own.
- *
- * `resolveMcpPort` asks the identity question at BOOT and relocates rather than adopting a stranger.
- * The wake path asked only whether a daemon answered, so after an idle exit freed the port and
- * another project's daemon bound it, a dormant proxy could reattach to a daemon that was not its
- * own — and then serve an agent verdicts about a different application. `adoptable` is the same rule
- * boot uses; this is just the wake path finally asking it.
- */
-import { PortPresence } from './port-presence.js';
-export declare const WakeAction: {
-    /** A daemon we may use is already here. */
-    readonly USE: "use";
-    /** Nothing is listening: start one. */
-    readonly SPAWN: "spawn";
-    /** Somebody else's. Go dormant with a reason rather than pretend the wake succeeded. */
-    readonly REFUSE: "refuse";
-};
-export type WakeAction = (typeof WakeAction)[keyof typeof WakeAction];
-/**
- * Identity is asked only of a port that actually holds a daemon.
- *
- * A FREE port must stay spawnable whatever the registry says about it, because a stale entry is the
- * registry's ordinary state for the moment after any daemon exits — and refusing there would turn
- * every idle retirement into a permanent lockout, which is the failure this whole path exists to
- * prevent.
- */
-export declare function decideWake(presence: PortPresence, daemonProjectId: string | undefined, callerProjectId: string | undefined): WakeAction;

package/dist/daemon/wake-decision.js

@@ -1,38 +0,0 @@
-/**
- * What a woken MCP proxy may do with whatever is sitting on its port.
- *
- * Pulled out as a pure function because the wake path lives inside a long side-effecting closure in
- * `mcp-command.ts`, and the decision it was getting wrong is three lines of reasoning that deserve a
- * test of their own.
- *
- * `resolveMcpPort` asks the identity question at BOOT and relocates rather than adopting a stranger.
- * The wake path asked only whether a daemon answered, so after an idle exit freed the port and
- * another project's daemon bound it, a dormant proxy could reattach to a daemon that was not its
- * own — and then serve an agent verdicts about a different application. `adoptable` is the same rule
- * boot uses; this is just the wake path finally asking it.
- */
-import { PortPresence } from './port-presence.js';
-import { adoptable } from './daemon-resolve.js';
-export const WakeAction = {
-    /** A daemon we may use is already here. */
-    USE: 'use',
-    /** Nothing is listening: start one. */
-    SPAWN: 'spawn',
-    /** Somebody else's. Go dormant with a reason rather than pretend the wake succeeded. */
-    REFUSE: 'refuse',
-};
-/**
- * Identity is asked only of a port that actually holds a daemon.
- *
- * A FREE port must stay spawnable whatever the registry says about it, because a stale entry is the
- * registry's ordinary state for the moment after any daemon exits — and refusing there would turn
- * every idle retirement into a permanent lockout, which is the failure this whole path exists to
- * prevent.
- */
-export function decideWake(presence, daemonProjectId, callerProjectId) {
-    if (PortPresence.FREE === presence)
-        return WakeAction.SPAWN;
-    if (PortPresence.DAEMON !== presence)
-        return WakeAction.REFUSE;
-    return adoptable(daemonProjectId, callerProjectId) ? WakeAction.USE : WakeAction.REFUSE;
-}

package/dist/dev/stale-issue-guard.d.ts

@@ -1,41 +0,0 @@
-/**
- * An issue we have already fixed must not still read as available work.
- *
- * Three contributor PRs died on arrival in one week for this. #373 was filed at 09:52 and fixed by
- * us at 12:33 the same day, then left open for three more days — somebody started on it on day two.
- * #398 shipped and stayed open; a second contributor rebuilt it from scratch. `GITHUB.md` already
- * documents the same failure costing three contributors before either of those, which makes this the
- * third recurrence of a defect we have written down and asked ourselves to remember.
- *
- * Remembering is not a mechanism, and this is the smallest one that works: a commit saying it closes
- * an issue is a claim that the issue is done. If that issue is still open and unlabelled afterwards,
- * the tracker is lying to whoever reads it next — and the person it lies to is by definition someone
- * looking for something to work on.
- *
- * ## Why `fixed-pending-release` is an accepted answer
- *
- * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
- * ships. The label is what tells a contributor not to start, so the label — not the closure — is
- * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
- * when they close things, only to say so.
- *
- * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
- * below testable without a network or a repo.
- */
-export interface IssueState {
-    number: number;
-    state: 'open' | 'closed';
-    labels: readonly string[];
-}
-export declare function closedRefsIn(commitMessage: string): number[];
-/**
- * Of the issues these commits claimed to close, the ones still reading as available work.
- *
- * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
- * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
- * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
- * defect it was catching.
- */
-export declare function staleIssues(claimed: readonly number[], issues: readonly IssueState[]): number[];
-/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
-export declare function staleIssueReport(stale: readonly number[]): string;

package/dist/dev/stale-issue-guard.js

@@ -1,75 +0,0 @@
-/**
- * An issue we have already fixed must not still read as available work.
- *
- * Three contributor PRs died on arrival in one week for this. #373 was filed at 09:52 and fixed by
- * us at 12:33 the same day, then left open for three more days — somebody started on it on day two.
- * #398 shipped and stayed open; a second contributor rebuilt it from scratch. `GITHUB.md` already
- * documents the same failure costing three contributors before either of those, which makes this the
- * third recurrence of a defect we have written down and asked ourselves to remember.
- *
- * Remembering is not a mechanism, and this is the smallest one that works: a commit saying it closes
- * an issue is a claim that the issue is done. If that issue is still open and unlabelled afterwards,
- * the tracker is lying to whoever reads it next — and the person it lies to is by definition someone
- * looking for something to work on.
- *
- * ## Why `fixed-pending-release` is an accepted answer
- *
- * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
- * ships. The label is what tells a contributor not to start, so the label — not the closure — is
- * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
- * when they close things, only to say so.
- *
- * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
- * below testable without a network or a repo.
- */
-/** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
-const PENDING_RELEASE_LABEL = 'fixed-pending-release';
-/**
- * Issue numbers a commit message CLAIMS to have closed.
- *
- * Only the closing verbs GitHub itself acts on. A bare `#447`, a `Refs #447` or a `see #447` is how
- * a change points at context it did not close — the exact habit we want to encourage — so counting
- * those would make the guard cry wolf on good behaviour, and a check that cries wolf is one people
- * learn to skip.
- */
-const CLOSING_REF = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi;
-export function closedRefsIn(commitMessage) {
-    const seen = new Set();
-    for (const match of commitMessage.matchAll(CLOSING_REF)) {
-        const raw = match[1];
-        if (raw === undefined)
-            continue;
-        const parsed = Number.parseInt(raw, 10);
-        if (Number.isFinite(parsed))
-            seen.add(parsed);
-    }
-    return [...seen];
-}
-/**
- * Of the issues these commits claimed to close, the ones still reading as available work.
- *
- * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
- * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
- * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
- * defect it was catching.
- */
-export function staleIssues(claimed, issues) {
-    const byNumber = new Map(issues.map((issue) => [issue.number, issue]));
-    return claimed.filter((number) => {
-        const issue = byNumber.get(number);
-        if (issue === undefined)
-            return false;
-        if ('closed' === issue.state)
-            return false;
-        return !issue.labels.includes(PENDING_RELEASE_LABEL);
-    });
-}
-/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
-export function staleIssueReport(stale) {
-    const list = stale.map((n) => `#${String(n)}`).join(', ');
-    return (`${list} ${1 === stale.length ? 'is' : 'are'} still OPEN, and a commit on this branch says it ` +
-        `closes ${1 === stale.length ? 'it' : 'them'}. Anyone browsing the tracker reads that as work ` +
-        `nobody has started. Close ${1 === stale.length ? 'it' : 'them'}, or label ` +
-        `${1 === stale.length ? 'it' : 'them'} \`${PENDING_RELEASE_LABEL}\` if the fix is waiting on a ` +
-        `release. This has cost three contributors an evening each; it is not bookkeeping.`);
-}