meno-core 1.0.48 → 1.0.50

package/lib/server/providers/fileSystemCMSProvider.ts

@@ -7,10 +7,12 @@ import { existsSync, readdirSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import type { CMSProvider, CMSSchemaInfo } from '../../shared/interfaces/contentProvider';
 import type { CMSSchema, CMSItem } from '../../shared/types';
-import { validateCMSItem } from '../../shared/validation/validators';
-import { isSafePathSegment, isValidIdentifier } from '../../shared/pathSecurity';
+import { validateCMSItem, validateCMSDraftItem } from '../../shared/validation/validators';
+import { isSafePathSegment, isValidIdentifier, isReservedDraftFilename, CMS_DRAFT_SUFFIX } from '../../shared/pathSecurity';
 import { readJsonFile, fileExists } from '../runtime';
 
+const DRAFT_FILE_SUFFIX = `${CMS_DRAFT_SUFFIX}.json`;
+
 /**
  * Load JSON file content from disk
  * Logs a warning if JSON parsing fails (helps debug malformed files)
@@ -28,14 +30,37 @@ async function loadJSONFile(filePath: string): Promise<unknown | null> {
 }
 
 /**
- * Normalize a raw CMS item by adding _slug and _filename fields
+ * Normalize a raw CMS item by adding _slug, _filename, and _id (backfilled
+ * from filename for items written without one — the editor stopped writing
+ * a separate random _id once _filename became the canonical identifier).
+ * If `isDraft` is true, also sets the transient `_isDraft` flag.
  */
-function normalizeItem(content: unknown, filename: string): CMSItem {
-  return {
-    ...content as CMSItem,
+function normalizeItem(content: unknown, filename: string, isDraft = false): CMSItem {
+  const raw = content as CMSItem;
+  const base: CMSItem = {
+    ...raw,
+    _id: raw._id || filename,
     _slug: filename,
     _filename: filename,
   };
+  if (isDraft) base._isDraft = true;
+  return base;
+}
+
+/**
+ * Strip transient fields that must never be persisted to disk.
+ * Also drops `_filename` when it equals `_id` (the canonical case for new
+ * items) so the field stops accumulating in storage. Legacy items where
+ * `_filename` differs from `_id` keep the field on disk so the on-disk
+ * file-routing path can still find them.
+ */
+function stripTransient<T extends Record<string, unknown>>(item: T): Omit<T, '_slug' | '_isDraft' | '_hasDraft' | '_url'> {
+  const { _slug, _isDraft, _hasDraft, _url, _filename, ...rest } = item;
+  const out = rest as Omit<T, '_slug' | '_isDraft' | '_hasDraft' | '_url'>;
+  if (typeof _filename === 'string' && _filename !== (out as Record<string, unknown>)._id) {
+    (out as Record<string, unknown>)._filename = _filename;
+  }
+  return out;
 }
 
 /**
@@ -61,13 +86,16 @@ export class FileSystemCMSProvider implements CMSProvider {
   }
 
   /**
-   * Validate filename to prevent path traversal attacks
+   * Validate filename to prevent path traversal attacks and reserved-suffix collisions.
    * @throws Error if filename is invalid
    */
   private validateFilename(filename: string): void {
     if (!isSafePathSegment(filename)) {
       throw new Error(`Invalid filename: "${filename}". Filenames cannot contain path separators or traversal sequences.`);
     }
+    if (isReservedDraftFilename(filename)) {
+      throw new Error(`Invalid filename: "${filename}". The "${CMS_DRAFT_SUFFIX}" suffix is reserved for draft files.`);
+    }
   }
 
   /**
@@ -131,7 +159,8 @@ export class FileSystemCMSProvider implements CMSProvider {
     }
 
     const files = readdirSync(collectionDir);
-    const jsonFiles = files.filter(f => f.endsWith('.json'));
+    // Published items only — exclude `*.draft.json` files (draft-version siblings)
+    const jsonFiles = files.filter(f => f.endsWith('.json') && !f.endsWith(DRAFT_FILE_SUFFIX));
 
     const results = await Promise.all(
       jsonFiles.map(async file => {
@@ -200,8 +229,10 @@ export class FileSystemCMSProvider implements CMSProvider {
   }
 
   /**
-   * Save item to file system
-   * Uses _filename for file path (stable, doesn't change when slug changes)
+   * Save item to file system.
+   * The on-disk filename is derived from `_filename` (legacy alias) when set,
+   * otherwise from `_id` (canonical identifier; equals the filename for new
+   * items). Falls back to the slugField value as a last resort.
    */
   async saveItem(collection: string, item: CMSItem): Promise<void> {
     this.validateCollection(collection);
@@ -215,21 +246,31 @@ export class FileSystemCMSProvider implements CMSProvider {
       throw new Error(`Unknown collection: ${collection}`);
     }
 
-    // Use _filename for file path (new behavior)
-    // Falls back to slugField for backward compatibility with items without _filename
+    // Filename derivation precedence:
+    // 1. `_filename` — explicit on-disk filename. Used by the editor (preserves
+    //    legacy items where `_filename` differs from `_id`).
+    // 2. slug-field value — back-compat for external API callers who build
+    //    items from raw input with a slug field.
+    // 3. `_id` — last resort. For new items written by the editor `_id`
+    //    equals the filename, so this path also produces the correct name.
     let filename: string;
 
     if (item._filename) {
       filename = item._filename;
     } else {
-      // Legacy fallback: use slug field value (may break for i18n slugs)
       const slugField = schemaInfo.schema.slugField;
       const slugValue = item[slugField];
-      filename = typeof slugValue === 'string' ? slugValue : String(slugValue);
+      if (typeof slugValue === 'string' && slugValue) {
+        filename = slugValue;
+      } else if (typeof item._id === 'string' && item._id) {
+        filename = item._id;
+      } else {
+        filename = String(slugValue);
+      }
     }
 
     if (!filename || filename === '[object Object]') {
-      throw new Error('Missing _filename field. Items must have _filename set on creation.');
+      throw new Error('Cannot derive filename: item is missing _id, _filename, and a usable slug-field value.');
     }
 
     // Validate filename to prevent path traversal
@@ -241,27 +282,207 @@ export class FileSystemCMSProvider implements CMSProvider {
       mkdirSync(collectionDir, { recursive: true });
     }
 
-    // Remove internal _slug field before saving (keep _filename in file for persistence)
-    const { _slug, ...itemData } = item;
+    // Strip transient fields (_slug, _isDraft, _hasDraft, _url) before persisting
+    const itemData = stripTransient(item as Record<string, unknown>);
 
     const filePath = join(collectionDir, `${filename}.json`);
     await writeFile(filePath, JSON.stringify(itemData, null, 2), 'utf-8');
   }
 
   /**
-   * Delete item by filename (or slug for backward compat)
+   * Delete item by filename. Removes the published file AND any draft sibling.
    */
   async deleteItem(collection: string, filename: string): Promise<void> {
     this.validateCollection(collection);
     this.validateFilename(filename);
     const { unlink } = await import('fs/promises');
-    const filePath = join(this.cmsDir, collection, `${filename}.json`);
 
+    const publishedPath = join(this.cmsDir, collection, `${filename}.json`);
+    if (existsSync(publishedPath)) {
+      await unlink(publishedPath);
+    }
+
+    const draftPath = this.draftPath(collection, filename);
+    if (existsSync(draftPath)) {
+      await unlink(draftPath);
+    }
+  }
+
+  // ---- Draft helpers ----------------------------------------------------
+
+  private draftPath(collection: string, filename: string): string {
+    return join(this.cmsDir, collection, `${filename}${DRAFT_FILE_SUFFIX}`);
+  }
+
+  /**
+   * Get the draft version of an item, or null if no draft file exists.
+   * Drafts skip strict validation — they may be partial / WIP.
+   */
+  async getDraft(collection: string, filename: string): Promise<CMSItem | null> {
+    this.validateCollection(collection);
+    this.validateFilename(filename);
+    const filePath = this.draftPath(collection, filename);
+    const content = await loadJSONFile(filePath);
+
+    if (!content || typeof content !== 'object') {
+      return null;
+    }
+
+    return normalizeItem(content, filename, /*isDraft*/ true);
+  }
+
+  /**
+   * List all drafts in a collection. Used by the Studio item list to mark
+   * items that have an outstanding draft sibling (or are draft-only).
+   */
+  async getAllDrafts(collection: string): Promise<CMSItem[]> {
+    this.validateCollection(collection);
+    const collectionDir = join(this.cmsDir, collection);
+    if (!existsSync(collectionDir)) return [];
+
+    const files = readdirSync(collectionDir).filter(f => f.endsWith(DRAFT_FILE_SUFFIX));
+
+    const results = await Promise.all(
+      files.map(async file => {
+        const filePath = join(collectionDir, file);
+        const content = await loadJSONFile(filePath);
+        return { file, content };
+      })
+    );
+
+    const drafts: CMSItem[] = [];
+    for (const { file, content } of results) {
+      if (content && typeof content === 'object') {
+        const filename = file.slice(0, -DRAFT_FILE_SUFFIX.length);
+        drafts.push(normalizeItem(content, filename, /*isDraft*/ true));
+      }
+    }
+    return drafts;
+  }
+
+  async hasDraft(collection: string, filename: string): Promise<boolean> {
+    this.validateCollection(collection);
+    this.validateFilename(filename);
+    return existsSync(this.draftPath(collection, filename));
+  }
+
+  /**
+   * Save the draft version of an item. Loose validation — drafts may have
+   * missing required fields or partial data. Strict validation only runs at
+   * publish time. The on-disk filename is derived the same way as for
+   * `saveItem` (prefer `_filename`, fall back to `_id`).
+   */
+  async saveDraft(collection: string, item: CMSItem): Promise<void> {
+    this.validateCollection(collection);
+    const { writeFile } = await import('fs/promises');
+
+    const schemas = await this.getAllSchemas();
+    const schemaInfo = schemas.get(collection);
+    if (!schemaInfo) {
+      throw new Error(`Unknown collection: ${collection}`);
+    }
+
+    // Filename derivation: same precedence as saveItem.
+    let filename: string;
+    if (item._filename) {
+      filename = item._filename;
+    } else {
+      const slugField = schemaInfo.schema.slugField;
+      const slugValue = item[slugField];
+      if (typeof slugValue === 'string' && slugValue) {
+        filename = slugValue;
+      } else if (typeof item._id === 'string' && item._id) {
+        filename = item._id;
+      } else {
+        filename = String(slugValue);
+      }
+    }
+
+    if (!filename || filename === '[object Object]') {
+      throw new Error('Cannot derive draft filename: item is missing _id, _filename, and a usable slug-field value.');
+    }
+
+    this.validateFilename(filename);
+
+    const collectionDir = join(this.cmsDir, collection);
+    if (!existsSync(collectionDir)) {
+      mkdirSync(collectionDir, { recursive: true });
+    }
+
+    const itemData = stripTransient(item as Record<string, unknown>);
+
+    // Loose validation — drafts may be partial WIP. Strict validation
+    // (validateCMSItem) runs on Publish.
+    const validation = validateCMSDraftItem(itemData);
+    if (!validation.valid) {
+      const messages = validation.errors.map(e => `${e.path}: ${e.message}`).join(', ');
+      throw new Error(`Invalid draft: ${messages}`);
+    }
+
+    const filePath = this.draftPath(collection, filename);
+    await writeFile(filePath, JSON.stringify(itemData, null, 2), 'utf-8');
+  }
+
+  /**
+   * Discard the draft version of an item. No-op if no draft exists.
+   */
+  async discardDraft(collection: string, filename: string): Promise<void> {
+    this.validateCollection(collection);
+    this.validateFilename(filename);
+    const { unlink } = await import('fs/promises');
+    const filePath = this.draftPath(collection, filename);
     if (existsSync(filePath)) {
       await unlink(filePath);
     }
   }
 
+  /**
+   * Promote a draft to published. Reads `{filename}.draft.json`, writes the
+   * content to `{filename}.json`, then unlinks the draft. The published write
+   * happens first so a crash mid-operation leaves a valid published file plus
+   * an orphan draft (recoverable via the editor's Discard button) — never a
+   * gap with no published content.
+   *
+   * Throws if no draft exists.
+   */
+  async publishDraft(collection: string, filename: string): Promise<CMSItem> {
+    this.validateCollection(collection);
+    this.validateFilename(filename);
+    const { writeFile, unlink } = await import('fs/promises');
+
+    const draftFilePath = this.draftPath(collection, filename);
+    const content = await loadJSONFile(draftFilePath);
+    if (!content || typeof content !== 'object') {
+      throw new Error(`No draft to publish for ${collection}/${filename}`);
+    }
+
+    // Strict validation when going live
+    const item = normalizeItem(content, filename);
+    const validation = validateCMSItem(item);
+    if (!validation.valid) {
+      const messages = validation.errors.map(e => `${e.path}: ${e.message}`).join(', ');
+      throw new Error(`Cannot publish invalid draft: ${messages}`);
+    }
+
+    const collectionDir = join(this.cmsDir, collection);
+    if (!existsSync(collectionDir)) {
+      mkdirSync(collectionDir, { recursive: true });
+    }
+
+    const itemData = stripTransient(validation.data as unknown as Record<string, unknown>);
+    const publishedPath = join(collectionDir, `${filename}.json`);
+    await writeFile(publishedPath, JSON.stringify(itemData, null, 2), 'utf-8');
+
+    // Published written successfully — now retire the draft. If unlink fails,
+    // the published copy is already in place; an orphan draft can be cleared
+    // via the editor's Discard action.
+    if (existsSync(draftFilePath)) {
+      await unlink(draftFilePath);
+    }
+
+    return normalizeItem(itemData, filename);
+  }
+
   /**
    * Clear schema cache (useful when pages are modified)
    */

package/lib/server/routes/index.ts

@@ -141,7 +141,7 @@ export async function handleRoutes(
 
     // Page routes (SSR)
     if (url.pathname === '/' || (url.pathname.startsWith('/') && !url.pathname.includes('.'))) {
-      const response = await handlePageRoute(url, context);
+      const response = await handlePageRoute(url, context, req);
       logResponseTime(startTime, req);
       return response;
     }

package/lib/server/routes/pages.ts

@@ -15,15 +15,23 @@ import { generateErrorPage } from '../ssr/errorOverlay';
 import { cacheScript, hashContent } from '../scriptCache';
 import { readTextFile, fileExists, serveFile } from '../runtime';
 
+/** HTTP header sent by the studio's /__static__/ proxy to flag editor-preview requests. */
+const EDITOR_HEADER = 'x-meno-editor';
+
 /**
  * Handle page route requests
  */
 export async function handlePageRoute(
   url: URL,
-  context: RouteContext
+  context: RouteContext,
+  req?: Request
 ): Promise<Response | undefined> {
   const { pageService, componentService, cmsService, injectLiveReload, isEditor, serverPort } = context;
   const pagePath = url.pathname;
+  // Editor selection attributes (data-element-path, data-cms-context, ...) are emitted
+  // only when the request is proxied from the studio editor (it sets `x-meno-editor: 1`).
+  // Direct access to the SSR preview server (e.g., http://localhost:8082/) gets clean output.
+  const injectEditorAttrs = req?.headers.get(EDITOR_HEADER) === '1';
 
   // Load i18n config for locale extraction
   const i18nConfig = await loadI18nConfig();
@@ -40,6 +48,16 @@ export async function handlePageRoute(
     const cmsMatch = await cmsService.matchRoute(pathWithoutLocale, locale);
 
     if (cmsMatch) {
+      // Editor-only draft preview: when the studio editor requests a CMS page
+      // with `?previewDraft=1` and a draft exists for that item, swap the
+      // matched item for the draft. SSR continues to render normally; the
+      // live site (no editor header, no query param) is unaffected.
+      if (injectEditorAttrs && url.searchParams.get('previewDraft') === '1' && cmsMatch.item._filename) {
+        const draft = await cmsService.getDraft(cmsMatch.collection, cmsMatch.item._filename);
+        if (draft) {
+          cmsMatch.item = draft;
+        }
+      }
       // Load template page content by file path
       const templatePageContent = await loadPageByFilePath(cmsMatch.pagePath);
 
@@ -79,6 +97,7 @@ export async function handlePageRoute(
               pageLibraries: typedPageData.meta?.libraries,
             pageCustomCode: typedPageData.meta?.customCode,
               injectLiveReload,
+              injectEditorAttrs,
               isEditor,
               serverPort,
               returnSeparateJS: true,
@@ -115,6 +134,7 @@ export async function handlePageRoute(
             cmsTemplatePath,
             pageLibraries: typedPageData.meta?.libraries,
             pageCustomCode: typedPageData.meta?.customCode,
+            injectEditorAttrs,
             isEditor,
           });
 
@@ -200,6 +220,7 @@ export async function handlePageRoute(
           pageLibraries: pageData.meta?.libraries,
         pageCustomCode: pageData.meta?.customCode,
           injectLiveReload,
+          injectEditorAttrs,
           isEditor,
           serverPort,
           returnSeparateJS: true,
@@ -234,6 +255,7 @@ export async function handlePageRoute(
         cmsService,
         pageLibraries: pageData.meta?.libraries,
         pageCustomCode: pageData.meta?.customCode,
+        injectEditorAttrs,
         isEditor,
       });