@thevinci/web 1.0.0

package/server/lib/magic-prompts/routes.js

@@ -0,0 +1,63 @@
+import { createMagicPromptRuntime } from './runtime.js';
+
+export const registerMagicPromptRoutes = (app, dependencies) => {
+  const {
+    fsPromises,
+    path,
+    vinciDataDir,
+  } = dependencies;
+
+  const runtime = createMagicPromptRuntime({
+    fsPromises,
+    path,
+    filePath: path.join(vinciDataDir, 'magic-prompts.json'),
+  });
+
+  app.get('/api/magic-prompts', async (_req, res) => {
+    try {
+      const state = await runtime.readPromptState();
+      res.json(state);
+    } catch (error) {
+      res.status(500).json({ error: error instanceof Error ? error.message : 'Failed to read magic prompts' });
+    }
+  });
+
+  app.put('/api/magic-prompts/:id', async (req, res) => {
+    const id = typeof req.params?.id === 'string' ? req.params.id : '';
+    const text = typeof req.body?.text === 'string' ? req.body.text : null;
+    if (text === null) {
+      return res.status(400).json({ error: 'text is required' });
+    }
+
+    try {
+      const state = await runtime.setOverride(id, text);
+      return res.json(state);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const status = message.includes('Invalid prompt id') || message.includes('too long') || message.includes('cannot be empty') ? 400 : 500;
+      return res.status(status).json({ error: message });
+    }
+  });
+
+  app.delete('/api/magic-prompts/:id', async (req, res) => {
+    const id = typeof req.params?.id === 'string' ? req.params.id : '';
+    try {
+      const state = await runtime.resetOverride(id);
+      return res.json(state);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const status = message.includes('Invalid prompt id') ? 400 : 500;
+      return res.status(status).json({ error: message });
+    }
+  });
+
+  app.delete('/api/magic-prompts', async (_req, res) => {
+    try {
+      const state = await runtime.resetAllOverrides();
+      return res.json(state);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return res.status(500).json({ error: message || 'Failed to reset magic prompts' });
+    }
+  });
+};

package/server/lib/magic-prompts/runtime.js

@@ -0,0 +1,119 @@
+const FILE_VERSION = 1;
+const MAX_PROMPT_TEXT_LENGTH = 200_000;
+const PROMPT_ID_PATTERN = /^[a-z0-9._-]{1,160}$/;
+const isVisiblePromptID = (id) => typeof id === 'string' && id.endsWith('.visible');
+
+const hasOwn = (input, key) => Object.prototype.hasOwnProperty.call(input, key);
+
+const sanitizeOverrides = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+
+  const next = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (!PROMPT_ID_PATTERN.test(key) || typeof entry !== 'string') {
+      continue;
+    }
+    next[key] = entry;
+  }
+  return next;
+};
+
+export const createMagicPromptRuntime = (dependencies) => {
+  const {
+    fsPromises,
+    path,
+    filePath,
+  } = dependencies;
+
+  let writeLock = Promise.resolve();
+
+  const readPromptState = async () => {
+    try {
+      const raw = await fsPromises.readFile(filePath, 'utf8');
+      const parsed = JSON.parse(raw);
+      const overrides = sanitizeOverrides(parsed?.overrides);
+      return {
+        version: FILE_VERSION,
+        overrides,
+      };
+    } catch (error) {
+      if (error && typeof error === 'object' && error.code === 'ENOENT') {
+        return { version: FILE_VERSION, overrides: {} };
+      }
+      console.warn('Failed to read magic prompts file:', error);
+      return { version: FILE_VERSION, overrides: {} };
+    }
+  };
+
+  const writePromptState = async (state) => {
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+    await fsPromises.writeFile(filePath, JSON.stringify(state, null, 2), 'utf8');
+  };
+
+  const persist = async (mutator) => {
+    const run = async () => {
+      const current = await readPromptState();
+      const next = await mutator(current);
+      await writePromptState(next);
+      return next;
+    };
+    writeLock = writeLock.then(run, run);
+    return writeLock;
+  };
+
+  const setOverride = async (id, text) => {
+    const normalizedId = typeof id === 'string' ? id.trim() : '';
+    if (!PROMPT_ID_PATTERN.test(normalizedId)) {
+      throw new Error('Invalid prompt id');
+    }
+    if (typeof text !== 'string') {
+      throw new Error('Prompt text must be a string');
+    }
+    if (isVisiblePromptID(normalizedId) && text.trim().length === 0) {
+      throw new Error('Visible prompt text cannot be empty');
+    }
+    if (text.length > MAX_PROMPT_TEXT_LENGTH) {
+      throw new Error('Prompt text is too long');
+    }
+
+    return persist(async (state) => {
+      const nextOverrides = { ...state.overrides, [normalizedId]: text };
+      return {
+        version: FILE_VERSION,
+        overrides: nextOverrides,
+      };
+    });
+  };
+
+  const resetOverride = async (id) => {
+    const normalizedId = typeof id === 'string' ? id.trim() : '';
+    if (!PROMPT_ID_PATTERN.test(normalizedId)) {
+      throw new Error('Invalid prompt id');
+    }
+
+    return persist(async (state) => {
+      if (!hasOwn(state.overrides, normalizedId)) {
+        return state;
+      }
+      const nextOverrides = { ...state.overrides };
+      delete nextOverrides[normalizedId];
+      return {
+        version: FILE_VERSION,
+        overrides: nextOverrides,
+      };
+    });
+  };
+
+  const resetAllOverrides = async () => {
+    return persist(async () => ({ version: FILE_VERSION, overrides: {} }));
+  };
+
+  return {
+    readPromptState,
+    setOverride,
+    resetOverride,
+    resetAllOverrides,
+  };
+};

package/server/lib/notifications/DOCUMENTATION.md

@@ -0,0 +1,122 @@
+# Notifications Module Documentation
+
+## Purpose
+This module provides notification message preparation utilities for the web server runtime, including text truncation and plain-text normalization for system notifications.
+
+## Entrypoints and structure
+- `packages/web/server/lib/notifications/index.js`: public entrypoint imported by `packages/web/server/index.js`.
+- `packages/web/server/lib/notifications/routes.js`: route registration for push, visibility, and session status/attention endpoints.
+- `packages/web/server/lib/notifications/push-runtime.js`: push subscription persistence, VAPID initialization, and UI visibility runtime.
+- `packages/web/server/lib/notifications/emitter-runtime.js`: desktop/stdout + UI SSE notification emission runtime.
+- `packages/web/server/lib/notifications/runtime.js`: trigger runtime for OpenCode event-driven notification fanout.
+- `packages/web/server/lib/notifications/template-runtime.js`: notification template variables and session text/title enrichment runtime. Zen-model helpers are retained as compatibility stubs only.
+- `packages/web/server/lib/notifications/message.js`: helper implementation module.
+- `packages/web/server/lib/notifications/message.test.js`: unit tests for notification message helpers.
+
+## Public exports
+
+### Notifications API (re-exported from message.js)
+- `truncateNotificationText(text, maxLength)`: Truncates text to specified max length, appending `...` if truncated.
+- `prepareNotificationLastMessage({ message, settings })`: Prepares the last message for notification display by normalizing and truncating text.
+
+### Route registration API (routes.js)
+- `registerNotificationRoutes(app, dependencies)`: Registers notification-owned endpoints:
+  - `GET /api/push/vapid-public-key`
+  - `POST /api/push/subscribe`
+  - `DELETE /api/push/subscribe`
+  - `POST /api/push/visibility`
+  - `GET /api/push/visibility`
+  - `GET /api/session-activity`
+  - `GET /api/sessions/snapshot`
+  - `GET /api/sessions/status`
+  - `GET /api/sessions/:id/status`
+  - `GET /api/sessions/attention`
+  - `GET /api/sessions/:id/attention`
+  - `POST /api/sessions/:id/view`
+  - `POST /api/sessions/:id/unview`
+  - `POST /api/sessions/:id/message-sent`
+
+### Trigger runtime API (runtime.js)
+- `createNotificationTriggerRuntime(dependencies)`: creates runtime-owned debounced trigger handling for OpenCode events.
+- Returned API:
+  - `maybeSendPushForTrigger(payload)`
+- Owns:
+  - completion/error/question/permission trigger routing
+  - session parent cache for subtask suppression
+  - template resolution and fallback behavior
+  - native notification fanout and web push payload fanout
+
+### Push runtime API (push-runtime.js)
+- `createPushRuntime(dependencies)`: creates runtime for web push and UI visibility state.
+- Returned API:
+  - `getOrCreateVapidKeys()`
+  - `ensurePushInitialized()`
+  - `setPushInitialized(value)`
+  - `addOrUpdatePushSubscription(uiSessionToken, subscription, userAgent)`
+  - `removePushSubscription(uiSessionToken, endpoint)`
+  - `sendPushToAllUiSessions(payload, options?)`
+  - `updateUiVisibility(token, visible)`
+  - `isAnyUiVisible()`
+  - `isUiVisible(token)`
+
+### Emitter runtime API (emitter-runtime.js)
+- `createNotificationEmitterRuntime(dependencies)`: creates runtime for unified notification emission channels.
+- Returned API:
+  - `writeSseEvent(res, payload)`
+  - `emitDesktopNotification(payload)`
+  - `broadcastUiNotification(payload)`
+
+### Template runtime API (template-runtime.js)
+- `createNotificationTemplateRuntime(dependencies)`: creates shared notification/template runtime. Model-backed summarization was retired after the Zen provider became unavailable.
+- Returned API:
+  - `resolveNotificationTemplate(template, variables)`
+  - `shouldApplyResolvedTemplateMessage(template, resolved, variables)`
+  - `fetchFreeZenModels()` compatibility stub returning `[]`
+  - `resolveZenModel(override)` compatibility stub preserving stored values without validation
+  - `validateZenModelAtStartup()` compatibility no-op
+  - `summarizeText(text, targetLength, zenModel)` compatibility stub returning local fallback text
+  - `extractLastMessageText(payload, maxLength?)`
+  - `fetchLastAssistantMessageText(sessionId, messageId, maxLength?)`
+  - `maybeCacheSessionInfoFromEvent(payload)`
+  - `buildTemplateVariables(payload, sessionId)`
+  - `getCachedZenModels()`
+
+## Constants
+
+### Default values
+- `DEFAULT_NOTIFICATION_MESSAGE_MAX_LENGTH`: 250 (default max length for notification text).
+
+## Settings object format
+
+The `settings` parameter for `prepareNotificationLastMessage` supports `maxLastMessageLength` (number), the maximum length for the final notification text (default: 250). Legacy summarization settings may still exist in persisted settings but are ignored.
+
+## Response contracts
+
+### `truncateNotificationText`
+- Returns empty string for non-string input.
+- Returns original text if under max length.
+- Returns `${text.slice(0, maxLength)}...` for truncated text.
+
+### `prepareNotificationLastMessage`
+- Returns empty string for empty/null message.
+- Returns truncated original message. Model-backed notification summarization is retired.
+- Normalizes markdown-like formatting to plain text before truncation.
+- Always applies `maxLastMessageLength` truncation to final result.
+
+## Notes for contributors
+
+### Adding new notification helpers
+1. Add new helper functions to `packages/web/server/lib/notifications/message.js`.
+2. Export functions that are intended for public use.
+3. Follow existing patterns for input validation (e.g., type checking for strings).
+4. Use `resolvePositiveNumber` for numeric parameters with fallbacks to maintain safe defaults.
+5. Add corresponding unit tests in `packages/web/server/lib/notifications/message.test.js`.
+
+### Error handling
+- `prepareNotificationLastMessage` does not call model summarization.
+- Invalid numeric parameters default to safe fallback values.
+- Non-string inputs are handled gracefully (return empty string).
+
+### Testing
+- Run `bun run type-check`, `bun run lint`, and `bun run build` before finalizing changes.
+- Unit tests should cover truncation behavior and edge cases (empty strings, invalid inputs).

package/server/lib/notifications/emitter-runtime.js

@@ -0,0 +1,102 @@
+export const createNotificationEmitterRuntime = (dependencies) => {
+  const {
+    process,
+    getDesktopNotifyEnabled,
+    desktopNotifyPrefix,
+    getUiNotificationClients,
+    getBroadcastGlobalUiEvent,
+    // Optional: in-process desktop shells (Electron main) inject a callback so
+    // notifications are delivered as a direct function call instead of a stdout
+    // stringly-typed IPC.
+    onDesktopNotification: initialOnDesktopNotification,
+  } = dependencies;
+
+  // Late-bindable: main() in server/index.js may call setOnDesktopNotification
+  // after runtime construction so the in-process shell can subscribe without
+  // restructuring the module-level wiring.
+  let onDesktopNotification = typeof initialOnDesktopNotification === 'function'
+    ? initialOnDesktopNotification
+    : null;
+
+  const setOnDesktopNotification = (cb) => {
+    onDesktopNotification = typeof cb === 'function' ? cb : null;
+  };
+
+  const writeSseEvent = (res, payload) => {
+    res.write(`data: ${JSON.stringify(payload)}\n\n`);
+  };
+
+  const emitDesktopNotification = (payload) => {
+    const desktopNotifyEnabled = getDesktopNotifyEnabled();
+    if (!desktopNotifyEnabled) {
+      return;
+    }
+
+    if (!payload || typeof payload !== 'object') {
+      return;
+    }
+
+    if (onDesktopNotification) {
+      try {
+        onDesktopNotification(payload);
+      } catch {
+        // ignore host-side throw
+      }
+      return;
+    }
+
+    try {
+      // stdout IPC: Tauri shell spawns this process as a sidecar and parses
+      // its stdout for the one-line `${prefix}{json}` protocol.
+      process.stdout.write(`${desktopNotifyPrefix}${JSON.stringify(payload)}\n`);
+    } catch {
+      // ignore
+    }
+  };
+
+  const broadcastUiNotification = (payload) => {
+    const desktopNotifyEnabled = getDesktopNotifyEnabled();
+    if (!payload || typeof payload !== 'object') {
+      return;
+    }
+
+    const syntheticPayload = {
+      type: 'vinci:notification',
+      properties: {
+        ...payload,
+        // Tell the UI whether the sidecar stdout notification channel is active.
+        // When true, the desktop UI should skip this SSE notification to avoid duplicates.
+        // When false (e.g. tauri dev), the UI must handle this SSE notification itself.
+        desktopStdoutActive: desktopNotifyEnabled,
+      },
+    };
+
+    const broadcastGlobalUiEvent = typeof getBroadcastGlobalUiEvent === 'function'
+      ? getBroadcastGlobalUiEvent()
+      : null;
+    if (broadcastGlobalUiEvent) {
+      broadcastGlobalUiEvent(syntheticPayload);
+      return;
+    }
+
+    const clients = getUiNotificationClients();
+    if (clients.size === 0) {
+      return;
+    }
+
+    for (const res of clients) {
+      try {
+        writeSseEvent(res, syntheticPayload);
+      } catch {
+        // ignore
+      }
+    }
+  };
+
+  return {
+    writeSseEvent,
+    emitDesktopNotification,
+    broadcastUiNotification,
+    setOnDesktopNotification,
+  };
+};

package/server/lib/notifications/index.js

@@ -0,0 +1,4 @@
+export { truncateNotificationText, prepareNotificationLastMessage } from './message.js';
+export { createNotificationTriggerRuntime } from './runtime.js';
+export { createPushRuntime } from './push-runtime.js';
+export { createNotificationTemplateRuntime } from './template-runtime.js';

package/server/lib/notifications/message.js

@@ -0,0 +1,52 @@
+const DEFAULT_NOTIFICATION_MESSAGE_MAX_LENGTH = 250;
+
+const resolvePositiveNumber = (value, fallback) => {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+  return value;
+};
+
+const normalizeNotificationPlainText = (text) => {
+  if (typeof text !== 'string') {
+    return '';
+  }
+
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/^[\t ]*[-*+]\s+/gm, '')
+    .replace(/^#{1,6}\s+/gm, '')
+    .replace(/\*\*(.*?)\*\*/g, '$1')
+    .replace(/__(.*?)__/g, '$1')
+    .replace(/\*(.*?)\*/g, '$1')
+    .replace(/_(.*?)_/g, '$1')
+    .replace(/\[(.*?)\]\((.*?)\)/g, '$1')
+    .replace(/\s*\n\s*/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+};
+
+export const truncateNotificationText = (text, maxLength = DEFAULT_NOTIFICATION_MESSAGE_MAX_LENGTH) => {
+  if (typeof text !== 'string') {
+    return '';
+  }
+
+  const safeMaxLength = resolvePositiveNumber(maxLength, DEFAULT_NOTIFICATION_MESSAGE_MAX_LENGTH);
+  if (text.length <= safeMaxLength) {
+    return text;
+  }
+
+  return `${text.slice(0, safeMaxLength)}...`;
+};
+
+export const prepareNotificationLastMessage = async ({ message, settings }) => {
+  const originalMessage = typeof message === 'string' ? message : '';
+  if (!originalMessage) {
+    return '';
+  }
+
+  const maxLastMessageLength = resolvePositiveNumber(settings?.maxLastMessageLength, DEFAULT_NOTIFICATION_MESSAGE_MAX_LENGTH);
+  const plainTextMessage = normalizeNotificationPlainText(originalMessage);
+  return truncateNotificationText(plainTextMessage, maxLastMessageLength);
+};

package/server/lib/notifications/message.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { prepareNotificationLastMessage, truncateNotificationText } from './message.js';
+
+describe('notification message helpers', () => {
+  it('truncates oversized notification text', () => {
+    expect(truncateNotificationText('abcdef', 3)).toBe('abc...');
+  });
+
+  it('ignores retired summarization settings and truncates original message', async () => {
+    const result = await prepareNotificationLastMessage({
+      message: '0123456789',
+      settings: {
+        summarizeLastMessage: true,
+        summaryThreshold: 5,
+        summaryLength: 3,
+        maxLastMessageLength: 4,
+      },
+    });
+
+    expect(result).toBe('0123...');
+  });
+
+  it('normalizes markdown message to plain text', async () => {
+    const result = await prepareNotificationLastMessage({
+      message: "**Committed.**\n\n- Commit: `85924b9d`\n- Message: `fix desktop notifications`",
+      settings: {
+        maxLastMessageLength: 200,
+      },
+    });
+
+    expect(result).toBe('Committed. Commit: 85924b9d Message: fix desktop notifications');
+  });
+});