koguma 0.6.6 → 2.0.0

package/cli/content.ts

@@ -0,0 +1,503 @@
+/**
+ * cli/content.ts — content/ directory ↔ D1 database sync
+ *
+ * The content/ directory is the git-friendly representation of CMS entries:
+ *
+ *   content/
+ *   ├── post/
+ *   │   ├── hello-world.md        # markdown body + frontmatter
+ *   │   └── our-mission.md
+ *   ├── siteSettings/
+ *   │   └── index.yml             # singletons use index.yml
+ *   └── media/                    # optional local images (not managed here)
+ *       └── hero.jpg
+ *
+ * Markdown files use YAML frontmatter for structured fields.
+ * The file body (below the frontmatter) is mapped to the first `markdown`
+ * field in the content type definition. If the content type has no markdown
+ * field, YAML-only files (.yml) are used.
+ */
+
+import matter from 'gray-matter';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  statSync
+} from 'fs';
+import { resolve, join, extname, basename } from 'path';
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export interface ContentEntry {
+  /** Content type ID (derived from parent folder name) */
+  contentType: string;
+  /** Slug derived from filename (without extension) */
+  slug: string;
+  /** Whether this is a singleton (index.yml) */
+  singleton: boolean;
+  /** All frontmatter fields */
+  fields: Record<string, unknown>;
+  /** Markdown body (if present) */
+  body: string | null;
+  /** Absolute path to the source file */
+  filePath: string;
+}
+
+export interface ContentTypeInfo {
+  id: string;
+  singleton?: boolean;
+  /** Map of fieldId → { fieldType, ... } */
+  fieldMeta: Record<string, { fieldType: string; required: boolean }>;
+}
+
+// ── Parse a single content file ────────────────────────────────────
+
+/**
+ * Parse a .md or .yml file into a ContentEntry.
+ */
+export function parseContentFile(
+  filePath: string,
+  contentType: string
+): ContentEntry {
+  const raw = readFileSync(filePath, 'utf-8');
+  const ext = extname(filePath).toLowerCase();
+  const name = basename(filePath, ext);
+  const singleton = name === 'index' && ext === '.yml';
+
+  if (ext === '.yml' || ext === '.yaml') {
+    // YAML-only file (no markdown body)
+    const parsed = matter(raw);
+
+    // gray-matter needs `---` delimiters. If the file is plain YAML
+    // (no delimiters), parsed.data will be empty and the content ends
+    // up in parsed.content. Detect this and re-parse as raw YAML.
+    let fields = parsed.data;
+    if (Object.keys(fields).length === 0 && parsed.content.trim().length > 0) {
+      // Wrap in --- delimiters so gray-matter can parse it
+      const wrapped = `---\n${raw.trim()}\n---\n`;
+      fields = matter(wrapped).data;
+    }
+
+    return {
+      contentType,
+      slug: singleton ? contentType : name,
+      singleton,
+      fields,
+      body: null,
+      filePath
+    };
+  }
+
+  // Markdown file with frontmatter
+  const parsed = matter(raw);
+  const body = parsed.content.trim() || null;
+
+  return {
+    contentType,
+    slug: name,
+    singleton: false,
+    fields: parsed.data,
+    body,
+    filePath
+  };
+}
+
+// ── Read entire content/ directory ─────────────────────────────────
+
+/**
+ * Scan the content/ directory and return all parsed entries.
+ * Skips the `media/` subdirectory and any files/directories starting with `_`.
+ */
+export function readContentDir(contentDir: string): ContentEntry[] {
+  if (!existsSync(contentDir)) return [];
+
+  const entries: ContentEntry[] = [];
+  const subdirs = readdirSync(contentDir);
+
+  for (const subdir of subdirs) {
+    // Skip media/ — it's for local image storage, not content
+    if (subdir === 'media') continue;
+    // Skip _-prefixed dirs (_orphaned/, _example dirs, dev drafts, etc.)
+    if (subdir.startsWith('_')) continue;
+
+    const subdirPath = resolve(contentDir, subdir);
+    if (!statSync(subdirPath).isDirectory()) continue;
+
+    const files = readdirSync(subdirPath);
+    for (const file of files) {
+      // Skip _-prefixed files (_example.md, dev drafts, etc.)
+      if (file.startsWith('_')) continue;
+
+      const ext = extname(file).toLowerCase();
+      if (!['.md', '.yml', '.yaml'].includes(ext)) continue;
+
+      const filePath = resolve(subdirPath, file);
+      if (!statSync(filePath).isFile()) continue;
+
+      entries.push(parseContentFile(filePath, subdir));
+    }
+  }
+
+  return entries;
+}
+
+// ── Convert ContentEntry → D1 row data ─────────────────────────────
+
+/**
+ * Find the first markdown field ID in a content type's field metadata.
+ * Returns null if the content type has no markdown field.
+ */
+export function findMarkdownField(
+  fieldMeta: Record<string, { fieldType: string }>
+): string | null {
+  for (const [id, meta] of Object.entries(fieldMeta)) {
+    if (meta.fieldType === 'markdown') return id;
+  }
+  return null;
+}
+
+/**
+ * Convert a ContentEntry into the flat data object suitable for D1 insertion.
+ * The markdown body (if present) is assigned to the first markdown field.
+ */
+export function contentEntryToDbRow(
+  entry: ContentEntry,
+  ctInfo: ContentTypeInfo
+): Record<string, unknown> {
+  const data: Record<string, unknown> = { ...entry.fields };
+
+  // Assign markdown body to the first markdown field
+  if (entry.body) {
+    const mdField = findMarkdownField(ctInfo.fieldMeta);
+    if (mdField) {
+      data[mdField] = entry.body;
+    }
+  }
+
+  // Set slug
+  if (!data.slug && !entry.singleton) {
+    data.slug = entry.slug;
+  }
+
+  // Ensure an ID exists
+  if (!data.id) {
+    // Use a deterministic ID based on content type + slug for idempotent sync
+    data.id = `${entry.contentType}-${entry.slug}`;
+  }
+
+  // Map common frontmatter conventions
+  if ('published' in data) {
+    data.status = data.published ? 'published' : 'draft';
+    delete data.published;
+  }
+  if (!data.status) {
+    data.status = 'published';
+  }
+  if ('date' in data && data.date instanceof Date) {
+    data.date = (data.date as Date).toISOString();
+  }
+  if ('publish_at' in data && data.publish_at instanceof Date) {
+    data.publish_at = (data.publish_at as Date).toISOString();
+  }
+
+  return data;
+}
+
+// ── Convert D1 row → content file ──────────────────────────────────
+
+/**
+ * Convert a D1 entry row into a markdown/yml file content string.
+ * System fields (id, content_type, created_at, updated_at) are stripped
+ * from frontmatter. The markdown field (if any) becomes the file body.
+ */
+export function dbRowToContentFile(
+  row: Record<string, unknown>,
+  ctInfo: ContentTypeInfo
+): { content: string; extension: string } {
+  // Parse the data blob if it's still a JSON string
+  let fields: Record<string, unknown>;
+  if (typeof row.data === 'string') {
+    fields = { ...JSON.parse(row.data) };
+  } else {
+    // Already unpacked — strip system fields
+    const { id, content_type, created_at, updated_at, data, ...rest } = row;
+    fields = { ...rest };
+  }
+
+  // Map status back to published boolean for friendlier frontmatter
+  if (row.status === 'published') {
+    fields.published = true;
+    delete fields.status;
+  } else if (row.status === 'draft') {
+    fields.published = false;
+    delete fields.status;
+  }
+
+  // Strip system-only fields from frontmatter
+  delete fields.slug;
+
+  const mdFieldId = findMarkdownField(ctInfo.fieldMeta);
+
+  if (mdFieldId && fields[mdFieldId]) {
+    // Markdown file: body goes below frontmatter
+    const body = String(fields[mdFieldId]);
+    delete fields[mdFieldId];
+    const fm = matter.stringify('', fields).trim();
+    return {
+      content: `${fm}\n\n${body}\n`,
+      extension: '.md'
+    };
+  }
+
+  // YAML-only file (no markdown field or empty body)
+  const fm = matter.stringify('', fields).trim();
+  return { content: fm + '\n', extension: '.yml' };
+}
+
+// ── Write content/ directory from D1 entries ───────────────────────
+
+/**
+ * Write D1 entries to the content/ directory as .md/.yml files.
+ * Each content type gets its own subdirectory.
+ *
+ * @param contentDir - Absolute path to the content/ directory
+ * @param entries - Array of D1 entry rows (with content_type, slug, data, status)
+ * @param contentTypes - Content type definitions for field metadata
+ * @returns Number of files written
+ */
+export function writeContentDir(
+  contentDir: string,
+  entries: Record<string, unknown>[],
+  contentTypes: ContentTypeInfo[]
+): number {
+  const ctMap = new Map(contentTypes.map(ct => [ct.id, ct]));
+  let count = 0;
+
+  for (const entry of entries) {
+    const typeId = entry.content_type as string;
+    const ctInfo = ctMap.get(typeId);
+    if (!ctInfo) continue;
+
+    const typeDir = resolve(contentDir, typeId);
+    mkdirSync(typeDir, { recursive: true });
+
+    const { content, extension } = dbRowToContentFile(entry, ctInfo);
+
+    // Determine filename
+    const slug = (entry.slug as string) || (entry.id as string);
+    const isSingleton = ctInfo.singleton;
+    const filename = isSingleton ? `index${extension}` : `${slug}${extension}`;
+
+    writeFileSync(resolve(typeDir, filename), content);
+    count++;
+  }
+
+  return count;
+}
+
+// ── Sync helpers ───────────────────────────────────────────────────
+
+/**
+ * Read content/ files and produce D1 row data for each.
+ * Returns data ready for INSERT OR REPLACE into the entries table.
+ *
+ * @param contentDir - Absolute path to the content/ directory
+ * @param contentTypes - Content type definitions for field metadata
+ * @returns Array of { contentType, rowData } ready for SQL generation
+ */
+export function prepareContentForSync(
+  contentDir: string,
+  contentTypes: ContentTypeInfo[]
+): { contentType: string; rowData: Record<string, unknown> }[] {
+  const ctMap = new Map(contentTypes.map(ct => [ct.id, ct]));
+  const entries = readContentDir(contentDir);
+  const results: { contentType: string; rowData: Record<string, unknown> }[] =
+    [];
+
+  for (const entry of entries) {
+    const ctInfo = ctMap.get(entry.contentType);
+    if (!ctInfo) continue;
+    results.push({
+      contentType: entry.contentType,
+      rowData: contentEntryToDbRow(entry, ctInfo)
+    });
+  }
+
+  return results;
+}
+
+// ── Content validation ─────────────────────────────────────────────
+
+export interface ValidationWarning {
+  level: 'warn';
+  file: string;
+  message: string;
+}
+
+/**
+ * Levenshtein distance between two strings.
+ * Used for "did you mean?" suggestions.
+ */
+export function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () =>
+    Array(n + 1).fill(0)
+  );
+  for (let i = 0; i <= m; i++) dp[i]![0] = i;
+  for (let j = 0; j <= n; j++) dp[0]![j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i]![j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1]![j - 1]!
+          : 1 + Math.min(dp[i - 1]![j]!, dp[i]![j - 1]!, dp[i - 1]![j - 1]!);
+    }
+  }
+  return dp[m]![n]!;
+}
+
+/**
+ * Find the closest match for a string from a list of candidates.
+ * Returns null if no candidate is within maxDistance.
+ */
+export function closestMatch(
+  input: string,
+  candidates: string[],
+  maxDistance = 3
+): string | null {
+  let best: string | null = null;
+  let bestDist = maxDistance + 1;
+  for (const c of candidates) {
+    const d = levenshtein(input.toLowerCase(), c.toLowerCase());
+    if (d < bestDist) {
+      bestDist = d;
+      best = c;
+    }
+  }
+  return best;
+}
+
+/**
+ * Validate the content/ directory against content type definitions.
+ * Returns warnings for:
+ *   1. Unknown directories (typos like content/posts/ when type is "post")
+ *   2. Unknown frontmatter keys not defined in the schema
+ *   3. Missing required fields
+ *
+ * Never errors — only warns. Skips media/ and _-prefixed files/dirs.
+ */
+export function validateContent(
+  contentDir: string,
+  contentTypes: ContentTypeInfo[]
+): ValidationWarning[] {
+  if (!existsSync(contentDir)) return [];
+
+  const warnings: ValidationWarning[] = [];
+  const ctIds = contentTypes.map(ct => ct.id);
+  const ctMap = new Map(contentTypes.map(ct => [ct.id, ct]));
+
+  const subdirs = readdirSync(contentDir);
+
+  for (const subdir of subdirs) {
+    // Skip reserved/internal dirs
+    if (subdir === 'media') continue;
+    if (subdir.startsWith('_')) continue;
+
+    const subdirPath = resolve(contentDir, subdir);
+    if (!statSync(subdirPath).isDirectory()) continue;
+
+    // Check 1: Unknown directory
+    if (!ctMap.has(subdir)) {
+      const suggestion = closestMatch(subdir, ctIds);
+      const hint = suggestion ? ` Did you mean "${suggestion}"?` : '';
+      warnings.push({
+        level: 'warn',
+        file: `content/${subdir}/`,
+        message: `does not match any content type.${hint}`
+      });
+      continue;
+    }
+
+    // Warn if content type ID is 'media' (reserved)
+    // (This would only fire if someone had media in both config and as dir)
+
+    const ctInfo = ctMap.get(subdir)!;
+    const fieldIds = Object.keys(ctInfo.fieldMeta);
+    // Include conventional keys that are valid but not in fieldMeta
+    const knownKeys = new Set([
+      ...fieldIds,
+      'id',
+      'slug',
+      'status',
+      'published',
+      'publish_at',
+      'created_at',
+      'updated_at'
+    ]);
+
+    const files = readdirSync(subdirPath);
+    for (const file of files) {
+      if (file.startsWith('_')) continue;
+      const ext = extname(file).toLowerCase();
+      if (!['.md', '.yml', '.yaml'].includes(ext)) continue;
+
+      const filePath = resolve(subdirPath, file);
+      if (!statSync(filePath).isFile()) continue;
+
+      const entry = parseContentFile(filePath, subdir);
+      const relPath = `${subdir}/${file}`;
+
+      // Check 2: Unknown frontmatter keys
+      for (const key of Object.keys(entry.fields)) {
+        if (!knownKeys.has(key)) {
+          warnings.push({
+            level: 'warn',
+            file: relPath,
+            message: `unknown field "${key}" — not defined in site.config.ts`
+          });
+        }
+      }
+
+      // Check 3: Missing required fields
+      for (const [fieldId, meta] of Object.entries(ctInfo.fieldMeta)) {
+        if (!meta.required) continue;
+        // Markdown fields get their value from the body
+        if (meta.fieldType === 'markdown') {
+          if (!entry.body) {
+            warnings.push({
+              level: 'warn',
+              file: relPath,
+              message: `missing required field "${fieldId}" (markdown body is empty)`
+            });
+          }
+          continue;
+        }
+        const val = entry.fields[fieldId];
+        if (val === undefined || val === null || val === '') {
+          warnings.push({
+            level: 'warn',
+            file: relPath,
+            message: `missing required field "${fieldId}"`
+          });
+        }
+      }
+    }
+  }
+
+  // Check for reserved name conflict
+  for (const ct of contentTypes) {
+    if (ct.id === 'media') {
+      warnings.push({
+        level: 'warn',
+        file: 'site.config.ts',
+        message: `content type "media" conflicts with reserved directory content/media/`
+      });
+    }
+  }
+
+  return warnings;
+}