litmus-cli 1.4.5 → 1.4.7-eng1502.0

package/dist/lib/deadline.d.ts

@@ -9,29 +9,107 @@
  * wake: the interval also pauses while suspended, but the first tick after
  * resume sees that wall-clock has passed the deadline and fires immediately.
  * Polling additionally sidesteps the ~24.8-day `setTimeout` ceiling.
+ *
+ * Two pieces (ENG-1489 / ENG-1490):
+ *
+ * - `armDeadlinePoll` — the dumb wall-clock poll. It reads the CURRENT
+ *   deadline through a getter on every tick, because the deadline can move
+ *   mid-session (server-side extensions and corrections arrive via the
+ *   heartbeat response). It never latches and never clears itself on fire —
+ *   dedupe, retries, and the fire decision live in the controller.
+ *
+ * - `createAutoSubmitController` — the fire decision. It never submits on
+ *   local state alone: every attempt re-verifies the deadline against the
+ *   server first. A stale-early local deadline that fires "successfully" is
+ *   strictly worse than one that fails — the server, which believes the
+ *   deadline is still hours or days away, accepts the upload as an ordinary
+ *   early submission and the candidate's session ends prematurely. The
+ *   verification is what makes retrying safe at all.
  */
 export interface DeadlinePollHandle {
     stop(): void;
 }
-export interface ArmDeadlineOptions {
-    /** Absolute deadline as an epoch-ms timestamp. */
-    deadline: number;
+/** Tick gaps beyond this are reported as a suspend/resume (wake) even when the
+ * poll cadence is long. */
+export declare const WAKE_GAP_MIN_MS: number;
+export interface DeadlinePollOptions {
+    /** Read the current effective deadline (epoch ms), or null when none is
+     * configured. Re-read every tick so mid-session changes take effect. */
+    getDeadline: () => number | null;
     /** Poll cadence in ms. */
     pollMs: number;
-    /** Fired exactly once, on the first tick at/after the deadline. */
-    onFire: () => void;
+    /** Called on EVERY tick at/after the deadline. The caller owns dedupe. */
+    onDue: () => void;
     /** Injectable clock (defaults to Date.now) — used by tests. */
     now?: () => number;
-    /** Called when the poll is armed, with ms until the deadline. */
-    onArmed?: (msUntilDeadline: number) => void;
-    /** Called instead of arming when the deadline is already in the past. */
-    onAlreadyPassed?: () => void;
+    /** Called once when the poll is armed, with ms until the deadline (null when
+     * no deadline is configured yet). */
+    onArmed?: (msUntilDeadline: number | null) => void;
+    /** Called when consecutive ticks are separated by far more than pollMs — the
+     * process was suspended (lid close / sleep) and just resumed. */
+    onWake?: (gapMs: number) => void;
 }
 /**
- * Arm a poll that fires `onFire` once when `now() >= deadline`.
- * Returns a handle to stop the poll, or `null` if the deadline had already
- * passed at arm time (in which case `onAlreadyPassed` is called and nothing is
- * scheduled — the server-side deadline path owns that case).
+ * Arm a poll that calls `onDue` on every tick where `now() >= getDeadline()`.
+ * Always arms, even when the deadline is currently null or already past: a
+ * null deadline can become real via server sync, and a watcher restarted
+ * after the deadline should still hand the (server-verified) recovery
+ * decision to the controller instead of silently skipping.
  */
-export declare function armDeadlineAutoSubmit(opts: ArmDeadlineOptions): DeadlinePollHandle | null;
+export declare function armDeadlinePoll(opts: DeadlinePollOptions): DeadlinePollHandle;
+/** Outcome of asking the server for the authoritative times. */
+export type VerifyTimesResult = 
+/** Server answered; times were synced by the caller. `effectiveDeadline` is
+ * the post-sync effective deadline (epoch ms) or null. */
+{
+    status: "ok";
+    effectiveDeadline: number | null;
+}
+/** Network error / 5xx — transient; try again shortly. */
+ | {
+    status: "unavailable";
+}
+/** 4xx — the token was refused (session likely over). Do not submit; the
+ * activity-upload path independently shuts the watcher down on
+ * "Session over". */
+ | {
+    status: "rejected";
+};
+export interface AutoSubmitOutcome {
+    kind: "submitted" | "failed" | "averted" | "deferred" | "exhausted";
+    /** 1-based attempt number for submitted/failed. */
+    attempt?: number;
+    detail?: string;
+}
+export interface AutoSubmitControllerOptions {
+    /** Fetch authoritative times from the server AND apply them locally
+     * (config + poll getter). Must not throw. */
+    verifyTimes: () => Promise<VerifyTimesResult>;
+    /** Run `litmus submit --yes`. Must not throw. */
+    runSubmit: () => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    onOutcome?: (outcome: AutoSubmitOutcome) => void;
+    now?: () => number;
+    /** Verified-due submit attempts before giving up (server cron owns the
+     * session after that). */
+    maxAttempts?: number;
+    /** Backoff after a failed submit attempt; last entry repeats. */
+    retryBackoffMs?: number[];
+    /** Re-check cadence while the server is unreachable at the deadline. */
+    verifyRetryMs?: number;
+}
+export interface AutoSubmitController {
+    /** Called by the poll on every due tick. Serialized internally. */
+    handleDue(): Promise<void>;
+    /** Called when a server sync moved the deadline. A deadline now in the
+     * future resets the attempt budget — the earlier failures belonged to a
+     * cutoff that no longer exists. */
+    noteDeadlineChanged(newDeadlineMs: number | null): void;
+    /** External signal that the session is over (e.g. upload path saw
+     * "Session over") — stop attempting. */
+    markDone(): void;
+}
+export declare function createAutoSubmitController(opts: AutoSubmitControllerOptions): AutoSubmitController;
 //# sourceMappingURL=deadline.d.ts.map

package/dist/lib/deadline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/lib/deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,kBAAkB;IACjC,IAAI,IAAI,IAAI,CAAA;CACb;AAED,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAA;IAChB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,iEAAiE;IACjE,OAAO,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3C,yEAAyE;IACzE,eAAe,CAAC,EAAE,MAAM,IAAI,CAAA;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,GAAG,IAAI,CAuBzF"}
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/lib/deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,kBAAkB;IACjC,IAAI,IAAI,IAAI,CAAA;CACb;AAED;2BAC2B;AAC3B,eAAO,MAAM,eAAe,QAAa,CAAA;AAEzC,MAAM,WAAW,mBAAmB;IAClC;4EACwE;IACxE,WAAW,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IAChC,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,0EAA0E;IAC1E,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB;yCACqC;IACrC,OAAO,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAClD;qEACiE;IACjE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,kBAAkB,CAuB7E;AAED,gEAAgE;AAChE,MAAM,MAAM,iBAAiB;AAC3B;0DAC0D;AACxD;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;AACpD,0DAA0D;GACxD;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE;AAC3B;;qBAEqB;GACnB;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAA;AAE1B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAA;IACnE,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,2BAA2B;IAC1C;iDAC6C;IAC7C,WAAW,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC7C,iDAAiD;IACjD,SAAS,EAAE,MAAM,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACzD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB;8BAC0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B;;uCAEmC;IACnC,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IACvD;4CACwC;IACxC,QAAQ,IAAI,IAAI,CAAA;CACjB;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,2BAA2B,GAAG,oBAAoB,CA6ElG"}

package/dist/lib/deadline.js

@@ -9,32 +9,127 @@
  * wake: the interval also pauses while suspended, but the first tick after
  * resume sees that wall-clock has passed the deadline and fires immediately.
  * Polling additionally sidesteps the ~24.8-day `setTimeout` ceiling.
+ *
+ * Two pieces (ENG-1489 / ENG-1490):
+ *
+ * - `armDeadlinePoll` — the dumb wall-clock poll. It reads the CURRENT
+ *   deadline through a getter on every tick, because the deadline can move
+ *   mid-session (server-side extensions and corrections arrive via the
+ *   heartbeat response). It never latches and never clears itself on fire —
+ *   dedupe, retries, and the fire decision live in the controller.
+ *
+ * - `createAutoSubmitController` — the fire decision. It never submits on
+ *   local state alone: every attempt re-verifies the deadline against the
+ *   server first. A stale-early local deadline that fires "successfully" is
+ *   strictly worse than one that fails — the server, which believes the
+ *   deadline is still hours or days away, accepts the upload as an ordinary
+ *   early submission and the candidate's session ends prematurely. The
+ *   verification is what makes retrying safe at all.
  */
+/** Tick gaps beyond this are reported as a suspend/resume (wake) even when the
+ * poll cadence is long. */
+export const WAKE_GAP_MIN_MS = 2 * 60000;
 /**
- * Arm a poll that fires `onFire` once when `now() >= deadline`.
- * Returns a handle to stop the poll, or `null` if the deadline had already
- * passed at arm time (in which case `onAlreadyPassed` is called and nothing is
- * scheduled — the server-side deadline path owns that case).
+ * Arm a poll that calls `onDue` on every tick where `now() >= getDeadline()`.
+ * Always arms, even when the deadline is currently null or already past: a
+ * null deadline can become real via server sync, and a watcher restarted
+ * after the deadline should still hand the (server-verified) recovery
+ * decision to the controller instead of silently skipping.
  */
-export function armDeadlineAutoSubmit(opts) {
+export function armDeadlinePoll(opts) {
     const now = opts.now ?? Date.now;
-    if (now() >= opts.deadline) {
-        opts.onAlreadyPassed?.();
-        return null;
-    }
-    opts.onArmed?.(opts.deadline - now());
-    let fired = false;
+    const initial = opts.getDeadline();
+    opts.onArmed?.(initial === null ? null : initial - now());
+    let lastTick = now();
     const timer = setInterval(() => {
-        if (fired)
-            return;
-        if (now() >= opts.deadline) {
-            fired = true;
-            clearInterval(timer);
-            opts.onFire();
+        const t = now();
+        const gap = t - lastTick;
+        lastTick = t;
+        if (gap > Math.max(opts.pollMs * 4, WAKE_GAP_MIN_MS)) {
+            opts.onWake?.(gap);
+        }
+        const deadline = opts.getDeadline();
+        if (deadline !== null && t >= deadline) {
+            opts.onDue();
         }
     }, opts.pollMs);
     // Intentionally NOT unref()'d: the watcher should stay alive to fire the
     // auto-submit even if every other keep-alive source went quiet.
     return { stop: () => clearInterval(timer) };
 }
+export function createAutoSubmitController(opts) {
+    const now = opts.now ?? Date.now;
+    const maxAttempts = opts.maxAttempts ?? 3;
+    const backoffs = opts.retryBackoffMs ?? [60000, 5 * 60000];
+    const verifyRetryMs = opts.verifyRetryMs ?? 2 * 60000;
+    let state = "idle";
+    let attempts = 0;
+    let gateUntil = 0;
+    let exhaustedReported = false;
+    async function handleDue() {
+        if (state !== "idle")
+            return;
+        if (now() < gateUntil)
+            return;
+        if (attempts >= maxAttempts) {
+            if (!exhaustedReported) {
+                exhaustedReported = true;
+                opts.onOutcome?.({ kind: "exhausted", attempt: attempts });
+            }
+            return;
+        }
+        state = "in_flight";
+        try {
+            const verdict = await opts.verifyTimes();
+            if (verdict.status === "unavailable") {
+                // Can't verify ⇒ can't safely submit (and an upload would almost
+                // certainly fail on the same dead network). Doesn't burn an attempt:
+                // a machine that wakes offline must still submit when the network
+                // returns, however long that takes.
+                gateUntil = now() + verifyRetryMs;
+                opts.onOutcome?.({ kind: "deferred", detail: "server unreachable for deadline verification" });
+                return;
+            }
+            if (verdict.status === "rejected") {
+                gateUntil = now() + verifyRetryMs * 5;
+                opts.onOutcome?.({ kind: "deferred", detail: "server rejected deadline verification" });
+                return;
+            }
+            if (verdict.effectiveDeadline === null || now() < verdict.effectiveDeadline) {
+                // The local deadline was stale-early — the sync inside verifyTimes
+                // already re-armed the poll with the server's value. This is the
+                // protective path: without it, a submit here would have been
+                // ACCEPTED by the server as an ordinary early submission.
+                opts.onOutcome?.({ kind: "averted" });
+                return;
+            }
+            attempts += 1;
+            const res = await opts.runSubmit();
+            if (res.ok) {
+                state = "done";
+                opts.onOutcome?.({ kind: "submitted", attempt: attempts });
+                return;
+            }
+            gateUntil = now() + backoffs[Math.min(attempts - 1, backoffs.length - 1)];
+            opts.onOutcome?.({ kind: "failed", attempt: attempts, detail: res.error });
+        }
+        finally {
+            if (state === "in_flight")
+                state = "idle";
+        }
+    }
+    function noteDeadlineChanged(newDeadlineMs) {
+        if (state === "done")
+            return;
+        if (newDeadlineMs !== null && newDeadlineMs > now()) {
+            attempts = 0;
+            gateUntil = 0;
+            exhaustedReported = false;
+        }
+    }
+    function markDone() {
+        state = "done";
+    }
+    return { handleDue, noteDeadlineChanged, markDone };
+}
 //# sourceMappingURL=deadline.js.map

package/dist/lib/deadline.js.map

@@ -1 +1 @@
-{"version":3,"file":"deadline.js","sourceRoot":"","sources":["../../src/lib/deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAqBH;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAwB;IAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAA;IAEhC,IAAI,GAAG,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,eAAe,EAAE,EAAE,CAAA;QACxB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC,CAAA;IAErC,IAAI,KAAK,GAAG,KAAK,CAAA;IACjB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,IAAI,KAAK;YAAE,OAAM;QACjB,IAAI,GAAG,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3B,KAAK,GAAG,IAAI,CAAA;YACZ,aAAa,CAAC,KAAK,CAAC,CAAA;YACpB,IAAI,CAAC,MAAM,EAAE,CAAA;QACf,CAAC;IACH,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IACf,yEAAyE;IACzE,gEAAgE;IAEhE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAA;AAC7C,CAAC"}
+{"version":3,"file":"deadline.js","sourceRoot":"","sources":["../../src/lib/deadline.ts"],"names":[],"mappings":"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"}

package/dist/lib/detect-project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect-project.d.ts","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,QAAQ,GACR,MAAM,GACN,MAAM,GACN,KAAK,GACL,SAAS,CAAA;AAEb,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,SAAS,CAAA;AA0D5C;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,OAAO,CAAA;IACtB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B,CAkBA;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAwEtD"}
+{"version":3,"file":"detect-project.d.ts","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,QAAQ,GACR,IAAI,GACJ,MAAM,GACN,QAAQ,GACR,MAAM,GACN,MAAM,GACN,KAAK,GACL,SAAS,CAAA;AAEb,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,SAAS,CAAA;AA0D5C;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,OAAO,CAAA;IACtB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B,CAkBA;AAyBD;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAmGtD"}

package/dist/lib/detect-project.js

@@ -92,6 +92,27 @@ export function resolvePythonInterpreter() {
     const last = candidates[candidates.length - 1];
     return { command: last.command, matchesGrader: false, detectedVersion: null };
 }
+/**
+ * Is `bin` runnable from PATH?
+ *
+ * `--version` rather than `which`/`where`: one probe that works on all three
+ * platforms, and it proves the binary actually EXECUTES. A PATH entry pointing at
+ * a broken install or the wrong architecture resolves fine and then fails on use,
+ * which is the case a warning most needs to catch. `shell: true` on Windows so
+ * `.cmd`/`.ps1` shims resolve, matching the Python probe above.
+ */
+function isOnPath(bin) {
+    try {
+        return (spawnSync(bin, ["--version"], {
+            encoding: "utf8",
+            shell: process.platform === "win32",
+        }).status === 0);
+    }
+    catch {
+        // spawnSync throws (rather than returning a status) on some ENOENT paths.
+        return false;
+    }
+}
 /**
  * Detect project type and suggest an install command.
  */
@@ -99,12 +120,37 @@ export function detectProject(dir) {
     if (existsSync(path.join(dir, "package.json"))) {
         const hasYarnLock = existsSync(path.join(dir, "yarn.lock"));
         const hasPnpmLock = existsSync(path.join(dir, "pnpm-lock.yaml"));
+        // A bun lockfile has to steer this, not just be tolerated. `npm install` on a
+        // Bun project does populate node_modules, but it ignores bun.lock and writes a
+        // COMPETING package-lock.json next to it — so the candidate ends up with a tree
+        // resolved fresh from the caret ranges, which is the drift the lockfile exists
+        // to prevent, plus a stray lockfile in their submission.
+        const hasBunLock = existsSync(path.join(dir, "bun.lock")) || existsSync(path.join(dir, "bun.lockb"));
         const installCommand = hasPnpmLock
             ? "pnpm install"
             : hasYarnLock
                 ? "yarn"
-                : "npm install";
-        return { type: "node", installCommand };
+                : hasBunLock
+                    ? "bun install"
+                    : "npm install";
+        // Same disclosure contract as the Python skew below: a missing toolchain is
+        // ours to state here, not theirs to infer. Without this, `init`'s install
+        // failure prints "run `bun install` manually", which is the command that just
+        // failed — and the candidate is left guessing that a runtime they may never
+        // have heard of is the missing piece.
+        //
+        // Gated on the SELECTED command, not on `hasBunLock`. A repo carrying both a
+        // bun lockfile and a pnpm/yarn one resolves to pnpm/yarn above, and telling
+        // that candidate to install Bun and run `bun install` would send them to
+        // install a second, competing dependency tree over the one we just built.
+        // Also means npm/yarn/pnpm repos never pay for the PATH probe.
+        const toolchainWarning = installCommand === "bun install" && !isOnPath("bun")
+            ? "This assessment's scaffold is a Bun project (bun.lock), and Bun isn't on " +
+                "your PATH. Install it from https://bun.sh, then re-run `bun install` in " +
+                "this folder. npm can install the dependencies but cannot run the " +
+                "scaffold's server — it uses Bun-only APIs."
+            : undefined;
+        return { type: "node", installCommand, toolchainWarning };
     }
     if (existsSync(path.join(dir, "requirements.txt")) ||
         existsSync(path.join(dir, "pyproject.toml")) ||

package/dist/lib/detect-project.js.map

@@ -1 +1 @@
-{"version":3,"file":"detect-project.js","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,CAAA;AAC5C,OAAO,IAAI,MAAM,MAAM,CAAA;AAyBvB;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAA;AAS5C;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,gBAAgB;IACvB,MAAM,OAAO,GAAG,sBAAsB,CAAA;IACtC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO;YACL,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,OAAO,EAAE,EAAE;YAC/D,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;YACtC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE;YAC9C,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE;SACjD,CAAA;IACH,CAAC;IACD,OAAO;QACL,EAAE,GAAG,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,OAAO,EAAE,EAAE;QAClE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE;KACjD,CAAA;AACH,CAAC;AAED,2EAA2E;AAC3E,SAAS,YAAY,CAAC,SAA0B;IAC9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE;YACxE,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO;SACpC,CAAC,CAAA;QACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;QACpC,MAAM,KAAK,GAAG,6BAA6B,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC,CAAA;QAChG,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;QACjE,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB;IAKtC,MAAM,UAAU,GAAG,gBAAgB,EAAE,CAAA;IACrC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAA;QAC/C,IAAI,CAAC,eAAe;YAAE,SAAQ;QAC9B,OAAO;YACL,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,wEAAwE;YACxE,mEAAmE;YACnE,sCAAsC;YACtC,aAAa,EAAE,eAAe,CAAC,UAAU,CAAC,GAAG,sBAAsB,GAAG,CAAC;gBACrE,eAAe,KAAK,sBAAsB;YAC5C,eAAe;SAChB,CAAA;IACH,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC9C,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,CAAA;AAC/E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;QAC/C,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAA;QAC3D,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAA;QAChE,MAAM,cAAc,GAAG,WAAW;YAChC,CAAC,CAAC,cAAc;YAChB,CAAC,CAAC,WAAW;gBACX,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,aAAa,CAAA;QACnB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;IACzC,CAAC;IAED,IACE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;QAC9C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;QAC5C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,EACtC,CAAC;QACD,0EAA0E;QAC1E,0EAA0E;QAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,cAAc,CAAA;QACnF,MAAM,MAAM,GAAG,wBAAwB,EAAE,CAAA;QACzC,MAAM,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;YACnE,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,oBAAoB,MAAM,8BAA8B;YAC3E,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,oBAAoB,MAAM,eAAe,CAAA;QAC9D,2EAA2E;QAC3E,yEAAyE;QACzE,yEAAyE;QACzE,4EAA4E;QAC5E,mDAAmD;QACnD,MAAM,gBAAgB,GAAG,MAAM,CAAC,aAAa;YAC3C,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,MAAM,CAAC,eAAe;gBACtB,CAAC,CAAC,uCAAuC,sBAAsB,yBAAyB;oBACtF,UAAU,MAAM,CAAC,eAAe,OAAO,MAAM,CAAC,OAAO,wCAAwC;oBAC7F,oEAAoE;oBACpE,GAAG,sBAAsB,oDAAoD;gBAC/E,CAAC,CAAC,sDAAsD,MAAM,CAAC,OAAO,kBAAkB;oBACtF,sDAAsD,sBAAsB,aAAa;oBACzF,0CAA0C,CAAA;QAChD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;IAC7D,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAA;IAC1D,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,CAAA;IACxD,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC;QACjG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,CAAA;IACzD,CAAC;IAED,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAA;IAC9B,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QACjE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;IAC7D,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,CAAA;IAC/C,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAA;IAC3D,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAA;IAC5D,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,CAAA;AAClD,CAAC"}
+{"version":3,"file":"detect-project.js","sourceRoot":"","sources":["../../src/lib/detect-project.ts"],"names":[],"mappings":"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"}

package/dist/lib/editor.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Opening — and later closing — the candidate's editor on their own machine.
+ *
+ * `litmus init` offers the editors it can actually launch and opens the
+ * assessment in the chosen one; `litmus submit` closes that window again once
+ * the work is in, so the agent chat session that was open against the
+ * assessment ends with the assessment instead of outliving it.
+ *
+ * Closing is best-effort and SILENT. Neither VS Code nor Cursor exposes a
+ * "close this window" command, so every route here is an OS window-manager
+ * trick that can legitimately be unavailable: macOS gates UI scripting behind
+ * Accessibility permission, and a Linux box may have neither wmctrl nor
+ * xdotool. A candidate who has just submitted should not be handed a warning
+ * about a window they can close themselves, so a failure produces no output at
+ * all.
+ */
+export type EditorId = "vscode" | "cursor";
+interface EditorSpec {
+    id: EditorId;
+    label: string;
+    /** Command the editor installs on PATH ("Shell Command: Install ... in PATH"). */
+    cli: string;
+    /** Bundle name under /Applications on macOS. */
+    macApp: string;
+    /** Process name as System Events sees it (NOT the bundle name for VS Code). */
+    macProcess: string;
+    /** Process name for Get-Process on Windows, and the WM_CLASS prefix on Linux. */
+    processName: string;
+}
+export interface DetectedEditor {
+    spec: EditorSpec;
+    /** "cli" launches through the editor's own PATH command; "app" is the macOS
+     *  bundle fallback for candidates who never ran "Install 'code' in PATH". */
+    how: "cli" | "app";
+    appPath?: string;
+}
+/**
+ * The editors we can actually open on this machine, in menu order. An editor
+ * the candidate has installed but never added to PATH still shows up on macOS
+ * (we open the bundle directly) — that gap is common enough with Cursor that
+ * omitting it would hide the option most candidates want.
+ */
+export declare function detectEditors(): DetectedEditor[];
+/**
+ * Open `dir` in the chosen editor. Resolves false only when the launcher itself
+ * is missing — spawn reports that asynchronously via 'error', so we give it a
+ * short grace period rather than reporting success and printing a line that
+ * turns out to be a lie. The editor is detached: it outlives the CLI.
+ */
+export declare function openInEditor(editor: DetectedEditor, dir: string): Promise<boolean>;
+/**
+ * Close every window of `process` whose title mentions `folderName`, by
+ * pressing its close button through the Accessibility API. Editor window titles
+ * carry the workspace folder ("index.ts — acme-backend"), so this hits the
+ * assessment window and leaves the candidate's other projects alone.
+ *
+ * Exported for tests: the escaping is the part worth pinning.
+ */
+export declare function macCloseScript(processName: string, folderName: string): string;
+/**
+ * Windows equivalent. `.Contains` rather than `-like '*x*'` so a folder name
+ * with a wildcard character in it can't widen the match. CloseMainWindow is the
+ * polite close — an editor with unsaved work still gets to prompt.
+ */
+export declare function winCloseScript(processName: string, folderName: string): string;
+/**
+ * Best-effort, silent close of the assessment's editor window. Every failure
+ * mode — no permission, no window manager, editor already quit, window renamed
+ * — is a no-op with no output.
+ */
+export declare function closeEditorWindow(editorId: EditorId, folderName: string): void;
+export {};
+//# sourceMappingURL=editor.d.ts.map

package/dist/lib/editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../../src/lib/editor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE1C,UAAU,UAAU;IAClB,EAAE,EAAE,QAAQ,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAA;IACX,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAA;IACd,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAA;CACpB;AAOD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAA;IAChB;iFAC6E;IAC7E,GAAG,EAAE,KAAK,GAAG,KAAK,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AA0BD;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,cAAc,EAAE,CAWhD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAqBlF;AAYD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAe9E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ9E;AA8CD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAwB9E"}