nebula-cms 0.1.0

package/src/astro/index.ts

@@ -0,0 +1,295 @@
+/*
+ * 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/Admin.svelte

@@ -0,0 +1,283 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { initRouter, nav, adminPath } from './js/state/router.svelte';
+  import {
+    backend,
+    content,
+    drafts,
+    restoreBackend,
+    loadCollection,
+  } from './js/state/state.svelte';
+  import {
+    preloadFile,
+    loadFileBody,
+    clearEditor,
+    editor,
+    getEditorFile,
+    setDefaultFormat,
+  } from './js/editor/editor.svelte';
+  import { loadDraftById } from './js/drafts/ops.svelte';
+  import {
+    fetchSchema,
+    schema,
+    clearSchema,
+    prefetchAllSchemas,
+    collectionHasDates,
+    getCollectionTitle,
+  } from './js/state/schema.svelte';
+  import {
+    handleDeleteDraft,
+    handleFilenameConfirm,
+    buildContentItems,
+    buildCollectionItems,
+    buildActiveFileHref,
+  } from './js/handlers/admin';
+  import { dialog } from './js/state/dialogs.svelte';
+  import { stripExtension } from './js/utils/file-types';
+  import { initTheme, theme } from './js/state/theme.svelte';
+  import './css/reset.css';
+  import './css/icons.css';
+  import './css/theme.css';
+  import './css/btn.css';
+  import './css/field-input.css';
+  import './css/dialog.css';
+  import './css/a11y.css';
+  import BackendPicker from './components/BackendPicker.svelte';
+  import AdminSidebar from './components/sidebar/AdminSidebar.svelte';
+  import EditorToolbar from './components/editor/EditorToolbar.svelte';
+  import EditorPane from './components/editor/EditorPane.svelte';
+  import EditorTabs from './components/editor/EditorTabs.svelte';
+  import MetadataForm from './components/MetadataForm.svelte';
+  import FilenameDialog from './components/dialogs/FilenameDialog.svelte';
+  import DeleteDraftDialog from './components/dialogs/DeleteDraftDialog.svelte';
+
+  // Whether a collection is currently selected (including draft view)
+  const hasCollection = $derived(nav.route.view !== 'home');
+
+  // The active collection name, if any
+  const activeCollection = $derived(
+    nav.route.view !== 'home' ? nav.route.collection : null,
+  );
+
+  // Whether a file or draft is currently open in the editor
+  const fileOpen = $derived(
+    nav.route.view === 'file' || nav.route.view === 'draft',
+  );
+
+  // The active file/draft href for highlighting in the content sidebar
+  const activeFileHref = $derived(buildActiveFileHref(nav.route));
+
+  // Collection names mapped to SidebarItems, using schema title/description when available
+  const collectionItems = $derived(buildCollectionItems());
+
+  // Content items merged with draft data (DRAFT/OUTDATED chips) plus new draft items
+  const contentItems = $derived(
+    buildContentItems(
+      content.list,
+      drafts.all,
+      drafts.outdated,
+      activeCollection,
+    ),
+  );
+
+  // Whether the active collection has date fields for sort controls
+  const contentHasDates = $derived(
+    activeCollection ? collectionHasDates(activeCollection) : false,
+  );
+
+  // Existing filenames for uniqueness validation in the filename dialog — includes both live files and drafts with filenames
+  const existingFilenames = $derived([
+    ...content.list.map((item) => item.filename),
+    ...drafts.all.filter((d) => d.filename).map((d) => d.filename!),
+  ]);
+
+  // Type identifiers from the schema's files array, used to show the format selector
+  const schemaFileTypes = $derived(
+    Array.isArray(schema.active?.['files'])
+      ? (schema.active['files'] as string[])
+      : [],
+  );
+
+  // Sync the resolved theme to :root so top-layer elements (dialogs) inherit the tokens
+  $effect(() => {
+    document.documentElement.dataset.theme = theme.resolved;
+  });
+
+  // Trigger collection loading when route changes to a collection, file, or draft view
+  $effect(() => {
+    if (backend.ready && nav.route.view !== 'home') {
+      loadCollection(nav.route.collection);
+    }
+  });
+
+  /*
+   * Loads content for the file or draft view. Both branches gate on `backend.ready`
+   * so they re-run when the directory handle is restored on page load.
+   */
+  $effect(() => {
+    if (backend.ready && nav.route.view === 'file' && content.list.length > 0) {
+      const item = content.list.find(
+        (i) => stripExtension(i.filename) === nav.route.slug,
+      );
+      if (!item) return;
+
+      // preloadFile is async — it checks IDB for a draft first
+      preloadFile(nav.route.collection, item.filename, item.data).then(() => {
+        // If preloadFile loaded a draft (body already present), skip disk read
+        const editorFile = getEditorFile();
+        if (editorFile?.draftId) return;
+
+        loadFileBody(nav.route.collection, item.filename);
+      });
+    } else if (backend.ready && nav.route.view === 'draft') {
+      loadDraftById(nav.route.draftId, nav.route.collection);
+    } else if (nav.route.view !== 'file' && nav.route.view !== 'draft') {
+      clearEditor();
+    }
+  });
+
+  /*
+   * Set the default format for new drafts once the schema is available.
+   * New drafts start with an empty filename, so setDefaultFormat assigns
+   * the collection's first file type extension (e.g. '.mdx' for guides).
+   */
+  $effect(() => {
+    const file = getEditorFile();
+    if (file?.isNewDraft && !file.filename && schemaFileTypes.length > 0) {
+      setDefaultFormat(schemaFileTypes);
+    }
+  });
+
+  // Fetch the JSON Schema when the active collection changes
+  $effect(() => {
+    if (backend.ready && nav.route.view !== 'home') {
+      fetchSchema(nav.route.collection);
+    } else {
+      clearSchema();
+    }
+  });
+
+  /**
+   * Handles filename dialog confirmation — hides the dialog and triggers publish with the chosen filename.
+   * @param {string} filename - The chosen filename
+   * @return {Promise<void>}
+   */
+  async function onFilenameConfirm(filename: string): Promise<void> {
+    dialog.close();
+    await handleFilenameConfirm(filename, activeCollection);
+  }
+
+  /**
+   * Handles delete draft confirmation — hides the dialog and deletes the current draft.
+   * @return {Promise<void>}
+   */
+  async function onDeleteConfirm(): Promise<void> {
+    dialog.close();
+    await handleDeleteDraft(activeCollection);
+  }
+
+  onMount(() => {
+    const cleanupTheme = initTheme();
+    initRouter();
+    restoreBackend();
+    prefetchAllSchemas();
+    return cleanupTheme;
+  });
+</script>
+
+<div
+  class="admin"
+  class:admin--connected={backend.ready}
+  class:admin--collection={backend.ready && hasCollection}
+  class:admin--file-open={backend.ready && fileOpen}
+>
+  {#if !backend.ready}
+    <BackendPicker />
+  {:else}
+    <AdminSidebar
+      title="Collections"
+      items={collectionItems}
+      activeItem={activeCollection ? adminPath(activeCollection) : undefined}
+      showFooter={true}
+    />
+    {#if hasCollection && activeCollection}
+      <AdminSidebar
+        title={getCollectionTitle(activeCollection) ??
+          activeCollection.charAt(0).toUpperCase() + activeCollection.slice(1)}
+        items={contentItems}
+        activeItem={activeFileHref}
+        storageKey={activeCollection}
+        loading={content.loading}
+        error={content.error ?? undefined}
+        hasDates={contentHasDates}
+        collection={activeCollection}
+        showAdd={true}
+      />
+    {/if}
+    {#if fileOpen}
+      <div class="editor-area">
+        <EditorToolbar />
+        <EditorTabs schema={schema.active} />
+        <div class="editor-content">
+          {#if editor.tab === 'body'}
+            <EditorPane />
+          {:else if schema.active}
+            <MetadataForm
+              schema={schema.active}
+              tab={editor.tab === 'metadata' ? null : editor.tab}
+            />
+          {/if}
+        </div>
+      </div>
+    {/if}
+  {/if}
+</div>
+
+{#if dialog.active === 'filename'}
+  {@const file = getEditorFile()}
+  <FilenameDialog
+    title={typeof file?.formData.title === 'string' ? file.formData.title : ''}
+    {existingFilenames}
+    onConfirm={onFilenameConfirm}
+    onCancel={dialog.close}
+  />
+{/if}
+
+{#if dialog.active === 'delete'}
+  <DeleteDraftDialog onConfirm={onDeleteConfirm} onCancel={dialog.close} />
+{/if}
+
+<style>
+  .admin {
+    /* Lock to viewport height so the page never scrolls — all scrolling happens inside editor-content or sidebars */
+    height: 100dvh;
+  }
+
+  .admin--connected {
+    display: grid;
+    grid-template-columns: 15rem 1fr;
+  }
+
+  .admin--collection {
+    grid-template-columns: 15rem 15rem 1fr;
+  }
+
+  .admin--file-open {
+    grid-template-columns: 15rem 15rem 1fr;
+  }
+
+  .editor-area {
+    display: grid;
+    /* Toolbar + tabs above, scrollable content below */
+    grid-template-rows: auto auto 1fr;
+    overflow: hidden;
+    border-left: 1px solid var(--cms-border);
+  }
+
+  /* Scrollable content area; min-height: 0 allows the 1fr grid row to shrink */
+  .editor-content {
+    overflow-y: auto;
+    overflow-x: hidden;
+    min-height: 0;
+  }
+</style>