koguma 0.6.6 → 2.0.0

package/cli/scaffold.ts

@@ -0,0 +1,680 @@
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync
+} from 'fs';
+import { resolve } from 'path';
+import { ok, warn } from './log.ts';
+import { generateKogumaToml } from './config.ts';
+import { findMarkdownField, type ContentTypeInfo } from './content.ts';
+import matter from 'gray-matter';
+
+// ── Template types ─────────────────────────────────────────────────
+
+export interface Template {
+  name: string;
+  description: string;
+  contentTypes: {
+    id: string;
+    name: string;
+    displayField: string;
+    singleton?: boolean;
+    fields: Record<string, string>; // fieldId → builder expression
+  }[];
+}
+
+// ── Template registry ──────────────────────────────────────────────
+
+export const TEMPLATES: Template[] = [
+  {
+    name: 'Blog',
+    description: 'Blog with posts and site settings',
+    contentTypes: [
+      {
+        id: 'siteSettings',
+        name: 'Site Settings',
+        displayField: 'siteName',
+        singleton: true,
+        fields: {
+          siteName: 'field.text("Site Name").required()',
+          tagline: 'field.text("Tagline")',
+          footerText: 'field.text("Footer Text")'
+        }
+      },
+      {
+        id: 'post',
+        name: 'Posts',
+        displayField: 'title',
+        fields: {
+          title: 'field.text("Title").required()',
+          slug: 'field.text("Slug").required().max(120)',
+          excerpt: 'field.longText("Excerpt")',
+          body: 'field.markdown("Body")',
+          coverImage: 'field.image("Cover Image")',
+          published: 'field.boolean("Published").default(false)',
+          date: 'field.date("Date")'
+        }
+      }
+    ]
+  },
+  {
+    name: 'Portfolio',
+    description: 'Portfolio with projects and about page',
+    contentTypes: [
+      {
+        id: 'about',
+        name: 'About',
+        displayField: 'name',
+        singleton: true,
+        fields: {
+          name: 'field.text("Name").required()',
+          bio: 'field.markdown("Bio")',
+          avatar: 'field.image("Avatar")',
+          email: 'field.text("Email")'
+        }
+      },
+      {
+        id: 'project',
+        name: 'Projects',
+        displayField: 'title',
+        fields: {
+          title: 'field.text("Title").required()',
+          description: 'field.longText("Description")',
+          heroImage: 'field.image("Hero Image")',
+          url: 'field.url("Live URL")',
+          year: 'field.number("Year")'
+        }
+      }
+    ]
+  },
+  {
+    name: 'Docs',
+    description: 'Documentation site with pages and categories',
+    contentTypes: [
+      {
+        id: 'page',
+        name: 'Pages',
+        displayField: 'title',
+        fields: {
+          title: 'field.text("Title").required()',
+          slug: 'field.text("Slug").required()',
+          body: 'field.markdown("Body")',
+          sortOrder: 'field.number("Sort Order").default(0)'
+        }
+      }
+    ]
+  },
+  {
+    name: 'Blank',
+    description: 'Empty project — start from scratch',
+    contentTypes: [
+      {
+        id: 'page',
+        name: 'Pages',
+        displayField: 'title',
+        fields: {
+          title: 'field.text("Title").required()',
+          body: 'field.markdown("Body")'
+        }
+      }
+    ]
+  }
+];
+
+// ── File generators ────────────────────────────────────────────────
+
+export function generateSiteConfig(
+  template: Template,
+  siteName: string
+): string {
+  const lines: string[] = [
+    `import { defineConfig, contentType, field } from "koguma";`,
+    ``
+  ];
+
+  for (const ct of template.contentTypes) {
+    lines.push(`const ${ct.id} = contentType({`);
+    lines.push(`  id: "${ct.id}",`);
+    lines.push(`  name: "${ct.name}",`);
+    lines.push(`  displayField: "${ct.displayField}",`);
+    if (ct.singleton) lines.push(`  singleton: true,`);
+    lines.push(`  fields: {`);
+    for (const [fid, expr] of Object.entries(ct.fields)) {
+      lines.push(`    ${fid}: ${expr},`);
+    }
+    lines.push(`  },`);
+    lines.push(`});`);
+    lines.push(``);
+  }
+
+  const ctIds = template.contentTypes.map(ct => ct.id).join(', ');
+  lines.push(`export default defineConfig({`);
+  lines.push(`  siteName: "${siteName}",`);
+  lines.push(`  contentTypes: [${ctIds}],`);
+  lines.push(`});`);
+  lines.push(``);
+
+  return lines.join('\n');
+}
+
+export function generateWorkerTs(): string {
+  return `import { createWorker } from "koguma/worker";
+import config from "./site.config";
+export default createWorker(config);
+`;
+}
+
+export function generatePackageJson(projectName: string): string {
+  return (
+    JSON.stringify(
+      {
+        name: projectName,
+        private: true,
+        scripts: {
+          dev: 'koguma dev',
+          deploy: 'koguma push --remote https://YOUR-SITE.workers.dev'
+        },
+        dependencies: {
+          koguma: 'latest'
+        },
+        devDependencies: {
+          wrangler: 'latest'
+        }
+      },
+      null,
+      2
+    ) + '\n'
+  );
+}
+
+export function generateTsconfig(): string {
+  return (
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: 'ESNext',
+          module: 'ESNext',
+          moduleResolution: 'Bundler',
+          strict: true,
+          esModuleInterop: true,
+          skipLibCheck: true,
+          types: ['@cloudflare/workers-types']
+        },
+        include: ['*.ts']
+      },
+      null,
+      2
+    ) + '\n'
+  );
+}
+
+export function generateGitignore(): string {
+  return `node_modules/
+.koguma/
+.dev.vars
+koguma.d.ts
+`;
+}
+
+// ── Scaffold orchestrator ──────────────────────────────────────────
+
+/**
+ * Scaffold a new Koguma project in the current directory.
+ *
+ * @param projectName — Name for the project (used in package.json, koguma.toml)
+ * @param template — The selected Template to scaffold from
+ * @returns The project root path and list of created file names
+ */
+export function scaffoldNewProject(
+  projectName: string,
+  template: Template
+): { root: string; createdFiles: string[]; skippedFiles: string[] } {
+  const root = process.cwd();
+  const createdFiles: string[] = [];
+  const skippedFiles: string[] = [];
+
+  const files: [string, string][] = [
+    ['site.config.ts', generateSiteConfig(template, projectName)],
+    ['koguma.toml', generateKogumaToml(projectName)],
+    ['package.json', generatePackageJson(projectName)],
+    ['tsconfig.json', generateTsconfig()],
+    ['.gitignore', generateGitignore()]
+  ];
+
+  for (const [name, content] of files) {
+    const path = resolve(root, name);
+    if (existsSync(path)) {
+      skippedFiles.push(name);
+    } else {
+      writeFileSync(path, content);
+      createdFiles.push(name);
+    }
+  }
+
+  // Scaffold content/ directories from template
+  scaffoldContentDirFromTemplate(root, template);
+
+  return { root, createdFiles, skippedFiles };
+}
+
+// ── Content directory scaffolding ──────────────────────────────────
+
+/**
+ * Map a field type string to a sensible placeholder value for _example files.
+ */
+export function placeholderForFieldType(fieldType: string): unknown {
+  switch (fieldType) {
+    case 'text':
+    case 'longText':
+    case 'url':
+    case 'email':
+    case 'phone':
+    case 'color':
+    case 'instagram':
+    case 'youtube':
+    case 'date':
+    case 'select':
+    case 'image':
+      return '';
+    case 'images':
+    case 'refs':
+      return [];
+    case 'ref':
+      return '';
+    case 'number':
+      return 0;
+    case 'boolean':
+      return false;
+    case 'markdown':
+      return null; // handled as body, not frontmatter
+    default:
+      return '';
+  }
+}
+
+/**
+ * Extract the field type from a template builder expression like:
+ *   'field.text("Title").required()' → 'text'
+ *   'field.markdown("Body")' → 'markdown'
+ */
+export function fieldTypeFromExpression(expr: string): string {
+  const match = expr.match(/^field\.(\w+)\(/);
+  return match ? match[1]! : 'text';
+}
+
+/**
+ * Generate the content of an _example file for a content type.
+ * Returns { content, extension }.
+ */
+export function generateExampleFile(
+  ctId: string,
+  fields: Record<string, { fieldType: string }>,
+  singleton?: boolean
+): { content: string; extension: string } {
+  const frontmatter: Record<string, unknown> = {};
+  let hasMarkdown = false;
+
+  for (const [fieldId, meta] of Object.entries(fields)) {
+    if (meta.fieldType === 'markdown') {
+      hasMarkdown = true;
+      continue; // markdown goes in body, not frontmatter
+    }
+    frontmatter[fieldId] = placeholderForFieldType(meta.fieldType);
+  }
+
+  if (hasMarkdown) {
+    const fm = matter.stringify('', frontmatter).trim();
+    const bodyHint = singleton ? '' : `\nWrite your ${ctId} content here.\n`;
+    return {
+      content: `${fm}\n${bodyHint}`,
+      extension: '.md'
+    };
+  }
+
+  const fm = matter.stringify('', frontmatter).trim();
+  return { content: fm + '\n', extension: '.yml' };
+}
+
+/**
+ * Scaffold content/ directories from a Template (used by `koguma init` for new projects).
+ */
+export function scaffoldContentDirFromTemplate(
+  root: string,
+  template: Template
+): void {
+  const contentDir = resolve(root, 'content');
+
+  for (const ct of template.contentTypes) {
+    const typeDir = resolve(contentDir, ct.id);
+    const dirExisted = existsSync(typeDir);
+
+    if (!dirExisted) {
+      mkdirSync(typeDir, { recursive: true });
+    }
+
+    // Create _example file if dir is new or empty
+    const isEmpty = dirExisted ? readdirSync(typeDir).length === 0 : true;
+
+    if (isEmpty) {
+      // Convert template fields to { fieldType } format
+      const fields: Record<string, { fieldType: string }> = {};
+      for (const [fid, expr] of Object.entries(ct.fields)) {
+        fields[fid] = { fieldType: fieldTypeFromExpression(expr) };
+      }
+
+      const { content, extension } = generateExampleFile(
+        ct.id,
+        fields,
+        ct.singleton
+      );
+      const filename = `_example${extension}`;
+      writeFileSync(resolve(typeDir, filename), content);
+      ok(`Created content/${ct.id}/${filename}`);
+    } else if (!dirExisted) {
+      ok(`Created content/${ct.id}/`);
+    }
+  }
+
+  // Ensure content/media/ exists
+  const mediaDir = resolve(contentDir, 'media');
+  if (!existsSync(mediaDir)) {
+    mkdirSync(mediaDir, { recursive: true });
+    ok('Created content/media/');
+  }
+}
+
+/**
+ * Scaffold content/ directories from ContentTypeInfo[] (used when site.config.ts exists).
+ */
+export function scaffoldContentDir(
+  root: string,
+  contentTypes: ContentTypeInfo[]
+): void {
+  const contentDir = resolve(root, 'content');
+
+  for (const ct of contentTypes) {
+    const typeDir = resolve(contentDir, ct.id);
+    const dirExisted = existsSync(typeDir);
+
+    if (!dirExisted) {
+      mkdirSync(typeDir, { recursive: true });
+    }
+
+    const isEmpty = dirExisted ? readdirSync(typeDir).length === 0 : true;
+
+    if (isEmpty) {
+      const { content, extension } = generateExampleFile(
+        ct.id,
+        ct.fieldMeta,
+        ct.singleton
+      );
+      const filename = `_example${extension}`;
+      writeFileSync(resolve(typeDir, filename), content);
+      ok(`Created content/${ct.id}/${filename}`);
+    } else if (!dirExisted) {
+      ok(`Created content/${ct.id}/`);
+    }
+  }
+
+  // Ensure content/media/ exists
+  const mediaDir = resolve(contentDir, 'media');
+  if (!existsSync(mediaDir)) {
+    mkdirSync(mediaDir, { recursive: true });
+    ok('Created content/media/');
+  }
+}
+
+// ── Config-drift sync ──────────────────────────────────────────────
+
+export interface DriftAction {
+  type:
+    | 'create_dir'
+    | 'create_example'
+    | 'update_example'
+    | 'delete_dir'
+    | 'orphan_dir'
+    | 'restore_dir';
+  path: string;
+  detail?: string;
+}
+
+/**
+ * Check if a directory contains only _example files (and nothing else).
+ */
+function dirHasOnlyExamples(dirPath: string): boolean {
+  const files = readdirSync(dirPath);
+  if (files.length === 0) return false; // empty != only examples
+  return files.every(f => f.startsWith('_'));
+}
+
+/**
+ * Sync content/ directories with the current config.
+ *
+ * - Creates missing dirs + _example files
+ * - Regenerates _example files when fields change
+ * - Orphans dirs for removed content types (moves to _orphaned/)
+ * - Restores dirs from _orphaned/ when content type is re-added
+ *
+ * When dryRun=true, returns actions without executing them.
+ */
+export function syncContentDirsWithConfig(
+  root: string,
+  contentTypes: ContentTypeInfo[],
+  dryRun = false
+): DriftAction[] {
+  const contentDir = resolve(root, 'content');
+  const orphanedDir = resolve(contentDir, '_orphaned');
+  const actions: DriftAction[] = [];
+  const ctMap = new Map(contentTypes.map(ct => [ct.id, ct]));
+  const ctIds = new Set(contentTypes.map(ct => ct.id));
+
+  // Ensure content/ exists
+  if (!existsSync(contentDir)) {
+    if (!dryRun) mkdirSync(contentDir, { recursive: true });
+  }
+
+  // ── Step 1: Restore from _orphaned/ if matching config type exists ──
+
+  if (existsSync(orphanedDir)) {
+    for (const orphan of readdirSync(orphanedDir)) {
+      if (!ctIds.has(orphan)) continue;
+
+      const orphanPath = resolve(orphanedDir, orphan);
+      const targetPath = resolve(contentDir, orphan);
+
+      if (existsSync(targetPath)) {
+        // Both exist — warn for manual merge
+        actions.push({
+          type: 'restore_dir',
+          path: `content/${orphan}/`,
+          detail: `Both content/${orphan}/ and _orphaned/${orphan}/ exist — manual merge needed`
+        });
+        if (!dryRun) {
+          warn(
+            `Both content/${orphan}/ and _orphaned/${orphan}/ exist — manual merge needed`
+          );
+        }
+      } else {
+        actions.push({
+          type: 'restore_dir',
+          path: `content/${orphan}/`,
+          detail: `Restored from _orphaned/${orphan}/`
+        });
+        if (!dryRun) {
+          renameSync(orphanPath, targetPath);
+          ok(`Restored content/${orphan}/ from _orphaned/`);
+        }
+      }
+    }
+
+    // Clean up _orphaned/ if it's now empty
+    if (
+      !dryRun &&
+      existsSync(orphanedDir) &&
+      readdirSync(orphanedDir).length === 0
+    ) {
+      rmSync(orphanedDir, { recursive: true });
+    }
+  }
+
+  // ── Step 2: Create/update dirs for current config types ──
+
+  for (const ct of contentTypes) {
+    const typeDir = resolve(contentDir, ct.id);
+    const dirExists = existsSync(typeDir);
+
+    if (!dirExists) {
+      // New content type, no dir — create + _example
+      actions.push({
+        type: 'create_dir',
+        path: `content/${ct.id}/`
+      });
+      if (!dryRun) {
+        mkdirSync(typeDir, { recursive: true });
+      }
+
+      const { content, extension } = generateExampleFile(
+        ct.id,
+        ct.fieldMeta,
+        ct.singleton
+      );
+      const filename = `_example${extension}`;
+      actions.push({
+        type: 'create_example',
+        path: `content/${ct.id}/${filename}`
+      });
+      if (!dryRun) {
+        writeFileSync(resolve(typeDir, filename), content);
+        ok(`Created content/${ct.id}/${filename}`);
+      }
+      continue;
+    }
+
+    const files = readdirSync(typeDir);
+
+    // If dir is empty, create _example
+    if (files.length === 0) {
+      const { content, extension } = generateExampleFile(
+        ct.id,
+        ct.fieldMeta,
+        ct.singleton
+      );
+      const filename = `_example${extension}`;
+      actions.push({
+        type: 'create_example',
+        path: `content/${ct.id}/${filename}`
+      });
+      if (!dryRun) {
+        writeFileSync(resolve(typeDir, filename), content);
+        ok(`Created content/${ct.id}/${filename}`);
+      }
+      continue;
+    }
+
+    // Check if _example file exists and needs updating
+    const exampleFile = files.find(
+      f => f.startsWith('_example') && /\.(md|yml|yaml)$/.test(f)
+    );
+    if (exampleFile) {
+      // Regenerate and compare
+      const { content: newContent, extension: newExt } = generateExampleFile(
+        ct.id,
+        ct.fieldMeta,
+        ct.singleton
+      );
+      const newFilename = `_example${newExt}`;
+      const existingPath = resolve(typeDir, exampleFile);
+      const existingContent = readFileSync(existingPath, 'utf-8');
+
+      // Check if file type changed (singleton ↔ collection) or content changed
+      if (exampleFile !== newFilename || existingContent !== newContent) {
+        actions.push({
+          type: 'update_example',
+          path: `content/${ct.id}/${newFilename}`
+        });
+        if (!dryRun) {
+          // Remove old if filename changed
+          if (exampleFile !== newFilename) {
+            rmSync(existingPath);
+          }
+          writeFileSync(resolve(typeDir, newFilename), newContent);
+          ok(`Updated content/${ct.id}/${newFilename}`);
+        }
+      }
+    }
+  }
+
+  // ── Step 3: Orphan/delete dirs not in config ──
+
+  if (existsSync(contentDir)) {
+    for (const subdir of readdirSync(contentDir)) {
+      if (subdir === 'media') continue;
+      if (subdir.startsWith('_')) continue;
+
+      const subdirPath = resolve(contentDir, subdir);
+      if (!statSync(subdirPath).isDirectory()) continue;
+
+      if (!ctIds.has(subdir)) {
+        const files = readdirSync(subdirPath);
+
+        if (files.length === 0) {
+          // Empty dir — just delete
+          actions.push({
+            type: 'delete_dir',
+            path: `content/${subdir}/`,
+            detail: 'empty directory'
+          });
+          if (!dryRun) {
+            rmSync(subdirPath, { recursive: true });
+            ok(`Deleted empty content/${subdir}/`);
+          }
+        } else if (dirHasOnlyExamples(subdirPath)) {
+          // Only _example files — delete (nothing of value)
+          actions.push({
+            type: 'delete_dir',
+            path: `content/${subdir}/`,
+            detail: 'contained only _example files'
+          });
+          if (!dryRun) {
+            rmSync(subdirPath, { recursive: true });
+            ok(`Deleted content/${subdir}/ (only contained _example files)`);
+          }
+        } else {
+          // Has real files — move to _orphaned/
+          const realFileCount = files.filter(f => !f.startsWith('_')).length;
+          actions.push({
+            type: 'orphan_dir',
+            path: `content/${subdir}/`,
+            detail: `${realFileCount} content file${realFileCount === 1 ? '' : 's'}`
+          });
+          if (!dryRun) {
+            if (!existsSync(orphanedDir)) {
+              mkdirSync(orphanedDir, { recursive: true });
+            }
+            renameSync(subdirPath, resolve(orphanedDir, subdir));
+            warn(
+              `Moved content/${subdir}/ → _orphaned/${subdir}/ (${realFileCount} file${realFileCount === 1 ? '' : 's'} — no matching content type)`
+            );
+          }
+        }
+      }
+    }
+  }
+
+  // Ensure content/media/ exists
+  const mediaDir = resolve(contentDir, 'media');
+  if (!existsSync(mediaDir)) {
+    if (!dryRun) {
+      mkdirSync(mediaDir, { recursive: true });
+      ok('Created content/media/');
+    }
+    actions.push({ type: 'create_dir', path: 'content/media/' });
+  }
+
+  return actions;
+}