@mjasnikovs/pi-task 0.38.10 → 0.38.12

package/dist/task/boot-probe.d.ts

@@ -0,0 +1,298 @@
+import type { RenderOutcome } from './render-check.js';
+import { type DeepRenderOutcome } from './deep-render-check.js';
+import type { HealthCommand } from './repo-health-check.js';
+/**
+ * Why this script is NOT a launch of the shipped app, or null when it plausibly
+ * is one (mx5 run 18, validated).
+ *
+ * Run 18's boot command resolved to `bun run dev`, whose body is
+ * `docker compose -f docker-compose.dev.yml up -d && until docker compose … pg_isready
+ * … && concurrently "bun run dev:css" "bun run dev:js" "bun run --watch
+ * src/server/index.ts"`. The gate sandbox has no docker, so the chain died at 127 and
+ * the boot SKIPPED as an environment gap — while the shipped app had no HTTP listener
+ * at all. A script whose first act is `docker compose up` cannot distinguish "the app
+ * is broken" from "this box has no docker", so it is not evidence either way: better
+ * to discover NO boot command — reported as "nothing to boot" — and let the static
+ * serve-entry check (serve-entry.ts) carry the signal, than to spend the grace window
+ * producing an unfalsifiable skip.
+ *
+ * CONSERVATIVE AND LEXICAL BY CONSTRUCTION. Only two shapes are rejected, both
+ * decidable from the script text alone:
+ *   1. the chain OPENS with container orchestration (docker/podman/nerdctl … up|start|run);
+ *   2. the whole body is a multiplexer (concurrently/npm-run-all/run-p/run-s/turbo)
+ *      whose every child is an ASSET watcher in watch mode (tailwind/tsc/esbuild/…),
+ *      i.e. nothing in it can ever listen.
+ * Anything else — `vite`, `next dev`, `node dist/index.js`, `nodemon`, `bun --watch
+ * src/index.ts`, and any multiplexer with one non-asset child — is accepted
+ * unchanged. Deciding whether a watcher actually SERVES is not attempted here; that
+ * is exactly what the static serve-entry check is for.
+ */
+export declare function nonLaunchScriptReason(body: string, scripts?: Record<string, string>): string | null;
+/**
+ * The project's OWN launch command, if it declares one (package.json `start`,
+ * else `dev`; Makefile `run`). null means the project has nothing to boot —
+ * the boot check degrades to nothing-to-run.
+ *
+ * A script that is not a LAUNCH at all (nonLaunchScriptReason — mx5 run 18's
+ * `docker compose up` orchestrator) is rejected here and falls through to the
+ * next candidate, then to null. Discovering nothing is strictly better than
+ * discovering something unfalsifiable: an env-gap skip of an orchestration script
+ * says nothing about the app, and null is reported as "nothing to boot".
+ */
+export declare function discoverBootCommand(cwd: string): HealthCommand | null;
+/**
+ * The launch script that EXISTS but was rejected as not-a-launch, if any. Without
+ * this the rejection would trade run 18's unfalsifiable skip for pure silence: no
+ * boot command means bootSkipVerdict has no label to name, and a project whose test
+ * suite ran still reports `observed > 0`, so unobservedVerdict stays quiet too. A
+ * served app whose only declared launch script cannot start it was not observed to
+ * run, and must say so.
+ */
+export declare function rejectedLaunchScript(cwd: string): {
+    name: string;
+    reason: string;
+} | null;
+type BootOutcome = {
+    outcome: 'skip' | 'pass';
+    /** Set when the render check could not OBSERVE the served page (no browser,
+     *  undeterminable port) or its AUTHENTICATED half (no declared credentials,
+     *  an undrivable sign-in form, credentials the server rejected) — surfaced
+     *  by the gate as an UNOBSERVED warning. */
+    renderNote?: string;
+    /** skip only: the boot command never spawned (ENOENT) — feeds the
+     *  full-blindness guard (mx5 run 16), unlike a 127 where the runner ran. */
+    spawnFailed?: boolean;
+} | {
+    outcome: 'fail';
+    detail: string;
+} | {
+    outcome: 'orphan-port';
+    detail: string;
+    port: number | null;
+};
+/** Injectable environment probes for the boot check's orphan-port recovery, so the
+ *  reap-and-retry path is deterministically testable without a real listener. */
+export interface BootDeps {
+    /** The pid + command line holding `port` in LISTEN, or null if none/unknown. */
+    findPortHolder?: (port: number) => {
+        pid: number;
+        command: string;
+    } | null;
+    /** Terminate a pid we attribute to ourselves; returns whether it was signalled. */
+    reap?: (pid: number) => boolean;
+    /**
+     * Does process group `pgid` currently own a LISTENing TCP socket? Drives the
+     * served-app boot check (mx5 run 10): a watcher (`dev` = tailwind/bundler
+     * --watch) stays alive forever without ever listening, so "still alive after the
+     * grace window = PASS" blessed a project that cannot serve a single request.
+     * Injected so the listener requirement is deterministically testable without a
+     * real socket; the default probes ss/lsof + pgid.
+     */
+    groupHasListener?: (pgid: number) => boolean;
+    /**
+     * The (lowest) TCP port a listener owned by process group `pgid` is bound to,
+     * or null when it cannot be determined. Feeds the render check's URL; injected
+     * for tests, default probes ss/lsof + pgid.
+     */
+    groupListeningPort?: (pgid: number) => number | null;
+    /**
+     * Load the served page once in a headless browser and judge the RENDERED DOM
+     * (mx5 runs 8/11: curl cannot execute JS, so a blank-mount app passed every
+     * gate). Runs only for a served app, against the live listener, before the
+     * boot child is killed. Absent → the boot check behaves exactly as before;
+     * the gate wires runRenderCheck by default for served apps.
+     */
+    renderProbe?: (url: string) => RenderOutcome;
+    /**
+     * SIGN IN on the served page and judge the AUTHENTICATED half of the app (mx5
+     * run 17). Runs only after `renderProbe` PASSED — the shallow blank-page rule
+     * keeps its own RED/GREEN-proven verdict and is never shadowed by this one.
+     * Absent → the boot check behaves exactly as before; the gate wires
+     * runDeepRenderCheck by default for served apps. May only FAIL when the SERVER
+     * itself authenticated the session (see deep-render-check.judgeDeepSession);
+     * anything else — no browser, no declared credentials, an undrivable form,
+     * rejected credentials — is an env gap and skips with an UNOBSERVED note.
+     */
+    deepRenderProbe?: (url: string) => DeepRenderOutcome | Promise<DeepRenderOutcome>;
+    /**
+     * Can this box enumerate listeners with pids AT ALL (ss/netstat/lsof)? False
+     * means the served-app requirement is UNOBSERVABLE here and must degrade to the
+     * survival rule rather than fail — see canEnumerateListeners.
+     */
+    enumerationCapable?: () => boolean;
+    /**
+     * Reserve a free port to hand the boot child as PORT, so an HTTP answer on it is
+     * ownership evidence. null → no port could be reserved (the check then relies on
+     * pgid attribution alone). Injected for tests.
+     */
+    pickPort?: () => Promise<number | null>;
+    /**
+     * The port the project's own client was BUILT to call, when it declares one and
+     * nothing is holding it — preferred over a freshly reserved port so the served
+     * origin and the origin the client calls are the same one (see pinnedLocalPort).
+     * null → use the reserved private port exactly as before.
+     */
+    preferredPort?: () => Promise<number | null>;
+    /** Does anything answer HTTP on 127.0.0.1:`port`? Injected for tests. */
+    httpProbe?: (port: number) => boolean;
+}
+/**
+ * Does the finished run stand up a listening HTTP server? Deterministic, from the
+ * built manifest (a server-framework dependency is the plan's own artifact) OR, when
+ * available, the plan/spec text. Used to decide whether the boot check must observe a
+ * LISTENER (served app) or may pass on mere survival / quick exit (CLI project).
+ */
+export declare function detectsServedApp(cwd: string, planText?: string): boolean;
+/** `ss -tlnpH` rows → {pid, port}. Column 4 (0-based 3) is the local address; the
+ *  port is its last `:`-suffixed number ("0.0.0.0:3000", "[::]:3000"). */
+export declare function parseSsListeners(stdout: string): Array<{
+    pid: number;
+    port: number;
+}>;
+/**
+ * `netstat -tlnp` rows → {pid, port} (mx5 run 14, validated: the agent-sandbox
+ * image ships NEITHER ss NOR lsof — only ps and netstat — so the served-app boot
+ * check could never observe a listener and failed unfalsifiably). The pid rides
+ * in the trailing "PID/Program name" column ("1234/bun"); rows the kernel will
+ * not attribute to us print "-" there and are skipped.
+ */
+export declare function parseNetstatListeners(stdout: string): Array<{
+    pid: number;
+    port: number;
+}>;
+/** `lsof -iTCP -sTCP:LISTEN -n -P` rows → {pid, port}. */
+export declare function parseLsofListeners(stdout: string): Array<{
+    pid: number;
+    port: number;
+}>;
+export declare function canEnumerateListeners(): boolean;
+/**
+ * A free TCP port on the loopback interface, or null if one cannot be reserved.
+ * The boot check hands this to the child as PORT so that a successful HTTP
+ * request to it is OWNERSHIP evidence: nobody else knows the number (mx5 runs
+ * 8/10/11 — orphaned servers from earlier checks answered curl on the
+ * conventional :3000 and passed checks the app had not earned).
+ */
+export declare function pickFreePort(): Promise<number | null>;
+/** Can we bind 127.0.0.1:`port` right now? (Free ⇒ the boot child can have it.) */
+export declare function isPortFree(port: number): Promise<boolean>;
+/**
+ * The project's own declared local port, but only if nothing is holding it — the
+ * default `preferredPort` for the gate. A declared port that is BUSY falls back to
+ * a reserved one rather than colliding: a stranger's server on :3000 must never be
+ * mistaken for the app we just booted.
+ */
+export declare function preferredDeclaredPort(cwd: string): Promise<number | null>;
+/** Default port-holder lookup: `lsof` first, then `ss`/`fuser`. Returns null on any
+ *  failure (the diagnosis then omits the pid — never blocks). */
+export declare function defaultFindPortHolder(port: number): {
+    pid: number;
+    command: string;
+} | null;
+/**
+ * Exercise the start command ONCE. For a CLI project (`expectServer` false) the
+ * command's own fate within the grace window decides:
+ *
+ *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
+ *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
+ *   - still alive when the window closes → PASS, then the whole process group is
+ *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
+ *
+ * For a SERVED app (`expectServer` true — the spec/plan promised an HTTP server) mere
+ * survival is not enough: a watcher (`dev` = tailwind/bundler --watch) stays alive
+ * forever without ever listening, and a type-only entrypoint exits 0 in <1s having
+ * served nothing (mx5 run 10 — both were blessed by the survival rule). The boot then
+ * PASSes only once a LISTENing socket owned by our process group is observed; if the
+ * command exits, or the grace window closes, with no listener ever seen → FAIL naming
+ * that a listening server was expected.
+ *
+ * OBSERVABILITY is a precondition of that FAIL (mx5 run 14, validated). The listener
+ * requirement needs pgid-attributed socket enumeration; win32 has none, and neither
+ * does a Linux image shipping no ss/netstat/lsof — run 14's sandbox was exactly that,
+ * so the check emitted "never opened a listening socket" against an app that
+ * demonstrably served, three autofix passes could not falsify it, and the run was
+ * recorded failed. Two defences, in order:
+ *
+ *   - the child is spawned with a freshly reserved, otherwise-unused PORT, and an
+ *     HTTP answer on THAT port proves a listener regardless of tooling. The private
+ *     port is what makes the HTTP probe trustworthy: an orphaned server from an
+ *     earlier check answers on :3000, but nobody else knows this number.
+ *   - if nothing can enumerate listeners AND the assigned port never answered, the
+ *     served-app requirement is unobservable here, so `expectServer` collapses to
+ *     the survival rule and the PASS is stamped UNOBSERVED. An app that ignores PORT
+ *     is indistinguishable from one that never listened — an observer limitation,
+ *     not an app defect, and it may not be reported as one.
+ *
+ * A child that EXITS non-zero still FAILs in every environment: "the process died"
+ * needs no socket probe, so run 14's original true positive (a `--hot` runtime
+ * pinning a crashed app) stays reportable wherever the tooling exists.
+ *
+ * Env-gap contract as everywhere: spawn error (ENOENT) or a command-not-found
+ * inside the chain (exit 127, or the runner's own wording where the platform
+ * reports it that way — see isCommandNotFound) → skip.
+ */
+export declare function runBootCheck(cwd: string, [bin, args]: HealthCommand, graceMs?: number, opts?: {
+    expectServer?: boolean;
+    deps?: BootDeps;
+}): Promise<BootOutcome>;
+/**
+ * The SAME third verdict, at the door unobservedVerdict cannot reach: the boot
+ * check specifically (mx5 run 18, validated).
+ *
+ * Run 18 shipped an app with no HTTP server behind a converged final gate. Its
+ * `src/server/index.ts` ends at `export {app}` — no `Bun.serve`, no
+ * `export default app`, no `start` script — so `bun run src/server/index.ts` exits
+ * 0 immediately and the product cannot be started at all. The gate's boot command
+ * resolved to `bun run dev`, whose body begins `docker compose … up -d`; the gate
+ * sandbox had no docker, so the boot SKIPPED as an environment gap. Skips
+ * contribute nothing to `dynObserved`, and `bun run test`, `test:ct`, `build`,
+ * `lint`, `seed` and `migrate` all ran — so `dynObserved > 0`, the full-skip
+ * blindness guard (observabilityGapFailure) stayed correctly quiet, and the trail
+ * read `final-gate: autofix converged — statics + … passed` with 24/24 tasks green.
+ *
+ * The defect is that "the app was never observed to boot" and "the app booted
+ * fine" produced BYTE-IDENTICAL gate output. That is the class scripts/ab-verdict.ts
+ * exists to kill one layer up: absence of evidence rendered in the shape of
+ * evidence. So a discovered-but-skipped boot now names itself, and — unlike every
+ * other skip — it CANNOT be cancelled by observations from other commands.
+ * Component tests are the trap here, not the alibi: run 18 had 51 green Playwright
+ * CT tests, and CT mounts components in a browser without ever assembling or
+ * starting the server.
+ *
+ * DECIDED, do not silently re-open:
+ *  - NOT a FAIL. A boot skip on a docker-less box is a genuine environment gap, and
+ *    failing it re-creates run 16's unfalsifiable-FAIL mistake pointing the other
+ *    way. UNOBSERVED blocks nothing while being loud and durable (the caller records
+ *    it as final-gate debt the next run re-surfaces), and it keeps "boot never ran"
+ *    out of the autofix child's seed — a child cannot fix a missing docker, so the
+ *    highest-probability response would be to FABRICATE a bootable command, the
+ *    class that refuted the `## verified tooling` harvest.
+ *  - BOTH skip flavours count. Run 18's skip carried `spawnFailed: false` (127 inside
+ *    the script chain, not an ENOENT on the runner), so keying off spawnFailed would
+ *    have missed the actual defect.
+ *  - SERVED APPS ONLY. `expectServer === false` (a CLI/library project) is fenced off
+ *    deliberately: a CLI whose `dev` script needs an absent tool has no server to be
+ *    unobserved, and widening the lever there buys warnings nobody can act on.
+ */
+export declare function bootSkipVerdict(args: {
+    /** `bin args…` of the DISCOVERED boot command; null ⇒ nothing to boot, which is
+     *  not the same thing as a boot that was not observed. */
+    label: string | null;
+    /** Did the boot check end in `skip` (either flavour)? */
+    skipped: boolean;
+    /** Does this project stand up an HTTP server (detectsServedApp)? */
+    expectServer: boolean;
+}): string | null;
+/**
+ * Boot check hit an address-in-use bind failure. If the port is held by one of OUR
+ * own orphaned gate children (a `dev`/`start` run), reap it and retry the boot once
+ * so the app gets a fair launch; otherwise leave the (foreign) holder alone and let
+ * the caller emit the harness diagnosis. Never reaps a process we cannot attribute
+ * to ourselves.
+ */
+export declare function recoverOrphanPort(cwd: string, boot: HealthCommand, first: {
+    outcome: 'orphan-port';
+    detail: string;
+    port: number | null;
+}, bootGraceMs: number, deps: BootDeps, expectServer: boolean): Promise<BootOutcome>;
+export {};