mcard-studio 0.0.0-stage → 0.0.2

package/src/server/handlers/webrtcHandler.mjs

@@ -0,0 +1,62 @@
+import { WS_MESSAGE_TYPES } from '../../shared/wsProtocol.js';
+import os from 'os';
+
+function extractHostname(remoteAddress) {
+    if (!remoteAddress) return 'unknown';
+    // Try to extract hostname from IP
+    // For local network, return a friendly name
+    if (remoteAddress.includes('127.0.0.1') || remoteAddress.includes('::1')) {
+        return os.hostname().split('.')[0];
+    }
+    return remoteAddress;
+}
+
+export function createWebrtcHandler({ clients }) {
+    return async (ws, clientId, payload) => {
+        const { type } = payload;
+
+        if (type === WS_MESSAGE_TYPES.GET_PEERS) {
+            const peers = [];
+            for (const [id, client] of clients.entries()) {
+                if (client.did && client.isActive) {
+                    peers.push({
+                        clientId: id,
+                        did: client.did,
+                        userAgent: client.info?.userAgent,
+                        remoteAddress: client.info?.remoteAddress,
+                        hostname: client.info?.hostname || extractHostname(client.info?.remoteAddress)
+                    });
+                }
+            }
+            console.log('[WS] Returning peer list:', peers);
+            return {
+                type: WS_MESSAGE_TYPES.PEER_LIST,
+                peers
+            };
+        }
+
+        if (type === WS_MESSAGE_TYPES.WEBRTC_SIGNAL) {
+            const { targetClientId, signal } = payload;
+            if (!targetClientId || !signal) {
+                throw new Error('WEBRTC_SIGNAL requires targetClientId and signal');
+            }
+
+            const senderClient = clients.get(clientId);
+            const targetClient = clients.get(targetClientId);
+
+            if (targetClient && targetClient.ws) {
+                targetClient.ws.send(JSON.stringify({
+                    type: WS_MESSAGE_TYPES.WEBRTC_SIGNAL,
+                    fromClientId: clientId,
+                    fromDid: senderClient?.did,
+                    signal
+                }));
+                return null; // No response to sender, it's a relay
+            } else {
+                throw new Error(`Target peer ${targetClientId} not found`);
+            }
+        }
+
+        return null;
+    };
+}

package/src/server/kernelHash.ts

@@ -0,0 +1,22 @@
+import { createRequire } from 'node:module';
+
+/**
+ * Node ESM bridge to the published kernel's SHA-256 surface.
+ *
+ * `clm-kernel@0.0.3`'s ESM build implements `sha256HashSync` with a bare
+ * `require('node:crypto')`, which is undefined in ESM scope. The failure is
+ * swallowed and rethrown as "SHA-256 requires Node.js crypto module or Web
+ * Crypto API", so every `computeSha256` call in an ESM server process throws.
+ * The package's CJS build — declared under `exports.require` — has a working
+ * `require`, so load that entry point rather than forking the kernel's
+ * hashing logic.
+ *
+ * Remove this shim and import `computeSha256` from `clm-kernel/layer0`
+ * directly once the published ESM build is fixed.
+ */
+const require = createRequire(import.meta.url);
+
+const kernelLayer0 = require('clm-kernel/layer0') as typeof import('clm-kernel/layer0');
+
+/** Raw 64-character lowercase hex SHA-256 digest (published kernel implementation). */
+export const computeSha256 = kernelLayer0.computeSha256;

package/src/server/layoutLoader.ts

@@ -0,0 +1,18 @@
+import type { LayoutDefinition } from '../types/layout';
+import { getLayout } from '../config/layouts';
+
+/**
+ * Resolve a layout from the built-in registry.
+ *
+ * Accepts a relative path (e.g. "default_layout.yaml", "chatbot_layout")
+ * and strips directory prefixes and extensions before looking up the registry.
+ *
+ * This replaces the previous implementation that read YAML from
+ * public/default_artifacts/ — layouts are now embedded in source code.
+ */
+export function loadLayoutFromDefaultArtifacts(relativePath: string): LayoutDefinition | null {
+    // Strip path components and extension so callers can pass filenames
+    const basename = relativePath.replace(/^.*\//, '').replace(/\.(yaml|yml)$/, '');
+    return getLayout(basename);
+}
+

package/src/server/mesh/mdnsService.mjs

@@ -0,0 +1,70 @@
+import pkg from 'bonjour-service';
+const Bonjour = pkg.default || pkg;
+import os from 'os';
+
+export class MDNSService {
+    constructor(port, did, capabilities = ['clm', 'storage'], onPeerChange = null) {
+        this.bonjour = new Bonjour();
+        this.port = port;
+        this.did = did || `did:key:z6Mk${Math.random().toString(36).substring(2, 10)}`;
+        this.capabilities = capabilities;
+        this.onPeerChange = onPeerChange;
+        this.service = null;
+        this.browser = null;
+        this.peers = new Map();
+    }
+
+    start() {
+        const hostname = os.hostname().split('.')[0];
+        
+        // Advertise this node
+        this.service = this.bonjour.publish({
+            name: `${hostname}-pkc-node-${Math.floor(Math.random() * 1000)}`,
+            type: 'pkc',
+            protocol: 'tcp',
+            port: this.port,
+            txt: {
+                version: '1.0.0',
+                did: this.did,
+                capabilities: this.capabilities.join(',')
+            }
+        });
+
+        console.log(`[mDNS] Advertising service _pkc._tcp.local. on port ${this.port}`);
+
+        // Discover peers
+        this.browser = this.bonjour.find({ type: 'pkc', protocol: 'tcp' });
+
+        this.browser.on('up', (service) => {
+            // Ignore ourselves if we see our own broadcast
+            if (service.name === this.service.name) return;
+            
+            console.log(`[mDNS] Peer up: ${service.name} at ${service.addresses?.[0]}:${service.port}`);
+            this.peers.set(service.name, service);
+            if (this.onPeerChange) this.onPeerChange('up', service, Array.from(this.peers.values()));
+        });
+
+        this.browser.on('down', (service) => {
+            if (service.name === this.service.name) return;
+            
+            console.log(`[mDNS] Peer down: ${service.name}`);
+            this.peers.delete(service.name);
+            if (this.onPeerChange) this.onPeerChange('down', service, Array.from(this.peers.values()));
+        });
+    }
+
+    getPeers() {
+        return Array.from(this.peers.values());
+    }
+
+    stop() {
+        if (this.service) {
+            this.service.stop();
+        }
+        if (this.browser) {
+            this.browser.stop();
+        }
+        this.bonjour.destroy();
+        console.log('[mDNS] Stopped.');
+    }
+}

package/src/server/networkUtils.mjs

@@ -0,0 +1,67 @@
+/**
+ * Utility functions for classifying network IP addresses.
+ */
+
+/**
+ * Classifies an IP address into one of four categories:
+ * - 'local': loopback addresses (127.0.0.1, ::1)
+ * - 'overlay': known overlay VPN ranges (e.g., Tailscale 100.64.0.0/10)
+ * - 'lan': RFC 1918 private network addresses (10.x.x.x, 172.16.x.x-172.31.x.x, 192.168.x.x)
+ * - 'public': everything else
+ *
+ * @param {string} ip - The IP address to classify.
+ * @returns {'local' | 'lan' | 'overlay' | 'public' | 'unknown'}
+ */
+export function classifyNetwork(ip) {
+    if (!ip || typeof ip !== 'string') return 'unknown';
+
+    // Remove IPv4 mapped IPv6 prefix if present
+    if (ip.startsWith('::ffff:')) {
+        ip = ip.substring(7);
+    }
+
+    // Localhost
+    if (ip === '127.0.0.1' || ip === '::1') {
+        return 'local';
+    }
+
+    // Tailscale / CGNAT (100.64.0.0/10)
+    // 100.64.0.0 to 100.127.255.255
+    if (ip.startsWith('100.')) {
+        const parts = ip.split('.');
+        if (parts.length === 4) {
+            const secondOctet = parseInt(parts[1], 10);
+            if (secondOctet >= 64 && secondOctet <= 127) {
+                return 'overlay';
+            }
+        }
+    }
+
+    // LAN / Private IPv4 (RFC 1918)
+    // 10.0.0.0/8
+    if (ip.startsWith('10.')) {
+        // Many overlays like ZeroTier use 10.x, but we'll classify as LAN for now unless we have more headers
+        return 'lan';
+    }
+    // 192.168.0.0/16
+    if (ip.startsWith('192.168.')) {
+        return 'lan';
+    }
+    // 172.16.0.0/12 (172.16.x.x to 172.31.x.x)
+    if (ip.startsWith('172.')) {
+        const parts = ip.split('.');
+        if (parts.length === 4) {
+            const secondOctet = parseInt(parts[1], 10);
+            if (secondOctet >= 16 && secondOctet <= 31) {
+                return 'lan';
+            }
+        }
+    }
+    
+    // Unique Local Addresses for IPv6 (fc00::/7)
+    if (ip.toLowerCase().startsWith('fc') || ip.toLowerCase().startsWith('fd')) {
+        return 'lan';
+    }
+
+    return 'public';
+}

package/src/server/notificationService.mjs

@@ -0,0 +1,149 @@
+import { WS_MESSAGE_TYPES } from '../shared/wsProtocol.js';
+import { PENDING_NOTIFICATION_LIMIT } from './serverConfig.js';
+
+export function createNotificationService({ clients, pushSubscriptions, pendingNotifications, webpush, publicVapidKey, privateVapidKey }) {
+    const NotificationPriority = {
+        HIGH: 'high',
+        NORMAL: 'normal',
+        LOW: 'low'
+    };
+
+    async function sendVAPIDPush(clientId, notification) {
+        if (!publicVapidKey || !privateVapidKey) {
+            console.error('[Notify] VAPID not configured');
+            return { success: false, method: 'vapid', error: 'VAPID not configured' };
+        }
+
+        const subscription = pushSubscriptions.get(clientId);
+        if (!subscription) {
+            console.error(`[Notify] No push subscription for ${clientId}`);
+            return { success: false, method: 'vapid', error: 'No subscription' };
+        }
+
+        try {
+            const payload = JSON.stringify({
+                title: notification.title || 'MCard Notification',
+                body: notification.body || JSON.stringify(notification.data),
+                data: notification.data,
+                timestamp: Date.now()
+            });
+
+            await webpush.sendNotification(subscription, payload);
+            console.log(`[Notify] VAPID push sent to ${clientId}`);
+            return { success: true, method: 'vapid' };
+        } catch (error) {
+            console.error(`[Notify] VAPID push failed for ${clientId}:`, error);
+            if (error.statusCode === 410) {
+                pushSubscriptions.delete(clientId);
+                console.log(`[Notify] Removed invalid subscription for ${clientId}`);
+            }
+            return { success: false, method: 'vapid', error: error.message };
+        }
+    }
+
+    function storePendingNotification(clientId, notification) {
+        if (!pendingNotifications.has(clientId)) {
+            pendingNotifications.set(clientId, []);
+        }
+        const pending = pendingNotifications.get(clientId);
+        pending.push({
+            ...notification,
+            timestamp: Date.now()
+        });
+
+        if (pending.length > PENDING_NOTIFICATION_LIMIT) {
+            pending.shift();
+        }
+    }
+
+    function deliverPendingNotifications(clientId, ws) {
+        if (!pendingNotifications.has(clientId)) {
+            return;
+        }
+
+        const pending = pendingNotifications.get(clientId);
+        console.log(`[Notify] Delivering ${pending.length} pending notifications to ${clientId}`);
+
+        pending.forEach(notification => {
+            try {
+                ws.send(JSON.stringify({
+                    type: WS_MESSAGE_TYPES.NOTIFICATION,
+                    isPending: true,
+                    ...notification
+                }));
+            } catch (error) {
+                console.error('[Notify] Failed to deliver pending notification:', error);
+            }
+        });
+
+        pendingNotifications.delete(clientId);
+    }
+
+    async function sendNotification(clientId, notification) {
+        const priority = notification.priority || NotificationPriority.NORMAL;
+
+        if (priority === NotificationPriority.HIGH && pushSubscriptions.has(clientId)) {
+            console.log(`[Notify] HIGH priority - using VAPID for ${clientId}`);
+            return await sendVAPIDPush(clientId, notification);
+        }
+
+        const client = clients.get(clientId);
+        if (client && client.isActive) {
+            try {
+                client.ws.send(JSON.stringify({
+                    type: WS_MESSAGE_TYPES.NOTIFICATION,
+                    ...notification
+                }));
+                console.log(`[Notify] Sent via WebSocket to ${clientId}`);
+                return { success: true, method: 'websocket' };
+            } catch {
+                console.log(`[Notify] WebSocket failed for ${clientId}, trying VAPID...`);
+            }
+        }
+
+        if (priority === NotificationPriority.LOW) {
+            console.log(`[Notify] LOW priority - storing for later delivery to ${clientId}`);
+            storePendingNotification(clientId, notification);
+            return { success: false, method: 'pending' };
+        }
+
+        if (pushSubscriptions.has(clientId)) {
+            console.log(`[Notify] WebSocket unavailable, using VAPID for ${clientId}`);
+            return await sendVAPIDPush(clientId, notification);
+        }
+
+        console.log(`[Notify] No delivery method available for ${clientId}, storing...`);
+        storePendingNotification(clientId, notification);
+        return { success: false, method: 'pending' };
+    }
+
+    async function broadcastToAll(notification) {
+        const results = [];
+        for (const [clientId] of clients) {
+            const result = await sendNotification(clientId, notification);
+            results.push({ clientId, ...result });
+        }
+        return results;
+    }
+
+    async function broadcastToChannel(channel, notification) {
+        const results = [];
+        for (const [clientId, client] of clients) {
+            if (client.subscriptions && client.subscriptions.has(channel)) {
+                const result = await sendNotification(clientId, notification);
+                results.push({ clientId, ...result });
+            }
+        }
+        return results;
+    }
+
+    return {
+        NotificationPriority,
+        sendNotification,
+        sendVAPIDPush,
+        storePendingNotification,
+        deliverPendingNotifications,
+        broadcastToAll,
+        broadcastToChannel
+    };
+}

package/src/server/repositoryRouter.ts

@@ -0,0 +1,49 @@
+import type { ArtifactRepository } from './artifactRepository';
+import { SERVER_FS_PREFIX, SERVER_COL_PREFIX_SLASH } from '../utils/artifactHandles';
+
+export interface RepositoryRoute {
+    /** Return true if this route should handle the given handle string. */
+    matches(handle: string): boolean;
+    /** The repository that owns matching handles. */
+    repository: ArtifactRepository;
+    /** Optional handle rewrite before passing to the repository. */
+    normalizeHandle?(handle: string): string;
+}
+
+export class RepositoryRouter {
+    private routes: RepositoryRoute[] = [];
+    private fallbackRepository: ArtifactRepository;
+
+    constructor(fallbackRepository: ArtifactRepository) {
+        this.fallbackRepository = fallbackRepository;
+        this.resetToDefaults(fallbackRepository);
+    }
+
+    private resetToDefaults(fileSystemRepository: ArtifactRepository) {
+        this.routes = [
+            {
+                // Legacy: handles starting with 'server/' → normalize to serverfs/ prefix
+                matches: (h) => h.startsWith('server/') && !h.startsWith(`${SERVER_FS_PREFIX}/`),
+                repository: fileSystemRepository,
+                normalizeHandle: (h) => h.replace(/^server\//, `${SERVER_FS_PREFIX}/`),
+            }
+        ];
+    }
+
+    public registerRoute(route: RepositoryRoute) {
+        // Enforce prepending so specific routes take precedence over fallback routes
+        this.routes.unshift(route);
+    }
+
+    public resolve(handle: string): { repository: ArtifactRepository; resolvedHandle: string } {
+        for (const route of this.routes) {
+            if (route.matches(handle)) {
+                return {
+                    repository: route.repository,
+                    resolvedHandle: route.normalizeHandle ? route.normalizeHandle(handle) : handle,
+                };
+            }
+        }
+        return { repository: this.fallbackRepository, resolvedHandle: handle };
+    }
+}

package/src/server/scripts/buildSeedingMemory.mjs

@@ -0,0 +1,60 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { createCollectionOwner } from '../collectionOwner.mjs';
+import { resolveServerConfig } from '../serverConfig.js';
+import { MCard } from '../storage/index.ts';
+
+const config = resolveServerConfig(process.env);
+const SEEDING_DB_PATH = config.seedingMemoryDbPath;
+const ARTIFACTS_DIR = config.artifactsDir;
+
+// Directories to seed (relative to artifactsDir)
+const DIRS_TO_SEED = [
+    'clm/chapter_01_arithmetic',
+];
+
+async function buildSeedingMemory() {
+    console.log(`[buildSeedingMemory] Starting build...`);
+    console.log(`[buildSeedingMemory] DB Path: ${SEEDING_DB_PATH}`);
+    console.log(`[buildSeedingMemory] Artifacts Dir: ${ARTIFACTS_DIR}`);
+
+    const owner = createCollectionOwner(SEEDING_DB_PATH);
+    const collection = await owner.getCollection();
+
+    let addedCount = 0;
+
+    for (const relativeDir of DIRS_TO_SEED) {
+        const fullDir = path.join(ARTIFACTS_DIR, relativeDir);
+        
+        try {
+            const files = await fs.readdir(fullDir);
+            for (const file of files) {
+                if (file.endsWith('.yaml') || file.endsWith('.yml') || file.endsWith('.json') || file.endsWith('.md') || file.endsWith('.js')) {
+                    const filePath = path.join(fullDir, file);
+                    const contentStr = await fs.readFile(filePath, 'utf-8');
+                    const contentBytes = new TextEncoder().encode(contentStr);
+                    
+                    const card = await MCard.create(contentBytes);
+                    // The handle format in MCard Studio is typically local/dir/file
+                    // Wait, what should be the handle? In loadArtifactIndex it's 'local/clm/chapter_01_arithmetic/addition_js.yaml'
+                    // For browsermemory, the handle is just `local/clm/chapter_01_arithmetic/addition_js.yaml` (when fetched lazily)
+                    const handle = `local/${relativeDir}/${file}`;
+                    
+                    await collection.addWithHandle(card, handle);
+                    addedCount++;
+                    console.log(`[buildSeedingMemory] Added ${handle}`);
+                }
+            }
+        } catch (err) {
+            console.warn(`[buildSeedingMemory] Failed to read ${fullDir}:`, err.message);
+        }
+    }
+
+    console.log(`[buildSeedingMemory] Build complete. Added ${addedCount} cards.`);
+    process.exit(0);
+}
+
+buildSeedingMemory().catch(err => {
+    console.error(`[buildSeedingMemory] Error:`, err);
+    process.exit(1);
+});

package/src/server/serverConfig.d.ts

@@ -0,0 +1,18 @@
+export const CLM_RUNNER_TIMEOUT_MS: number;
+export const FILE_WATCH_DEBOUNCE_MS: number;
+export const PENDING_NOTIFICATION_LIMIT: number;
+export function resolveServerConfig(env?: Record<string, string | undefined>): {
+    dataRoot: string;
+    dataUser: string;
+    userDir: string;
+    seedDir: string;
+    wsHost: string;
+    wsPort: string;
+    artifactsDir: string;
+    mcardDbPath: string;
+    serverLogDbPath: string;
+    serverMemoryDbPath: string;
+    seedingMemoryDbPath: string;
+    pushSubscriptionsPath: string;
+    vapidContact: string;
+};

package/src/server/serverConfig.js

@@ -0,0 +1,108 @@
+import path from 'path';
+import {
+    DEFAULT_VAPID_CONTACT,
+    DEFAULT_WS_HOST,
+    DEFAULT_WS_PORT,
+    DEFAULT_MINIO_ENDPOINT,
+    DEFAULT_MINIO_PORT,
+    DEFAULT_MINIO_USE_SSL,
+    DEFAULT_MINIO_BUCKET,
+    DEFAULT_IPFS_GATEWAY,
+    DEFAULT_IPFS_API_URL,
+    DEFAULT_STUN_SERVERS,
+    ENV_KEYS,
+} from '../config/constants.js';
+import { PATHS } from '../config/pathsConfig.js';
+
+// ── Per-user data directory layout ──────────────────────────────────────
+// data/
+// ├── seed/              (read-only template for new users)
+// │   ├── servermemory.db
+// │   └── artifacts/
+// ├── guest/             (default anonymous user)
+// │   ├── servermemory.db
+// │   └── artifacts/
+// └── <username>/        (authenticated users — future)
+//
+// Directory names now resolve from src/config/pathsConfig.js (SSOT, INV-PC-01);
+// DATA_ROOT / DATA_USER / ARTIFACTS_DIR env vars still override (INV-PC-02).
+
+export const CLM_RUNNER_TIMEOUT_MS = PATHS.execution.clm_runner_timeout_ms;
+export const FILE_WATCH_DEBOUNCE_MS = PATHS.ingest.watch_debounce_ms;
+export const PENDING_NOTIFICATION_LIMIT = PATHS.execution.pending_notification_limit;
+
+export function resolveServerConfig(env = process.env) {
+    // Core layout
+    // MCARD_DATA_ROOT / MCARD_PROJECT_ROOT are set by the mcard-studio CLI
+    // (Program NP · INV-NP-05). MCARD_DATA_ROOT is an absolute root owned by the
+    // CLI; it is deliberately distinct from DATA_ROOT, which pathsConfig.js binds
+    // to the relative `paths.data_root_dirname` field (INV-PC-06).
+    const dataRoot = env.MCARD_DATA_ROOT
+        ? path.resolve(env.MCARD_DATA_ROOT)
+        : env[ENV_KEYS.DATA_ROOT]
+            ? path.resolve(env[ENV_KEYS.DATA_ROOT])
+            : path.resolve(env.MCARD_PROJECT_ROOT || process.cwd(), PATHS.paths.data_root_dirname);
+    const dataUser = env[ENV_KEYS.DATA_USER] || PATHS.paths.data_user;
+    const userDir  = path.join(dataRoot, dataUser);
+    const seedDir  = path.join(dataRoot, PATHS.paths.seed_dirname);
+
+    // Derived defaults (from user directory)
+    const defaultArtifactsDir      = path.join(userDir, PATHS.paths.artifacts_dirname);
+    const defaultServerMemoryDb    = path.join(userDir, PATHS.stores.server_memory_db);
+    const defaultMcardDb           = path.join(userDir, PATHS.stores.mcard_db);
+    const defaultServerLogDb       = path.join(userDir, PATHS.stores.server_log_db);
+    const defaultSeedingMemoryDb   = path.join(seedDir, PATHS.stores.server_memory_db);
+    const defaultPushSubscriptions = path.join(userDir, PATHS.stores.push_subscriptions_file);
+
+    return {
+        // Layout
+        dataRoot,
+        dataUser,
+        userDir,
+        seedDir,
+
+        // Network
+        wsHost: env[ENV_KEYS.WS_HOST] || env.WS_HOST || env.VITE_WS_HOST || DEFAULT_WS_HOST,
+        wsPort: env[ENV_KEYS.WS_PORT] || env.WS_PORT || env.VITE_WS_PORT || DEFAULT_WS_PORT,
+        terminalWsPath: env.TERMINAL_WS_PATH || PATHS.endpoints.terminal_ws,
+        satoriEventsPath: env.SATORI_EVENTS_PATH || PATHS.endpoints.satori_events,
+        ptyEnabled: env.PTY_ENABLED !== 'false',
+
+        // Paths (legacy env vars override the per-user defaults)
+        artifactsDir: env[ENV_KEYS.ARTIFACTS_DIR] ? path.resolve(env[ENV_KEYS.ARTIFACTS_DIR]) : defaultArtifactsDir,
+        mcardDbPath: env[ENV_KEYS.MCARD_DB_PATH] ? path.resolve(env[ENV_KEYS.MCARD_DB_PATH])
+                   : env[ENV_KEYS.MCARD_STORAGE_PATH] ? path.resolve(env[ENV_KEYS.MCARD_STORAGE_PATH])
+                   : defaultMcardDb,
+        serverLogDbPath: env[ENV_KEYS.EXECUTION_LOGS_DB_PATH] ? path.resolve(env[ENV_KEYS.EXECUTION_LOGS_DB_PATH])
+                       : env[ENV_KEYS.SERVER_LOG_DB_PATH] ? path.resolve(env[ENV_KEYS.SERVER_LOG_DB_PATH])
+                       : defaultServerLogDb,
+        serverMemoryDbPath: env[ENV_KEYS.SERVER_MEMORY_DB_PATH] ? path.resolve(env[ENV_KEYS.SERVER_MEMORY_DB_PATH])
+                          : env[ENV_KEYS.SERVERMEMORY_DB_PATH] ? path.resolve(env[ENV_KEYS.SERVERMEMORY_DB_PATH])
+                          : defaultServerMemoryDb,
+        seedingMemoryDbPath: env[ENV_KEYS.SEEDING_MEMORY_DB_PATH] ? path.resolve(env[ENV_KEYS.SEEDING_MEMORY_DB_PATH])
+                           : defaultSeedingMemoryDb,
+        pushSubscriptionsPath: env[ENV_KEYS.PUSH_SUBSCRIPTIONS_PATH] ? path.resolve(env[ENV_KEYS.PUSH_SUBSCRIPTIONS_PATH])
+                             : defaultPushSubscriptions,
+        vapidContact: env[ENV_KEYS.VAPID_CONTACT_EMAIL] ? `mailto:${env[ENV_KEYS.VAPID_CONTACT_EMAIL]}`
+                    : env[ENV_KEYS.VAPID_CONTACT] || DEFAULT_VAPID_CONTACT,
+
+        // MinIO
+        minio: {
+            endPoint: env[ENV_KEYS.MINIO_ENDPOINT] || DEFAULT_MINIO_ENDPOINT,
+            port: parseInt(env[ENV_KEYS.MINIO_PORT], 10) || DEFAULT_MINIO_PORT,
+            useSSL: env[ENV_KEYS.MINIO_USE_SSL] === 'true' || (env[ENV_KEYS.MINIO_USE_SSL] === undefined ? DEFAULT_MINIO_USE_SSL : false),
+            accessKey: env[ENV_KEYS.MINIO_ACCESS_KEY],
+            secretKey: env[ENV_KEYS.MINIO_SECRET_KEY],
+            bucket: env[ENV_KEYS.MINIO_BUCKET] || DEFAULT_MINIO_BUCKET
+        },
+
+        // IPFS
+        ipfs: {
+            gateway: env[ENV_KEYS.IPFS_GATEWAY] || DEFAULT_IPFS_GATEWAY,
+            apiUrl: env[ENV_KEYS.IPFS_API_URL] || DEFAULT_IPFS_API_URL
+        },
+
+        // STUN
+        stunServers: env[ENV_KEYS.STUN_SERVERS] ? env[ENV_KEYS.STUN_SERVERS].split(',').map(s => s.trim()) : DEFAULT_STUN_SERVERS,
+    };
+}

package/src/server/serverMemoryCacheSignal.mjs

@@ -0,0 +1,39 @@
+/**
+ * Shared cache invalidation signal for servermemory.db.
+ *
+ * Problem: The WebSocket layer (.mjs) and the Astro API layer (.ts)
+ * both interact with servermemory.db but live in different module
+ * systems. The .ts layer owns the ServerMemoryArtifactRepository
+ * singleton with its in-memory cachedMeta array. The .mjs layer
+ * cannot import .ts modules directly.
+ *
+ * Solution: This .mjs module acts as a shared signal bus.
+ * - The .ts layer registers an invalidation callback on import.
+ * - The .mjs layer calls signalInvalidate() to trigger it.
+ *
+ * Both sides import this plain .mjs file, which works in any
+ * module system without Vite compilation.
+ */
+
+/** @type {(() => void) | null} */
+let _invalidateCallback = null;
+
+/**
+ * Register the cache invalidation callback.
+ * Called once by artifactCollectionService.ts on first import.
+ * @param {() => void} cb
+ */
+export function registerCacheInvalidator(cb) {
+    _invalidateCallback = cb;
+}
+
+/**
+ * Signal that the servermemory.db backing data has changed
+ * (e.g. a handle was removed or added by the file watcher).
+ * Called by fileChangeHandler.mjs after processing a change.
+ */
+export function signalCacheInvalidate() {
+    if (_invalidateCallback) {
+        _invalidateCallback();
+    }
+}