commandmate 0.22.1 → 0.23.0

package/dist/server/src/lib/hooks/sources/opencode/ports.js

@@ -0,0 +1,295 @@
+"use strict";
+/**
+ * Which port each opencode instance's server listens on (Issue #1763).
+ *
+ * ## Why CommandMate assigns the port instead of reading it
+ *
+ * `opencode --help` calls `--port` "default: 0" and 0 looks like "ask the OS
+ * for a free port". It is not. #1758 §5.9.1 measured it: the first server took
+ * **4096**, and only the second — finding 4096 taken — fell through to an
+ * ephemeral port (58153). So under `--port 0`, several instances land on
+ * unpredictable numbers.
+ *
+ * And the port cannot be read back. §5.9.2 searched an isolated `HOME` after a
+ * launch and found no port file, no lock file and no pid file; the only two
+ * ways to learn it are the one stdout line (behind a stderr warning, from a
+ * process running inside a tmux pane) and `lsof`. Both are worse than deciding
+ * the number in the first place, so CommandMate does — which also removes the
+ * "two owners of one port" problem the Issue worried about, because there is
+ * only ever one owner.
+ *
+ * ## Why the assignment is written to disk
+ *
+ * A CommandMate restart loses in-memory state while the pane keeps running, so
+ * without a record the still-live server on port N is unreachable — the
+ * subscription would never come back and the session would silently drop to the
+ * scraper for the rest of its life. Re-deriving the port from a hash is not
+ * enough: two instances whose hashes collide are allocated *different* ports
+ * (the second scans forward), and after a restart both would re-derive the same
+ * first candidate and one would attach to the other's server. Events would then
+ * be filed against the wrong worktree, silently. The file records what was
+ * actually allocated, so recovery reads rather than guesses.
+ *
+ * Entries are verified before use: a port is only recovered when something
+ * answers `/global/health` as opencode, and when the recorded worktree still
+ * matches. A stale entry costs one failed health check.
+ *
+ * ## Range
+ *
+ * Deliberately not 3000-3100 (CommandMate's own servers, `--auto-port`) and
+ * deliberately not 4096 (opencode's own first choice, which a hand-started
+ * `opencode serve` will take).
+ *
+ * @module lib/hooks/sources/opencode/ports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_PORT_RANGE = void 0;
+exports.getOpencodePortFilePath = getOpencodePortFilePath;
+exports.readPersistedOpencodePorts = readPersistedOpencodePorts;
+exports.getAssignedOpencodePort = getAssignedOpencodePort;
+exports.rememberOpencodePort = rememberOpencodePort;
+exports.forgetOpencodePort = forgetOpencodePort;
+exports.isPortFree = isPortFree;
+exports.derivePortStart = derivePortStart;
+exports.opencodePortCandidates = opencodePortCandidates;
+exports.allocateOpencodePort = allocateOpencodePort;
+exports.recoverOpencodePort = recoverOpencodePort;
+exports.resetOpencodePortAssignments = resetOpencodePortAssignments;
+const net_1 = require("net");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const safe_directory_1 = require("../../../../config/safe-directory");
+const auto_yes_state_1 = require("../../../../lib/auto-yes-state");
+const hook_settings_generator_1 = require("../../../../lib/hooks/hook-settings-generator");
+const logger_1 = require("../../../../lib/logger");
+const client_1 = require("./client");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/ports');
+/** The window opencode instances are placed in. 100 ports, one per instance. */
+exports.OPENCODE_PORT_RANGE = { min: 4200, max: 4299 };
+/** How many candidates a scan will try before giving up. */
+const PORT_SPAN = exports.OPENCODE_PORT_RANGE.max - exports.OPENCODE_PORT_RANGE.min + 1;
+const assignments = (globalThis.__opencodePortAssignments ??= new Map());
+function keyOf(target) {
+    return (0, auto_yes_state_1.buildCompositeKey)(target.worktreeId, target.cliToolId, target.instanceId);
+}
+/**
+ * Where the assignments are persisted. `CM_OPENCODE_PORT_FILE` overrides.
+ *
+ * Issue #1774: `writePersistedOpencodePorts` creates this file's directory with
+ * a recursive mkdir. For a path inside `/proc`, `/sys` or `/dev` that call does
+ * not throw — it spins the event loop forever, so the `try/catch` around it
+ * never runs. A file path is checked the same way a directory is (the match is
+ * on the prefix), so the override is refused here and the default is used.
+ */
+function getOpencodePortFilePath() {
+    const fallback = (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'opencode-ports.json');
+    return (0, safe_directory_1.resolveSafeDirectory)(process.env.CM_OPENCODE_PORT_FILE, fallback, 'CM_OPENCODE_PORT_FILE');
+}
+function isAssignment(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return (typeof record.port === 'number' &&
+        Number.isInteger(record.port) &&
+        record.port > 0 &&
+        record.port < 65536 &&
+        typeof record.worktreePath === 'string');
+}
+/** Read the persisted assignments. Never throws — a bad file means "none". */
+function readPersistedOpencodePorts() {
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(getOpencodePortFilePath(), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return {};
+        const result = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (isAssignment(value)) {
+                result[key] = {
+                    port: value.port,
+                    worktreePath: value.worktreePath,
+                    updatedAt: typeof value.updatedAt === 'number' ? value.updatedAt : 0,
+                };
+            }
+        }
+        return result;
+    }
+    catch {
+        // Absent on a first run, unreadable if somebody edited it. Both mean the
+        // same thing to a caller: nothing to recover.
+        return {};
+    }
+}
+/** Write the assignments back. Never throws — losing the file costs recovery. */
+function writePersistedOpencodePorts(all) {
+    const path = getOpencodePortFilePath();
+    try {
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(path), { recursive: true });
+        (0, fs_1.writeFileSync)(path, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+    }
+    catch (error) {
+        logger.warn('opencode-port-file-write-failed', {
+            path,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/** The port assigned to this instance in this process, or null. */
+function getAssignedOpencodePort(target) {
+    return assignments.get(keyOf(target))?.port ?? null;
+}
+/** Record an assignment in memory and on disk. */
+function rememberOpencodePort(target, port, worktreePath, at = Date.now()) {
+    const key = keyOf(target);
+    const assignment = { port, worktreePath, updatedAt: at };
+    assignments.set(key, assignment);
+    const all = readPersistedOpencodePorts();
+    all[key] = assignment;
+    writePersistedOpencodePorts(all);
+}
+/** Drop an assignment from memory and disk. Called when the pane is killed. */
+function forgetOpencodePort(target) {
+    const key = keyOf(target);
+    assignments.delete(key);
+    const all = readPersistedOpencodePorts();
+    if (key in all) {
+        delete all[key];
+        writePersistedOpencodePorts(all);
+    }
+}
+/**
+ * Whether nothing is listening on a port.
+ *
+ * Binds and immediately closes, which is the only answer that is true at the
+ * moment it is given. `EADDRINUSE` — and anything else — reads as "not free".
+ */
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = (0, net_1.createServer)();
+        server.once('error', () => resolve(false));
+        // Bound on the loopback interface — the one opencode itself will bind.
+        server.listen(port, client_1.OPENCODE_SERVER_HOST, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+/**
+ * Where a given instance starts scanning.
+ *
+ * FNV-1a over the composite key, so the same instance prefers the same port
+ * across restarts and two instances rarely start at the same number. It is a
+ * preference, not an identity: {@link allocateOpencodePort} scans forward and
+ * the result is recorded, precisely because a hash can collide.
+ */
+function derivePortStart(key) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < key.length; index += 1) {
+        hash ^= key.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return exports.OPENCODE_PORT_RANGE.min + (hash % PORT_SPAN);
+}
+/** The candidate ports for one instance, in the order they are tried. */
+function opencodePortCandidates(target) {
+    const start = derivePortStart(keyOf(target));
+    const candidates = [];
+    for (let offset = 0; offset < PORT_SPAN; offset += 1) {
+        candidates.push(exports.OPENCODE_PORT_RANGE.min + ((start - exports.OPENCODE_PORT_RANGE.min + offset) % PORT_SPAN));
+    }
+    return candidates;
+}
+/**
+ * Pick the port this instance's TUI will be launched on.
+ *
+ * Must be called *before* the launch command is built, because
+ * `prepareLaunch` is synchronous and reads the result.
+ *
+ * @param target - The instance about to start
+ * @param worktreePath - Recorded so a recovered entry can be checked
+ * @returns The port, or null when structured events are switched off
+ *   (`CM_AGENT_HOOKS_INJECT=0`) or every candidate is occupied — both of which
+ *   mean "launch bare and let the scraper do it", never "fail to launch"
+ */
+async function allocateOpencodePort(target, worktreePath) {
+    if (!(0, hook_settings_generator_1.isHookInjectionEnabled)())
+        return null;
+    const existing = getAssignedOpencodePort(target);
+    if (existing !== null)
+        return existing;
+    const key = keyOf(target);
+    const persisted = readPersistedOpencodePorts()[key];
+    // A previous run's number first, so a pane restarted in place keeps its port
+    // and anybody watching `lsof` sees a stable mapping.
+    const preferred = persisted?.port;
+    const candidates = opencodePortCandidates(target);
+    const ordered = preferred !== undefined ? [preferred, ...candidates.filter((p) => p !== preferred)] : candidates;
+    for (const port of ordered) {
+        if (await isPortFree(port)) {
+            rememberOpencodePort(target, port, worktreePath);
+            logger.info('opencode-port-allocated', {
+                worktreeId: target.worktreeId,
+                instanceId: target.instanceId ?? target.cliToolId,
+                port,
+            });
+            return port;
+        }
+    }
+    logger.warn('opencode-port-exhausted', {
+        worktreeId: target.worktreeId,
+        instanceId: target.instanceId ?? target.cliToolId,
+        range: `${exports.OPENCODE_PORT_RANGE.min}-${exports.OPENCODE_PORT_RANGE.max}`,
+    });
+    return null;
+}
+/**
+ * Find the port of an instance that is already running.
+ *
+ * The CommandMate-restart path: the pane and its server survived, this process
+ * did not. Recovery is a lookup plus a health check rather than a scan, so a
+ * hash collision cannot make one instance adopt another's server.
+ *
+ * @param target - The instance whose pane is already alive
+ * @param worktreePath - Rejects an entry recorded for a different worktree
+ * @returns The port, or null when nothing verifiable is there
+ */
+async function recoverOpencodePort(target, worktreePath) {
+    if (!(0, hook_settings_generator_1.isHookInjectionEnabled)())
+        return null;
+    const existing = getAssignedOpencodePort(target);
+    if (existing !== null)
+        return existing;
+    const persisted = readPersistedOpencodePorts()[keyOf(target)];
+    if (!persisted)
+        return null;
+    if (persisted.worktreePath !== worktreePath) {
+        // The worktree was recreated under the same id at a different path, or the
+        // file is from another machine's home directory. Either way the recorded
+        // number says nothing about this instance.
+        logger.info('opencode-port-recovery-path-mismatch', {
+            worktreeId: target.worktreeId,
+            recorded: persisted.worktreePath,
+        });
+        return null;
+    }
+    const health = await (0, client_1.fetchOpencodeHealth)(persisted.port);
+    if (!health) {
+        logger.info('opencode-port-recovery-unhealthy', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            port: persisted.port,
+        });
+        return null;
+    }
+    assignments.set(keyOf(target), persisted);
+    logger.info('opencode-port-recovered', {
+        worktreeId: target.worktreeId,
+        instanceId: target.instanceId ?? target.cliToolId,
+        port: persisted.port,
+        version: health.version,
+    });
+    return persisted.port;
+}
+/** Drop every in-memory assignment. Test seam; production only ever forgets one. */
+function resetOpencodePortAssignments() {
+    assignments.clear();
+}

package/dist/server/src/lib/hooks/sources/opencode/runtime.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * The three calls `OpenCodeTool` makes (Issue #1763).
+ *
+ * `src/lib/cli-tools/opencode.ts` owns the tmux pane; this module owns the
+ * event stream that runs beside it. Keeping them apart is what stops the
+ * launcher from importing the database, the adjudicator and the SSE client:
+ * `../registry` statically imports `./source`, so anything `./source` reaches
+ * is reached by every import of `@/lib/hooks/sources`, and the wiring below is
+ * the only place that pulls `./ingest` in.
+ *
+ * ## The lifecycle, and what it deliberately does not include
+ *
+ * There is **no server process to manage**. Issue #1763's text asked for
+ * "serve process lifecycle management — start, port allocation, stop, orphan
+ * reaping", and #1758 §5.1.2 measured that away: the plain TUI is the server
+ * when it is given `--port`, so the server starts when the pane starts, dies
+ * when the pane dies, and cannot be orphaned. What is left is a port to choose
+ * and a connection to hold.
+ *
+ * Every function here is fail-open. Structured events are an enhancement to a
+ * session that has to start anyway, so a port that cannot be allocated, a
+ * server that does not answer and a stream that will not open all end the same
+ * way: the pane runs, the screen scraper decides, and CommandMate behaves
+ * exactly as it did before this Issue.
+ *
+ * @module lib/hooks/sources/opencode/runtime
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.opencodeTarget = opencodeTarget;
+exports.reserveOpencodeServerPort = reserveOpencodeServerPort;
+exports.attachOpencodeEventStream = attachOpencodeEventStream;
+exports.resumeOpencodeEventStream = resumeOpencodeEventStream;
+exports.releaseOpencodeEventStream = releaseOpencodeEventStream;
+const logger_1 = require("../../../../lib/logger");
+const client_1 = require("./client");
+const ingest_1 = require("./ingest");
+const ports_1 = require("./ports");
+const source_1 = require("./source");
+const subscription_1 = require("./subscription");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/runtime');
+/** The instance ref for one worktree's opencode instance. */
+function opencodeTarget(worktreeId, instanceId) {
+    return { worktreeId, cliToolId: 'opencode', instanceId };
+}
+/**
+ * Choose the port the TUI will serve on.
+ *
+ * Must run before the launch command is built: `prepareLaunch` is synchronous
+ * and reads the assignment. Returns null when there will be no server — the
+ * caller launches bare and skips {@link attachOpencodeEventStream}.
+ *
+ * @param target - The instance about to be created
+ * @param worktreePath - Recorded so a later recovery can verify the entry
+ */
+async function reserveOpencodeServerPort(target, worktreePath) {
+    try {
+        return await (0, ports_1.allocateOpencodePort)(target, worktreePath);
+    }
+    catch (error) {
+        logger.warn('opencode-port-reserve-failed', {
+            worktreeId: target.worktreeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/**
+ * Open the event stream for an instance whose pane has just started.
+ *
+ * Health-checked first, and this is not belt-and-braces: a user running an
+ * opencode old enough not to accept `--port` gets a TUI with no server, and
+ * subscribing to a port nothing is listening on would spend the rest of the
+ * session reconnecting to it. One sub-millisecond probe (#1758 §5.7.2) is the
+ * difference between "no structured events, scraper as before" and a reconnect
+ * loop that never succeeds.
+ *
+ * @returns Whether a stream was opened
+ */
+async function attachOpencodeEventStream(target) {
+    try {
+        const port = (0, ports_1.getAssignedOpencodePort)(target);
+        if (port === null)
+            return false;
+        if ((0, subscription_1.isOpencodeSubscribed)(target))
+            return true;
+        const health = await (0, client_1.fetchOpencodeHealth)(port);
+        if (!health) {
+            logger.info('opencode-server-not-reachable', {
+                worktreeId: target.worktreeId,
+                instanceId: target.instanceId ?? target.cliToolId,
+                port,
+            });
+            return false;
+        }
+        await source_1.opencodeAgentEventSource.subscribe(target, (event) => {
+            void (0, ingest_1.ingestOpencodeEvent)(target, event);
+        });
+        logger.info('opencode-event-stream-attached', {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId ?? target.cliToolId,
+            port,
+            version: health.version,
+        });
+        return true;
+    }
+    catch (error) {
+        logger.warn('opencode-event-stream-attach-failed', {
+            worktreeId: target.worktreeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Re-open the stream for an instance whose pane outlived this process.
+ *
+ * The CommandMate-restart path, and the reuse branch of `startSession`. The
+ * port comes from the persisted assignment rather than from a fresh scan, so a
+ * hash collision cannot make one instance adopt another's server — see
+ * `./ports`.
+ *
+ * @returns Whether a stream was opened
+ */
+async function resumeOpencodeEventStream(target, worktreePath) {
+    try {
+        if ((0, subscription_1.isOpencodeSubscribed)(target))
+            return true;
+        const port = await (0, ports_1.recoverOpencodePort)(target, worktreePath);
+        if (port === null)
+            return false;
+        return await attachOpencodeEventStream(target);
+    }
+    catch (error) {
+        logger.warn('opencode-event-stream-resume-failed', {
+            worktreeId: target.worktreeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Stop watching an instance and give its port back.
+ *
+ * Called from `killSession`. The port is released here rather than on a timer
+ * because the pane is what held it, and the pane is gone.
+ */
+async function releaseOpencodeEventStream(target) {
+    try {
+        await (0, subscription_1.closeOpencodeSubscription)(target);
+        (0, ports_1.forgetOpencodePort)(target);
+    }
+    catch (error) {
+        logger.warn('opencode-event-stream-release-failed', {
+            worktreeId: target.worktreeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}