specrails-desktop 2.0.0

package/server/dist/ticket-watcher.js

@@ -0,0 +1,117 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TicketWatcher = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const chokidar_1 = require("chokidar");
+const TICKET_FILE = '.specrails/local-tickets.json';
+const DEBOUNCE_MS = 150;
+/**
+ * Watches `.specrails/local-tickets.json` for external changes and broadcasts
+ * ticket_updated via WebSocket. One instance per project context.
+ */
+class TicketWatcher {
+    _watcher = null;
+    _debounceTimer = null;
+    _projectPath;
+    _projectId;
+    _broadcast;
+    _lastRevision = null;
+    _closed = false;
+    constructor(projectPath, projectId, broadcast) {
+        this._projectPath = projectPath;
+        this._projectId = projectId;
+        this._broadcast = broadcast;
+    }
+    /**
+     * Start watching the ticket file. Safe to call if file doesn't exist yet —
+     * chokidar will detect when it's created.
+     */
+    start() {
+        if (this._closed)
+            return;
+        const filePath = path_1.default.join(this._projectPath, TICKET_FILE);
+        // Seed initial revision so we can detect external changes
+        this._lastRevision = this._readRevision(filePath);
+        this._watcher = new chokidar_1.FSWatcher({
+            persistent: false, // don't keep the process alive
+            ignoreInitial: true,
+            // awaitWriteFinish helps with rapid writes from CLI agents
+            awaitWriteFinish: {
+                stabilityThreshold: 80,
+                pollInterval: 50,
+            },
+        });
+        this._watcher.add(filePath);
+        this._watcher.on('change', () => this._onFileChange(filePath));
+        this._watcher.on('add', () => this._onFileChange(filePath));
+        this._watcher.on('error', (err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[ticket-watcher] error for project ${this._projectId}:`, msg);
+        });
+    }
+    /**
+     * Stop watching and clean up. Safe to call multiple times.
+     */
+    async close() {
+        this._closed = true;
+        if (this._debounceTimer) {
+            clearTimeout(this._debounceTimer);
+            this._debounceTimer = null;
+        }
+        if (this._watcher) {
+            await this._watcher.close();
+            this._watcher = null;
+        }
+    }
+    /**
+     * Notify the watcher that the app itself just wrote to the file,
+     * so the next file-change event should be skipped (avoids echo).
+     * Call this from ticket API mutation handlers.
+     */
+    notifyDesktopWrite(newRevision) {
+        this._lastRevision = newRevision;
+    }
+    _onFileChange(filePath) {
+        if (this._debounceTimer) {
+            clearTimeout(this._debounceTimer);
+        }
+        this._debounceTimer = setTimeout(() => {
+            this._debounceTimer = null;
+            this._handleChange(filePath);
+        }, DEBOUNCE_MS);
+    }
+    _handleChange(filePath) {
+        const revision = this._readRevision(filePath);
+        if (revision === null)
+            return; // file unreadable or malformed
+        // Skip if revision hasn't changed (app's own write)
+        if (this._lastRevision !== null && revision === this._lastRevision)
+            return;
+        this._lastRevision = revision;
+        // Broadcast a generic ticket_updated with the full ticket set so the
+        // client can diff. We use a synthetic ticket with id 0 to signal
+        // "full refresh" — this is simpler than diffing individual tickets
+        // and the client will refetch via API anyway.
+        this._broadcast({
+            type: 'ticket_updated',
+            projectId: this._projectId,
+            ticket: { id: 0 },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    _readRevision(filePath) {
+        try {
+            const raw = fs_1.default.readFileSync(filePath, 'utf-8');
+            const data = JSON.parse(raw);
+            return typeof data.revision === 'number' ? data.revision : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.TicketWatcher = TicketWatcher;

package/server/dist/types.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_PRIORITIES = exports.PRIORITY_WEIGHT = void 0;
+exports.PRIORITY_WEIGHT = {
+    low: 0,
+    normal: 1,
+    high: 2,
+    critical: 3,
+};
+exports.VALID_PRIORITIES = new Set(['low', 'normal', 'high', 'critical']);

package/server/dist/user-mcp-config.js

@@ -0,0 +1,117 @@
+"use strict";
+// User-approved MCP injection for Explore Spec turns.
+//
+// When a conversation's ContextScope has `userMcp: true`, the app makes the
+// user's OWN already-approved MCP servers available to the spawned CLI — the
+// ones they registered locally with `claude mcp add` / `codex mcp add`, NOT the
+// project-committed `.mcp.json` (that is the separate `mcp` toggle).
+//
+// Provider behaviour:
+//   - claude: read `~/.claude.json` and collect the user-scope (top-level
+//     `mcpServers`) and project-local-scope (`projects[<projectPath>].mcpServers`)
+//     server definitions, merge them (local wins on key conflict, mirroring
+//     claude's own scope precedence), write a `{ "mcpServers": {…} }` file and
+//     return `['--mcp-config', <file>]`. The CLI loads `--mcp-config` ADDITIVELY
+//     on top of whatever else it discovers (no `--strict-mcp-config`), and the
+//     existing `--dangerously-skip-permissions` flag means the tools are
+//     callable without an approval prompt. Verified e2e against claude 2.1.169.
+//   - codex: returns `[]`. codex chat turns spawn with `env: process.env` and no
+//     `CODEX_HOME` override, so codex already reads the user's global
+//     `~/.codex/config.toml` MCP servers natively — no injection needed.
+//
+// The spawn cwd is intentionally left unchanged (the Explore latency win of the
+// app-managed `explore-cwd/` is preserved); `--mcp-config` carries an absolute
+// path so cwd is irrelevant.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readUserClaudeMcpServers = readUserClaudeMcpServers;
+exports.writeUserMcpConfig = writeUserMcpConfig;
+exports.buildUserMcpArgs = buildUserMcpArgs;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+/**
+ * Read the user's approved claude MCP servers from `~/.claude.json`:
+ * user-scope (top-level `mcpServers`) merged with the project's local-scope
+ * (`projects[projectPath].mcpServers`). Local scope overrides user scope on a
+ * key conflict, matching claude's documented precedence (local > user).
+ *
+ * Returns `{}` when the file is missing, unparseable, or has no servers. Never
+ * throws — a malformed user config must not break the chat turn.
+ *
+ * @param projectPath absolute path of the project (the local-scope key)
+ * @param homeDir     override the home directory (tests)
+ */
+function readUserClaudeMcpServers(projectPath, homeDir) {
+    const home = homeDir ?? node_os_1.default.homedir();
+    const configPath = node_path_1.default.join(home, '.claude.json');
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(configPath, 'utf-8');
+    }
+    catch {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    const userScope = parsed && typeof parsed.mcpServers === 'object' && parsed.mcpServers
+        ? parsed.mcpServers
+        : {};
+    const projectEntry = parsed && typeof parsed.projects === 'object' && parsed.projects
+        ? parsed.projects[projectPath]
+        : undefined;
+    const localScope = projectEntry && typeof projectEntry.mcpServers === 'object' && projectEntry.mcpServers
+        ? projectEntry.mcpServers
+        : {};
+    return { ...userScope, ...localScope };
+}
+/**
+ * Write the merged server map to a `{ "mcpServers": {…} }` file under the
+ * project's data directory and return its absolute path. chmod 600 because
+ * server `env` blocks can carry secrets (same trust domain as `~/.claude.json`).
+ *
+ * @param baseDir override `~/.specrails/projects` (tests)
+ */
+function writeUserMcpConfig(servers, slug, baseDir) {
+    // Defence-in-depth: slug is always DB-sourced and slugified upstream
+    // (`/^[a-z0-9-]+/`), but guard the filesystem write directly so a future
+    // caller passing untrusted input cannot escape the projects directory.
+    // buildUserMcpArgs() swallows the throw and falls back to no injection.
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+        throw new Error(`unsafe project slug for user-mcp config: ${JSON.stringify(slug)}`);
+    }
+    const base = baseDir ?? node_path_1.default.join(node_os_1.default.homedir(), '.specrails', 'projects');
+    const dir = node_path_1.default.join(base, slug);
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    const file = node_path_1.default.join(dir, 'user-mcp.json');
+    node_fs_1.default.writeFileSync(file, JSON.stringify({ mcpServers: servers }, null, 2), { mode: 0o600 });
+    return file;
+}
+/**
+ * Build the extra CLI args that load the user's approved MCP servers, or `[]`
+ * when there is nothing to inject (non-claude provider, or no user/local
+ * servers configured). Never throws.
+ */
+function buildUserMcpArgs(input) {
+    // codex reads ~/.codex natively; only claude needs explicit injection.
+    if (input.adapterId !== 'claude')
+        return [];
+    try {
+        const servers = readUserClaudeMcpServers(input.projectPath, input.homeDir);
+        if (Object.keys(servers).length === 0)
+            return [];
+        const file = writeUserMcpConfig(servers, input.slug, input.baseDir);
+        return ['--mcp-config', file];
+    }
+    catch (err) {
+        console.error('[user-mcp-config] failed to build --mcp-config args:', err);
+        return [];
+    }
+}

package/server/dist/util/cli-prompt.js

@@ -0,0 +1,181 @@
+"use strict";
+// Centralized claude/codex spawn wrapper.
+//
+// Why this exists:
+//
+//   On Windows, cross-spawn invokes claude.cmd / codex.cmd through
+//   `cmd.exe /d /s /c "..."`. cmd.exe does NOT preserve newlines
+//   inside argv values: any `\n` in `--system-prompt`,
+//   `--append-system-prompt`, `-p`, or codex's positional prompt
+//   truncates the arg there and the rest of the command line gets
+//   reparsed as orphan tokens. Visible symptoms include
+//   "Input must be provided either through stdin or as a prompt
+//   argument when using --print" and assistant messages that look
+//   like "your message got cut off — you wrote 'are' but I'm not
+//   sure what you were asking".
+//
+//   On POSIX argv passes through cleanly, so we keep that path.
+//
+// The helpers below detect multi-line argv values on Windows,
+// reroute them through child stdin (claude reads stdin when
+// `-p`/`--print` has no positional argument; codex `exec -` does the
+// equivalent), and call spawnCli. POSIX is unchanged byte-for-byte.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformClaudeArgsForWindows = transformClaudeArgsForWindows;
+exports.transformCodexArgsForWindows = transformCodexArgsForWindows;
+exports.ensureStdinPipe = ensureStdinPipe;
+exports.spawnClaude = spawnClaude;
+exports.spawnCodex = spawnCodex;
+exports.spawnAiCli = spawnAiCli;
+const win_spawn_1 = require("./win-spawn");
+const isWin = process.platform === 'win32';
+const CLAUDE_PROMPT_FLAGS = new Set([
+    '--system-prompt',
+    '--append-system-prompt',
+    '-p',
+    '--print',
+]);
+function transformClaudeArgsForWindows(args) {
+    const collected = [];
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (CLAUDE_PROMPT_FLAGS.has(a) && i + 1 < args.length) {
+            collected.push(args[i + 1]);
+            i++; // skip the value
+            continue;
+        }
+        out.push(a);
+    }
+    if (collected.length === 0) {
+        return { args: out, stdinPayload: null };
+    }
+    // Re-add `-p` so claude knows to read stdin (--print mode).
+    out.push('-p');
+    return { args: out, stdinPayload: collected.join('\n\n---\n\n') };
+}
+// Codex `exec` flags we currently use that take a value (rest are
+// boolean). Update if we ever pass new value-bearing flags.
+const CODEX_EXEC_VALUE_FLAGS = new Set(['--model', '--sandbox', '-c']);
+function transformCodexArgsForWindows(args) {
+    // Expected shapes:
+    //   exec [...flags] <prompt> [...flags]
+    //   exec resume [...flags] <sessionId> <prompt> [...flags]
+    if (args.length === 0 || args[0] !== 'exec') {
+        return { args, stdinPayload: null };
+    }
+    const out = ['exec'];
+    const isResume = args[1] === 'resume';
+    if (isResume)
+        out.push('resume');
+    let stdin = null;
+    let promptReplacedIdx = -1;
+    let positionalCount = 0;
+    let i = isResume ? 2 : 1;
+    while (i < args.length) {
+        const a = args[i];
+        if (a.startsWith('-') && a !== '-') {
+            out.push(a);
+            if (CODEX_EXEC_VALUE_FLAGS.has(a) && i + 1 < args.length) {
+                out.push(args[i + 1]);
+                i += 2;
+                continue;
+            }
+            i += 1;
+            continue;
+        }
+        positionalCount += 1;
+        const isPrompt = isResume ? positionalCount === 2 : positionalCount === 1;
+        if (isPrompt && stdin === null) {
+            stdin = a;
+            promptReplacedIdx = out.length;
+            out.push('-');
+        }
+        else {
+            out.push(a);
+        }
+        i += 1;
+    }
+    if (stdin === null || !stdin.includes('\n')) {
+        // Single-line prompts pass through cmd.exe fine — keep argv to
+        // dodge any codex versions that don't recognise `-` as stdin.
+        if (stdin !== null && promptReplacedIdx >= 0) {
+            out[promptReplacedIdx] = stdin;
+        }
+        return { args: out, stdinPayload: null };
+    }
+    return { args: out, stdinPayload: stdin };
+}
+function ensureStdinPipe(stdio) {
+    const fallback = ['pipe', 'pipe', 'pipe'];
+    if (stdio === undefined)
+        return fallback;
+    if (typeof stdio === 'string') {
+        // 'pipe' | 'inherit' | 'ignore' | 'overlapped'
+        return ['pipe', stdio, stdio];
+    }
+    if (Array.isArray(stdio)) {
+        return [
+            stdio[0] === 'ignore' ? 'pipe' : (stdio[0] ?? 'pipe'),
+            stdio[1] ?? 'pipe',
+            stdio[2] ?? 'pipe',
+        ];
+    }
+    return fallback;
+}
+/**
+ * Spawn `claude` with arg-rewrite on Windows so multi-line prompts
+ * survive. POSIX call is identical to `spawnCli('claude', args, options)`.
+ */
+function spawnClaude(args, options = {}) {
+    if (!isWin) {
+        return (0, win_spawn_1.spawnCli)('claude', args, options);
+    }
+    /* c8 ignore start -- Windows-only branch; coverage runs on Linux/macOS */
+    const { args: winArgs, stdinPayload } = transformClaudeArgsForWindows(args);
+    if (stdinPayload === null) {
+        return (0, win_spawn_1.spawnCli)('claude', winArgs, options);
+    }
+    const child = (0, win_spawn_1.spawnCli)('claude', winArgs, {
+        ...options,
+        stdio: ensureStdinPipe(options.stdio),
+    });
+    if (child.stdin)
+        child.stdin.end(stdinPayload);
+    return child;
+    /* c8 ignore stop */
+}
+/**
+ * Spawn `codex` with arg-rewrite on Windows so multi-line prompts
+ * survive. POSIX call is identical to `spawnCli('codex', args, options)`.
+ */
+function spawnCodex(args, options = {}) {
+    if (!isWin) {
+        return (0, win_spawn_1.spawnCli)('codex', args, options);
+    }
+    /* c8 ignore start -- Windows-only branch; coverage runs on Linux/macOS */
+    const { args: winArgs, stdinPayload } = transformCodexArgsForWindows(args);
+    if (stdinPayload === null) {
+        return (0, win_spawn_1.spawnCli)('codex', winArgs, options);
+    }
+    const child = (0, win_spawn_1.spawnCli)('codex', winArgs, {
+        ...options,
+        stdio: ensureStdinPipe(options.stdio),
+    });
+    if (child.stdin)
+        child.stdin.end(stdinPayload);
+    return child;
+    /* c8 ignore stop */
+}
+/**
+ * Convenience: dispatch on binary name. Use when callsite picks the
+ * binary dynamically (claude vs codex). Anything else routes through
+ * the underlying spawnCli unchanged.
+ */
+function spawnAiCli(binary, args, options = {}) {
+    if (binary === 'claude')
+        return spawnClaude(args, options);
+    if (binary === 'codex')
+        return spawnCodex(args, options);
+    return (0, win_spawn_1.spawnCli)(binary, args, options);
+}

package/server/dist/util/secure-fs.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secureDir = secureDir;
+exports.secureDbFile = secureDbFile;
+const fs_1 = __importDefault(require("fs"));
+/**
+ * Best-effort filesystem hardening for the ~/.specrails data stores (H-13).
+ *
+ * The auth token is deliberately persisted 0600, but the SQLite databases were
+ * created with the default umask (typically dir 0755 / file 0644), leaving
+ * webhook HMAC secrets, chat transcripts, and verbatim terminal command history
+ * world-readable on a multi-user machine. These helpers restrict the data dir to
+ * owner-only and the db files (plus their WAL sidecars) to owner read/write.
+ *
+ * POSIX permission bits are a no-op on Windows (NTFS uses ACLs and the per-user
+ * profile already isolates the home dir), so both helpers early-return there —
+ * we never pretend a chmod that did nothing succeeded.
+ */
+/** Restrict a directory to owner-only (0700). No-op on Windows / on error. */
+function secureDir(dir) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        fs_1.default.chmodSync(dir, 0o700);
+    }
+    catch {
+        // Best-effort: a chmod failure must never crash startup.
+    }
+}
+/**
+ * Restrict a SQLite db file and its `-wal`/`-shm` sidecars to 0600.
+ * No-op on Windows, for `:memory:`, and on error (sidecars may not exist yet).
+ */
+function secureDbFile(dbPath) {
+    if (process.platform === 'win32')
+        return;
+    if (dbPath === ':memory:')
+        return;
+    for (const file of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+        try {
+            fs_1.default.chmodSync(file, 0o600);
+        }
+        catch {
+            // Sidecar may not exist yet, or fs may reject — best-effort.
+        }
+    }
+}

package/server/dist/util/win-spawn.js

@@ -0,0 +1,43 @@
+"use strict";
+// Cross-platform spawn wrapper.
+//
+// Two Windows-specific problems forced this helper:
+//
+// 1) `claude` (and similar npm-installed binaries) is shipped as a
+//    `.cmd` shim. `spawn('claude', ..., { shell: false })` fails
+//    with ENOENT because Node looks for an exact `claude` file
+//    without extension expansion.
+//
+// 2) Setting `shell: true` makes Windows resolve the shim, but
+//    cmd.exe then re-parses the concatenated command line and
+//    truncates any arg containing `\n` (e.g. claude's
+//    `--system-prompt "You are a...\n..."`).
+//
+// Since Node 20.12 / CVE-2024-27980 the obvious middle ground —
+// `spawn('claude.cmd', ..., { shell: false })` — also fails, this
+// time with EINVAL: Node refuses to spawn .cmd/.bat without a
+// shell. `cross-spawn` is the de-facto fix: on Windows it
+// internally launches `cmd.exe /d /s /c` with quoted-then-escaped
+// args so newlines and shell metacharacters survive intact, and on
+// POSIX it falls through to the native `child_process.spawn`.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnCli = spawnCli;
+exports.resolveWindowsBinary = resolveWindowsBinary;
+const child_process_1 = require("child_process");
+const cross_spawn_1 = __importDefault(require("cross-spawn"));
+function spawnCli(binary, args, options = {}) {
+    /* c8 ignore next 3 -- Windows-only branch; coverage runs on Linux/macOS */
+    if (process.platform === 'win32') {
+        return (0, cross_spawn_1.default)(binary, args, options);
+    }
+    return (0, child_process_1.spawn)(binary, args, options);
+}
+// Back-compat for callsites that only need the resolved binary
+// (e.g. logging). Kept as a no-op identity on POSIX; on Windows
+// `where`-based resolution lives inside cross-spawn now.
+function resolveWindowsBinary(name) {
+    return name;
+}

package/server/dist/webhook-manager.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookManager = void 0;
+const crypto_1 = require("crypto");
+const desktop_db_1 = require("./desktop-db");
+const WEBHOOK_TIMEOUT_MS = 10_000;
+const MAX_ATTEMPTS = 3;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ─── WebhookManager ───────────────────────────────────────────────────────────
+class WebhookManager {
+    _desktopDb;
+    constructor(desktopDb) {
+        this._desktopDb = desktopDb;
+    }
+    /**
+     * Send a test ping to a single webhook (used by the test endpoint).
+     */
+    deliverTest(webhook) {
+        const payload = {
+            event: 'job.completed',
+            timestamp: new Date().toISOString(),
+            projectId: webhook.project_id ?? '*',
+            data: { test: true, message: 'specrails-desktop webhook test ping' },
+        };
+        setImmediate(() => {
+            this._deliverWithRetry(webhook, payload).catch(() => { });
+        });
+    }
+    /**
+     * Deliver an event to all matching webhooks for a project.
+     * Non-blocking: fires and forgets with retry logic.
+     */
+    deliver(projectId, event, data) {
+        const webhooks = (0, desktop_db_1.listWebhooksForProject)(this._desktopDb, projectId);
+        const matching = webhooks.filter((w) => {
+            try {
+                const events = JSON.parse(w.events);
+                return events.includes(event);
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const webhook of matching) {
+            const payload = {
+                event,
+                timestamp: new Date().toISOString(),
+                projectId,
+                data,
+            };
+            // Fire-and-forget with retry; errors are swallowed after exhausting attempts
+            setImmediate(() => {
+                this._deliverWithRetry(webhook, payload).catch(() => { });
+            });
+        }
+    }
+    async _deliverWithRetry(webhook, payload, attempt = 1) {
+        const body = JSON.stringify(payload);
+        const headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': 'specrails-desktop',
+        };
+        if (webhook.secret) {
+            const sig = (0, crypto_1.createHmac)('sha256', webhook.secret).update(body).digest('hex');
+            headers['X-Specrails-Signature'] = `sha256=${sig}`;
+        }
+        try {
+            const res = await fetch(webhook.url, {
+                method: 'POST',
+                headers,
+                body,
+                signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+            });
+            if (!res.ok && attempt < MAX_ATTEMPTS) {
+                await delay(1000 * attempt);
+                return this._deliverWithRetry(webhook, payload, attempt + 1);
+            }
+        }
+        catch {
+            if (attempt < MAX_ATTEMPTS) {
+                await delay(1000 * attempt);
+                return this._deliverWithRetry(webhook, payload, attempt + 1);
+            }
+        }
+    }
+}
+exports.WebhookManager = WebhookManager;

package/server/dist/ws-routing.js

@@ -0,0 +1,47 @@
+"use strict";
+// Pure, testable WebSocket routing decisions (H-09). Kept out of index.ts (which
+// is excluded from coverage and not unit-tested) so the project-isolation logic
+// that the Mobile Gateway will depend on is covered and verifiable.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldDeliverToSubscriber = shouldDeliverToSubscriber;
+exports.parseSubscribeFrame = parseSubscribeFrame;
+/**
+ * Decide whether a broadcast message should be delivered to a given connection.
+ *
+ * - App-level messages (no projectId) go to everyone.
+ * - A connection that has NOT declared a subscription (`subscribedProjectId`
+ *   null) receives everything — back-compat with the current web client, whose
+ *   own client-side filter remains as a redundant second layer.
+ * - A connection subscribed to project P receives only P's project-scoped
+ *   messages (plus all app-level ones).
+ *
+ * The Mobile Gateway turns this into a hard authorization boundary by always
+ * subscribing each device connection to exactly the project(s) it may see.
+ */
+function shouldDeliverToSubscriber(msgProjectId, subscribedProjectId) {
+    if (msgProjectId === undefined)
+        return true;
+    if (subscribedProjectId === null)
+        return true;
+    return subscribedProjectId === msgProjectId;
+}
+/**
+ * Parse an inbound WS control frame and return the projectId to subscribe to.
+ *
+ * Returns `{ subscribe: true, projectId }` for a well-formed
+ * `{ type: 'subscribe', projectId: <string|null> }` frame (a non-string
+ * projectId clears the subscription → null), or `{ subscribe: false }` for
+ * anything else / malformed input. Never throws.
+ */
+function parseSubscribeFrame(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.type === 'subscribe') {
+            return { subscribe: true, projectId: typeof parsed.projectId === 'string' ? parsed.projectId : null };
+        }
+    }
+    catch {
+        // Malformed control frame — ignore.
+    }
+    return { subscribe: false, projectId: null };
+}