studiograph 1.3.3 → 1.3.4

package/dist/server/ws-hub.js

@@ -0,0 +1,250 @@
+/**
+ * WebSocket Hub — event bus for real-time change notifications.
+ *
+ * Tracks authenticated WebSocket connections and broadcasts entity/repo
+ * change events scoped to each client's collection access.
+ */
+const PRESENCE_STALE_MS = 90_000; // 90s — heartbeat every 30s, so 3 missed = gone
+/** Assign a stable color to a user based on their id. */
+const PRESENCE_COLORS = ['#4f8ef7', '#e05252', '#52c27d', '#e0a252', '#9b52e0', '#52bde0'];
+function presenceColor(userId) {
+    let hash = 0;
+    for (let i = 0; i < userId.length; i++)
+        hash = (hash * 31 + userId.charCodeAt(i)) | 0;
+    return PRESENCE_COLORS[Math.abs(hash) % PRESENCE_COLORS.length];
+}
+export class WsHub {
+    clients = new Set();
+    heartbeatTimer = null;
+    // entityKey → Map<userId, PresenceEntry>
+    presenceMap = new Map();
+    // userId → { user info, connection count } for online tracking
+    onlineMap = new Map();
+    constructor() {
+        // Ping all clients every 30s; terminate any that haven't responded in 90s.
+        // Uses application-level ping/pong (JSON messages) instead of WS ping frames
+        // because Railway's proxy answers WS ping frames on behalf of sleeping clients.
+        this.heartbeatTimer = setInterval(() => {
+            const now = Date.now();
+            for (const client of this.clients) {
+                if (client.ws.readyState !== 1 /* OPEN */) {
+                    this.clients.delete(client);
+                    continue;
+                }
+                if (now - client.lastPongAt > 90_000) {
+                    client.ws.terminate();
+                    this.clients.delete(client);
+                    continue;
+                }
+                try {
+                    client.ws.send(JSON.stringify({ type: 'ping' }));
+                }
+                catch { /* non-fatal */ }
+            }
+            // Clean stale presence
+            for (const [entityKey, users] of this.presenceMap) {
+                for (const [userId, entry] of users) {
+                    if (now - entry.lastSeen > PRESENCE_STALE_MS) {
+                        users.delete(userId);
+                        // No broadcast needed — clients will expire stale entries themselves
+                    }
+                }
+                if (users.size === 0)
+                    this.presenceMap.delete(entityKey);
+            }
+        }, 30_000);
+    }
+    addClient(ws, user, collections) {
+        const client = {
+            ws,
+            user,
+            collections: collections ? new Set(collections) : null,
+            lastPongAt: Date.now(),
+        };
+        this.clients.add(client);
+        // Track online status (ref-counted for multiple tabs)
+        if (user) {
+            const uid = String(user.id);
+            const existing = this.onlineMap.get(uid);
+            if (existing) {
+                existing.count++;
+            }
+            else {
+                const onlineUser = { id: uid, name: user.displayName };
+                this.onlineMap.set(uid, { user: onlineUser, count: 1 });
+                this.broadcastOnline('join', onlineUser, ws); // broadcast to others (not new client)
+            }
+            this.sendOnlineSnapshot(ws); // send current online roster to new client
+        }
+        ws.on('close', () => {
+            this.clients.delete(client);
+            if (user) {
+                const uid = String(user.id);
+                const entry = this.onlineMap.get(uid);
+                if (entry) {
+                    entry.count--;
+                    if (entry.count === 0) {
+                        this.onlineMap.delete(uid);
+                        this.broadcastOnline('leave', entry.user);
+                    }
+                }
+                this.clearUserPresence(uid, user.displayName, collections);
+            }
+        });
+        ws.on('error', () => this.clients.delete(client));
+    }
+    /**
+     * Handle a presence message sent by a client.
+     * Updates server-side presence state and broadcasts to collection peers.
+     */
+    handlePresence(action, repo, entityType, entityId, user) {
+        const entityKey = `${repo}/${entityType}/${entityId}`;
+        const color = user.color ?? presenceColor(user.id);
+        if (action === 'leave') {
+            const users = this.presenceMap.get(entityKey);
+            if (users) {
+                users.delete(user.id);
+                if (users.size === 0)
+                    this.presenceMap.delete(entityKey);
+            }
+        }
+        else {
+            // enter or heartbeat
+            if (!this.presenceMap.has(entityKey)) {
+                this.presenceMap.set(entityKey, new Map());
+            }
+            this.presenceMap.get(entityKey).set(user.id, {
+                user: { id: user.id, name: user.name, color },
+                lastSeen: Date.now(),
+            });
+        }
+        this.broadcast({
+            type: 'presence',
+            action,
+            repo,
+            entityType,
+            entityId,
+            user: { id: user.id, name: user.name, color },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /** Return current presence for an entity (for initial state on connect). */
+    getPresence(repo, entityType, entityId) {
+        const entityKey = `${repo}/${entityType}/${entityId}`;
+        const users = this.presenceMap.get(entityKey);
+        if (!users)
+            return [];
+        return Array.from(users.values()).map(e => e.user);
+    }
+    /** Send the full current presence map to a single newly connected client. */
+    sendPresenceSnapshot(ws, collections) {
+        const now = new Date().toISOString();
+        for (const [entityKey, users] of this.presenceMap) {
+            const [repo, entityType, entityId] = entityKey.split('/');
+            if (!repo || !entityType || !entityId)
+                continue;
+            if (collections && !collections.has(repo))
+                continue;
+            for (const entry of users.values()) {
+                ws.send(JSON.stringify({
+                    type: 'presence',
+                    action: 'enter',
+                    repo,
+                    entityType,
+                    entityId,
+                    user: entry.user,
+                    timestamp: now,
+                }));
+            }
+        }
+    }
+    broadcastOnline(action, user, exclude) {
+        const payload = JSON.stringify({ type: 'online', action, user, timestamp: new Date().toISOString() });
+        for (const client of this.clients) {
+            if (client.ws.readyState !== 1 /* OPEN */ || client.ws === exclude)
+                continue;
+            client.ws.send(payload);
+        }
+    }
+    sendOnlineSnapshot(ws) {
+        const now = new Date().toISOString();
+        for (const { user } of this.onlineMap.values()) {
+            ws.send(JSON.stringify({ type: 'online', action: 'join', user, timestamp: now }));
+        }
+    }
+    clearUserPresence(userId, userName, collections) {
+        for (const [entityKey, users] of this.presenceMap) {
+            if (users.has(userId)) {
+                users.delete(userId);
+                const [repo, entityType, entityId] = entityKey.split('/');
+                if (repo && entityType && entityId) {
+                    this.broadcast({
+                        type: 'presence', action: 'leave',
+                        repo, entityType, entityId,
+                        user: { id: userId, name: userName },
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+                if (users.size === 0)
+                    this.presenceMap.delete(entityKey);
+            }
+        }
+    }
+    broadcast(event) {
+        const payload = JSON.stringify(event);
+        for (const client of this.clients) {
+            if (client.ws.readyState !== 1 /* OPEN */)
+                continue;
+            if (!this.canReceive(client, event.repo))
+                continue;
+            client.ws.send(payload);
+        }
+    }
+    /** Send an event directly to all connections belonging to a specific user, bypassing repo filtering. */
+    broadcastToUser(userId, event) {
+        const payload = JSON.stringify(event);
+        for (const client of this.clients) {
+            if (client.ws.readyState !== 1 /* OPEN */)
+                continue;
+            if (!client.user || String(client.user.id) !== userId)
+                continue;
+            client.ws.send(payload);
+        }
+    }
+    /** Record an app-level pong from a client (called by ws route on message). */
+    handlePong(ws) {
+        for (const client of this.clients) {
+            if (client.ws === ws) {
+                client.lastPongAt = Date.now();
+                break;
+            }
+        }
+    }
+    /** Iterate over all connected client sockets (for collab broadcasting). */
+    forEachSocket(fn) {
+        for (const client of this.clients) {
+            if (client.ws.readyState === 1 /* OPEN */)
+                fn(client.ws);
+        }
+    }
+    get connectionCount() {
+        return this.clients.size;
+    }
+    destroy() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        for (const client of this.clients) {
+            client.ws.close();
+        }
+        this.clients.clear();
+    }
+    canReceive(client, repo) {
+        // Open mode or null collections = receives everything
+        if (!client.collections)
+            return true;
+        return client.collections.has(repo);
+    }
+}
+//# sourceMappingURL=ws-hub.js.map

package/dist/server/ws-hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-hub.js","sourceRoot":"","sources":["../../src/server/ws-hub.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiHH,MAAM,iBAAiB,GAAG,MAAM,CAAC,CAAC,gDAAgD;AAElF,yDAAyD;AACzD,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAC3F,SAAS,aAAa,CAAC,MAAc;IACnC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtF,OAAO,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,OAAO,KAAK;IACR,OAAO,GAAG,IAAI,GAAG,EAAY,CAAC;IAC9B,cAAc,GAA0C,IAAI,CAAC;IACrE,yCAAyC;IACjC,WAAW,GAAG,IAAI,GAAG,EAAsC,CAAC;IACpE,+DAA+D;IACvD,SAAS,GAAG,IAAI,GAAG,EAAiE,CAAC;IAE7F;QACE,2EAA2E;QAC3E,6EAA6E;QAC7E,gFAAgF;QAChF,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;YACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAClC,IAAI,MAAM,CAAC,EAAE,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,EAAE,CAAC;oBAC1C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBAC5B,SAAS;gBACX,CAAC;gBACD,IAAI,GAAG,GAAG,MAAM,CAAC,UAAU,GAAG,MAAM,EAAE,CAAC;oBACrC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC;oBACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBAC5B,SAAS;gBACX,CAAC;gBACD,IAAI,CAAC;oBAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC;YACrF,CAAC;YACD,uBAAuB;YACvB,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBAClD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;oBACpC,IAAI,GAAG,GAAG,KAAK,CAAC,QAAQ,GAAG,iBAAiB,EAAE,CAAC;wBAC7C,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;wBACrB,qEAAqE;oBACvE,CAAC;gBACH,CAAC;gBACD,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;oBAAE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC,EAAE,MAAM,CAAC,CAAC;IACb,CAAC;IAED,SAAS,CAAC,EAAa,EAAE,IAAqB,EAAE,WAA4B;QAC1E,MAAM,MAAM,GAAa;YACvB,EAAE;YACF,IAAI;YACJ,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI;YACtD,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;SACvB,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAEzB,sDAAsD;QACtD,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACzC,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACN,MAAM,UAAU,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;gBACvD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;gBACxD,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,uCAAuC;YACvF,CAAC;YACD,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC,CAAC,2CAA2C;QAC1E,CAAC;QAED,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAClB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5B,IAAI,IAAI,EAAE,CAAC;gBACT,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACtC,IAAI,KAAK,EAAE,CAAC;oBACV,KAAK,CAAC,KAAK,EAAE,CAAC;oBACd,IAAI,KAAK,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;wBACtB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;wBAC3B,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;oBAC5C,CAAC;gBACH,CAAC;gBACD,IAAI,CAAC,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC,CAAC,CAAC;QACH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;OAGG;IACH,cAAc,CACZ,MAAuC,EACvC,IAAY,EACZ,UAAkB,EAClB,QAAgB,EAChB,IAAkD;QAElD,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEnD,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC9C,IAAI,KAAK,EAAE,CAAC;gBACV,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACtB,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;oBAAE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;aAAM,CAAC;YACN,qBAAqB;YACrB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBACrC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;YAC7C,CAAC;YACD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE;gBAC5C,IAAI,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;gBAC7C,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE;aACrB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,SAAS,CAAC;YACb,IAAI,EAAE,UAAU;YAChB,MAAM;YACN,IAAI;YACJ,UAAU;YACV,QAAQ;YACR,IAAI,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAC7C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,WAAW,CAAC,IAAY,EAAE,UAAkB,EAAE,QAAgB;QAC5D,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IAED,6EAA6E;IAC7E,oBAAoB,CAAC,EAAa,EAAE,WAA+B;QACjE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAClD,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC1D,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,QAAQ;gBAAE,SAAS;YAChD,IAAI,WAAW,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACpD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBACnC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;oBACrB,IAAI,EAAE,UAAU;oBAChB,MAAM,EAAE,OAAO;oBACf,IAAI;oBACJ,UAAU;oBACV,QAAQ;oBACR,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,SAAS,EAAE,GAAG;iBACf,CAAC,CAAC,CAAC;YACN,CAAC;QACH,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,MAAwB,EAAE,IAAkC,EAAE,OAAmB;QACvG,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACtG,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,EAAE,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,IAAI,MAAM,CAAC,EAAE,KAAK,OAAO;gBAAE,SAAS;YAC7E,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAEO,kBAAkB,CAAC,EAAa;QACtC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/C,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IAEO,iBAAiB,CAAC,MAAc,EAAE,QAAgB,EAAE,WAA4B;QACtF,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAClD,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACtB,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACrB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;gBAC1D,IAAI,IAAI,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;oBACnC,IAAI,CAAC,SAAS,CAAC;wBACb,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO;wBACjC,IAAI,EAAE,UAAU,EAAE,QAAQ;wBAC1B,IAAI,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;wBACpC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;qBACpC,CAAC,CAAC;gBACL,CAAC;gBACD,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;oBAAE,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,CAAC,KAAc;QACtB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACtC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,EAAE,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;gBAAE,SAAS;YACpD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAG,KAAa,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC5D,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,wGAAwG;IACxG,eAAe,CAAC,MAAc,EAAE,KAAc;QAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACtC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,EAAE,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;gBAAE,SAAS;YACpD,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,MAAM;gBAAE,SAAS;YAChE,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,UAAU,CAAC,EAAa;QACtB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;gBACrB,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC/B,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,aAAa,CAAC,EAA2B;QACvC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,EAAE,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;gBAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,OAAO;QACL,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YACnC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAEO,UAAU,CAAC,MAAgB,EAAE,IAAY;QAC/C,sDAAsD;QACtD,IAAI,CAAC,MAAM,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QACrC,OAAO,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/server/yjs-manager.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Server-side Y.Doc manager for collaborative editing.
+ *
+ * Maintains one Y.Doc per actively edited entity. The server is the single
+ * seeding authority — it loads entity content from disk into the Y.Doc when
+ * the first client connects. Clients start with empty Y.Docs and receive
+ * content via the Yjs sync protocol. This prevents the double-seeding bug
+ * where two clients independently insert the same content.
+ *
+ * Lifecycle:
+ * 1. First client opens entity → server creates Y.Doc, seeds from disk
+ * 2. Server sends sync-step-1 to client → client responds → both converge
+ * 3. Client edits → binary update to server → server applies + relays to peers
+ * 4. Last client leaves → server destroys Y.Doc (frees memory)
+ */
+import type { WorkspaceManager } from '../core/workspace-manager.js';
+export declare class YjsManager {
+    private workspaceManager;
+    private docs;
+    constructor(workspaceManager: WorkspaceManager);
+    /**
+     * Parse a docName ("repo/entityType/entityId") into its components.
+     */
+    private parseDocName;
+    /**
+     * Get or create a Y.Doc for an entity. Seeds from disk on first access.
+     */
+    private getOrCreate;
+    /**
+     * Add a client to a document. Sends initial sync state to the client.
+     */
+    addClient(docName: string, ws: import('ws').WebSocket): void;
+    /**
+     * Remove a client from a document. Destroys Y.Doc when last client leaves.
+     */
+    removeClient(docName: string, ws: import('ws').WebSocket): void;
+    /**
+     * Remove a client from ALL documents (called on WS close).
+     */
+    removeClientFromAll(ws: import('ws').WebSocket): void;
+    /**
+     * Handle a binary Yjs message from a client.
+     * Applies sync messages to the server Y.Doc and relays to peers.
+     * Awareness messages are relayed without server processing.
+     */
+    handleMessage(docName: string, sender: import('ws').WebSocket, msgType: number, payload: Uint8Array): void;
+    /**
+     * Encode and send a framed binary message to a client.
+     */
+    private sendToClient;
+    /**
+     * Get current Y.Doc text content for a document (for debugging/autosave).
+     */
+    getText(docName: string): string | null;
+    /**
+     * Destroy all Y.Docs (server shutdown).
+     */
+    destroy(): void;
+}

package/dist/server/yjs-manager.js

@@ -0,0 +1,194 @@
+/**
+ * Server-side Y.Doc manager for collaborative editing.
+ *
+ * Maintains one Y.Doc per actively edited entity. The server is the single
+ * seeding authority — it loads entity content from disk into the Y.Doc when
+ * the first client connects. Clients start with empty Y.Docs and receive
+ * content via the Yjs sync protocol. This prevents the double-seeding bug
+ * where two clients independently insert the same content.
+ *
+ * Lifecycle:
+ * 1. First client opens entity → server creates Y.Doc, seeds from disk
+ * 2. Server sends sync-step-1 to client → client responds → both converge
+ * 3. Client edits → binary update to server → server applies + relays to peers
+ * 4. Last client leaves → server destroys Y.Doc (frees memory)
+ */
+import * as Y from 'yjs';
+import * as syncProtocol from 'y-protocols/sync.js';
+import * as awarenessProtocol from 'y-protocols/awareness.js';
+import * as encoding from 'lib0/encoding';
+import * as decoding from 'lib0/decoding';
+const MSG_SYNC = 0;
+const MSG_AWARENESS = 1;
+export class YjsManager {
+    workspaceManager;
+    docs = new Map();
+    constructor(workspaceManager) {
+        this.workspaceManager = workspaceManager;
+    }
+    /**
+     * Parse a docName ("repo/entityType/entityId") into its components.
+     */
+    parseDocName(docName) {
+        const parts = docName.split('/');
+        if (parts.length < 3)
+            return null;
+        return { repo: parts[0], entityType: parts[1], entityId: parts.slice(2).join('/') };
+    }
+    /**
+     * Get or create a Y.Doc for an entity. Seeds from disk on first access.
+     */
+    getOrCreate(docName) {
+        const existing = this.docs.get(docName);
+        if (existing)
+            return existing;
+        // Load entity content from disk
+        const parsed = this.parseDocName(docName);
+        if (!parsed)
+            return null;
+        const graph = this.workspaceManager.getGraph(parsed.repo);
+        if (!graph)
+            return null;
+        let diskContent = '';
+        try {
+            const entity = graph.get(parsed.entityType, parsed.entityId);
+            diskContent = entity?.document?.content ?? '';
+        }
+        catch {
+            // Entity not found — start with empty doc
+        }
+        const ydoc = new Y.Doc();
+        const ytext = ydoc.getText('content');
+        const awareness = new awarenessProtocol.Awareness(ydoc);
+        // Seed Y.Doc with disk content (server is the single seeding authority)
+        if (diskContent.length > 0) {
+            ydoc.transact(() => {
+                ytext.insert(0, diskContent);
+            }, 'server-seed');
+        }
+        const entry = { ydoc, awareness, clients: new Set() };
+        this.docs.set(docName, entry);
+        return entry;
+    }
+    /**
+     * Add a client to a document. Sends initial sync state to the client.
+     */
+    addClient(docName, ws) {
+        const entry = this.getOrCreate(docName);
+        if (!entry)
+            return;
+        entry.clients.add(ws);
+        // Send sync-step-1 to the new client (our state vector)
+        // so the client can respond with what we're missing (sync-step-2)
+        const encoder = encoding.createEncoder();
+        syncProtocol.writeSyncStep1(encoder, entry.ydoc);
+        this.sendToClient(ws, docName, MSG_SYNC, encoding.toUint8Array(encoder));
+        // Also send sync-step-2 immediately (our full state)
+        // so the client gets our content without a round trip
+        const encoder2 = encoding.createEncoder();
+        syncProtocol.writeSyncStep2(encoder2, entry.ydoc);
+        this.sendToClient(ws, docName, MSG_SYNC, encoding.toUint8Array(encoder2));
+        // Send current awareness states to the new client
+        const awarenessStates = entry.awareness.getStates();
+        if (awarenessStates.size > 0) {
+            const clients = Array.from(awarenessStates.keys());
+            const update = awarenessProtocol.encodeAwarenessUpdate(entry.awareness, clients);
+            this.sendToClient(ws, docName, MSG_AWARENESS, update);
+        }
+    }
+    /**
+     * Remove a client from a document. Destroys Y.Doc when last client leaves.
+     */
+    removeClient(docName, ws) {
+        const entry = this.docs.get(docName);
+        if (!entry)
+            return;
+        entry.clients.delete(ws);
+        if (entry.clients.size === 0) {
+            entry.awareness.destroy();
+            entry.ydoc.destroy();
+            this.docs.delete(docName);
+        }
+    }
+    /**
+     * Remove a client from ALL documents (called on WS close).
+     */
+    removeClientFromAll(ws) {
+        for (const [docName, entry] of this.docs) {
+            if (entry.clients.has(ws)) {
+                this.removeClient(docName, ws);
+            }
+        }
+    }
+    /**
+     * Handle a binary Yjs message from a client.
+     * Applies sync messages to the server Y.Doc and relays to peers.
+     * Awareness messages are relayed without server processing.
+     */
+    handleMessage(docName, sender, msgType, payload) {
+        const entry = this.docs.get(docName);
+        if (!entry)
+            return;
+        if (msgType === MSG_SYNC) {
+            // Apply sync message to server Y.Doc
+            const decoder = decoding.createDecoder(payload);
+            const encoder = encoding.createEncoder();
+            syncProtocol.readSyncMessage(decoder, encoder, entry.ydoc, 'ws-client');
+            // If the sync produced a response, send it back to the sender
+            if (encoding.length(encoder) > 0) {
+                this.sendToClient(sender, docName, MSG_SYNC, encoding.toUint8Array(encoder));
+            }
+            // Relay the original message to all OTHER clients
+            for (const client of entry.clients) {
+                if (client === sender || client.readyState !== 1)
+                    continue;
+                this.sendToClient(client, docName, MSG_SYNC, payload);
+            }
+        }
+        else if (msgType === MSG_AWARENESS) {
+            // Apply awareness to server's awareness instance
+            awarenessProtocol.applyAwarenessUpdate(entry.awareness, payload, sender);
+            // Relay to all OTHER clients
+            for (const client of entry.clients) {
+                if (client === sender || client.readyState !== 1)
+                    continue;
+                this.sendToClient(client, docName, MSG_AWARENESS, payload);
+            }
+        }
+    }
+    /**
+     * Encode and send a framed binary message to a client.
+     */
+    sendToClient(ws, docName, msgType, payload) {
+        const nameBytes = Buffer.from(docName, 'utf8');
+        const frame = Buffer.alloc(2 + nameBytes.length + 1 + payload.length);
+        frame.writeUInt16BE(nameBytes.length, 0);
+        nameBytes.copy(frame, 2);
+        frame[2 + nameBytes.length] = msgType;
+        Buffer.from(payload).copy(frame, 2 + nameBytes.length + 1);
+        try {
+            ws.send(frame);
+        }
+        catch { /* non-fatal */ }
+    }
+    /**
+     * Get current Y.Doc text content for a document (for debugging/autosave).
+     */
+    getText(docName) {
+        const entry = this.docs.get(docName);
+        if (!entry)
+            return null;
+        return entry.ydoc.getText('content').toString();
+    }
+    /**
+     * Destroy all Y.Docs (server shutdown).
+     */
+    destroy() {
+        for (const [, entry] of this.docs) {
+            entry.awareness.destroy();
+            entry.ydoc.destroy();
+        }
+        this.docs.clear();
+    }
+}
+//# sourceMappingURL=yjs-manager.js.map

package/dist/server/yjs-manager.js.map

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

package/dist/services/auth-service.d.ts

@@ -3,6 +3,11 @@
  *
  * SQLite-backed user store with bcrypt password hashing and JWT sessions.
  * Database lives at .studiograph/auth.db inside the workspace.
+ *
+ * Auth state is portable via .studiograph/auth-seed.json — a JSON export of
+ * all users (with bcrypt hashes) and the JWT secret. The seed file is
+ * committed to the config repo so it syncs between local and Railway:
+ *   local setup → commit → push → Railway redeploy → users restored from seed
  */
 export interface AuthUser {
     id: number;
@@ -11,9 +16,26 @@ export interface AuthUser {
     role: 'admin' | 'member';
     createdAt: string;
 }
+export interface AuthSeed {
+    jwtSecret: string;
+    apiKey?: string;
+    users: Array<{
+        email: string;
+        password_hash: string;
+        display_name: string;
+        role: string;
+        created_at: string;
+    }>;
+    collection_access?: Array<{
+        user_email: string;
+        collection_name: string;
+    }>;
+}
 export declare class AuthService {
     private db;
     private jwtSecret;
+    private apiKey;
+    private sgDir;
     constructor(workspacePath: string);
     createUser(email: string, password: string, displayName: string, role?: 'admin' | 'member'): AuthUser;
     authenticate(email: string, password: string): {
@@ -24,8 +46,60 @@ export declare class AuthService {
     listUsers(): AuthUser[];
     deleteUser(email: string): boolean;
     updatePassword(email: string, newPassword: string): boolean;
+    grantCollectionAccess(userId: number, collectionName: string): void;
+    revokeCollectionAccess(userId: number, collectionName: string): void;
+    getUserCollections(userId: number): string[];
+    getCollectionUsers(collectionName: string): AuthUser[];
+    renameCollection(oldName: string, newName: string): void;
+    /** Get stored OAuth data (tokens, clientInfo, codeVerifier) for a user+connector. */
+    getOAuthData(userId: number, connectorName: string): Record<string, any> | null;
+    /** Save OAuth data (upsert). */
+    saveOAuthData(userId: number, connectorName: string, data: Record<string, any>): void;
+    /** Clear OAuth data for a user+connector. */
+    clearOAuthData(userId: number, connectorName: string): void;
+    /** Check if a user has OAuth tokens for a connector. */
+    hasOAuthTokens(userId: number, connectorName: string): boolean;
     hasUsers(): boolean;
     getUserCount(): number;
+    /** Get the workspace API key (for MCP and programmatic access). */
+    getApiKey(): string;
+    /** Check whether the given string matches the workspace API key. */
+    validateApiKey(key: string): boolean;
+    /**
+     * Ensure the current API key is present in auth-seed.json and pushed to the
+     * config repo. Called on server startup so the key is always reachable by CLI.
+     * Non-fatal — never throws.
+     */
+    syncApiKeyToSeed(): void;
+    /** Regenerate the workspace API key. Returns the new key. */
+    regenerateApiKey(): string;
+    /**
+     * Ensure auth.db and auth-secret are in .studiograph/.gitignore.
+     * Only the seed JSON file should be committed to the config repo.
+     */
+    private ensureGitignore;
+    /**
+     * Build and return the current auth seed data (users + JWT secret + collection access).
+     * Does not write to disk — use exportSeed() for that.
+     */
+    getSeedData(): AuthSeed;
+    /**
+     * Export all users and JWT secret to .studiograph/auth-seed.json.
+     * If .studiograph/ is a git repo with a remote, auto-commits and pushes
+     * the seed file so it syncs between environments.
+     */
+    exportSeed(): void;
+    /**
+     * Commit and push auth-seed.json if .studiograph/ is a git repo with a remote.
+     * Non-fatal — logs warnings on failure but never throws.
+     */
+    private pushSeed;
+    /**
+     * Import users and JWT secret from .studiograph/auth-seed.json.
+     * Uses INSERT OR IGNORE so it's safe to call on non-empty databases
+     * (e.g. after `studiograph pull` brings a new seed file).
+     */
+    applySeed(): void;
     close(): void;
     private toAuthUser;
 }