nebula-cms 0.1.0 → 0.1.4

package/src/astro/index.ts

@@ -1,295 +0,0 @@
-/*
- * Astro integration entry point for Nebula CMS.
- * Exposes content collection JSON schemas and CMS configuration to
- * client-side JavaScript via virtual modules, dev middleware, and
- * build-time file copy.
- */
-
-import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-} from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
-import type { NebulaCMSConfig } from '../types.js';
-
-// Vite virtual module IDs
-const CONFIG_VIRTUAL_ID = 'virtual:nebula/config';
-const CONFIG_RESOLVED_ID = '\0' + CONFIG_VIRTUAL_ID;
-const COLLECTIONS_VIRTUAL_ID = 'virtual:nebula/collections';
-const COLLECTIONS_RESOLVED_ID = '\0' + COLLECTIONS_VIRTUAL_ID;
-
-/**
- * Normalizes a path config value to an absolute path using the URL API.
- * Handles leading-slash prepending, consecutive-slash collapsing,
- * trailing-slash stripping, and rejects paths with characters that
- * require percent-encoding (e.g. spaces, angle brackets).
- * @param {string} label - Config field name for error messages (e.g. 'basePath')
- * @param {string} value - The raw config value
- * @return {string} The normalized absolute path
- */
-function normalizePath(label: string, value: string): string {
-  /*
-   * Reject protocol-relative inputs ('//admin') — the URL API interprets
-   * these as hostnames, silently producing pathname '/' instead of '/admin'.
-   */
-  if (value.startsWith('//')) {
-    throw new Error(
-      `Invalid ${label} "${value}". Path must not start with "//".`,
-    );
-  }
-  /*
-   * URL constructor with a dummy base handles both relative ('admin') and
-   * absolute ('/admin') inputs identically. Collapse consecutive slashes
-   * manually since the URL API preserves them in pathnames.
-   */
-  const collapsed = new URL(value, 'http://x').pathname.replace(/\/\/+/g, '/');
-  // Strip trailing slash unless root
-  const normalized =
-    collapsed.length > 1 && collapsed.endsWith('/')
-      ? collapsed.slice(0, -1)
-      : collapsed;
-  /*
-   * The URL API percent-encodes special characters rather than rejecting them
-   * (e.g. '/admin/<script>' → '/admin/%3Cscript%3E'). Comparing the decoded
-   * form to the normalized result catches any input that required encoding.
-   */
-  if (decodeURIComponent(normalized) !== normalized) {
-    throw new Error(
-      `Invalid ${label} "${value}". Path contains characters that require URL encoding.`,
-    );
-  }
-  return normalized;
-}
-
-/**
- * Astro integration that exposes CMS configuration and content collection JSON schemas to client-side JavaScript via virtual modules, dev middleware, and build-time file copy.
- * @param {NebulaCMSConfig} config - Optional configuration object
- * @return {AstroIntegration} The configured Astro integration object
- */
-export default function NebulaCMS(
-  config: NebulaCMSConfig = {},
-): AstroIntegration {
-  if (config.basePath === '') {
-    throw new Error(
-      'Invalid basePath "". Provide a path like "/admin" or "/".',
-    );
-  }
-
-  if (config.collectionsPath === '') {
-    throw new Error(
-      'Invalid collectionsPath "". Provide a path like "/collections".',
-    );
-  }
-
-  const basePath = normalizePath('basePath', config.basePath ?? '/admin');
-  const collectionsPath = normalizePath(
-    'collectionsPath',
-    config.collectionsPath ?? '/collections',
-  );
-
-  if (collectionsPath === '/') {
-    throw new Error(
-      'Invalid collectionsPath "/". Collections require a path prefix.',
-    );
-  }
-
-  // Normalized config passed to the Vite plugin
-  const normalizedConfig = { basePath, collectionsPath };
-
-  return {
-    name: 'nebula-cms',
-    hooks: {
-      'astro:config:setup': ({ updateConfig, logger }) => {
-        updateConfig({
-          vite: {
-            plugins: [
-              nebulaVitePlugin(logger, process.cwd(), normalizedConfig),
-            ],
-            /*
-             * Workers use dynamic imports (e.g. storage worker lazy-loads
-             * adapters), which require code splitting. The default 'iife'
-             * format does not support code splitting, so use ES modules.
-             */
-            worker: { format: 'es' },
-            /*
-             * smol-toml is only imported inside the TOML parser sub-worker,
-             * never on the main thread. Without this, Vite discovers it late
-             * and re-optimizes mid-session, causing the worker to request a
-             * stale dep hash (504 Outdated Optimize Dep).
-             */
-            optimizeDeps: {
-              include: ['smol-toml'],
-            },
-          },
-        });
-      },
-      // Copy schema files into the build output after Astro finishes.
-      'astro:build:done': ({ dir, logger }) => {
-        const source = resolve(process.cwd(), '.astro/collections');
-        if (!existsSync(source)) {
-          logger.warn(
-            '`.astro/collections` not found — schema files will not be in the build output.',
-          );
-          return;
-        }
-        const outDir = fileURLToPath(dir);
-        // Strip leading slash for filesystem path resolution
-        const target = resolve(outDir, collectionsPath.slice(1));
-        mkdirSync(target, { recursive: true });
-        const files = readdirSync(source).filter((f) =>
-          f.endsWith('.schema.json'),
-        );
-        for (const f of files) {
-          copyFileSync(resolve(source, f), resolve(target, f));
-        }
-      },
-    },
-  };
-}
-
-/**
- * Vite plugin that serves collection schemas and CMS config via virtual modules.
- * @internal Not part of the public API — exported for testing only
- * @param {AstroIntegrationLogger} logger - Astro integration logger for warnings
- * @param {string} root - Project root directory
- * @param {Required<NebulaCMSConfig>} config - Normalized CMS configuration (both paths absolute, no trailing slash)
- * @return {object} A Vite plugin object with configureServer, resolveId, and load hooks
- */
-export function nebulaVitePlugin(
-  logger: AstroIntegrationLogger,
-  root: string,
-  config: Required<NebulaCMSConfig>,
-) {
-  return {
-    name: 'vite-plugin-nebula-cms',
-
-    /**
-     * Registers dev middleware: serves schema files from .astro/collections/
-     * and rewrites SPA sub-routes under basePath to the basePath page.
-     * @param {{ middlewares: { use: Function } }} server - The Vite dev server
-     * @return {void}
-     */
-    configureServer(server: { middlewares: { use: Function } }) {
-      const prefix = config.collectionsPath + '/';
-      const collectionsDir = resolve(root, '.astro/collections');
-
-      // Serve collection schema JSON files
-      server.middlewares.use(
-        (
-          req: { url?: string },
-          res: { setHeader: Function; end: Function },
-          next: Function,
-        ) => {
-          // Extract pathname, stripping query strings and fragments
-          const url = new URL(req.url ?? '', 'http://x').pathname;
-          if (!url.startsWith(prefix) || !url.endsWith('.schema.json')) {
-            return next();
-          }
-          const filename = url.slice(prefix.length);
-          const filePath = resolve(collectionsDir, filename);
-          // Reject path traversal attempts (e.g. /../../../etc/passwd.schema.json)
-          if (!filePath.startsWith(collectionsDir + '/')) return next();
-
-          try {
-            res.setHeader('Content-Type', 'application/json');
-            res.end(readFileSync(filePath, 'utf-8'));
-          } catch (err: unknown) {
-            // File not found — fall through to Vite's default handler
-            if (
-              err instanceof Error &&
-              (err as NodeJS.ErrnoException).code === 'ENOENT'
-            ) {
-              return next();
-            }
-            // Re-throw permission errors, I/O errors, etc. so they surface
-            throw err;
-          }
-        },
-      );
-
-      // SPA fallback: rewrite HTML requests under basePath to basePath
-      server.middlewares.use(
-        (
-          req: { url?: string; headers?: Record<string, string | undefined> },
-          _res: unknown,
-          next: Function,
-        ) => {
-          const rawURL = req.url ?? '';
-          const accept = req.headers?.accept ?? '';
-
-          // Only rewrite document requests
-          if (!accept.includes('text/html')) return next();
-
-          const parsed = new URL(rawURL, 'http://x');
-
-          /*
-           * Check segment boundary: /admin/foo rewrites, /administrator does not.
-           * Root basePath '/' needs special handling — every path is a sub-path
-           * except '/' itself, mirroring router.svelte.ts isUnderBasePath.
-           */
-          const isSubPath =
-            config.basePath === '/'
-              ? parsed.pathname !== '/' && parsed.pathname.startsWith('/')
-              : parsed.pathname !== config.basePath &&
-                parsed.pathname.startsWith(config.basePath + '/');
-
-          if (isSubPath) {
-            // Preserve query string and hash for deep-linking and OAuth callbacks
-            req.url = config.basePath + parsed.search + parsed.hash;
-          }
-
-          return next();
-        },
-      );
-    },
-
-    /**
-     * Resolves virtual:nebula/* imports to Vite-internal IDs.
-     * @param {string} id - The module ID being resolved
-     * @return {string | undefined} The resolved internal ID, or undefined if not handled
-     */
-    resolveId(id: string) {
-      if (id === CONFIG_VIRTUAL_ID) return CONFIG_RESOLVED_ID;
-      if (id === COLLECTIONS_VIRTUAL_ID) return COLLECTIONS_RESOLVED_ID;
-    },
-
-    /**
-     * Generates virtual module source code for config and collections.
-     * @param {string} id - The resolved module ID to load
-     * @return {string | undefined} Generated module source code, or undefined if not handled
-     */
-    load(id: string) {
-      if (id === CONFIG_RESOLVED_ID) {
-        return `export default ${JSON.stringify(config)};`;
-      }
-
-      if (id !== COLLECTIONS_RESOLVED_ID) return;
-
-      const collectionsDir = resolve(root, '.astro/collections');
-
-      // Guard: return empty object if directory doesn't exist
-      if (!existsSync(collectionsDir)) {
-        logger.warn(
-          '`.astro/collections` not found — virtual:nebula/collections will be empty.',
-        );
-        return 'export default {};';
-      }
-
-      const files = readdirSync(collectionsDir).filter((f) =>
-        f.endsWith('.schema.json'),
-      );
-
-      const entries = files.map((f) => {
-        const name = f.replace('.schema.json', '');
-        return `  ${JSON.stringify(name)}: ${JSON.stringify(config.collectionsPath + '/' + f)}`;
-      });
-
-      return `export default {\n${entries.join(',\n')}\n};`;
-    },
-  };
-}

package/src/client/js/drafts/merge.svelte.ts

@@ -1,121 +0,0 @@
-import { loadDrafts, type Draft } from './storage';
-import { splitFrontmatter } from '../utils/frontmatter';
-import { storageClient } from '../state/state.svelte';
-
-// Drafts for the current collection
-let draftList = $state<Draft[]>([]);
-// Map of draftId → whether the live content has diverged from the draft's snapshot
-let outdatedMap = $state<Record<string, boolean>>({});
-
-export const drafts = {
-  // All drafts for the active collection.
-  get all(): Draft[] {
-    return draftList;
-  },
-  // Map of draft ID to whether live content has diverged.
-  get outdated(): Record<string, boolean> {
-    return outdatedMap;
-  },
-};
-// Worker for off-thread snapshot comparison
-let diffWorker: Worker | null = null;
-
-/**
- * Initializes the diff worker singleton and wires up the result handler.
- * @return {Worker} The existing or newly created diff worker
- */
-function ensureDiffWorker(): Worker {
-  if (diffWorker) return diffWorker;
-  // Uses .js extension because svelte-package does not rewrite URL string literals
-  diffWorker = new Worker(new URL('./workers/diff.js', import.meta.url), {
-    type: 'module',
-  });
-  diffWorker.addEventListener('message', (event) => {
-    const data = event.data;
-    if (data.type === 'diff-result') {
-      outdatedMap = data.results;
-    }
-  });
-  return diffWorker;
-}
-
-/**
- * Loads drafts for a collection from IndexedDB and dispatches snapshot comparisons to the diff worker for any drafts linked to live files. Reads live file contents via the StorageClient.
- * @param {string} collection - The collection to load drafts for
- * @return {Promise<void>}
- */
-export async function mergeDrafts(collection: string): Promise<void> {
-  draftList = await loadDrafts(collection);
-
-  /*
-   * Filter to drafts that need outdated checking:
-   * must be linked to a live file (not new), have a snapshot, and have a filename.
-   */
-  const candidates = draftList.filter(
-    (d) => !d.isNew && d.snapshot && d.filename,
-  );
-  if (candidates.length === 0) {
-    outdatedMap = {};
-    return;
-  }
-
-  /*
-   * Read all candidate files in parallel instead of sequentially.
-   * js-yaml is dynamically imported because it's a transitive dep — hoist
-   * before the loop so the import is evaluated once, not per-candidate.
-   */
-  const { load } = await import('js-yaml');
-  const settled = await Promise.all(
-    candidates.map(async (d) => {
-      try {
-        const text = await storageClient.readFile(collection, d.filename!);
-        const { rawFrontmatter, body } = splitFrontmatter(text);
-        const liveFormData = (load(rawFrontmatter) ?? {}) as Record<
-          string,
-          unknown
-        >;
-        const liveBody = body.replace(/^\n+/, '').replace(/\n+$/, '');
-        return {
-          draftId: d.id,
-          snapshot: d.snapshot!,
-          liveFormData,
-          liveBody,
-        };
-      } catch {
-        // File not found or unreadable — skip
-        return null;
-      }
-    }),
-  );
-  const entries = settled.filter((e): e is NonNullable<typeof e> => e !== null);
-
-  if (entries.length === 0) {
-    outdatedMap = {};
-    return;
-  }
-
-  // Dispatch to the diff worker for off-thread comparison
-  const worker = ensureDiffWorker();
-  worker.postMessage({ type: 'diff', entries });
-}
-
-/**
- * Re-reads drafts from IndexedDB for the given collection and updates the reactive drafts list.
- * Used after saving/deleting a draft so the sidebar reflects changes immediately without a full collection reload.
- * @param {string} collection - The collection to refresh drafts for
- * @return {Promise<void>}
- */
-export async function refreshDrafts(collection: string): Promise<void> {
-  draftList = await loadDrafts(collection);
-}
-
-/**
- * Resets draft-related state and terminates the diff worker. Called during disconnect.
- * @return {void}
- */
-export function resetDraftMerge(): void {
-  diffWorker?.terminate();
-  diffWorker = null;
-  draftList = [];
-  outdatedMap = {};
-}

package/src/client/js/drafts/ops.svelte.ts

@@ -1,227 +0,0 @@
-import {
-  saveDraft as persistDraft,
-  loadDraft as fetchDraft,
-  deleteDraft as removeDraft,
-  type Draft,
-} from './storage';
-import { stableStringify } from '../utils/stable-stringify';
-import {
-  applyEditorState,
-  _getDraftState,
-  _setDraftState,
-} from '../editor/editor.svelte';
-import { storageClient } from '../state/state.svelte';
-import { getFileCategory, getDataFormat } from '../utils/file-types';
-
-/**
- * Loads a draft by ID from IndexedDB and populates the editor. Falls back to empty state if the draft is not found (safety fallback for the "Add" button flow).
- * @param {string} id - The draft UUID to load
- * @param {string} collection - The collection this draft belongs to
- * @return {Promise<void>}
- */
-export async function loadDraftById(
-  id: string,
-  collection: string,
-): Promise<void> {
-  const draft = await fetchDraft(id);
-
-  if (!draft) {
-    applyEditorState(
-      {
-        body: '',
-        formData: {},
-        filename: '',
-        bodyLoaded: true,
-        draftId: id,
-        isNewDraft: true,
-        snapshot: null,
-        collection,
-        draftCreatedAt: new Date().toISOString(),
-      },
-      true,
-    );
-    return;
-  }
-
-  applyEditorState(
-    {
-      body: draft.body,
-      formData: draft.formData,
-      filename: draft.filename ?? '',
-      bodyLoaded: true,
-      draftId: draft.id,
-      isNewDraft: draft.isNew,
-      snapshot: draft.snapshot,
-      collection,
-      draftCreatedAt: draft.createdAt,
-    },
-    true,
-  );
-}
-
-/**
- * Saves the current editor content as a draft in IndexedDB. On first save, generates a UUID and createdAt timestamp. For live content edits, captures a snapshot of the original data.
- * @return {Promise<void>}
- */
-export async function saveDraftToIDB(): Promise<void> {
-  const s = _getDraftState();
-  _setDraftState({ saving: true });
-
-  try {
-    let { draftId, draftCreatedAt, snapshot } = s;
-
-    // Generate draft ID and timestamp on first save
-    if (!draftId) {
-      draftId = crypto.randomUUID();
-      draftCreatedAt = new Date().toISOString();
-
-      // For live content edits, capture a snapshot of the original saved data
-      if (!s.isNewDraft) {
-        snapshot = stableStringify({
-          formData: JSON.parse(s.lastSavedFormData),
-          body: s.lastSavedBody,
-        });
-      }
-
-      _setDraftState({ draftId, draftCreatedAt, snapshot });
-    }
-
-    const draft: Draft = {
-      id: draftId,
-      collection: s.currentCollection,
-      filename: s.filename || null,
-      isNew: s.isNewDraft,
-      formData: $state.snapshot(s.formData) as Record<string, unknown>,
-      body: s.body,
-      snapshot,
-      createdAt: draftCreatedAt!,
-    };
-
-    await persistDraft(draft);
-    _setDraftState({
-      lastSavedBody: s.body,
-      lastSavedFormData: JSON.stringify(s.formData),
-      dirty: false,
-    });
-  } finally {
-    _setDraftState({ saving: false });
-  }
-}
-
-/**
- * Legacy alias for saveDraftToIDB — preserves existing test mock call sites.
- * @return {Promise<void>}
- */
-export async function saveFile(): Promise<void> {
-  return saveDraftToIDB();
-}
-
-/**
- * Serializes editor content based on the target file format. Data files produce pure JSON/YAML/TOML; frontmatter files produce the standard `---` delimited format.
- * @param {string} filename - The target filename, used to determine format
- * @param {Record<string, unknown>} formData - The structured data to serialize
- * @param {string} body - The body content (only used for frontmatter files)
- * @return {Promise<string>} The serialized file content
- */
-async function serializeContent(
-  filename: string,
-  formData: Record<string, unknown>,
-  body: string,
-): Promise<string> {
-  const category = getFileCategory(filename);
-
-  // Lazy-load js-yaml once for both data and frontmatter YAML paths
-  const loadYAML = () => import('js-yaml');
-
-  if (category === 'data') {
-    const format = getDataFormat(filename);
-    switch (format) {
-      case 'json':
-        return JSON.stringify(formData, null, 2) + '\n';
-      case 'yaml': {
-        const { dump } = await loadYAML();
-        return dump(formData, { lineWidth: -1 });
-      }
-      case 'toml': {
-        const { stringify } = await import('smol-toml');
-        return stringify(formData);
-      }
-      default:
-        throw new Error(`Unsupported data format: ${format}`);
-    }
-  }
-
-  // Frontmatter files: ---\nyaml\n---\n\nbody\n
-  const { dump } = await loadYAML();
-  // dump() adds a trailing newline, so the template omits a \n before ---
-  const yaml = dump(formData, { lineWidth: -1 });
-  return `---\n${yaml}---\n\n${body}\n`;
-}
-
-/**
- * Writes editor content to the storage backend via StorageClient. Dispatches serialization by file format. If originalFilename is provided and differs from filename, deletes the old file (file type conversion). Deletes the associated draft from IndexedDB after a successful write.
- * @param {string} collection - The collection the file belongs to
- * @param {string} filename - The filename to write within the collection
- * @param {string} [originalFilename] - The previous filename if the file was renamed/converted
- * @return {Promise<void>}
- */
-export async function publishFile(
-  collection: string,
-  filename: string,
-  originalFilename?: string,
-): Promise<void> {
-  const s = _getDraftState();
-  _setDraftState({ saving: true });
-
-  try {
-    const content = await serializeContent(filename, s.formData, s.body);
-    await storageClient.writeFile(collection, filename, content);
-
-    // Remove the old file if the filename changed (file type conversion)
-    if (originalFilename && originalFilename !== filename) {
-      await storageClient.deleteFile(collection, originalFilename);
-    }
-
-    // Clean up the draft from IndexedDB after successful publish
-    if (s.draftId) {
-      await removeDraft(s.draftId);
-      _setDraftState({
-        draftId: null,
-        isNewDraft: false,
-        snapshot: null,
-        draftCreatedAt: null,
-      });
-    }
-
-    /*
-     * Update originalFilename so subsequent publishes know the current on-disk name.
-     * Without this, a second format change would not detect the rename because
-     * originalFilename would still point to the pre-first-publish name.
-     */
-    _setDraftState({
-      lastSavedBody: s.body,
-      lastSavedFormData: JSON.stringify(s.formData),
-      dirty: false,
-      originalFilename: filename,
-    });
-  } finally {
-    _setDraftState({ saving: false });
-  }
-}
-
-/**
- * Deletes the current draft from IndexedDB and resets draft-related state fields.
- * @return {Promise<void>}
- */
-export async function deleteCurrentDraft(): Promise<void> {
-  const { draftId } = _getDraftState();
-  if (draftId) {
-    await removeDraft(draftId);
-  }
-  _setDraftState({
-    draftId: null,
-    isNewDraft: false,
-    snapshot: null,
-    draftCreatedAt: null,
-  });
-}