@wildorder/nightshift 0.12.0 → 0.14.0

package/dist/preflight.js

@@ -0,0 +1,225 @@
+import { spawn } from "node:child_process";
+import { tail } from "./agent-runner.js";
+/**
+ * The preflight stage: at run start, before baseline verification and any
+ * agent spawn, executes every *pending* prerequisite's `verifyCommand` as a
+ * deterministic, bounded subprocess. Exit zero flips it to `satisfied` (in
+ * memory — the caller decides when to persist); anything else — nonzero
+ * exit, spawn failure, timeout — uniformly means unmet, with a captured
+ * reason, and never throws out of this module. See
+ * `tasks/human-prerequisites/ws-02-*.md` for the full design.
+ */
+/** The wall-clock ceiling on a single prerequisite check. A deterministic
+ *  check that has not answered in this long is treated as unmet, and the
+ *  process tree is killed so it can never outlive the run. A constant, never
+ *  a config key — the charter keeps tuning knobs off the config surface. */
+export const PREREQUISITE_TIMEOUT_MS = 60_000;
+// In-memory output is kept to a bounded tail, mirroring agent-runner.ts's
+// own OUTPUT_TAIL_LIMIT — this module intentionally does not import that
+// private constant.
+const OUTPUT_TAIL_LIMIT = 200_000;
+/** How long a timed-out check waits, past its own ceiling, for the kill
+ *  request to take effect before giving up on `close` and settling anyway.
+ *  A kill (`taskkill`, a signalled process group) has no completion callback
+ *  to await, so without this bound a slow or failed kill would turn a
+ *  *bounded* check into an unbounded one — this is the backstop that keeps
+ *  the promise settling promptly regardless. */
+const KILL_GRACE_MS = 3_000;
+/**
+ * Kills a spawned shell line's whole process tree, not just the shell
+ * process `spawn` returned — a `verifyCommand` may fork descendants (node,
+ * curl, a helper script), and `child.kill()` alone would orphan them: on
+ * Windows in particular, killing only the returned `cmd.exe` process leaves
+ * its own child (say, `node`) running and still holding the inherited stdio
+ * pipe handles, so `close` never fires until that orphan exits on its own —
+ * confirmed empirically (see the git history of this function's tests): a
+ * `child.kill()` issued *before* `taskkill /T` gets a chance to walk the
+ * still-live tree kills the wrapper first, orphans the descendant, and
+ * taskkill then reports "not found" for a pid that is already gone —
+ * reproducing exactly the unbounded-wait failure this function exists to
+ * prevent. So the whole tree is killed as a single unit, by pid, while the
+ * tree is still intact — never a separate signal to the immediate child
+ * first.
+ *
+ * POSIX: the child was spawned `detached: true`, making it its own
+ * process-group leader; signalling the negative pid signals the whole group
+ * atomically. `ESRCH` (the group already exited) is swallowed — best effort.
+ *
+ * Windows: there is no process-group signal, so `taskkill /T /F` is used,
+ * which walks the live process tree from `pid` and terminates it forcibly in
+ * one call. Fire-and-forget as far as this function is concerned — its
+ * caller (the grace timer in {@link makePrerequisiteRunner}) is what bounds
+ * the wait, since an external kill request has no completion callback of its
+ * own to await; a spawn failure for `taskkill` itself (e.g. an unusual PATH)
+ * is swallowed the same way.
+ */
+function killProcessTree(pid) {
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+        });
+        killer.on("error", () => {
+            // taskkill itself failed to spawn — the grace timer still bounds the
+            // wait regardless.
+        });
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or never became a group leader — best effort.
+    }
+}
+/**
+ * Builds a bounded, process-tree-killing `PrerequisiteRunner`. Fixing the
+ * timeout inside a `(command, cwd)` runner would leave a timeout test no
+ * choice but to wait out the real production ceiling; this factory keeps the
+ * ceiling a test seam while {@link defaultPrerequisiteRunner} wires the
+ * production constant once.
+ */
+export function makePrerequisiteRunner(timeoutMs = PREREQUISITE_TIMEOUT_MS) {
+    return (command, cwd) => new Promise((resolvePromise, rejectPromise) => {
+        // shell: true, exactly like defaultVerifyRunner — a verifyCommand is a
+        // whole shell line the human/planner authored, run under cmd /c or
+        // /bin/sh -c. detached: true on POSIX makes the child a process-group
+        // leader so killProcessTree can signal the whole tree; Windows has no
+        // such option and uses taskkill /T instead.
+        const child = spawn(command, [], {
+            cwd,
+            shell: true,
+            windowsHide: true,
+            stdio: ["pipe", "pipe", "pipe"],
+            ...(process.platform === "win32" ? {} : { detached: true }),
+        });
+        let buffered = "";
+        const push = (chunk) => {
+            buffered = (buffered + chunk).slice(-OUTPUT_TAIL_LIMIT);
+        };
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", push);
+        child.stderr?.on("data", push);
+        // Never reads stdin, and ends it immediately — the same headless
+        // posture as defaultVerifyRunner (agent-runner.ts).
+        child.stdin?.end();
+        let settled = false;
+        let timedOut = false;
+        let graceTimer;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(graceTimer);
+            resolvePromise(result);
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (child.pid !== undefined)
+                killProcessTree(child.pid);
+            // The kill above is a request, not a confirmation — `taskkill` and a
+            // signalled process group have no completion callback this runner
+            // can await, and a slow or failed kill must never turn a *bounded*
+            // check into an unbounded one (SC-03/SC-11: the run always
+            // terminates). `close` still wins the race in the overwhelmingly
+            // common case where the kill lands promptly; this grace window is
+            // strictly a backstop for the rest.
+            graceTimer = setTimeout(() => {
+                settle({ exitCode: 1, output: buffered, timedOut: true });
+            }, KILL_GRACE_MS);
+            graceTimer.unref();
+        }, timeoutMs);
+        timer.unref();
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(graceTimer);
+            rejectPromise(error);
+        });
+        child.on("close", (code) => {
+            settle({ exitCode: code ?? 1, output: buffered, timedOut });
+        });
+    });
+}
+/** The production runner: the 60 s ceiling, wired once. */
+export const defaultPrerequisiteRunner = makePrerequisiteRunner();
+/**
+ * Runs every pending prerequisite's `verifyCommand` once. Mutates
+ * `manifest.prerequisites` in place on a met check (pending → satisfied);
+ * the caller decides when (and whether) to persist that mutation to disk. An
+ * already-`satisfied` prerequisite is never re-run — settled facts stay
+ * settled (SC-06). No `verifyCommand` outcome can throw out of this
+ * function or halt the run (SC-03): a thrown spawn failure is caught here.
+ */
+export async function runPreflight(args) {
+    const { manifest, cwd, runner, now, runId, runStartCommit, log } = args;
+    const checks = [];
+    const events = [];
+    for (const prerequisite of manifest.prerequisites) {
+        if (prerequisite.status === "satisfied") {
+            checks.push({ id: prerequisite.id, met: true, newlySatisfied: false });
+            continue;
+        }
+        let run;
+        try {
+            run = await runner(prerequisite.verifyCommand, cwd);
+        }
+        catch (error) {
+            const message = error?.message?.trim();
+            const reason = message && message !== ""
+                ? message
+                : "the verify command could not be started";
+            checks.push({
+                id: prerequisite.id,
+                met: false,
+                reason,
+                newlySatisfied: false,
+            });
+            log(`preflight: ${prerequisite.id} unmet — ${reason}`);
+            continue;
+        }
+        if (run.timedOut) {
+            const reason = `the verify command did not finish within ` +
+                `${PREREQUISITE_TIMEOUT_MS}ms and was terminated`;
+            checks.push({
+                id: prerequisite.id,
+                met: false,
+                reason,
+                newlySatisfied: false,
+            });
+            log(`preflight: ${prerequisite.id} unmet — ${reason}`);
+            continue;
+        }
+        if (run.exitCode !== 0) {
+            const tailed = tail(run.output, 1500).trim();
+            const reason = tailed !== ""
+                ? tailed
+                : `the verify command exited ${run.exitCode} with no output`;
+            checks.push({
+                id: prerequisite.id,
+                met: false,
+                reason,
+                newlySatisfied: false,
+            });
+            log(`preflight: ${prerequisite.id} unmet — ${reason}`);
+            continue;
+        }
+        prerequisite.status = "satisfied";
+        checks.push({ id: prerequisite.id, met: true, newlySatisfied: true });
+        events.push({
+            kind: "prerequisite-verified",
+            at: now().toISOString(),
+            id: prerequisite.id,
+            verifyCommand: prerequisite.verifyCommand,
+            runId,
+            ...(runStartCommit === undefined ? {} : { commit: runStartCommit }),
+        });
+        log(`preflight: ${prerequisite.id} satisfied`);
+    }
+    return { checks, events };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"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"}

package/dist/publish.d.ts

@@ -1,3 +1,5 @@
+import { type AgentRunner } from "./agent-runner.js";
+import { type NightshiftConfig } from "./config.js";
 /**
  * The handover from a finished run to a reviewable pull request: pushes the
  * program branch, opens or updates exactly one draft PR through `gh`,
@@ -53,6 +55,17 @@ export interface GhClient {
     updateComment(cwd: string, commentId: string, body: string): Promise<void>;
     /** Removes a now-stale nightshift-authored comment. */
     deleteComment(cwd: string, commentId: string): Promise<void>;
+    /**
+     * GitHub's mergeability computation for a PR, as raw gh strings. `mergeable`
+     * is one of MERGEABLE | CONFLICTING | UNKNOWN; `mergeStateStatus` is the
+     * fuller state (CLEAN | DIRTY | BLOCKED | BEHIND | DRAFT | UNSTABLE |
+     * HAS_HOOKS | UNKNOWN). Normalization and the UNKNOWN retry live in
+     * `publish`, not here, so the boundary stays thin and the retry is testable.
+     */
+    viewMergeability(cwd: string, prNumber: number): Promise<{
+        mergeable: string;
+        mergeStateStatus: string;
+    }>;
 }
 /**
  * Git operations `publish` needs beyond `program-branch.ts`'s derivation —
@@ -65,6 +78,32 @@ export interface PublishGit {
     /** Is the branch ahead of base? `git rev-list --count <base>..<branch>`. */
     commitsAhead(cwd: string, base: string, branch: string): Promise<number>;
     push(cwd: string, remote: string, branch: string): Promise<void>;
+    /**
+     * Fetches `branch` from `remote` so a subsequent merge sees its current
+     * tip, not whatever this checkout last saw at clone/checkout time.
+     */
+    fetchBranch(cwd: string, remote: string, branch: string): Promise<void>;
+    /**
+     * Merges `ref` into the checked-out branch without committing
+     * (`git merge --no-commit --no-ff`). `"up-to-date"` means `ref` was
+     * already an ancestor of HEAD and nothing happened; `"merged"` means it
+     * merged cleanly and is staged, waiting for `commitMerge`; `"conflict"`
+     * means it left unmerged paths and the merge is still in progress.
+     */
+    mergeNoCommit(cwd: string, ref: string): Promise<{
+        status: "up-to-date";
+    } | {
+        status: "merged";
+    } | {
+        status: "conflict";
+        paths: string[];
+    }>;
+    /** Aborts an in-progress merge, restoring the pre-merge working tree. */
+    abortMerge(cwd: string): Promise<void>;
+    /** Resolves one unmerged path to the checked-out branch's own side, and stages it. */
+    checkoutOurs(cwd: string, path: string): Promise<void>;
+    /** Commits a merge staged by `mergeNoCommit`/`checkoutOurs`. */
+    commitMerge(cwd: string, message: string): Promise<void>;
 }
 export declare const defaultPublishGit: PublishGit;
 export declare const defaultGhClient: GhClient;
@@ -75,8 +114,32 @@ export interface PublishOptions {
     gh?: GhClient;
     /** Injected git boundary; default execFile-backed. */
     git?: PublishGit;
+    /**
+     * Loaded internally via `loadConfig` when omitted, exactly like `run` and
+     * `author` load it in `cli.ts` — publish has no dedicated action of its
+     * own to load it first. Test seam only; production never needs to pass it.
+     */
+    config?: NightshiftConfig;
+    /** Passed straight through to the pre-publish as-built refresh; default reviewer runner. */
+    agentRunner?: AgentRunner;
     log?: (line: string) => void;
+    /** Injected for tests so the UNKNOWN retry does not actually wait. */
+    sleep?: (ms: number) => Promise<void>;
 }
+/** GitHub's answer to "does this PR merge cleanly into its base?" */
+export type MergeableState = "mergeable" | "conflicting" | "unknown";
+/** What the pre-publish base sync did. */
+export type BaseSyncOutcome = {
+    status: "up-to-date";
+} | {
+    status: "merged";
+} | {
+    status: "conflict";
+    paths: string[];
+} | {
+    status: "skipped";
+    reason: string;
+};
 export interface PublishResult {
     prNumber: number;
     prUrl: string;
@@ -85,7 +148,15 @@ export interface PublishResult {
     escalationComments: number;
     /** Report-continuation comments upserted this publish (0 when the report fits). */
     continuationComments: number;
+    /** GitHub's mergeable state for the upserted PR (SC-07). */
+    mergeable: MergeableState;
+    /** What the pre-publish base sync did (SC-08). */
+    baseSync: BaseSyncOutcome;
 }
+/** The named `nightshift publish` / `nightshift run --publish` mergeability line (SC-07). */
+export declare function mergeabilityLine(mergeable: MergeableState): string;
+/** The named `nightshift publish` / `nightshift run --publish` base-sync line (SC-08). */
+export declare function baseSyncLine(baseSync: BaseSyncOutcome): string;
 interface ReportChunk {
     /** A verbatim, contiguous slice of the report — never rewritten or decorated. */
     payload: string;

package/dist/publish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../src/publish.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../src/publish.ts"],"names":[],"mappings":"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"}