koguma 2.3.7 → 2.3.8

package/README.md

@@ -145,29 +145,55 @@ Koguma uses a `content/` directory for file-based content that lives in your git
 
 ```
 content/
-├── post/                        # folder = content type ID
-│   ├── hello-world.md           # file = one entry
-│   └── our-mission.md
-├── siteSettings/
-│   └── index.md                 # singletons use index.md
-└── media/                       # optional local images
+├── post/                          # collection — one file per entry
+│   ├── hello-world.md             # slug = "hello-world"
+│   ├── our-mission.md
+│   └── our-mission.heroBody.md    # sibling markdown field
+├── landingPage/                   # singleton — always index.md
+│   ├── index.md                   # slug = content type ID
+│   ├── heroBody.md                # sibling markdown field
+│   └── ctaBody.md                 # sibling markdown field
+└── media/                         # local images (synced to R2)
     └── hero-banner.jpg
 ```
 
-**Markdown files with frontmatter:**
+### File Format
+
+Every content file uses **YAML frontmatter + markdown body**:
 
 ```markdown
 ---
 title: Our Mission
 slug: our-mission
-heroImage: hero-banner.jpg
+heroImage: media-hero-banner
 published: true
 date: 2026-03-01
 ---
 
-## Who We Are
+This body content maps to the **first** `field.markdown()` in the content type.
+```
+
+### Singletons vs Collections
+
+- **Collections** (default): Each entry is a file named `{slug}.md`
+- **Singletons** (`singleton: true`): One entry, always `index.md`. The slug is auto-set to the content type ID.
+
+### Sibling Markdown Fields
 
-Rich text body, stored as markdown.
+When a content type has **multiple** `field.markdown()` fields, the first one maps to the file body. Additional markdown fields are stored as **sibling files** (pure markdown, no frontmatter):
+
+|                     | Collections           | Singletons     |
+| ------------------- | --------------------- | -------------- |
+| **Main file**       | `{slug}.md`           | `index.md`     |
+| **Sibling pattern** | `{slug}.{fieldId}.md` | `{fieldId}.md` |
+
+Example singleton with 3 markdown fields:
+
+```
+content/landingPage/
+├── index.md           # frontmatter + 1st markdown field body
+├── heroBody.md        # 2nd markdown field (pure markdown)
+└── ctaBody.md         # 3rd markdown field (pure markdown)
 ```
 
 **Git is your version history.** No custom versioning table needed.

package/cli/content.ts

@@ -611,9 +611,55 @@ export function validateContent(
         if (dotIdx > 0 && extraMdFieldIds.has(name.slice(dotIdx + 1))) continue;
       }
 
-      const entry = parseContentFile(filePath, subdir);
       const relPath = `${subdir}/${file}`;
 
+      // Check for orphan / misnamed files
+      if (ctInfo.singleton) {
+        // Singletons: only index.md is a valid entry
+        if (name !== 'index') {
+          // Catch the index.{fieldId}.md mistake
+          if (name.startsWith('index.')) {
+            const possibleFieldId = name.slice('index.'.length);
+            if (extraMdFieldIds.has(possibleFieldId)) {
+              warnings.push({
+                level: 'warn',
+                file: relPath,
+                message: `misnamed sibling — singleton siblings should be "${possibleFieldId}.md", not "index.${possibleFieldId}.md"`
+              });
+            } else {
+              warnings.push({
+                level: 'warn',
+                file: relPath,
+                message: `unrecognized file in singleton — only index.md and {fieldId}.md siblings are expected`
+              });
+            }
+          } else if (!extraMdFieldIds.has(name)) {
+            warnings.push({
+              level: 'warn',
+              file: relPath,
+              message: `unrecognized file in singleton — expected index.md or a sibling like {fieldId}.md`
+            });
+          }
+          continue;
+        }
+      } else {
+        // Collections: warn about dotted names that aren't valid siblings
+        const dotIdx = name.lastIndexOf('.');
+        if (dotIdx > 0) {
+          const possibleFieldId = name.slice(dotIdx + 1);
+          if (!extraMdFieldIds.has(possibleFieldId)) {
+            warnings.push({
+              level: 'warn',
+              file: relPath,
+              message: `unrecognized dotted filename — not a known sibling field. Did you mean "{slug}.md"?`
+            });
+            continue;
+          }
+        }
+      }
+
+      const entry = parseContentFile(filePath, subdir);
+
       // Check 2: Unknown frontmatter keys
       for (const key of Object.keys(entry.fields)) {
         if (!knownKeys.has(key)) {

package/cli/index.ts

@@ -248,14 +248,25 @@ async function syncContentToLocalD1(
       );
     }
 
-    // Single batch: assets + entries written to one SQL file
-    const allStatements = [...assetSql, ...entrySql];
-    if (allStatements.length > 0) {
+    // Wipe and rebuild: DELETE all existing entries+assets, then re-insert
+    // from content/ files. This eliminates schema drift (stale fields, ghost
+    // entries) and ensures the local DB always matches the filesystem.
+    const allStatements = [
+      'DELETE FROM entries',
+      'DELETE FROM assets',
+      ...assetSql,
+      ...entrySql
+    ];
+    if (allStatements.length > 2) {
+      // Only run if there's actual content to sync (beyond the 2 DELETEs)
       if (s)
         s.message(
           `Syncing ${entrySql.length} entries + ${assetSql.length} assets...`
         );
       await d1ExecuteBatchSqlAsync(root, dbName, '--local', allStatements);
+    } else if (allStatements.length === 2) {
+      // No content files — still wipe stale data
+      await d1ExecuteBatchSqlAsync(root, dbName, '--local', allStatements);
     }
 
     // Upload media files to local R2

package/cli/scaffold.ts

@@ -404,7 +404,9 @@ export function scaffoldContentDirFromTemplate(
       // Write sibling example files for extra markdown fields
       if (siblingFiles) {
         for (const { fieldId, content: siblingContent } of siblingFiles) {
-          const siblingName = `_example.${fieldId}.md`;
+          const siblingName = ct.singleton
+            ? `${fieldId}.md`
+            : `_example.${fieldId}.md`;
           writeFileSync(resolve(typeDir, siblingName), siblingContent + '\n');
         }
       }
@@ -453,7 +455,9 @@ export function scaffoldContentDir(
       // Write sibling example files for extra markdown fields
       if (siblingFiles) {
         for (const { fieldId, content: siblingContent } of siblingFiles) {
-          const siblingName = `_example.${fieldId}.md`;
+          const siblingName = ct.singleton
+            ? `${fieldId}.md`
+            : `_example.${fieldId}.md`;
           writeFileSync(resolve(typeDir, siblingName), siblingContent + '\n');
         }
       }
@@ -596,7 +600,9 @@ export function syncContentDirsWithConfig(
         // Write sibling example files for extra markdown fields
         if (siblingFiles) {
           for (const { fieldId, content: siblingContent } of siblingFiles) {
-            const siblingName = `_example.${fieldId}.md`;
+            const siblingName = ct.singleton
+              ? `${fieldId}.md`
+              : `_example.${fieldId}.md`;
             writeFileSync(resolve(typeDir, siblingName), siblingContent + '\n');
           }
         }
@@ -625,7 +631,9 @@ export function syncContentDirsWithConfig(
         // Write sibling example files for extra markdown fields
         if (siblingFiles) {
           for (const { fieldId, content: siblingContent } of siblingFiles) {
-            const siblingName = `_example.${fieldId}.md`;
+            const siblingName = ct.singleton
+              ? `${fieldId}.md`
+              : `_example.${fieldId}.md`;
             writeFileSync(resolve(typeDir, siblingName), siblingContent + '\n');
           }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koguma",
-  "version": "2.3.7",
+  "version": "2.3.8",
   "description": "🐻 A little CMS with big heart — schema-driven, runs on Cloudflare's free tier",
   "type": "module",
   "license": "MIT",