approval-md 0.0.1 → 0.2.0

package/dist/src/cli/preflight.d.ts

@@ -0,0 +1,363 @@
+/**
+ * The startup preflight (APRV-215): is the code about to run the code that is
+ * on origin, and is the build behind it the one the sources describe?
+ *
+ * ## The four manual steps this replaces
+ *
+ * Deploying the APRV-212 fix in the primary checkout took `git fetch`, a
+ * judgment call about whether the ten upstream commits touched
+ * `.approval/log/events.jsonl` while the working log was dirty, `git pull
+ * --ff-only`, and `npm run build`. Three of those are typing; the second is the
+ * one a human cannot make from `git status` alone, because `git status` does not
+ * say what the *upstream range* changed. Carter's standing view is that manual
+ * git steps for the human are a defect rather than a runbook, so the judgment
+ * moves here and the typing moves with it.
+ *
+ * ## What it is allowed to do
+ *
+ * Read git, and at most three writes: a `--ff-only` merge, `npm run build`,
+ * and, when the merge refused over an untracked file under `backlog/tasks/`
+ * that main already contains, clearing that file out of the way (APRV-300, and
+ * the rules it obeys are in {@link reconcileUntrackedTaskFiles}).
+ *
+ * It never resets, never stashes, never checks anything out, and never touches
+ * the working log. That list is not conservatism for its own sake — it is fork 2
+ * of 2026-08-20 (APRV-104's notes, and the reason `approval log sync` exists at
+ * all): a working `events.jsonl` rewound through git underneath a live appender
+ * is two chains where there was one. `--ff-only` cannot rewind a file that
+ * upstream did not change, and when upstream DID change it while the working
+ * copy is dirty, this module refuses and names `approval log sync`, which is the
+ * verb that knows how to do it safely.
+ *
+ * ## Refusals, not repairs
+ *
+ * Four codes, each firing for exactly one condition. The first three are
+ * evaluated in this order, before anything is written:
+ *
+ * - `up-preflight-behind-ahead` — `origin/<branch>..HEAD` is non-empty. Local
+ *   commits exist that the remote does not have. A fast-forward is not the
+ *   operation for that state, and guessing which side to keep is a decision.
+ * - `up-preflight-log-diverged` — the upstream range changes the working log or
+ *   the queue projection, and the working copy has uncommitted changes to them.
+ *   This is the case the human could not judge by eye, and it is `approval log
+ *   sync`'s whole subject.
+ * - `up-preflight-dirty-protected` — some OTHER path the upstream range changes
+ *   is locally modified, so `git merge --ff-only` would refuse to overwrite it.
+ *   Named separately because the repair is different: look at the edit and
+ *   decide, or start on the current build with `--no-preflight`.
+ *
+ * The fourth is answered after the merge has already refused, and only for the
+ * one path shape where two checkouts routinely author one file (APRV-300):
+ *
+ * - `up-preflight-task-file-conflict` — an untracked file under
+ *   `backlog/tasks/` stopped the fast-forward, and it holds lines the incoming
+ *   copy does not. See {@link reconcileUntrackedTaskFiles} for what happens
+ *   when it holds none, and why that is a claim rather than an assumption.
+ *
+ * `git reset --hard` appears in none of them, and never will: it is the command
+ * that turns "your checkout is confusing" into "your work is gone".
+ *
+ * A fourth refusal reports a write that failed rather than a judgment:
+ * `up-preflight-failed` carries the step and, for the build, the exit code
+ * `npm run build` came back with. The runtime does not start after it, because the whole point
+ * of the rebuild is that a daemon and a hook running compiled-away code is the
+ * defect being fixed (APRV-301); `--no-build` is how an operator says they
+ * meant to run the stale build anyway.
+ *
+ * ## A fetch that fails is weather
+ *
+ * A laptop on a train has no origin to compare against. That is not a reason to
+ * refuse to run a gate — the log is local, the policy is local, and the human is
+ * holding the phone. A failed fetch is reported as a warning and the runtime
+ * starts on the build it has, saying so.
+ *
+ * ## Two callers, one judgment
+ *
+ * `approval up` (and therefore `approval daemon run --with-channels`) acts on
+ * it; `approval doctor`'s `main-behind-origin` row reports it. Doctor passes
+ * `fetch: false`, because a report is not allowed to make a network call the
+ * operator did not ask for, and says out loud that its answer is only as fresh
+ * as the last fetch.
+ */
+import type { DoctorCheck } from "./doctor.js";
+import { type RunbookStep } from "./style.js";
+/**
+ * The installation root: the directory holding `cli.js`, `src/`, `dist/`.
+ *
+ * Derived from this module's own location rather than from `cwd`, because the
+ * question is "is the code I am running stale", and the answer must not change
+ * when the operator runs the CLI from somewhere else. Compiled, this file is
+ * `<root>/dist/src/cli/preflight.js`, hence three levels up.
+ */
+export declare function installationRoot(): string;
+/** Thrown out of the source walk so a real I/O denial can become exit 4. */
+export declare class ScanError extends Error {
+}
+/**
+ * Is the built CLI at least as new as the sources it was built from?
+ *
+ * The marker is `dist/src/cli/main.js` — the exact file `cli.js` loads, so the
+ * thing being timestamped is the thing that will actually run. It is compared
+ * against the newest mtime under `src/` and of `tsconfig.json` (a compiler
+ * option change invalidates a build as surely as an edit does).
+ *
+ * Three shapes are distinguished because their repairs differ:
+ *
+ * - `cli.js` present, `dist/` absent — the placeholder-binary shape from the
+ *   ceremony. The loader exists, so the checkout *looks* installed; nothing
+ *   behind it does.
+ * - marker older than sources — the stale-checkout shape. Verbs that exist in
+ *   `src/` are missing from the binary.
+ * - no `src/` at all — a published install, where freshness is not a question
+ *   that can be asked. `skip`, not a silent pass.
+ *
+ * Note the self-reference: doctor itself runs *from* `dist`, so a completely
+ * absent `dist` means `cli.js` already refused and this code never ran. The
+ * check is still implemented for that shape because `--root` can point it at
+ * another tree, and because "the binary you ran is not the tree you edited" is
+ * exactly the confusion it exists to name.
+ */
+export declare function checkBuildFreshness(root: string): DoctorCheck;
+/**
+ * Is `root`'s build older than `root`'s sources?
+ *
+ * `null` when the question does not apply — a published install with no `src/`,
+ * or a tree that is not an installation at all. A caller that wants the full
+ * three-way answer asks {@link checkBuildFreshness}; this is the boolean the
+ * preflight acts on, and "cannot tell" must not read as "stale" or the preflight
+ * would rebuild a tree it has no business compiling.
+ */
+export declare function distStale(root: string): boolean | null;
+/** What the preflight did, or would have done. Frozen: it is a `--json` field. */
+export type PreflightAction = 
+/** Already at the remote tip with a build no older than the sources. */
+"none"
+/** Only the build was behind. */
+ | "rebuild"
+/** Only the checkout was behind. */
+ | "fast-forward"
+/** Both. The ordinary shape after a few days away. */
+ | "fast-forward+rebuild"
+/** The build was older than the sources and `--no-build` said to leave it. */
+ | "build-skipped"
+/** The checkout was behind, the build is now stale, and `--no-build` said so. */
+ | "fast-forward+build-skipped"
+/** A refusal: nothing was touched. */
+ | "refused"
+/** `--no-preflight`, or a checkout git cannot answer questions about. */
+ | "skipped"
+/** The fetch did not reach the remote. Weather, not a fault. */
+ | "fetch-failed";
+/** The machine-readable refusal codes. Frozen public API, distinct by repair. */
+export declare const PREFLIGHT_REFUSAL_CODES: readonly ["up-preflight-behind-ahead", "up-preflight-log-diverged", "up-preflight-dirty-protected", "up-preflight-task-file-conflict"];
+export type PreflightRefusalCode = (typeof PREFLIGHT_REFUSAL_CODES)[number];
+/** The facts, exactly as they are carried on the `--json` stream. */
+export interface PreflightFacts {
+    behind_by: number;
+    ahead_by: number;
+    log_touched: boolean;
+    dist_stale: boolean;
+    action: PreflightAction;
+    /**
+     * True when the preflight rebuilt and the runtime therefore re-executed into
+     * the fresh build rather than carrying on in the process that dated it.
+     *
+     * Always false from {@link inspectPreflight}: inspection builds nothing, so
+     * it can never be the reason a process was replaced. Doctor's row reads that
+     * answer and never this one.
+     */
+    reexec: boolean;
+}
+/** A refusal, in the APRV-129 runbook's own vocabulary. */
+export interface PreflightRefusal {
+    code: PreflightRefusalCode;
+    headline: string;
+    state: string[];
+    steps: RunbookStep[];
+    footer: string[];
+    /** The one command a machine caller should run next, unadorned. */
+    next: string;
+}
+/** What {@link inspectPreflight} answers. */
+export type PreflightReport = {
+    ok: true;
+    facts: PreflightFacts;
+    /** One sentence, for the human line and for doctor's `detail`. */
+    detail: string;
+    /** A fetch that did not reach the remote, or `null`. */
+    warning: string | null;
+    /** The commit a fast-forward would move to, when there is one. */
+    target: string | null;
+    /** Where the judgment was made. `null` when there was no repository. */
+    root: string | null;
+} | {
+    ok: false;
+    facts: PreflightFacts;
+    refusal: PreflightRefusal;
+    root: string;
+};
+export interface PreflightInput {
+    /** The working log, which also names the repository (as doctor's log-drift does). */
+    logPath: string;
+    /** The queue projection, the second path a fast-forward must not clobber. */
+    queuePath: string;
+    /** The installation whose `dist/` is dated against its `src/`. */
+    root: string;
+    /** Ask the remote, or judge against the last fetch. Doctor passes `false`. */
+    fetch: boolean;
+    /** Defaults to `origin`. */
+    remote?: string;
+    /** Defaults to the checked-out branch, or `main` on a detached HEAD. */
+    branch?: string;
+    /**
+     * Run the package's build when `dist/` is older than the sources. Defaults to
+     * `true`, which is the whole point of the preflight; `false` is `--no-build`.
+     *
+     * Opting out changes what the preflight DOES, never what it SAYS: the
+     * fast-forward still happens, `dist_stale` still reports the truth, and the
+     * action settles on `build-skipped` so neither the human line nor a machine
+     * caller can read "started" as "started on the code that was merged".
+     *
+     * {@link inspectPreflight} ignores it, because inspection builds nothing.
+     */
+    build?: boolean;
+}
+/**
+ * The whole judgment, and not one byte of action.
+ *
+ * Every write the preflight is allowed to make lives in {@link runPreflight};
+ * this function reads. That split is what lets doctor report the same facts
+ * without any risk of doctor repairing something, which doctor has never done.
+ */
+export declare function inspectPreflight(input: PreflightInput): PreflightReport;
+/** What {@link runPreflight} did, with the facts as they ended up. */
+export type PreflightOutcome = {
+    ok: true;
+    facts: PreflightFacts;
+    detail: string;
+    warning: string | null;
+    /** Present when a rebuild happened: the caller must become this child. */
+    reexec?: ReexecPlan;
+} | {
+    ok: false;
+    facts: PreflightFacts;
+    refusal: PreflightRefusal;
+}
+/** A write the preflight attempted and could not complete. Also a refusal. */
+ | {
+    ok: false;
+    facts: PreflightFacts;
+    failed: {
+        step: string;
+        message: string;
+    };
+};
+/**
+ * Inspect, then perform at most a fast-forward and a build.
+ *
+ * `npm run build` is spawned rather than shelled, with the checkout as its cwd,
+ * so nothing here depends on the operator's shell or on `npm` being on a
+ * particular PATH entry. Its output is discarded and its exit status is the
+ * whole answer: a build that fails is a failed preflight, and the runtime does
+ * not start on a half-compiled tree.
+ */
+export declare function runPreflight(input: PreflightInput, spawnBuild?: (root: string) => {
+    ok: boolean;
+    message: string;
+}): PreflightOutcome;
+/** Where the fresh build lives, and what to run it with. */
+export interface ReexecPlan {
+    /** `<root>/dist/src/cli/main.js` — resolved from the CHECKOUT, never from `import.meta`. */
+    entry: string;
+    /** This process's own argv, plus `--no-preflight` so the child cannot loop. */
+    argv: string[];
+}
+/**
+ * Run the fresh build in a child process and become its exit code.
+ *
+ * `stdio: "inherit"` so the child owns the terminal exactly as the parent would
+ * have: the daemon's lines, the token panel, a channel's prompts and an
+ * operator's ctrl-c all behave as though no re-exec happened. SIGINT and
+ * SIGTERM are forwarded rather than handled, because the child is the writer
+ * and the shutdown sequence that matters is its own.
+ *
+ * A child killed by the signal we forwarded exits 0: the operator asked the
+ * runtime to stop and it stopped, which is a clean stop under any spelling.
+ * Any other signal is reported as an I/O failure, because a writer that
+ * vanished is a fact about the machine rather than a decision of the runtime.
+ */
+export declare function reexecFreshBuild(plan: ReexecPlan, cwd: string): Promise<number>;
+/**
+ * The preflight's two lines on the event stream.
+ *
+ * They live here rather than in `cli/up.ts` because `approval daemon run` runs
+ * the same preflight and must print the same lines, and `daemon.ts` cannot
+ * import `up.ts` (the cycle APRV-110 already routes around with a dynamic
+ * import). `UpEvent` includes this union, so the `--json` stream stays one union
+ * of additive shapes with no field added to any shape that already existed.
+ */
+export type PreflightEvent = ({
+    event: "preflight";
+    commit: string | null;
+    detail: string;
+} & PreflightFacts) | {
+    event: "preflight_warning";
+    message: string;
+};
+/** One preflight line as a human sentence, and where it belongs. */
+export declare function describePreflightEvent(event: PreflightEvent): {
+    text: string;
+    stderr: boolean;
+};
+/** How a caller emits one line. `up` and `daemon run` route theirs identically. */
+export type PreflightEmit = (event: PreflightEvent) => void;
+export interface StartupPreflightInput {
+    logPath: string;
+    queuePath: string;
+    /** The installation whose `dist/` is dated. `null` means "ask this build". */
+    root: string | null;
+    remote: string | null;
+    branch: string | null;
+    /** `false` is `--no-build`: fast-forward, but leave a stale `dist/` alone. */
+    build: boolean;
+    emit: PreflightEmit;
+    /** Where a refusal is written. One line under `--json`, a runbook otherwise. */
+    refuse: (text: string) => void;
+    json: boolean;
+}
+/**
+ * Run the preflight, print what it did, and answer whether the caller may start.
+ *
+ * `ok: false` carries nothing but the fact: everything a human or a machine
+ * needs has already been written by `refuse`, and the caller's only remaining
+ * job is to return the exit code.
+ */
+export declare function startupPreflight(input: StartupPreflightInput): {
+    ok: boolean;
+    reexec: ReexecPlan | null;
+};
+/**
+ * A preflight refusal, on both surfaces (APRV-129).
+ *
+ * The human surface is the runbook: the code, the state, one runnable command
+ * per numbered line, and the rationale compressed into the footer. The machine
+ * surface is one object carrying the stable code and the same facts the success
+ * path carries, so a supervisor can branch on `error.code` without reading a
+ * word of it.
+ */
+export declare function renderPreflightRefusal(outcome: PreflightOutcome & {
+    ok: false;
+}, json: boolean): string;
+/**
+ * `main-behind-origin`, doctor's twenty-first row.
+ *
+ * It makes no network call (`fetch: false`), for the reason every doctor row
+ * makes none it was not asked for: doctor is a report, and a report that reached
+ * the network to be more accurate would be doing something on its own account.
+ * So the answer is as fresh as the last fetch, and the detail says so.
+ *
+ * `fix` strings stay inside `FIX_COMMAND_PREFIXES`: they name `approval` verbs,
+ * never `git`. That constraint predates this row and is the right one — a repair
+ * line telling an operator to reset a branch would be doctor making a decision.
+ */
+export declare function checkMainBehindOrigin(logPath: string, queuePath: string, root: string): DoctorCheck;