wicked-crew 0.5.0 → 0.6.0

package/dist/interactive/ledger.js

@@ -0,0 +1,93 @@
+/**
+ * Durable handoff ledger shared by crew's wicked-interactive seams (task #86, Phase 7c).
+ *
+ * Extracted from the draft leg (draft-events.ts, PR #241) when the structural-edit leg arrived,
+ * because both seams need the same replay-dedup discipline with DIFFERENT key grammars:
+ *
+ *  - the DRAFT leg keys by document id — one first draft per document lifetime;
+ *  - the EDIT leg keys by `<doc>:v<version>` — one governed edit per HANDOFF, because the same
+ *    document legitimately produces many structural handoffs over its life (versioned targeting).
+ *
+ * The ledger itself is key-agnostic: a durable map `key → HandoffLedgerEntry`, JSON on disk,
+ * written atomically (tmp + rename). The bus cursor alone cannot carry this: at-least-once
+ * delivery means the same trigger can arrive again after a crash between handling and cursor
+ * advance, and in-memory state dies with the process. The ledger is the system of record for
+ * "this handoff was answered"; each seam's in-flight map is just the live half.
+ */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+export class InteractiveHandoffLedger {
+    path;
+    entries;
+    constructor(path) {
+        this.path = path;
+        this.entries = {};
+        try {
+            // The persisted top-level field stays `docs` for wire-compat with ledgers the draft leg
+            // already wrote to operator machines (~/.wicked-crew/interactive-draft-ledger.json).
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (parsed && typeof parsed === 'object' && parsed.docs && typeof parsed.docs === 'object') {
+                for (const [key, entry] of Object.entries(parsed.docs)) {
+                    // Per-row validation: one malformed row (null, primitive, missing/empty fields) costs
+                    // that row alone — letting it throw into the outer catch would blank the WHOLE ledger
+                    // and defeat replay-dedup for every handoff already answered. A kept row must satisfy
+                    // the full HandoffLedgerEntry contract (non-empty runId + launchedAt strings).
+                    if (typeof entry !== 'object' ||
+                        entry === null ||
+                        typeof entry.runId !== 'string' ||
+                        entry.runId.length === 0 ||
+                        typeof entry.launchedAt !== 'string') {
+                        continue;
+                    }
+                    const { draftEmittedAt, ...rest } = entry;
+                    this.entries[key] = {
+                        ...rest,
+                        // Migrate the draft leg's original field name in place.
+                        ...(rest.emittedAt === undefined && draftEmittedAt !== undefined
+                            ? { emittedAt: draftEmittedAt }
+                            : {}),
+                    };
+                }
+            }
+        }
+        catch {
+            // Missing or malformed ledger — start empty. Malformed is deliberately NOT fatal: a
+            // corrupt ledger must not stop the daemon, and the worst case is one duplicate closing
+            // emit, which the deterministic bus idempotency key still dedupes.
+        }
+    }
+    has(key) {
+        return Object.prototype.hasOwnProperty.call(this.entries, key);
+    }
+    get(key) {
+        return this.entries[key];
+    }
+    recordLaunch(key, runId) {
+        this.entries[key] = { runId, launchedAt: new Date().toISOString() };
+        this.persist();
+    }
+    recordEmitted(key) {
+        const entry = this.entries[key];
+        if (entry) {
+            entry.emittedAt = new Date().toISOString();
+            this.persist();
+        }
+    }
+    recordFailure(key) {
+        const entry = this.entries[key];
+        if (entry) {
+            entry.failedAt = new Date().toISOString();
+            this.persist();
+        }
+    }
+    size() {
+        return Object.keys(this.entries).length;
+    }
+    persist() {
+        mkdirSync(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.tmp-${process.pid}`;
+        writeFileSync(tmp, JSON.stringify({ docs: this.entries }, null, 2), 'utf8');
+        renameSync(tmp, this.path);
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/interactive/ledger.js.map

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

package/dist/interactive/proxy-routes.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `/api/v1/projects/:projectId/interactive/*` — crew reverse-proxies the wicked-interactive
+ * bridge (DES-MERGE-001 §5.3, §7.2; slice 1).
+ *
+ * PURE TRANSPORT. Nothing user-visible moves in this slice: what changes is that interactive's
+ * HTTP surface becomes reachable through crew's OWN origin, so the studio client never learns a
+ * second origin, never needs CORS, and never carries a bridge port literal — ADR-0022's dynamic
+ * port is honored rather than worked around, and the bridge stops being browser-reachable at all.
+ *
+ * The path encodes the project (§7.2) because the ROOT is a per-project setting: the same proxy
+ * mount serves N interactive instances, one bridge per resolved root.
+ *
+ * Two things are deliberately hand-rolled over `node:http` rather than delegated to `fetch`:
+ *
+ *  1. UNBUFFERED STREAMING BOTH WAYS. Interactive's generation surface is SSE; a proxy that
+ *     buffers turns a live narration into a single blob delivered at stream close. Piping raw
+ *     sockets keeps every chunk flowing as it arrives, in both directions.
+ *  2. VERBATIM FORWARDING. The path remainder and query string are taken from `req.raw.url`,
+ *     not from Fastify's decoded wildcard param, so percent-encoding survives the hop intact.
+ */
+import type { FastifyInstance } from 'fastify';
+import type { CoreAdapter } from '../core/adapter.js';
+import type { ProjectSettingsStore } from '../projects/settings.js';
+import { InteractiveBridgePool, type LiveBridge } from './bridge-pool.js';
+/**
+ * Point a `Location` back at the proxy. The bridge answers on its own origin and knows nothing
+ * about the mount prefix, so both spellings it can emit have to be re-anchored: an absolute URL
+ * on the bridge origin, and a root-relative path. Anything else (a foreign origin, a relative
+ * path) is left exactly as-is — rewriting those would be inventing a redirect target.
+ */
+export declare function rewriteLocation(location: string, bridge: LiveBridge, prefix: string): string;
+export interface InteractiveProxyDeps {
+    settings: ProjectSettingsStore;
+    pool: InteractiveBridgePool;
+    env?: NodeJS.ProcessEnv;
+    log?: (msg: string) => void;
+}
+export declare function registerInteractiveProxy(app: FastifyInstance, adapter: CoreAdapter, deps: InteractiveProxyDeps): void;
+//# sourceMappingURL=proxy-routes.d.ts.map

package/dist/interactive/proxy-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-routes.d.ts","sourceRoot":"","sources":["../../src/interactive/proxy-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE,OAAO,EAA0B,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AA4BlG;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAO5F;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAiErH"}

package/dist/interactive/proxy-routes.js

@@ -0,0 +1,189 @@
+/**
+ * `/api/v1/projects/:projectId/interactive/*` — crew reverse-proxies the wicked-interactive
+ * bridge (DES-MERGE-001 §5.3, §7.2; slice 1).
+ *
+ * PURE TRANSPORT. Nothing user-visible moves in this slice: what changes is that interactive's
+ * HTTP surface becomes reachable through crew's OWN origin, so the studio client never learns a
+ * second origin, never needs CORS, and never carries a bridge port literal — ADR-0022's dynamic
+ * port is honored rather than worked around, and the bridge stops being browser-reachable at all.
+ *
+ * The path encodes the project (§7.2) because the ROOT is a per-project setting: the same proxy
+ * mount serves N interactive instances, one bridge per resolved root.
+ *
+ * Two things are deliberately hand-rolled over `node:http` rather than delegated to `fetch`:
+ *
+ *  1. UNBUFFERED STREAMING BOTH WAYS. Interactive's generation surface is SSE; a proxy that
+ *     buffers turns a live narration into a single blob delivered at stream close. Piping raw
+ *     sockets keeps every chunk flowing as it arrives, in both directions.
+ *  2. VERBATIM FORWARDING. The path remainder and query string are taken from `req.raw.url`,
+ *     not from Fastify's decoded wildcard param, so percent-encoding survives the hop intact.
+ */
+import { request as httpRequest } from 'node:http';
+import { API_PREFIX } from '../api/api-prefix.js';
+import { ProjectsUnsupportedError } from '../core/adapter.js';
+import { DEFAULT_PROJECT_ID } from '../projects/routes.js';
+import { resolveInteractiveRoot } from './bridge-root.js';
+import { BridgeUnavailableError } from './bridge-pool.js';
+/** Per-hop headers that must never be forwarded across a proxy (RFC 9110 §7.6.1). */
+const HOP_BY_HOP = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+function forwardableRequestHeaders(headers, bridge) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (HOP_BY_HOP.has(name) || value === undefined)
+            continue;
+        // Crew's bearer token is CREW's credential. The bridge is a local process with no auth of
+        // its own and no use for it; forwarding it would hand a third-party child crew's ambient
+        // authority for free. One auth path (§5.3) means crew terminates auth, it does not relay it.
+        if (name === 'authorization')
+            continue;
+        out[name] = value;
+    }
+    out['host'] = `${bridge.host}:${bridge.port}`;
+    return out;
+}
+/**
+ * Point a `Location` back at the proxy. The bridge answers on its own origin and knows nothing
+ * about the mount prefix, so both spellings it can emit have to be re-anchored: an absolute URL
+ * on the bridge origin, and a root-relative path. Anything else (a foreign origin, a relative
+ * path) is left exactly as-is — rewriting those would be inventing a redirect target.
+ */
+export function rewriteLocation(location, bridge, prefix) {
+    for (const host of new Set([bridge.host, 'localhost', '127.0.0.1'])) {
+        const origin = `http://${host}:${bridge.port}`;
+        if (location.startsWith(origin))
+            return `${prefix}${location.slice(origin.length)}`;
+    }
+    if (location.startsWith('/'))
+        return `${prefix}${location}`;
+    return location;
+}
+export function registerInteractiveProxy(app, adapter, deps) {
+    const { settings, pool } = deps;
+    const env = deps.env ?? process.env;
+    // Strips exactly the mount prefix off the RAW url, leaving the remainder + query untouched.
+    const prefixRe = new RegExp(`^${API_PREFIX}/projects/[^/?#]+/interactive`);
+    /** The resolved docs root for a project, or null when no such project exists. */
+    async function rootFor(projectId) {
+        // `default` is SYNTHESIZED by the route layer (DES-PROJECT-001 §7) — the engine has no row
+        // for it, so an existence check there would 404 the one project every operator starts with.
+        if (projectId !== DEFAULT_PROJECT_ID) {
+            try {
+                if ((await adapter.projectGet(projectId)) === null)
+                    return null;
+            }
+            catch (err) {
+                // A pre-0.6.0 engine has no project surface at all; the shared default root is still
+                // a truthful answer for the only project such a deployment can have.
+                if (!(err instanceof ProjectsUnsupportedError))
+                    throw err;
+            }
+        }
+        return resolveInteractiveRoot(settings.get(projectId), env);
+    }
+    // Encapsulated so the raw-body parser below applies to the PROXY ONLY. The root instance
+    // installs a JSON parser that buffers and parses the body — correct for every other route,
+    // fatal here: a parsed body is a consumed stream, and an SSE POST would arrive at the bridge
+    // only once the client finished sending.
+    void app.register(async (scope) => {
+        scope.removeAllContentTypeParsers();
+        scope.addContentTypeParser('*', (_req, payload, done) => {
+            done(null, payload);
+        });
+        scope.all(`${API_PREFIX}/projects/:projectId/interactive/*`, async (req, reply) => {
+            const { projectId } = req.params;
+            const prefix = `${API_PREFIX}/projects/${encodeURIComponent(projectId)}/interactive`;
+            const root = await rootFor(projectId);
+            if (root === null)
+                return reply.code(404).send({ error: `Project ${projectId} not found` });
+            let bridge;
+            try {
+                bridge = await pool.ensure(root);
+            }
+            catch (err) {
+                return unavailable(reply, err, deps.log);
+            }
+            const target = (req.raw.url ?? '').replace(prefixRe, '') || '/';
+            try {
+                await forward(req, reply, bridge, target, prefix);
+            }
+            catch (err) {
+                // The cached bridge died between the pid check and the connect (an operator killed it,
+                // a crash). Invalidate and let `ensure` restart it — ONE retry, so a genuinely broken
+                // bridge fails fast to a 503 instead of looping.
+                if (!isConnectionRefused(err) || reply.raw.headersSent)
+                    throw err;
+                pool.invalidate(root);
+                try {
+                    bridge = await pool.ensure(root);
+                }
+                catch (startErr) {
+                    return unavailable(reply, startErr, deps.log);
+                }
+                await forward(req, reply, bridge, target, prefix);
+            }
+            return reply;
+        });
+    });
+}
+function isConnectionRefused(err) {
+    const code = err?.code;
+    return code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'EHOSTUNREACH';
+}
+/** §5.6's failure shape: a machine-readable code plus a command the operator can actually run. */
+function unavailable(reply, err, log) {
+    if (!(err instanceof BridgeUnavailableError))
+        throw err;
+    log?.(`interactive bridge unavailable: ${err.message}`);
+    return reply.code(503).send({ code: 'bridge_unavailable', hint: err.hint });
+}
+/**
+ * One proxied exchange, socket to socket. `reply.hijack()` hands us the raw response before
+ * Fastify can serialize or buffer anything, which is what lets an SSE chunk reach the browser
+ * the moment the bridge emits it rather than at stream close.
+ */
+function forward(req, reply, bridge, target, prefix) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const upstream = httpRequest({
+            host: bridge.host,
+            port: bridge.port,
+            method: req.method,
+            path: target,
+            headers: forwardableRequestHeaders(req.headers, bridge),
+        }, (res) => {
+            reply.hijack();
+            const headers = {};
+            for (const [name, value] of Object.entries(res.headers)) {
+                if (HOP_BY_HOP.has(name) || value === undefined)
+                    continue;
+                headers[name] = name === 'location' && typeof value === 'string' ? rewriteLocation(value, bridge, prefix) : value;
+            }
+            reply.raw.writeHead(res.statusCode ?? 502, headers);
+            // No `pipeline` and no buffering layer: `pipe` forwards each chunk as it lands, and
+            // Node flushes it because we never set a highWaterMark barrier in between.
+            res.pipe(reply.raw);
+            res.on('end', () => resolvePromise());
+            res.on('error', (err) => {
+                reply.raw.destroy();
+                rejectPromise(err);
+            });
+        });
+        upstream.on('error', (err) => {
+            if (reply.raw.headersSent)
+                reply.raw.destroy();
+            rejectPromise(err);
+        });
+        // If the client hangs up mid-stream (closing an SSE tab), stop pulling from the bridge.
+        reply.raw.on('close', () => upstream.destroy());
+        req.raw.pipe(upstream);
+    });
+}
+//# sourceMappingURL=proxy-routes.js.map

package/dist/interactive/proxy-routes.js.map

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

package/dist/interactive/ws-relay.d.ts

@@ -0,0 +1,85 @@
+/**
+ * DES-MERGE-001 §5.4 / §6.1 (slice 3) — the `wicked.interactive.*` ↔ `/ws` relay.
+ *
+ * wicked-studio is absorbing wicked-interactive. The SPA already holds crew's `/ws` socket for
+ * CoreEvent frames; interactive's own progress travels on the wicked-bus. This module bridges the
+ * two so the skin needs exactly ONE socket — no second websocket, no new port.
+ *
+ * Two halves, one bus handle:
+ *
+ * 1. RELAY (bus → /ws). Subscribe to `wicked.interactive.**` and rebroadcast each event as
+ *    `{ type: 'interactiveEvent', event: <the full bus event> }` — ONE envelope type, the original
+ *    event nested whole, no field renaming, no project filter. Ordering is as received (the bus
+ *    hands a batch to the handler in order and `broadcast` is synchronous), and there is no
+ *    buffering beyond what the existing broadcast path already does.
+ *
+ * 2. EMIT (/ws client → bus). `POST /projects/:projectId/interactive-events` validates the body
+ *    against a SERVER-SIDE whitelist ({@link EMITTABLE_TYPES}) and puts the event on the bus with
+ *    interactive's own envelope conventions (domain `wicked-interactive`, producer `wi-crew`,
+ *    `ts`-stamped payload — draft-events.ts is the precedent), so interactive's own subscribers
+ *    see a UI-originated event exactly as they see a service-originated one.
+ *
+ * Deliberately DISTINCT from the `projectActivity` bridge in projects/events.ts, which reads the
+ * same filter: that one is project-FILTERED and reshapes the event into an activity frame for a
+ * project view. This one is unfiltered and verbatim, because the studio's document canvas must see
+ * the events of a doc that was never filed under a project. Separate plugin identity → separate
+ * durable cursor, so neither seam can strand the other.
+ *
+ * Posture mirrors every other bus seam here: LOUD-non-fatal. No wicked-bus, or a broken db → the
+ * factory logs once and returns null, the daemon boots without the relay, and the POST route
+ * answers 503 instead of pretending the emit landed.
+ */
+import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+/** The ONE envelope type this relay puts on `/ws`. Consumers that don't know it ignore it — the
+ *  CoreEvent contract is additive-safe (DES-STUDIO-001 §2.1). */
+export declare const INTERACTIVE_EVENT_FRAME = "interactiveEvent";
+/**
+ * Server-side whitelist of the event types a `/ws` client may emit through
+ * `POST /projects/:projectId/interactive-events`. A non-whitelisted type is a 400 that NAMES this
+ * array — the UI never has to guess. Extend here; nothing else needs to change.
+ */
+export declare const EMITTABLE_TYPES: readonly string[];
+/** The request body: a whitelisted type plus that type's own payload. Strict — an unknown key is
+ *  a 400, not a silently-dropped field. */
+export declare const EmitInteractiveEventSchema: z.ZodObject<{
+    type: z.ZodString;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    payload?: Record<string, unknown> | undefined;
+}, {
+    type: string;
+    payload?: Record<string, unknown> | undefined;
+}>;
+export interface InteractiveRelay {
+    /**
+     * Emit one interactive event onto the bus. Returns true on success (or on WB-002, a duplicate
+     * key — the emit already happened); logs and returns false otherwise. Never throws.
+     */
+    emitInteractive(type: string, payload: Record<string, unknown>, idempotencyKey: string): boolean;
+    stop(): Promise<void>;
+}
+export interface InteractiveRelayOptions {
+    /** Bus db path; omit for wicked-bus's own resolution (honors WICKED_BUS_DATA_DIR). */
+    dbPath?: string;
+    /** Poll cadence for the relay subscriber, ms (tests shorten it). */
+    pollIntervalMs?: number;
+    log?: (msg: string) => void;
+}
+/**
+ * Open the bus and arm both halves. Returns `null` (logged) when wicked-bus is not importable or
+ * the db cannot open — the caller degrades to a daemon whose `/ws` simply carries no interactive
+ * frames, exactly as before this slice.
+ */
+export declare function startInteractiveWsRelay(opts?: InteractiveRelayOptions): Promise<InteractiveRelay | null>;
+/** Occurrence-unique, type-inclusive (DES-EXEC-001 rev0.2 #4a): two types sharing a key would
+ *  silently drop one on the bus's UNIQUE constraint, and every UI emission is a new fact. */
+export declare function interactiveEmitKey(projectId: string, type: string): string;
+/**
+ * `POST /api/v1/projects/:projectId/interactive-events` — the UI-emittable direction (§6.1).
+ * Registered even when the relay is null, so the failure is an honest 503 rather than a 404 that
+ * reads like "this daemon doesn't have the feature".
+ */
+export declare function registerInteractiveEventRoutes(app: FastifyInstance, relay: InteractiveRelay | null): void;
+//# sourceMappingURL=ws-relay.d.ts.map

package/dist/interactive/ws-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-relay.d.ts","sourceRoot":"","sources":["../../src/interactive/ws-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;iEACiE;AACjE,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAG5C,CAAC;AAEF;2CAC2C;AAC3C,eAAO,MAAM,0BAA0B;;;;;;;;;EAK5B,CAAC;AAEZ,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;IACjG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAgGlC;AAED;6FAC6F;AAC7F,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAC7B,IAAI,CAmCN"}

package/dist/interactive/ws-relay.js

@@ -0,0 +1,191 @@
+/**
+ * DES-MERGE-001 §5.4 / §6.1 (slice 3) — the `wicked.interactive.*` ↔ `/ws` relay.
+ *
+ * wicked-studio is absorbing wicked-interactive. The SPA already holds crew's `/ws` socket for
+ * CoreEvent frames; interactive's own progress travels on the wicked-bus. This module bridges the
+ * two so the skin needs exactly ONE socket — no second websocket, no new port.
+ *
+ * Two halves, one bus handle:
+ *
+ * 1. RELAY (bus → /ws). Subscribe to `wicked.interactive.**` and rebroadcast each event as
+ *    `{ type: 'interactiveEvent', event: <the full bus event> }` — ONE envelope type, the original
+ *    event nested whole, no field renaming, no project filter. Ordering is as received (the bus
+ *    hands a batch to the handler in order and `broadcast` is synchronous), and there is no
+ *    buffering beyond what the existing broadcast path already does.
+ *
+ * 2. EMIT (/ws client → bus). `POST /projects/:projectId/interactive-events` validates the body
+ *    against a SERVER-SIDE whitelist ({@link EMITTABLE_TYPES}) and puts the event on the bus with
+ *    interactive's own envelope conventions (domain `wicked-interactive`, producer `wi-crew`,
+ *    `ts`-stamped payload — draft-events.ts is the precedent), so interactive's own subscribers
+ *    see a UI-originated event exactly as they see a service-originated one.
+ *
+ * Deliberately DISTINCT from the `projectActivity` bridge in projects/events.ts, which reads the
+ * same filter: that one is project-FILTERED and reshapes the event into an activity frame for a
+ * project view. This one is unfiltered and verbatim, because the studio's document canvas must see
+ * the events of a doc that was never filed under a project. Separate plugin identity → separate
+ * durable cursor, so neither seam can strand the other.
+ *
+ * Posture mirrors every other bus seam here: LOUD-non-fatal. No wicked-bus, or a broken db → the
+ * factory logs once and returns null, the daemon boots without the relay, and the POST route
+ * answers 503 instead of pretending the emit landed.
+ */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { broadcast } from '../events/bus.js';
+import { API_PREFIX } from '../api/api-prefix.js';
+import { LOCAL_ACTOR } from '../api/auth.js';
+import { INTERACTIVE_DOMAIN, INTERACTIVE_PRODUCER } from './draft-events.js';
+const V = API_PREFIX;
+/** Dedicated durable-cursor identity — NOT the projects bridge's, so the two seams that read
+ *  `wicked.interactive.**` advance independent cursors. */
+const RELAY_PLUGIN = 'wicked-crew-interactive-relay';
+const RELAY_FILTER = 'wicked.interactive.**';
+/** The scope guard, restated locally: the property "only interactive events are relayed" is this
+ *  module's, not the bus glob's. */
+const RELAY_TYPE_PREFIX = 'wicked.interactive.';
+/** The ONE envelope type this relay puts on `/ws`. Consumers that don't know it ignore it — the
+ *  CoreEvent contract is additive-safe (DES-STUDIO-001 §2.1). */
+export const INTERACTIVE_EVENT_FRAME = 'interactiveEvent';
+/**
+ * Server-side whitelist of the event types a `/ws` client may emit through
+ * `POST /projects/:projectId/interactive-events`. A non-whitelisted type is a 400 that NAMES this
+ * array — the UI never has to guess. Extend here; nothing else needs to change.
+ */
+export const EMITTABLE_TYPES = [
+    'wicked.interactive.feedback.submitted',
+    'wicked.interactive.status.requested',
+];
+/** The request body: a whitelisted type plus that type's own payload. Strict — an unknown key is
+ *  a 400, not a silently-dropped field. */
+export const EmitInteractiveEventSchema = z
+    .object({
+    type: z.string().min(1).max(128),
+    payload: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+/**
+ * Open the bus and arm both halves. Returns `null` (logged) when wicked-bus is not importable or
+ * the db cannot open — the caller degrades to a daemon whose `/ws` simply carries no interactive
+ * frames, exactly as before this slice.
+ */
+export async function startInteractiveWsRelay(opts = {}) {
+    const log = opts.log ?? (() => undefined);
+    let bus;
+    try {
+        bus = await import('wicked-bus');
+    }
+    catch (err) {
+        log(`[interactive-relay] wicked-bus is not importable — the interactive /ws relay is disabled: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    let db;
+    let config;
+    try {
+        const override = opts.dbPath !== undefined ? { db_path: opts.dbPath } : {};
+        config = bus.loadConfig(override);
+        db = bus.openDb(override);
+    }
+    catch (err) {
+        log(`[interactive-relay] could not open the bus db${opts.dbPath !== undefined ? ` at ${opts.dbPath}` : ''} — the interactive /ws relay is disabled: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    // Half 1 — bus → /ws. maxRetries: 0 for the same reason the projects bridge uses it: a retry
+    // loop or a DLQ entry for a lost liveness frame is noise, and the durable feed is the record.
+    //
+    // This subscription also sees the events emitted by half 2 (they match the same filter). That
+    // is not a loop — the relay only broadcasts, never re-emits — and the echo is the UI's
+    // confirmation that its own emission actually landed on the bus.
+    let subscription = null;
+    try {
+        subscription = bus.subscribe({
+            db,
+            plugin: RELAY_PLUGIN,
+            filter: RELAY_FILTER,
+            cursor_init: 'latest',
+            pollIntervalMs: opts.pollIntervalMs ?? 2000,
+            maxRetries: 0,
+            handler: (event) => {
+                if (!event.event_type.startsWith(RELAY_TYPE_PREFIX))
+                    return;
+                broadcast({ type: INTERACTIVE_EVENT_FRAME, event });
+            },
+            onError: (err, event) => {
+                log(`[interactive-relay] relay error on event ${String(event?.event_id ?? '?')}: ${err.message}`);
+            },
+        });
+    }
+    catch (err) {
+        log(`[interactive-relay] could not arm the /ws relay subscriber (the emit direction still works): ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Half 2 — the emit surface the POST route calls after the whitelist check. The subdomain is
+    // the third segment of interactive's own type grammar (`wicked.interactive.<subdomain>.<verb>`).
+    function emitInteractive(type, payload, idempotencyKey) {
+        try {
+            bus.emit(db, config, {
+                event_type: type,
+                domain: INTERACTIVE_DOMAIN,
+                subdomain: type.split('.')[2] ?? 'status',
+                payload: { ts: new Date().toISOString(), ...payload },
+                producer_id: INTERACTIVE_PRODUCER,
+                idempotency_key: idempotencyKey,
+            });
+            return true;
+        }
+        catch (err) {
+            const code = err.error;
+            if (code === 'WB-002')
+                return true; // duplicate key — the emit already happened
+            log(`[interactive-relay] emit ${type} failed: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
+    return {
+        emitInteractive,
+        stop: async () => {
+            if (subscription !== null)
+                await subscription.stop();
+        },
+    };
+}
+/** Occurrence-unique, type-inclusive (DES-EXEC-001 rev0.2 #4a): two types sharing a key would
+ *  silently drop one on the bus's UNIQUE constraint, and every UI emission is a new fact. */
+export function interactiveEmitKey(projectId, type) {
+    return `crew:interactive.ui:${projectId}:${type}:${randomUUID()}`;
+}
+/**
+ * `POST /api/v1/projects/:projectId/interactive-events` — the UI-emittable direction (§6.1).
+ * Registered even when the relay is null, so the failure is an honest 503 rather than a 404 that
+ * reads like "this daemon doesn't have the feature".
+ */
+export function registerInteractiveEventRoutes(app, relay) {
+    const actorOf = (req) => req.actor ?? LOCAL_ACTOR;
+    app.post(`${V}/projects/:projectId/interactive-events`, async (req, reply) => {
+        const { projectId } = req.params;
+        const parsed = EmitInteractiveEventSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return reply.code(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+        }
+        const { type } = parsed.data;
+        if (!EMITTABLE_TYPES.includes(type)) {
+            return reply.code(400).send({
+                error: `Event type '${type}' is not emittable from a client`,
+                allowed: EMITTABLE_TYPES,
+            });
+        }
+        if (relay === null) {
+            return reply
+                .code(503)
+                .send({ error: 'the interactive bus seam is not armed on this daemon' });
+        }
+        // Server-side fields go LAST: `project_id` and `actor` are the daemon's to state, never the
+        // caller's (task #88 — event actors are not caller-supplied), so a payload that names either
+        // one cannot override them.
+        const idempotencyKey = interactiveEmitKey(projectId, type);
+        const emitted = relay.emitInteractive(type, { ...(parsed.data.payload ?? {}), project_id: projectId, actor: actorOf(req).id }, idempotencyKey);
+        if (!emitted) {
+            return reply.code(502).send({ error: `the bus refused the ${type} emit` });
+        }
+        return reply.code(202).send({ emitted: true, type, projectId, idempotencyKey });
+    });
+}
+//# sourceMappingURL=ws-relay.js.map

package/dist/interactive/ws-relay.js.map

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