nebula-cms 0.1.0

package/src/client/js/storage/storage.ts

@@ -0,0 +1,83 @@
+/*
+ * Backend configuration persistence using IndexedDB.
+ * Stores and retrieves the active storage backend (FSA or GitHub).
+ */
+
+import { openDB } from './db';
+
+// Fixed key for the backend config
+const BACKEND_KEY = 'backend';
+
+/**
+ * Backend configuration stored in IndexedDB. Tagged union discriminated on `type`.
+ * Security note: the GitHub token is stored in plaintext in IndexedDB. This is a
+ * deliberate trade-off for a client-only app with no server to proxy through.
+ * Same-origin policy protects it from other sites, but any XSS vulnerability
+ * would expose the token.
+ */
+export type BackendConfig =
+  | { type: 'fsa'; handle: FileSystemDirectoryHandle }
+  | { type: 'github'; token: string; repo: string };
+
+/**
+ * Stores backend configuration in IndexedDB for persistence across sessions.
+ * @param {BackendConfig} config - The backend config to store
+ * @return {Promise<void>}
+ */
+export async function saveBackend(config: BackendConfig): Promise<void> {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('handles', 'readwrite');
+    tx.objectStore('handles').put(config, BACKEND_KEY);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}
+
+/**
+ * Retrieves stored backend configuration from IndexedDB. Handles migration from the old format where a bare FileSystemDirectoryHandle was stored.
+ * @return {Promise<BackendConfig | null>} The stored config, or null if none exists
+ */
+export async function loadBackend(): Promise<BackendConfig | null> {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('handles', 'readonly');
+    const request = tx.objectStore('handles').get(BACKEND_KEY);
+    request.onsuccess = () => {
+      const result = request.result;
+      if (!result) {
+        // Check for old-format handle stored under the legacy key
+        const legacyRequest = tx.objectStore('handles').get('projectRoot');
+        legacyRequest.onsuccess = () => {
+          const legacy = legacyRequest.result;
+          if (legacy && legacy instanceof FileSystemDirectoryHandle) {
+            resolve({ type: 'fsa', handle: legacy });
+          } else {
+            resolve(null);
+          }
+        };
+        legacyRequest.onerror = () => resolve(null);
+        return;
+      }
+      resolve(result as BackendConfig);
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+
+/**
+ * Removes the stored backend configuration from IndexedDB. Also clears the legacy key if present.
+ * @return {Promise<void>}
+ */
+export async function clearBackend(): Promise<void> {
+  const db = await openDB();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction('handles', 'readwrite');
+    const store = tx.objectStore('handles');
+    store.delete(BACKEND_KEY);
+    // Clean up legacy key if present
+    store.delete('projectRoot');
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+}

package/src/client/js/storage/workers/frontmatter.ts

@@ -0,0 +1,320 @@
+/*
+ * Orchestrator Worker
+ *
+ * Routes file parsing by category: frontmatter files have their YAML block
+ * extracted via string manipulation and sent to the YAML parser worker;
+ * JSON data files are parsed inline; YAML/TOML data files are sent to their
+ * respective parser workers. Parser workers are lazily spawned on first need.
+ */
+
+import { StorageClient } from '../client';
+import { getFileCategory, getDataFormat } from '../../utils/file-types';
+import { splitFrontmatter } from '../../utils/frontmatter';
+import type { FileEntry } from '../adapter';
+
+/**
+ * Extracts the raw YAML block from a frontmatter-delimited file (markdown/MDX/Markdoc).
+ * Delegates BOM stripping, CRLF normalization, and delimiter logic to splitFrontmatter.
+ * Returns the raw YAML string without parsing it — parsing is delegated to the YAML parser worker.
+ * @param {string} content - Raw file content
+ * @return {string | null} The raw YAML string between --- delimiters, or null if none found
+ */
+function extractYamlBlock(content: string): string | null {
+  const { rawFrontmatter } = splitFrontmatter(content);
+  return rawFrontmatter.trim() ? rawFrontmatter : null;
+}
+
+/*
+//////////////////////////////
+// Batch item type for parser worker communication
+//////////////////////////////
+*/
+
+// A key/content pair for batch parsing requests.
+type BatchItem = {
+  key: string;
+  content: string;
+};
+
+/*
+//////////////////////////////
+// Parser worker management
+//////////////////////////////
+*/
+
+// Lazily-spawned parser workers
+let yamlWorker: Worker | null = null;
+let tomlWorker: Worker | null = null;
+
+// Incrementing ID for correlating batch requests with responses
+let batchIdCounter = 0;
+
+// Pending batch response promises keyed by ID
+const pendingBatches = new Map<
+  string,
+  {
+    resolve: (results: Record<string, Record<string, unknown>>) => void;
+    reject: (err: Error) => void;
+  }
+>();
+
+/**
+ * Returns the lazily-spawned YAML parser worker, creating it on first call.
+ * Uses `.js` extension in the URL because svelte-package doesn't rewrite URL strings.
+ * @return {Worker} The YAML parser worker instance
+ */
+function getYamlWorker(): Worker {
+  if (!yamlWorker) {
+    yamlWorker = new Worker(new URL('./yaml-parser.js', import.meta.url), {
+      type: 'module',
+    });
+    yamlWorker.onmessage = handleParserResponse;
+    yamlWorker.onerror = handleWorkerError;
+  }
+  return yamlWorker;
+}
+
+/**
+ * Returns the lazily-spawned TOML parser worker, creating it on first call.
+ * Uses `.js` extension in the URL because svelte-package doesn't rewrite URL strings.
+ * @return {Worker} The TOML parser worker instance
+ */
+function getTomlWorker(): Worker {
+  if (!tomlWorker) {
+    tomlWorker = new Worker(new URL('./toml-parser.js', import.meta.url), {
+      type: 'module',
+    });
+    tomlWorker.onmessage = handleParserResponse;
+    tomlWorker.onerror = handleWorkerError;
+  }
+  return tomlWorker;
+}
+
+/**
+ * Handles fatal errors from parser workers by rejecting all pending batch promises
+ * so callers don't hang indefinitely waiting for a response that will never arrive.
+ * @param {ErrorEvent} e - The error event from the worker
+ * @return {void}
+ */
+function handleWorkerError(e: ErrorEvent): void {
+  for (const [id, { reject }] of pendingBatches) {
+    reject(new Error(`Parser worker error: ${e.message}`));
+    pendingBatches.delete(id);
+  }
+}
+
+/**
+ * Handles responses from parser workers by resolving/rejecting the corresponding
+ * pending batch promise based on the response ID.
+ * @param {MessageEvent} event - The message event from the parser worker
+ * @return {void}
+ */
+function handleParserResponse(event: MessageEvent): void {
+  const { type, id, ok, results, error } = event.data;
+  // Ignore messages that aren't batch results (e.g. single parse results, stringify results)
+  if (type !== 'parse-batch-result') return;
+  const pending = pendingBatches.get(id);
+  if (!pending) return;
+  pendingBatches.delete(id);
+
+  if (ok) {
+    pending.resolve(results);
+  } else {
+    pending.reject(new Error(error));
+  }
+}
+
+/**
+ * Sends a batch of key/content pairs to a parser worker and returns a promise
+ * that resolves with the parsed results map. Uses an incrementing ID for
+ * request/response correlation, following the same pattern as StorageClient.
+ * @param {Worker} worker - The parser worker to send the batch to
+ * @param {BatchItem[]} items - Array of key/content pairs to parse
+ * @return {Promise<Record<string, Record<string, unknown>>>} Map of key to parsed data
+ */
+function sendBatch(
+  worker: Worker,
+  items: BatchItem[],
+): Promise<Record<string, Record<string, unknown>>> {
+  const id = String(++batchIdCounter);
+  return new Promise((resolve, reject) => {
+    pendingBatches.set(id, { resolve, reject });
+    worker.postMessage({ type: 'parse-batch', id, items });
+  });
+}
+
+/*
+//////////////////////////////
+// File categorization and parsing
+//////////////////////////////
+*/
+
+/**
+ * Processes a list of files by categorizing each file, collecting batch items
+ * for YAML/TOML parser workers, parsing JSON inline, and assembling the final
+ * items array with parsed data.
+ * @param {FileEntry[]} files - The files returned by the storage adapter
+ * @return {Promise<Array<{ filename: string; data: Record<string, unknown> }>>} Parsed items
+ */
+async function processFiles(
+  files: FileEntry[],
+): Promise<Array<{ filename: string; data: Record<string, unknown> }>> {
+  // Inline-parsed results (JSON files)
+  const inlineResults: Array<{
+    filename: string;
+    data: Record<string, unknown>;
+  }> = [];
+
+  // Batch items for YAML worker (frontmatter YAML blocks + YAML data files)
+  const yamlBatch: BatchItem[] = [];
+  // Batch items for TOML worker
+  const tomlBatch: BatchItem[] = [];
+  // Files with no frontmatter get empty data
+  const emptyDataFiles: string[] = [];
+
+  for (const file of files) {
+    const category = getFileCategory(file.filename);
+
+    if (category === 'frontmatter') {
+      const yamlBlock = extractYamlBlock(file.content);
+      if (yamlBlock) {
+        yamlBatch.push({ key: file.filename, content: yamlBlock });
+      } else {
+        // No frontmatter found — include with empty data
+        emptyDataFiles.push(file.filename);
+      }
+      continue;
+    }
+
+    if (category === 'data') {
+      const format = getDataFormat(file.filename);
+
+      if (format === 'json') {
+        try {
+          const data = JSON.parse(file.content) as Record<string, unknown>;
+          inlineResults.push({ filename: file.filename, data });
+        } catch {
+          // Invalid JSON — include with empty data
+          inlineResults.push({ filename: file.filename, data: {} });
+        }
+        continue;
+      }
+
+      if (format === 'yaml') {
+        yamlBatch.push({ key: file.filename, content: file.content });
+        continue;
+      }
+
+      if (format === 'toml') {
+        tomlBatch.push({ key: file.filename, content: file.content });
+        continue;
+      }
+    }
+
+    // Unrecognised file type — include with empty data
+    emptyDataFiles.push(file.filename);
+  }
+
+  // Send batches to parser workers in parallel
+  const promises: Promise<Record<string, Record<string, unknown>>>[] = [];
+  let yamlPromiseIdx = -1;
+  let tomlPromiseIdx = -1;
+
+  if (yamlBatch.length > 0) {
+    yamlPromiseIdx = promises.length;
+    promises.push(sendBatch(getYamlWorker(), yamlBatch));
+  }
+
+  if (tomlBatch.length > 0) {
+    tomlPromiseIdx = promises.length;
+    promises.push(sendBatch(getTomlWorker(), tomlBatch));
+  }
+
+  const batchResults = await Promise.all(promises);
+
+  // Assemble final items from all sources
+  const items: Array<{ filename: string; data: Record<string, unknown> }> = [];
+
+  // Add inline results (JSON)
+  items.push(...inlineResults);
+
+  // Add YAML results — filenames are derived from the batch result keys
+  if (yamlPromiseIdx >= 0) {
+    const yamlResults = batchResults[yamlPromiseIdx];
+    for (const [filename, data] of Object.entries(yamlResults)) {
+      items.push({ filename, data });
+    }
+  }
+
+  // Add TOML results — filenames are derived from the batch result keys
+  if (tomlPromiseIdx >= 0) {
+    const tomlResults = batchResults[tomlPromiseIdx];
+    for (const [filename, data] of Object.entries(tomlResults)) {
+      items.push({ filename, data });
+    }
+  }
+
+  // Add empty-data files
+  for (const filename of emptyDataFiles) {
+    items.push({ filename, data: {} });
+  }
+
+  return items;
+}
+
+/*
+//////////////////////////////
+// Main message handler
+//////////////////////////////
+*/
+
+// Storage client, initialized when the main thread transfers a port
+let storageClient: StorageClient | null = null;
+
+// Handle messages from main thread
+self.addEventListener('message', async (event) => {
+  const { type } = event.data;
+
+  if (type === 'port') {
+    // Main thread is transferring a MessagePort connected to the storage SharedWorker
+    const port = event.ports[0];
+    storageClient = new StorageClient(port);
+    return;
+  }
+
+  if (type === 'parse') {
+    const { collection } = event.data;
+    if (!storageClient) {
+      self.postMessage({
+        type: 'error',
+        message: 'Storage port not initialized',
+      });
+      return;
+    }
+
+    try {
+      // Pass extensions from the message, defaulting to markdown for backward compatibility
+      const extensions: string[] = event.data.extensions ?? ['.md', '.mdx'];
+      const files: FileEntry[] = await storageClient.listFiles(
+        collection,
+        extensions,
+      );
+
+      const items = await processFiles(files);
+
+      // Sort alphabetically by title, falling back to filename
+      items.sort((a, b) => {
+        const aTitle =
+          typeof a.data.title === 'string' ? a.data.title : a.filename;
+        const bTitle =
+          typeof b.data.title === 'string' ? b.data.title : b.filename;
+        return aTitle.toLowerCase().localeCompare(bTitle.toLowerCase());
+      });
+
+      self.postMessage({ type: 'result', collection, items });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      self.postMessage({ type: 'error', message });
+    }
+  }
+});

package/src/client/js/storage/workers/storage.ts

@@ -0,0 +1,177 @@
+/*
+ * SharedWorker entry point for storage operations.
+ * Receives requests over MessagePort, dispatches to the active StorageAdapter,
+ * and posts responses back to each connected client.
+ */
+
+import type {
+  StorageAdapter,
+  StorageRequest,
+  StorageResponse,
+} from '../adapter';
+
+// The single active adapter instance shared across all connected ports
+let adapter: StorageAdapter | null = null;
+
+/**
+ * Handles a request message and returns the appropriate response.
+ * @param {StorageRequest} msg - The incoming request message
+ * @return {Promise<StorageResponse>} The response to send back
+ */
+async function handleMessage(msg: StorageRequest): Promise<StorageResponse> {
+  switch (msg.type) {
+    case 'init': {
+      try {
+        if (msg.backend.type === 'fsa') {
+          const { FsaAdapter } = await import('../fsa');
+          adapter = new FsaAdapter(msg.backend.handle);
+        } else {
+          const { GitHubAdapter } = await import('../github');
+          const gh = new GitHubAdapter(msg.backend.token, msg.backend.repo);
+          await gh.validate();
+          adapter = gh;
+        }
+        return { type: 'init', ok: true };
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return { type: 'init', ok: false, error };
+      }
+    }
+
+    case 'listFiles': {
+      if (!adapter)
+        return {
+          type: 'listFiles',
+          ok: false,
+          error: 'No backend initialized',
+        };
+      try {
+        const files = await adapter.listFiles(msg.collection, msg.extensions);
+        return { type: 'listFiles', ok: true, files };
+      } catch (err) {
+        return {
+          type: 'listFiles',
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    case 'readFile': {
+      if (!adapter)
+        return { type: 'readFile', ok: false, error: 'No backend initialized' };
+      try {
+        const content = await adapter.readFile(msg.collection, msg.filename);
+        return { type: 'readFile', ok: true, content };
+      } catch (err) {
+        return {
+          type: 'readFile',
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    case 'writeFile': {
+      if (!adapter)
+        return {
+          type: 'writeFile',
+          ok: false,
+          error: 'No backend initialized',
+        };
+      try {
+        await adapter.writeFile(msg.collection, msg.filename, msg.content);
+        return { type: 'writeFile', ok: true };
+      } catch (err) {
+        return {
+          type: 'writeFile',
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    case 'writeFiles': {
+      if (!adapter)
+        return {
+          type: 'writeFiles',
+          ok: false,
+          error: 'No backend initialized',
+        };
+      try {
+        await adapter.writeFiles(msg.files);
+        return { type: 'writeFiles', ok: true };
+      } catch (err) {
+        return {
+          type: 'writeFiles',
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    case 'deleteFile': {
+      if (!adapter)
+        return {
+          type: 'deleteFile',
+          ok: false,
+          error: 'No backend initialized',
+        };
+      try {
+        await adapter.deleteFile(msg.collection, msg.filename);
+        return { type: 'deleteFile', ok: true };
+      } catch (err) {
+        return {
+          type: 'deleteFile',
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    case 'teardown': {
+      adapter = null;
+      return { type: 'teardown', ok: true };
+    }
+
+    default: {
+      // Prevents silent hangs if an unrecognized message type arrives
+      const exhaustive: never = msg;
+      return {
+        type: (exhaustive as any).type,
+        ok: false,
+        error: 'Unknown message type',
+      } as StorageResponse;
+    }
+  }
+}
+
+/**
+ * Wires up message handling for a connected port. Passes through `_id` from requests so the StorageClient can correlate responses.
+ * @param {MessagePort} port - The port to listen on
+ * @return {void}
+ */
+function setupPort(port: MessagePort): void {
+  port.addEventListener('message', async (event) => {
+    const { _id, ...msg } = event.data;
+
+    // Handle port bridging — main thread transfers ports for dedicated workers
+    if (msg.type === 'connect-port') {
+      const transferredPort = event.ports[0];
+      if (transferredPort) setupPort(transferredPort);
+      return;
+    }
+
+    const response = await handleMessage(msg as StorageRequest);
+    port.postMessage({ ...response, _id });
+  });
+  port.start();
+  // Acknowledge the connection so the caller knows the port is ready
+  port.postMessage({ type: 'port-connected' });
+}
+
+// SharedWorker entry — handle direct connections from Window contexts
+self.addEventListener('connect', (event: MessageEvent) => {
+  const port = (event as any).ports[0] as MessagePort;
+  setupPort(port);
+});

package/src/client/js/storage/workers/toml-parser.ts

@@ -0,0 +1,106 @@
+/*
+ * TOML parser worker
+ *
+ * Runs as a dedicated Worker. Handles three message types — parse, parse-batch,
+ * stringify — and posts results back to the main thread via self.postMessage.
+ * All handlers are wrapped in try/catch so errors are returned as structured
+ * failure messages rather than unhandled rejections.
+ */
+
+import { parse, stringify } from 'smol-toml';
+
+// Inbound message shape for a single TOML parse request.
+interface ParseMessage {
+  type: 'parse';
+  id: string;
+  content: string;
+}
+
+// A single item in a batch parse request.
+interface BatchItem {
+  key: string;
+  content: string;
+}
+
+// Inbound message shape for a batch TOML parse request.
+interface ParseBatchMessage {
+  type: 'parse-batch';
+  id: string;
+  items: BatchItem[];
+}
+
+// Inbound message shape for a TOML stringify request.
+interface StringifyMessage {
+  type: 'stringify';
+  id: string;
+  data: Record<string, unknown>;
+}
+
+// Union of all inbound message types.
+type InboundMessage = ParseMessage | ParseBatchMessage | StringifyMessage;
+
+/**
+ * Handles a 'parse' request: parses a single TOML string and posts the result.
+ * @param {ParseMessage} msg - The inbound parse message
+ * @return {void}
+ */
+function handleParse(msg: ParseMessage): void {
+  const { id, content } = msg;
+  try {
+    const data = parse(content) as Record<string, unknown>;
+    self.postMessage({ type: 'parse-result', id, ok: true, data });
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    self.postMessage({ type: 'parse-result', id, ok: false, error });
+  }
+}
+
+/**
+ * Handles a 'parse-batch' request: parses multiple TOML strings keyed by
+ * a caller-supplied key, and posts a single result containing all parsed values.
+ * @param {ParseBatchMessage} msg - The inbound parse-batch message
+ * @return {void}
+ */
+function handleParseBatch(msg: ParseBatchMessage): void {
+  const { id, items } = msg;
+  try {
+    const results: Record<string, Record<string, unknown>> = {};
+    for (const item of items) {
+      results[item.key] = parse(item.content) as Record<string, unknown>;
+    }
+    self.postMessage({ type: 'parse-batch-result', id, ok: true, results });
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    self.postMessage({ type: 'parse-batch-result', id, ok: false, error });
+  }
+}
+
+/**
+ * Handles a 'stringify' request: serializes a plain object to a TOML string
+ * and posts the result.
+ * @param {StringifyMessage} msg - The inbound stringify message
+ * @return {void}
+ */
+function handleStringify(msg: StringifyMessage): void {
+  const { id, data } = msg;
+  try {
+    const content = stringify(data);
+    self.postMessage({ type: 'stringify-result', id, ok: true, content });
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    self.postMessage({ type: 'stringify-result', id, ok: false, error });
+  }
+}
+
+// Dispatch incoming messages by type
+self.addEventListener('message', (event: MessageEvent<InboundMessage>) => {
+  const msg = event.data;
+
+  if (msg.type === 'parse') {
+    handleParse(msg);
+  } else if (msg.type === 'parse-batch') {
+    handleParseBatch(msg);
+  } else if (msg.type === 'stringify') {
+    handleStringify(msg);
+  }
+});