commandmate 0.29.1 → 0.30.0

package/dist/server/src/lib/verification/run-verdict-vocabulary.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Vocabulary the two Verification surfaces read (Issue #2062).
+ *
+ * Until this Issue the Web UI printed the run and gate statuses as the raw
+ * database tokens — `passed`, `not_started`, `SKIP`, `TIMEOUT` — identically in
+ * both locales, and said nothing about what any of them meant. The words now
+ * live in `locales/{en,ja}/worktree.json`; what lives here is the part that is
+ * *not* wording: which CLI exit code a verdict corresponds to, which gate ids
+ * are built in, and how to read the reason out of a skipped gate's log.
+ *
+ * BROWSER-SAFE ON PURPOSE. `VerificationPane` is a client component, and every
+ * other module in this directory reads the filesystem or the database. This one
+ * imports types only, so it erases out of the browser bundle entirely; a
+ * runtime import of `verify-config.ts` here would drag `fs` and `yaml` in with
+ * it. Keep it that way.
+ *
+ * @module lib/verification/run-verdict-vocabulary
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKIP_LOG_MARKERS = exports.CANCELLED_SKIP_LOG = exports.WORK_EVIDENCE_SKIP_LOG = exports.PRIMARY_CHECKOUT_SKIP_LOG = exports.BUILTIN_GATE_DESCRIPTION_KEYS = exports.LEGEND_RUN_STATUSES = exports.RUN_STATUS_EXIT_CODE = void 0;
+exports.builtinGateDescriptionKey = builtinGateDescriptionKey;
+exports.classifySkipReason = classifySkipReason;
+/**
+ * The process exit code `commandmate verify` reports for each run verdict.
+ *
+ * A mirror of `exitCodeForRunStatus` in `src/cli/utils/verify-runner.ts`, which
+ * the browser cannot import (it wraps `process.exit` and the CLI's HTTP client).
+ * `tests/unit/verification/run-verdict-vocabulary-2062.test.ts` pins the two
+ * together, so the mirror cannot drift silently.
+ *
+ * `running` is `null` rather than a number: a run still in flight has produced
+ * no verdict, so there is no code to report — which is a different statement
+ * from "it produced 0".
+ */
+exports.RUN_STATUS_EXIT_CODE = {
+    running: null,
+    passed: 0,
+    failed: 20,
+    not_started: 21,
+    // `error` and `cancelled` both mean "we could not judge", which the CLI maps
+    // to the generic UNEXPECTED_ERROR rather than to VERIFY_FAILED — a caller
+    // branching on 20 must be able to trust that gates actually ran.
+    error: 99,
+    cancelled: 99,
+};
+/**
+ * Verdicts the pane spells out in its `exit 0 / 20 / 21` legend, in that order.
+ *
+ * `running` is absent because it has no code. `cancelled` was absent for the
+ * same reason it was dead vocabulary in #2062 — nothing could produce one — and
+ * is listed from #2063 on, because the pane now has a Stop button and the
+ * operator who presses it is entitled to know what the CLI would have exited
+ * with. It shares 99 with `error`, which is a fact about the CLI worth stating
+ * rather than hiding: a caller branching on 20 must be able to trust that gates
+ * actually ran, and neither verdict can promise that.
+ */
+exports.LEGEND_RUN_STATUSES = [
+    'passed',
+    'failed',
+    'not_started',
+    'error',
+    'cancelled',
+];
+/**
+ * Built-in gate id → the key segment under `verification.gates.builtin` that
+ * describes it.
+ *
+ * Spelled as data rather than as `t('...' + gateId)` because the ids contain
+ * hyphens and the dictionary keys do not: the mapping is the one place that
+ * knows `work-evidence` is described by `workEvidence`.
+ *
+ * `config` is the pseudo-gate the runner writes when `.commandmate/verify.yaml`
+ * itself could not be read — it is the only row a run in that state has, and
+ * without a description it reads as a gate the repository declared.
+ */
+exports.BUILTIN_GATE_DESCRIPTION_KEYS = {
+    'work-evidence': 'workEvidence',
+    scope: 'scope',
+    'env-clean': 'envClean',
+    config: 'config',
+};
+/** The description key for a built-in gate, or `null` for a declared one. */
+function builtinGateDescriptionKey(gateId) {
+    return exports.BUILTIN_GATE_DESCRIPTION_KEYS[gateId] ?? null;
+}
+/**
+ * Exact `logTail` the runner records for a gate the primary-checkout guard
+ * declined to run.
+ *
+ * Owned here rather than inline in `gate-runner.ts` so the producer and the
+ * reader are the same string. This is the skip that made `skipInPrimaryCheckout`
+ * look like a bug: it turns the run into `error` (see `aggregateRunStatus`),
+ * and until #2062 the pane showed that `error` with no cause at all.
+ */
+exports.PRIMARY_CHECKOUT_SKIP_LOG = 'skipped: worktreePath is the server process working directory and ' +
+    'options.skipInPrimaryCheckout is true.';
+/**
+ * Exact `logTail` the runner records for the gates it leaves unrun once
+ * `work-evidence` has failed. Kept in step with `WORK_EVIDENCE_GATE_ID` by
+ * `tests/unit/verification/run-verdict-vocabulary-2062.test.ts`.
+ */
+exports.WORK_EVIDENCE_SKIP_LOG = 'skipped: the work-evidence gate did not pass.';
+/**
+ * Marker every gate carries once a run was cancelled (Issue #2063).
+ *
+ * One marker for two situations — the gate that was executing when the signal
+ * arrived, and the gates the run never reached — because a reader's question is
+ * the same in both: *why is this row not a verdict?* The sentence that follows
+ * the marker in the log says which of the two it was; the classifier only needs
+ * to recognise that the cause was a cancel and not a declined check.
+ *
+ * Owned here rather than in `gate-runner.ts` so the producer and the pane read
+ * one string, exactly as {@link PRIMARY_CHECKOUT_SKIP_LOG} is. Pinned to its
+ * producer by `tests/unit/verification/gate-cancel-2063.test.ts`.
+ */
+exports.CANCELLED_SKIP_LOG = 'skipped: the verification run was cancelled.';
+/**
+ * Substrings that identify the remaining skip producers.
+ *
+ * Substrings and not whole strings: `scopeSkipDetachedContract` and
+ * `mutexWaitTimeoutLog` interpolate ids, durations and paths, so only the fixed
+ * clause can be matched. Each one is pinned against its producer by the test
+ * named above, so a reworded producer fails there instead of silently falling
+ * through to the generic reason.
+ */
+exports.SKIP_LOG_MARKERS = {
+    mutex: 'reason=mutex-wait',
+    detachedContract: 'was NOT judged',
+    noContract: 'no contract is attached to this run',
+    notRequired: 'success.requireScopeClean: false',
+};
+/** Read the reason a `skipped` gate carries in its log tail. */
+function classifySkipReason(logTail) {
+    const log = logTail ?? '';
+    if (log.includes(exports.PRIMARY_CHECKOUT_SKIP_LOG))
+        return 'primaryCheckout';
+    if (log.includes(exports.WORK_EVIDENCE_SKIP_LOG))
+        return 'workEvidence';
+    if (log.includes(exports.CANCELLED_SKIP_LOG))
+        return 'cancelled';
+    if (log.includes(exports.SKIP_LOG_MARKERS.mutex))
+        return 'mutex';
+    if (log.includes(exports.SKIP_LOG_MARKERS.detachedContract))
+        return 'detachedContract';
+    if (log.includes(exports.SKIP_LOG_MARKERS.noContract))
+        return 'noContract';
+    if (log.includes(exports.SKIP_LOG_MARKERS.notRequired))
+        return 'notRequired';
+    return 'unknown';
+}

package/dist/server/src/lib/verification/verify-config.js

@@ -9,6 +9,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VerifyConfigError = exports.MAX_RETRY_ON_FAIL = exports.MAX_GATE_MUTEX_LENGTH = exports.GATE_MUTEX_PATTERN = exports.GATE_ID_PATTERN = exports.DEFAULT_MAX_LOG_TAIL_BYTES = exports.DEFAULT_TIMEOUT_SEC = exports.VERIFY_CONFIG_RELATIVE_PATH = exports.RESERVED_GATE_IDS = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
+exports.defaultPlannedGateIds = defaultPlannedGateIds;
 exports.validateGateEntries = validateGateEntries;
 exports.loadVerifyConfig = loadVerifyConfig;
 const fs_1 = require("fs");
@@ -42,6 +43,38 @@ exports.RESERVED_GATE_IDS = [
     exports.ENV_CLEAN_GATE_ID,
 ];
 exports.VERIFY_CONFIG_RELATIVE_PATH = '.commandmate/verify.yaml';
+/**
+ * Gate ids a default full run executes, in the order the runner records them
+ * (Issue #2061).
+ *
+ * The Verification pane needs a denominator while a run is in flight — gate
+ * rows are created as each gate starts, so "3 gates recorded" is progress, not
+ * a total. Declared here rather than in the pane because the composition is the
+ * runner's: `work-evidence`, then `scope`, then `env-clean` only when a
+ * declaration switched it on, then verify.yaml's own gates in file order.
+ *
+ * A *default* run, which is what the pane's "run verification" button starts.
+ * A run narrowed with `--gates` / `gateIds` executes a subset of this.
+ *
+ * @param contractGates gate definitions the worktree's execution contract
+ *        carries (#1791). They run after verify.yaml's, exactly as
+ *        `declaredGates()` orders them, and leaving them out understated both
+ *        the pane's progress denominator and — since #2063 made the list
+ *        selectable — which gates an operator is allowed to re-run: a run whose
+ *        only failure was a contract gate offered nothing to re-run at all.
+ */
+function defaultPlannedGateIds(config, contractGates = []) {
+    return [
+        exports.WORK_EVIDENCE_GATE_ID,
+        exports.SCOPE_GATE_ID,
+        ...(config.options.requireEnvClean ? [exports.ENV_CLEAN_GATE_ID] : []),
+        ...config.gates.map((gate) => gate.id),
+        // A contract gate whose id collides with verify.yaml is refused at send
+        // (#1791) and the runner refuses it again, so no de-duplication is needed
+        // here; a duplicate id would be a bug worth seeing rather than hiding.
+        ...contractGates.map((gate) => gate.id),
+    ];
+}
 exports.DEFAULT_TIMEOUT_SEC = 600;
 exports.DEFAULT_MAX_LOG_TAIL_BYTES = 8192;
 const MIN_TIMEOUT_SEC = 1;

package/dist/server/src/lib/ws-server.js

@@ -34,12 +34,24 @@ const cache_1 = require("./external-apps/cache");
 const version_checker_1 = require("../lib/version-checker");
 const types_2 = require("../lib/realtime/types");
 const waiting_broadcast_1 = require("../lib/realtime/waiting-broadcast");
+// Issue #2220: this module's `rooms` is per module instance, and a production
+// build has two instances of it (`dist/server` + a `.next/server/chunks` copy).
+// The registry is how a route handler's copy reaches the one holding sockets.
+const publisher_registry_1 = require("../lib/realtime/publisher-registry");
 const logger_1 = require("../lib/logger");
 const logger = (0, logger_1.createLogger)('ws-server');
 // Global state
 let wss = null;
 const clients = new Map();
 const rooms = new Map();
+/**
+ * This instance's claim on the process's rooms, or null when it never called
+ * `setupWebSocket` (every route bundle) or has already withdrawn.
+ *
+ * Issue #2220: held so `closeWebSocket` can present the token it was given. A
+ * bare "clear the registry" would let a torn-down instance silence a newer one.
+ */
+let publisherHandle = null;
 const MAX_TERMINAL_INPUT_LENGTH = 4096;
 const MAX_TERMINAL_SUBSCRIBERS_PER_SESSION = 4;
 const TERMINAL_FALLBACK_CAPTURE_LINES = -200;
@@ -237,6 +249,13 @@ function isExpectedWebSocketError(error) {
  */
 function setupWebSocket(server) {
     wss = new ws_1.WebSocketServer({ noServer: true });
+    // Issue #2220: this instance now owns the sockets, so publish the capability
+    // the other module instances have to borrow. Registered before anything can
+    // subscribe, and only from here — `setupWebSocket` is the one function that
+    // makes a `rooms` map real, so it is the one function allowed to claim the
+    // registry. Everything the registry hands out is a closure over the maps
+    // below; the maps themselves never leave this module.
+    publisherHandle = (0, publisher_registry_1.registerRoomPublisher)(localRoomPublisher);
     // Issue #1788: publish the waiting edge to the worktree room. Started here
     // rather than at module scope so the listener's lifetime matches the server's
     // — and so the closure it registers is the one holding *this* bundle's `rooms`
@@ -711,6 +730,66 @@ async function handleTerminalUnsubscribe(ws) {
     clientInfo.terminalSubscription = null;
     sendTerminalEvent(ws, { type: 'terminal_status', connected: false });
 }
+// ---------------------------------------------------------------------------
+// Issue #2220: cross-instance routing
+//
+// Everything below the line reads `rooms` / `clients`; everything above the
+// public API forwards to whichever module instance actually has them. The four
+// exported entry points (`broadcast`, `hasRoomSubscribers`, `cleanupRooms`,
+// `migrateWorktreeRooms`) keep their signatures, so no producer had to change:
+// a route handler importing `broadcastMessage` from this module now lands on
+// the custom server's sockets without knowing it crossed a bundle.
+//
+// (Spelling that import out as source text here would be a mistake: the cycle
+// guard in tests/unit/guards/no-ws-server-manager-cycle-1984.test.ts parses
+// comments too, and reads a specifier in one as a real edge.)
+// ---------------------------------------------------------------------------
+/** {@link hasRoomSubscribers} against *this* instance's maps. */
+function hasLocalRoomSubscribers(worktreeId) {
+    const room = rooms.get(worktreeId);
+    return !!room && room.size > 0;
+}
+/**
+ * This instance's capability, as published to the registry.
+ *
+ * Identity matters, not just shape: {@link remoteRoomPublisher} compares
+ * against this exact object to tell "someone else owns the sockets" from "I do".
+ * Without that check the owner would forward to itself and recurse.
+ */
+const localRoomPublisher = {
+    publish: handleBroadcast,
+    hasSubscribers: hasLocalRoomSubscribers,
+    cleanupRooms: cleanupLocalRooms,
+    migrateRooms: migrateLocalWorktreeRooms,
+};
+/**
+ * The owning instance's publisher, when that instance is not this one.
+ *
+ * Returns null in the two cases where the local maps are already the right
+ * target: this instance is the owner, or nothing has claimed the rooms at all
+ * (a unit test that never stood a server up, or the CLI). The second case
+ * preserves the pre-#2220 behaviour exactly — an unowned publish still writes
+ * to whatever the caller's own `rooms` holds, rather than becoming a hard
+ * failure.
+ */
+function remoteRoomPublisher() {
+    const publisher = (0, publisher_registry_1.getRoomPublisher)();
+    return publisher && publisher !== localRoomPublisher ? publisher : null;
+}
+/**
+ * Report the one state in which a frame is silently lost: nobody owns the rooms
+ * and this instance has none of its own.
+ *
+ * Deliberately not "the room was empty" — an empty room is the normal answer
+ * for a worktree nobody has open. This is narrower and always a defect: it says
+ * the process has no publisher, which is what #2220 looked like from the
+ * outside while every browser still reported its socket as `connected`.
+ */
+function noteIfUnroutable(operation, worktreeId) {
+    if ((0, publisher_registry_1.getRoomPublisher)() === null && rooms.size === 0) {
+        (0, publisher_registry_1.recordUnroutedPublish)(operation, worktreeId);
+    }
+}
 /**
  * Broadcast message to a specific worktree room (for API use)
  *
@@ -723,6 +802,12 @@ async function handleTerminalUnsubscribe(ws) {
  * ```
  */
 function broadcast(worktreeId, data) {
+    const owner = remoteRoomPublisher();
+    if (owner) {
+        owner.publish(worktreeId, data);
+        return;
+    }
+    noteIfUnroutable('broadcast', worktreeId);
     handleBroadcast(worktreeId, data);
 }
 /**
@@ -731,11 +816,20 @@ function broadcast(worktreeId, data) {
  * Issue #1120: lets the server-side terminal streamer skip the (relatively
  * expensive) tmux capture + detection work when nobody is watching the room.
  *
+ * Issue #2220: bridged as well, and not as an afterthought.
+ * `broadcastTerminalSnapshot` and `emitChatTurnProgress` call this *first* and
+ * return early on `false`, so a caller reading its own empty `rooms` never
+ * reaches the publish at all — bridging only `broadcast` would have left the
+ * terminal snapshot and `chat_turn_progress` exactly as broken as before.
+ *
  * @param worktreeId - Worktree identifier
  */
 function hasRoomSubscribers(worktreeId) {
-    const room = rooms.get(worktreeId);
-    return !!room && room.size > 0;
+    const owner = remoteRoomPublisher();
+    if (owner)
+        return owner.hasSubscribers(worktreeId);
+    noteIfUnroutable('hasRoomSubscribers', worktreeId);
+    return hasLocalRoomSubscribers(worktreeId);
 }
 /**
  * Broadcast message with type to a specific worktree room
@@ -750,7 +844,10 @@ function hasRoomSubscribers(worktreeId) {
  */
 function broadcastMessage(type, data) {
     if (data.worktreeId) {
-        handleBroadcast(data.worktreeId, { type, ...data });
+        // Issue #2220: through `broadcast`, not straight into `handleBroadcast` —
+        // this is the entry point every history producer uses, and it was the one
+        // reaching the caller's own empty `rooms`.
+        broadcast(data.worktreeId, { type, ...data });
     }
     else {
         logger.warn('broadcast:missing-worktree-id');
@@ -789,10 +886,22 @@ exports.WORKTREE_RENAMED_EVENT_TYPE = 'worktree_renamed';
  * already exists the two sets are merged rather than replaced — dropping the
  * incumbent subscribers would silence clients that did nothing wrong.
  *
+ * Issue #2220: bridged like the publish paths. A rename is applied from
+ * `/worktrees` and from the repository routes, i.e. from a bundle that owns no
+ * rooms; migrating only the caller's own empty map would leave the live
+ * subscribers stranded under the old key and silence them for good.
+ *
  * @param renames - Worktree ID pairs being applied
  * @returns The pairs that actually had room subscribers to move
  */
 function migrateWorktreeRooms(renames) {
+    const owner = remoteRoomPublisher();
+    if (owner)
+        return owner.migrateRooms(renames);
+    return migrateLocalWorktreeRooms(renames);
+}
+/** {@link migrateWorktreeRooms} against *this* instance's maps. */
+function migrateLocalWorktreeRooms(renames) {
     const targets = new Map();
     for (const { oldId, newId } of renames) {
         if (!oldId || !newId || oldId === newId)
@@ -861,6 +970,10 @@ function migrateWorktreeRooms(renames) {
  * Clean up WebSocket rooms for deleted worktrees
  * Removes rooms from the rooms map (clients will naturally disconnect or resubscribe)
  *
+ * Issue #2220: bridged. `/repositories` DELETE is the main caller and runs in a
+ * route bundle, so before the bridge it swept a map that was empty anyway and
+ * the owner kept the rooms of deleted worktrees for the life of the process.
+ *
  * @param worktreeIds - Array of worktree IDs to clean up
  *
  * @example
@@ -869,6 +982,15 @@ function migrateWorktreeRooms(renames) {
  * ```
  */
 function cleanupRooms(worktreeIds) {
+    const owner = remoteRoomPublisher();
+    if (owner) {
+        owner.cleanupRooms(worktreeIds);
+        return;
+    }
+    cleanupLocalRooms(worktreeIds);
+}
+/** {@link cleanupRooms} against *this* instance's maps. */
+function cleanupLocalRooms(worktreeIds) {
     for (const worktreeId of worktreeIds) {
         const room = rooms.get(worktreeId);
         if (room) {
@@ -890,9 +1012,24 @@ function cleanupRooms(worktreeIds) {
  * Used for testing and graceful shutdown
  */
 function closeWebSocket() {
-    // Issue #1788: drop the waiting-edge subscription first — it outlives `wss`
-    // otherwise, and CI shares one process across the whole suite.
-    (0, waiting_broadcast_1.stopWaitingStatusBroadcast)();
+    // Issue #2220: hand back the token rather than clearing the registry, and read
+    // the answer. If a newer `setupWebSocket` has already taken over — HMR, or a
+    // suite standing a second server up — this instance is not the owner any more,
+    // the withdrawal is declined, and the live publisher stays in place.
+    const wasOwner = publisherHandle !== null && publisherHandle.unregister();
+    publisherHandle = null;
+    // Issue #1788: drop the waiting-edge subscription before `wss` goes, or it
+    // outlives the server and CI shares one process across the whole suite.
+    //
+    // Issue #2220: but only when this instance was the owner, or when nobody is.
+    // That subscription is a single `globalThis` slot by design, so a superseded
+    // instance closing down would otherwise take the *running* server's waiting
+    // edge with it — the same hazard the token guard above exists for. The
+    // "nobody owns it" arm keeps the defensive teardown that suites rely on when
+    // they start a subscription by hand and never call `setupWebSocket`.
+    if (wasOwner || (0, publisher_registry_1.getRoomPublisher)() === null) {
+        (0, waiting_broadcast_1.stopWaitingStatusBroadcast)();
+    }
     if (wss) {
         // Close all client connections
         clients.forEach((clientInfo) => {