nebula-cms 0.1.0

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

@@ -0,0 +1,102 @@
+/*
+ * Storage adapter interface and shared types.
+ * Defines the contract that FSA and GitHub storage backends implement.
+ */
+
+// A single file's name and content as returned by listFiles.
+export type FileEntry = {
+  filename: string;
+  content: string;
+};
+
+// A file write target with collection path, filename, and content.
+export type FileWrite = {
+  collection: string;
+  filename: string;
+  content: string;
+};
+
+// Contract for storage backend adapters. Both FSA and GitHub adapters implement this.
+export interface StorageAdapter {
+  /**
+   * Lists files in a collection matching the given extensions, returning their names and content.
+   * @param {string} collection - The collection name
+   * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx', '.yaml'])
+   * @return {Promise<FileEntry[]>} Array of filename + content pairs
+   */
+  listFiles(collection: string, extensions: string[]): Promise<FileEntry[]>;
+
+  /**
+   * Deletes a single file from the collection. Used during file type conversion to remove the old file after the new one is written.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename to delete
+   * @return {Promise<void>}
+   */
+  deleteFile(collection: string, filename: string): Promise<void>;
+
+  /**
+   * Reads a single file's content.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename within the collection
+   * @return {Promise<string>} The file content as a string
+   */
+  readFile(collection: string, filename: string): Promise<string>;
+
+  /**
+   * Writes content to a single file, creating it if it doesn't exist.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename within the collection
+   * @param {string} content - The content to write
+   * @return {Promise<void>}
+   */
+  writeFile(
+    collection: string,
+    filename: string,
+    content: string,
+  ): Promise<void>;
+
+  /**
+   * Writes multiple files atomically (single commit for GitHub, sequential for FSA).
+   * @param {FileWrite[]} files - Array of files to write
+   * @return {Promise<void>}
+   */
+  writeFiles(files: FileWrite[]): Promise<void>;
+}
+
+/*
+//////////////////////////////
+// Message types for SharedWorker communication
+//////////////////////////////
+*/
+
+// Union of all request messages that can be sent to the storage SharedWorker.
+export type StorageRequest =
+  | {
+      type: 'init';
+      backend:
+        | { type: 'fsa'; handle: FileSystemDirectoryHandle }
+        | { type: 'github'; token: string; repo: string };
+    }
+  | { type: 'listFiles'; collection: string; extensions: string[] }
+  | { type: 'readFile'; collection: string; filename: string }
+  | { type: 'writeFile'; collection: string; filename: string; content: string }
+  | { type: 'writeFiles'; files: FileWrite[] }
+  | { type: 'deleteFile'; collection: string; filename: string }
+  | { type: 'teardown' };
+
+// Union of all response messages from the storage SharedWorker.
+export type StorageResponse =
+  | { type: 'init'; ok: true }
+  | { type: 'init'; ok: false; error: string }
+  | { type: 'listFiles'; ok: true; files: FileEntry[] }
+  | { type: 'listFiles'; ok: false; error: string }
+  | { type: 'readFile'; ok: true; content: string }
+  | { type: 'readFile'; ok: false; error: string }
+  | { type: 'writeFile'; ok: true }
+  | { type: 'writeFile'; ok: false; error: string }
+  | { type: 'writeFiles'; ok: true }
+  | { type: 'writeFiles'; ok: false; error: string }
+  | { type: 'deleteFile'; ok: true }
+  | { type: 'deleteFile'; ok: false; error: string }
+  | { type: 'teardown'; ok: true }
+  | { type: 'port-connected' };

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

@@ -0,0 +1,150 @@
+/*
+ * Typed client for communicating with the storage SharedWorker over a MessagePort.
+ * Wraps postMessage/onmessage into async request/response calls.
+ */
+
+import type {
+  StorageRequest,
+  StorageResponse,
+  FileEntry,
+  FileWrite,
+} from './adapter';
+
+export class StorageClient {
+  private port: MessagePort;
+  private pending = new Map<
+    string,
+    { resolve: (v: any) => void; reject: (e: Error) => void }
+  >();
+  private idCounter = 0;
+
+  /**
+   * Creates a client wrapping the given port.
+   * @param {MessagePort} port - The port connected to the storage SharedWorker
+   */
+  constructor(port: MessagePort) {
+    this.port = port;
+    this.port.addEventListener('message', (event) => {
+      this.handleResponse(event.data);
+    });
+    this.port.start();
+  }
+
+  /**
+   * Routes responses to their pending promises. Responses without an _id are broadcast (like port-connected) and are ignored here.
+   * @param {StorageResponse & { _id?: string }} data - The response data
+   * @return {void}
+   */
+  private handleResponse(data: StorageResponse & { _id?: string }): void {
+    if (!data._id) return;
+    const entry = this.pending.get(data._id);
+    if (!entry) return;
+    this.pending.delete(data._id);
+    if ('ok' in data && data.ok === false && 'error' in data) {
+      entry.reject(new Error((data as any).error));
+    } else {
+      entry.resolve(data);
+    }
+  }
+
+  /**
+   * Sends a request and waits for the matching response.
+   * @param {StorageRequest} msg - The request to send
+   * @return {Promise<StorageResponse>} The matched response
+   */
+  private send<T extends StorageResponse>(msg: StorageRequest): Promise<T> {
+    const _id = String(++this.idCounter);
+    return new Promise((resolve, reject) => {
+      this.pending.set(_id, { resolve, reject });
+      this.port.postMessage({ ...msg, _id });
+    });
+  }
+
+  /**
+   * Initializes the backend adapter in the SharedWorker.
+   * @param {StorageRequest & { type: 'init' }} config - The init config
+   * @return {Promise<void>}
+   */
+  async init(config: StorageRequest & { type: 'init' }): Promise<void> {
+    await this.send(config);
+  }
+
+  /**
+   * Lists files in a collection matching the given extensions.
+   * @param {string} collection - The collection name
+   * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx'])
+   * @return {Promise<FileEntry[]>} Array of file entries
+   */
+  async listFiles(
+    collection: string,
+    extensions: string[],
+  ): Promise<FileEntry[]> {
+    const res = await this.send<
+      Extract<StorageResponse, { type: 'listFiles'; ok: true }>
+    >({
+      type: 'listFiles',
+      collection,
+      extensions,
+    });
+    return res.files;
+  }
+
+  /**
+   * Reads a single file's content.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename
+   * @return {Promise<string>} The file content
+   */
+  async readFile(collection: string, filename: string): Promise<string> {
+    const res = await this.send<
+      Extract<StorageResponse, { type: 'readFile'; ok: true }>
+    >({
+      type: 'readFile',
+      collection,
+      filename,
+    });
+    return res.content;
+  }
+
+  /**
+   * Writes a single file.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename
+   * @param {string} content - The content to write
+   * @return {Promise<void>}
+   */
+  async writeFile(
+    collection: string,
+    filename: string,
+    content: string,
+  ): Promise<void> {
+    await this.send({ type: 'writeFile', collection, filename, content });
+  }
+
+  /**
+   * Writes multiple files atomically.
+   * @param {FileWrite[]} files - Array of files to write
+   * @return {Promise<void>}
+   */
+  async writeFiles(files: FileWrite[]): Promise<void> {
+    await this.send({ type: 'writeFiles', files });
+  }
+
+  /**
+   * Deletes a file from a collection. Used during file type conversion to remove the old file after the new one is written.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename to delete
+   * @return {Promise<void>}
+   */
+  async deleteFile(collection: string, filename: string): Promise<void> {
+    await this.send({ type: 'deleteFile', collection, filename });
+  }
+
+  /**
+   * Tears down the active backend adapter.
+   * @return {Promise<void>}
+   */
+  async teardown(): Promise<void> {
+    await this.send({ type: 'teardown' });
+  }
+}

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

@@ -0,0 +1,36 @@
+// Database name for admin CMS persistence
+const DB_NAME = 'cms-admin';
+// Current database version — bumped from 1 to add the drafts store
+const DB_VERSION = 2;
+
+// Cached database promise — opened once, reused by all callers
+let dbPromise: Promise<IDBDatabase> | null = null;
+
+/**
+ * Opens (or returns the cached) shared IndexedDB database, creating or upgrading stores as needed.
+ * The connection is opened once and reused, avoiding a new indexedDB.open() round-trip per call.
+ * Version 1: handles store only. Version 2: adds drafts store.
+ * @return {Promise<IDBDatabase>} Promise resolving to the database instance
+ */
+export function openDB(): Promise<IDBDatabase> {
+  if (dbPromise) return dbPromise;
+  dbPromise = new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains('handles')) {
+        db.createObjectStore('handles');
+      }
+      if (!db.objectStoreNames.contains('drafts')) {
+        db.createObjectStore('drafts', { keyPath: 'id' });
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => {
+      // Reset cache so the next caller retries instead of getting a stale rejection
+      dbPromise = null;
+      reject(request.error);
+    };
+  });
+  return dbPromise;
+}

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

@@ -0,0 +1,110 @@
+/*
+ * Storage adapter backed by the File System Access API.
+ * Traverses from a project root handle through src/content/{collection}/ for all operations.
+ */
+
+import type { StorageAdapter, FileEntry, FileWrite } from './adapter';
+
+// FSA adapter implementation
+export class FsaAdapter implements StorageAdapter {
+  /**
+   * Creates an FSA adapter rooted at the given directory handle.
+   * @param {FileSystemDirectoryHandle} root - The project root directory handle
+   */
+  constructor(private root: FileSystemDirectoryHandle) {}
+
+  /**
+   * Traverses root → src → content → {collection}.
+   * @param {string} collection - The collection name
+   * @return {Promise<FileSystemDirectoryHandle>} The collection directory handle
+   */
+  private async getCollectionDir(
+    collection: string,
+  ): Promise<FileSystemDirectoryHandle> {
+    const src = await this.root.getDirectoryHandle('src');
+    const content = await src.getDirectoryHandle('content');
+    return content.getDirectoryHandle(collection);
+  }
+
+  /**
+   * Lists files in the collection matching the given extensions, with their content.
+   * @param {string} collection - The collection name
+   * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx'])
+   * @return {Promise<FileEntry[]>} Array of filename + content pairs
+   */
+  async listFiles(
+    collection: string,
+    extensions: string[],
+  ): Promise<FileEntry[]> {
+    const dir = await this.getCollectionDir(collection);
+    const entries: FileEntry[] = [];
+
+    for await (const [name, entry] of dir.entries()) {
+      if (
+        entry.kind !== 'file' ||
+        !extensions.some((ext) => name.endsWith(ext))
+      ) {
+        continue;
+      }
+      const file = await entry.getFile();
+      const content = await file.text();
+      entries.push({ filename: name, content });
+    }
+
+    return entries;
+  }
+
+  /**
+   * Deletes a file from the collection directory.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename to delete
+   * @return {Promise<void>}
+   */
+  async deleteFile(collection: string, filename: string): Promise<void> {
+    const dir = await this.getCollectionDir(collection);
+    await dir.removeEntry(filename);
+  }
+
+  /**
+   * Reads a single file's content from the collection.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename
+   * @return {Promise<string>} The file content
+   */
+  async readFile(collection: string, filename: string): Promise<string> {
+    const dir = await this.getCollectionDir(collection);
+    const fileHandle = await dir.getFileHandle(filename);
+    const file = await fileHandle.getFile();
+    return file.text();
+  }
+
+  /**
+   * Writes content to a file, creating it if necessary.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename
+   * @param {string} content - The content to write
+   * @return {Promise<void>}
+   */
+  async writeFile(
+    collection: string,
+    filename: string,
+    content: string,
+  ): Promise<void> {
+    const dir = await this.getCollectionDir(collection);
+    const fileHandle = await dir.getFileHandle(filename, { create: true });
+    const writable = await fileHandle.createWritable();
+    await writable.write(content);
+    await writable.close();
+  }
+
+  /**
+   * Writes multiple files sequentially (FSA has no atomic multi-file write).
+   * @param {FileWrite[]} files - Array of files to write
+   * @return {Promise<void>}
+   */
+  async writeFiles(files: FileWrite[]): Promise<void> {
+    for (const f of files) {
+      await this.writeFile(f.collection, f.filename, f.content);
+    }
+  }
+}

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

@@ -0,0 +1,297 @@
+/*
+ * Storage adapter backed by the GitHub REST API.
+ * Uses a Personal Access Token for authentication. All file operations
+ * target src/content/{collection}/ within the repository.
+ */
+
+import type { StorageAdapter, FileEntry, FileWrite } from './adapter';
+
+/**
+ * Encodes a Uint8Array to a base64 string without using deprecated unescape().
+ * @param {Uint8Array} bytes - The bytes to encode
+ * @return {string} Base64-encoded string
+ */
+function uint8ToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export class GitHubAdapter implements StorageAdapter {
+  private token: string;
+  private owner: string;
+  private repo: string;
+  // Cached on validate(); defaults to 'main' before validation
+  private defaultBranch: string = 'main';
+
+  /**
+   * @param {string} token - GitHub Personal Access Token
+   * @param {string} repoSlug - Repository in "owner/repo" format
+   */
+  constructor(token: string, repoSlug: string) {
+    this.token = token;
+    const [owner, repo] = repoSlug.split('/');
+    this.owner = owner;
+    this.repo = repo;
+  }
+
+  /**
+   * Validates credentials by fetching repo metadata and caches the default branch.
+   * @return {Promise<void>}
+   */
+  async validate(): Promise<void> {
+    const res = await this.request('GET', `/repos/${this.owner}/${this.repo}`);
+    if (!res.ok) {
+      const status = res.status;
+      if (status === 401) throw new Error('Invalid or expired token');
+      if (status === 403) throw new Error('Token lacks repository access');
+      if (status === 404)
+        throw new Error(`Repository "${this.owner}/${this.repo}" not found`);
+      throw new Error(`GitHub API error: ${status}`);
+    }
+    const data = await res.json();
+    this.defaultBranch = data.default_branch;
+  }
+
+  /**
+   * Lists files in a collection matching the given extensions, with their raw content.
+   * @param {string} collection - The collection name
+   * @param {string[]} extensions - File extensions to include (e.g. ['.md', '.mdx'])
+   * @return {Promise<FileEntry[]>} Array of filename + content pairs
+   */
+  async listFiles(
+    collection: string,
+    extensions: string[],
+  ): Promise<FileEntry[]> {
+    const path = `src/content/${collection}`;
+    // Get directory listing
+    const listRes = await this.request(
+      'GET',
+      `/repos/${this.owner}/${this.repo}/contents/${path}?ref=${this.defaultBranch}`,
+    );
+    if (!listRes.ok) {
+      if (listRes.status === 404) return [];
+      throw new Error(`Failed to list files: ${listRes.status}`);
+    }
+    const listing: Array<{ name: string; download_url: string }> =
+      await listRes.json();
+
+    // Filter to requested extensions and fetch all files in parallel
+    const filtered = listing.filter((f) =>
+      extensions.some((ext) => f.name.endsWith(ext)),
+    );
+
+    return Promise.all(
+      filtered.map(async (file) => ({
+        filename: file.name,
+        content: await this.readFile(collection, file.name),
+      })),
+    );
+  }
+
+  /**
+   * Deletes a file from the repository via the Contents API.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename to delete
+   * @return {Promise<void>}
+   */
+  async deleteFile(collection: string, filename: string): Promise<void> {
+    const path = `src/content/${collection}/${filename}`;
+    // Get the current SHA (required by the GitHub Contents API for deletion)
+    const existing = await this.request(
+      'GET',
+      `/repos/${this.owner}/${this.repo}/contents/${path}?ref=${this.defaultBranch}`,
+    );
+    if (!existing.ok) throw new Error(`File not found for deletion: ${path}`);
+    const data = await existing.json();
+
+    const res = await this.request(
+      'DELETE',
+      `/repos/${this.owner}/${this.repo}/contents/${path}`,
+      undefined,
+      {
+        message: `Delete ${path}`,
+        sha: data.sha,
+        branch: this.defaultBranch,
+      },
+    );
+    if (!res.ok) throw new Error(`Failed to delete ${path}: ${res.status}`);
+  }
+
+  /**
+   * Reads a single file's raw content via the raw+json Accept header.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename
+   * @return {Promise<string>} The file content
+   */
+  async readFile(collection: string, filename: string): Promise<string> {
+    const path = `src/content/${collection}/${filename}`;
+    const res = await this.request(
+      'GET',
+      `/repos/${this.owner}/${this.repo}/contents/${path}?ref=${this.defaultBranch}`,
+      { Accept: 'application/vnd.github.raw+json' },
+    );
+    if (!res.ok) {
+      throw new Error(`Failed to read ${path}: ${res.status}`);
+    }
+    return res.text();
+  }
+
+  /**
+   * Writes a single file via the Contents API. Fetches the current SHA for updates.
+   * @param {string} collection - The collection name
+   * @param {string} filename - The filename
+   * @param {string} content - The content to write
+   * @return {Promise<void>}
+   */
+  async writeFile(
+    collection: string,
+    filename: string,
+    content: string,
+  ): Promise<void> {
+    const path = `src/content/${collection}/${filename}`;
+    // Get current SHA if file exists (required by GitHub API for updates)
+    let sha: string | undefined;
+    const existing = await this.request(
+      'GET',
+      `/repos/${this.owner}/${this.repo}/contents/${path}?ref=${this.defaultBranch}`,
+    );
+    if (existing.ok) {
+      const data = await existing.json();
+      sha = data.sha;
+    }
+
+    const body: Record<string, string> = {
+      message: `Update ${path}`,
+      content: uint8ToBase64(new TextEncoder().encode(content)),
+      branch: this.defaultBranch,
+    };
+    if (sha) body.sha = sha;
+
+    const res = await this.request(
+      'PUT',
+      `/repos/${this.owner}/${this.repo}/contents/${path}`,
+      undefined,
+      body,
+    );
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`Failed to write ${path}: ${res.status} ${errText}`);
+    }
+  }
+
+  /**
+   * Writes multiple files in a single atomic commit using the Git Trees + Commits API.
+   * @param {FileWrite[]} files - Array of files to write
+   * @return {Promise<void>}
+   */
+  async writeFiles(files: FileWrite[]): Promise<void> {
+    if (files.length === 0) return;
+    if (files.length === 1) {
+      await this.writeFile(
+        files[0].collection,
+        files[0].filename,
+        files[0].content,
+      );
+      return;
+    }
+
+    // 1. Get current commit SHA for the default branch
+    const refRes = await this.request(
+      'GET',
+      `/repos/${this.owner}/${this.repo}/git/ref/heads/${this.defaultBranch}`,
+    );
+    if (!refRes.ok)
+      throw new Error(`Failed to get branch ref: ${refRes.status}`);
+    const refData = await refRes.json();
+    const baseCommitSHA = refData.object.sha;
+
+    // Get the base tree SHA from the current commit
+    const commitRes = await this.request(
+      'GET',
+      `/repos/${this.owner}/${this.repo}/git/commits/${baseCommitSHA}`,
+    );
+    if (!commitRes.ok)
+      throw new Error(`Failed to get commit: ${commitRes.status}`);
+    const commitData = await commitRes.json();
+    const baseTreeSHA = commitData.tree.sha;
+
+    // 2. Create a new tree containing all file changes
+    const tree = files.map((f) => ({
+      path: `src/content/${f.collection}/${f.filename}`,
+      mode: '100644' as const,
+      type: 'blob' as const,
+      content: f.content,
+    }));
+
+    const treeRes = await this.request(
+      'POST',
+      `/repos/${this.owner}/${this.repo}/git/trees`,
+      undefined,
+      { base_tree: baseTreeSHA, tree },
+    );
+    if (!treeRes.ok)
+      throw new Error(`Failed to create tree: ${treeRes.status}`);
+    const treeData = await treeRes.json();
+
+    // 3. Create a new commit pointing at the new tree
+    const paths = files.map((f) => `${f.collection}/${f.filename}`).join(', ');
+    const newCommitRes = await this.request(
+      'POST',
+      `/repos/${this.owner}/${this.repo}/git/commits`,
+      undefined,
+      {
+        message: `Update ${paths}`,
+        tree: treeData.sha,
+        parents: [baseCommitSHA],
+      },
+    );
+    if (!newCommitRes.ok)
+      throw new Error(`Failed to create commit: ${newCommitRes.status}`);
+    const newCommitData = await newCommitRes.json();
+
+    // 4. Advance the branch ref to the new commit
+    const updateRefRes = await this.request(
+      'PATCH',
+      `/repos/${this.owner}/${this.repo}/git/refs/heads/${this.defaultBranch}`,
+      undefined,
+      { sha: newCommitData.sha },
+    );
+    if (!updateRefRes.ok)
+      throw new Error(`Failed to update ref: ${updateRefRes.status}`);
+  }
+
+  /**
+   * Makes an authenticated request to the GitHub API.
+   * @param {string} method - HTTP method
+   * @param {string} path - API path (appended to https://api.github.com)
+   * @param {Record<string, string>} [extraHeaders] - Additional headers to merge
+   * @param {unknown} [body] - JSON body to send
+   * @return {Promise<Response>} The fetch response
+   */
+  private async request(
+    method: string,
+    path: string,
+    extraHeaders?: Record<string, string>,
+    body?: unknown,
+  ): Promise<Response> {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.token}`,
+      'X-GitHub-Api-Version': '2026-03-10',
+      // Default to JSON so the browser cache distinguishes from raw content requests
+      Accept: 'application/vnd.github+json',
+      ...extraHeaders,
+    };
+    if (body) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    return fetch(`https://api.github.com${path}`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+      // API responses must never be served from browser cache
+      cache: 'no-store',
+    });
+  }
+}