koguma 0.4.0

package/cli/index.ts

@@ -0,0 +1,1150 @@
+#!/usr/bin/env bun
+/**
+ * Koguma CLI — the bear's toolbox 🐻
+ *
+ * Commands:
+ *   koguma init           — Create D1/R2 resources and patch wrangler.toml
+ *   koguma secret         — Set the admin password
+ *   koguma build          — Build the admin dashboard bundle
+ *   koguma seed           — Apply schema + seed SQL to D1
+ *   koguma migrate-media  — Download images from Contentful → upload to R2
+ *   koguma deploy         — Build admin + run wrangler deploy
+ *
+ * All commands auto-detect the project root by looking for wrangler.toml.
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { resolve, dirname, basename } from 'path';
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+
+function log(msg: string) {
+  console.log(`  ${msg}`);
+}
+function ok(msg: string) {
+  console.log(`  ${GREEN}✓${RESET} ${msg}`);
+}
+function warn(msg: string) {
+  console.log(`  ${YELLOW}⚠${RESET} ${msg}`);
+}
+function fail(msg: string) {
+  console.error(`  ${RED}✗${RESET} ${msg}`);
+}
+function header(msg: string) {
+  console.log(`\n${BOLD}🐻 ${msg}${RESET}\n`);
+}
+
+function run(cmd: string, opts?: { cwd?: string; silent?: boolean }): string {
+  try {
+    return execSync(cmd, {
+      cwd: opts?.cwd,
+      encoding: 'utf-8',
+      stdio: opts?.silent ? 'pipe' : 'inherit'
+    }) as string;
+  } catch (e: unknown) {
+    const error = e as { stdout?: string; stderr?: string; status?: number };
+    if (opts?.silent) return error.stdout ?? '';
+    throw e;
+  }
+}
+
+function runCapture(cmd: string, cwd?: string): string {
+  return run(cmd, { cwd, silent: true }).trim();
+}
+
+/** Find the project root (directory containing wrangler.toml) */
+function findProjectRoot(): string {
+  let dir = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(resolve(dir, 'wrangler.toml'))) return dir;
+    if (existsSync(resolve(dir, 'wrangler.jsonc'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  fail('Could not find wrangler.toml — run this from your project directory.');
+  process.exit(1);
+}
+
+/** Find the Koguma package root (where this CLI lives) */
+function findKogumaRoot(): string {
+  // This file is at cli/index.ts, so Koguma root is one level up
+  return resolve(dirname(new URL(import.meta.url).pathname), '..');
+}
+
+// ── Project templates ──────────────────────────────────────────────
+
+interface TemplateField {
+  method: string; // e.g. 'field.text("Title").required()'
+}
+
+interface Template {
+  name: string;
+  description: string;
+  contentTypes: {
+    id: string;
+    name: string;
+    displayField: string;
+    singleton?: boolean;
+    fields: Record<string, string>; // fieldId → builder expression
+  }[];
+}
+
+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.richText("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.richText("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.richText("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.richText("Body")'
+        }
+      }
+    ]
+  }
+];
+
+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');
+}
+
+function generateWorkerTs(): string {
+  return `import { createWorker } from "koguma/worker";
+import config from "./site.config";
+export default createWorker(config);
+`;
+}
+
+function generateWranglerToml(projectName: string): string {
+  return `name = "${projectName}"
+main = "worker.ts"
+compatibility_date = "2024-11-01"
+compatibility_flags = ["nodejs_compat"]
+
+# ── D1 Database ──
+[[d1_databases]]
+binding = "DB"
+database_name = "${projectName}-db"
+database_id = ""
+
+# ── R2 Media Storage ──
+[[r2_buckets]]
+binding = "MEDIA"
+bucket_name = "${projectName}-media"
+`;
+}
+
+function generatePackageJson(projectName: string): string {
+  return (
+    JSON.stringify(
+      {
+        name: projectName,
+        private: true,
+        scripts: {
+          dev: 'wrangler dev',
+          deploy: 'koguma deploy'
+        },
+        dependencies: {
+          koguma: 'latest'
+        },
+        devDependencies: {
+          wrangler: 'latest'
+        }
+      },
+      null,
+      2
+    ) + '\n'
+  );
+}
+
+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'
+  );
+}
+
+async function scaffoldNewProject(): Promise<string> {
+  header('koguma init — new project');
+  const root = process.cwd();
+
+  // Project name
+  const dirName = root.split('/').pop() ?? 'my-koguma-site';
+  log(`Project name: ${CYAN}${dirName}${RESET}`);
+  const projectName = dirName;
+
+  // Template selection
+  log(`\n  Pick a template:\n`);
+  for (let i = 0; i < TEMPLATES.length; i++) {
+    const t = TEMPLATES[i]!;
+    log(
+      `  ${BOLD}${i + 1}${RESET}. ${t.name} ${DIM}— ${t.description}${RESET}`
+    );
+  }
+  log('');
+
+  // Default to Blog (template 1), non-interactive for CI
+  const choice = process.env.KOGUMA_TEMPLATE
+    ? parseInt(process.env.KOGUMA_TEMPLATE, 10)
+    : 1;
+  const template = TEMPLATES[choice - 1] ?? TEMPLATES[0]!;
+
+  ok(`Using template: ${BOLD}${template.name}${RESET}`);
+
+  // Generate files
+  const files: [string, string][] = [
+    ['site.config.ts', generateSiteConfig(template, projectName)],
+    ['worker.ts', generateWorkerTs()],
+    ['wrangler.toml', generateWranglerToml(projectName)],
+    ['package.json', generatePackageJson(projectName)],
+    ['tsconfig.json', generateTsconfig()]
+  ];
+
+  for (const [name, content] of files) {
+    const path = resolve(root, name);
+    if (existsSync(path)) {
+      warn(`${name} already exists, skipping`);
+    } else {
+      writeFileSync(path, content);
+      ok(`Created ${name}`);
+    }
+  }
+
+  // Install dependencies
+  log(`\n  Installing dependencies…\n`);
+  try {
+    run('bun install', { cwd: root });
+    ok('Dependencies installed');
+  } catch {
+    warn("Failed to install — run 'bun install' manually");
+  }
+
+  return root;
+}
+
+// ── Commands ────────────────────────────────────────────────────────
+
+async function cmdInit() {
+  header('koguma init');
+
+  // Detect if this is a new project or existing
+  const cwd = process.cwd();
+  const hasWrangler =
+    existsSync(resolve(cwd, 'wrangler.toml')) ||
+    existsSync(resolve(cwd, 'wrangler.jsonc'));
+
+  let root: string;
+  if (!hasWrangler) {
+    // New project — scaffold first
+    root = await scaffoldNewProject();
+  } else {
+    root = findProjectRoot();
+  }
+
+  const wranglerPath = resolve(root, 'wrangler.toml');
+  let toml = readFileSync(wranglerPath, 'utf-8');
+
+  // Parse project name from wrangler.toml
+  const nameMatch = toml.match(/^name\s*=\s*"([^"]+)"/m);
+  const projectName = nameMatch?.[1] ?? 'my-project';
+
+  // ── D1 Database ──
+  const dbNameMatch = toml.match(/database_name\s*=\s*"([^"]+)"/);
+  const dbName = dbNameMatch?.[1] ?? `${projectName}-db`;
+  const dbIdMatch = toml.match(/database_id\s*=\s*"([^"]*)"/);
+  const existingId = dbIdMatch?.[1];
+
+  if (existingId) {
+    ok(
+      `D1 database already configured: ${DIM}${dbName} (${existingId})${RESET}`
+    );
+  } else {
+    log(`Creating D1 database: ${CYAN}${dbName}${RESET}`);
+    try {
+      const output = runCapture(`npx wrangler d1 create ${dbName}`, root);
+      const idMatch = output.match(/database_id\s*=\s*"([^"]+)"/);
+      if (idMatch?.[1]) {
+        toml = toml.replace(
+          /database_id\s*=\s*""/,
+          `database_id = "${idMatch[1]}"`
+        );
+        writeFileSync(wranglerPath, toml);
+        ok(
+          `Created D1 database and patched wrangler.toml: ${DIM}${idMatch[1]}${RESET}`
+        );
+      } else {
+        warn("D1 database created but couldn't parse ID. Check output above.");
+      }
+    } catch {
+      fail(
+        "Failed to create D1 database. Make sure you're logged into Cloudflare: npx wrangler login"
+      );
+    }
+  }
+
+  // ── R2 Bucket ──
+  const bucketMatch = toml.match(/bucket_name\s*=\s*"([^"]+)"/);
+  const bucketName = bucketMatch?.[1] ?? `${projectName}-media`;
+
+  log(`Checking R2 bucket: ${CYAN}${bucketName}${RESET}`);
+  try {
+    const buckets = runCapture('npx wrangler r2 bucket list', root);
+    if (buckets.includes(bucketName)) {
+      ok(`R2 bucket already exists: ${DIM}${bucketName}${RESET}`);
+    } else {
+      runCapture(`npx wrangler r2 bucket create ${bucketName}`, root);
+      ok(`Created R2 bucket: ${DIM}${bucketName}${RESET}`);
+    }
+  } catch {
+    fail(
+      "Failed to check/create R2 bucket. Make sure you're logged into Cloudflare."
+    );
+  }
+
+  // ── KOGUMA_SECRET ──
+  log(`\n  ${YELLOW}Next, set your admin password:${RESET}`);
+  log(`  ${DIM}$ koguma secret${RESET}\n`);
+
+  ok('Init complete!');
+}
+
+async function cmdBuild() {
+  header('koguma build');
+  const kogumaRoot = findKogumaRoot();
+  const adminDir = resolve(kogumaRoot, 'admin');
+
+  if (!existsSync(adminDir)) {
+    fail('Admin directory not found at: ' + adminDir);
+    process.exit(1);
+  }
+
+  // Install admin deps if needed
+  if (!existsSync(resolve(adminDir, 'node_modules'))) {
+    log('Installing admin dependencies...');
+    run('bun install', { cwd: adminDir });
+  }
+
+  // Build Vite app
+  log('Building admin dashboard...');
+  run('bun run build', { cwd: adminDir });
+
+  // Generate bundle
+  log('Generating admin bundle...');
+  const scriptPath = resolve(kogumaRoot, 'scripts/bundle-admin.ts');
+  run(`bun run ${scriptPath}`, { cwd: kogumaRoot });
+
+  ok('Admin bundle ready!');
+}
+
+async function cmdSeed() {
+  header('koguma seed');
+  const root = findProjectRoot();
+  const seedSql = resolve(root, 'db/seed.sql');
+
+  if (!existsSync(seedSql)) {
+    fail('db/seed.sql not found. Generate it first with your seed script.');
+    process.exit(1);
+  }
+
+  // Parse database name from wrangler.toml
+  const toml = readFileSync(resolve(root, 'wrangler.toml'), 'utf-8');
+  const dbNameMatch = toml.match(/database_name\s*=\s*"([^"]+)"/);
+  const dbName = dbNameMatch?.[1] ?? 'my-db';
+
+  const isRemote = process.argv.includes('--remote');
+  const target = isRemote ? '--remote' : '--local';
+
+  log(
+    `Seeding ${isRemote ? 'REMOTE' : 'local'} database: ${CYAN}${dbName}${RESET}`
+  );
+  run(`npx wrangler d1 execute ${dbName} ${target} --file=${seedSql}`, {
+    cwd: root
+  });
+
+  ok(`Database seeded (${isRemote ? 'remote' : 'local'})!`);
+}
+
+async function cmdDeploy() {
+  header('koguma deploy');
+
+  // Build admin first
+  await cmdBuild();
+
+  // Build frontend
+  const root = findProjectRoot();
+  log('\nBuilding frontend...');
+  run('bun run build', { cwd: root });
+
+  // Deploy
+  log('\nDeploying to Cloudflare...');
+  run('npx wrangler deploy', { cwd: root });
+
+  ok('Deployed! 🎉');
+}
+
+async function cmdSecret() {
+  header('koguma secret');
+  const root = findProjectRoot();
+  log('Setting KOGUMA_SECRET (your admin password)...');
+  run('npx wrangler secret put KOGUMA_SECRET', { cwd: root });
+  ok('Secret set!');
+}
+
+async function cmdMigrateMedia() {
+  header('koguma migrate-media');
+  const root = findProjectRoot();
+  const seedPath = resolve(root, 'db/seed.json');
+
+  if (!existsSync(seedPath)) {
+    fail('db/seed.json not found.');
+    process.exit(1);
+  }
+
+  // Read .dev.vars for local, or prompt for production URL
+  const isRemote = process.argv.includes('--remote');
+  const targetUrl = isRemote
+    ? process.argv[process.argv.indexOf('--remote') + 1]
+    : 'http://localhost:8787';
+
+  if (isRemote && !targetUrl) {
+    fail('Usage: koguma migrate-media --remote https://your-site.workers.dev');
+    process.exit(1);
+  }
+
+  log(`Target: ${CYAN}${targetUrl}${RESET}`);
+
+  // Read password from .dev.vars
+  const devVarsPath = resolve(root, '.dev.vars');
+  let password = '';
+  if (existsSync(devVarsPath)) {
+    const content = readFileSync(devVarsPath, 'utf-8');
+    const match = content.match(/KOGUMA_SECRET=(.+)/);
+    if (match?.[1]) password = match[1].trim();
+  }
+  if (!password) {
+    fail('KOGUMA_SECRET not found in .dev.vars');
+    process.exit(1);
+  }
+
+  // Login
+  log('Logging in...');
+  const loginRes = await fetch(`${targetUrl}/api/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ password }),
+    redirect: 'manual'
+  });
+  const setCookie = loginRes.headers.get('set-cookie') ?? '';
+  const cookieMatch = setCookie.match(/koguma_session=[^;]+/);
+  if (!cookieMatch) {
+    fail('Login failed — check your KOGUMA_SECRET');
+    process.exit(1);
+  }
+  const cookie = cookieMatch[0];
+  ok('Authenticated');
+
+  // Load seed.json
+  const seed = JSON.parse(readFileSync(seedPath, 'utf-8')) as {
+    assets: Array<{
+      id: string;
+      title: string;
+      file: { url: string; contentType: string; fileName: string };
+    }>;
+  };
+
+  log(`Found ${seed.assets.length} assets\n`);
+
+  const results: Array<{ id: string; newUrl: string }> = [];
+
+  for (const asset of seed.assets) {
+    const url = asset.file.url.startsWith('//')
+      ? `https:${asset.file.url}`
+      : asset.file.url;
+    log(`⬇ ${asset.title}`);
+
+    try {
+      const dlRes = await fetch(url);
+      if (!dlRes.ok) {
+        warn(`  Download failed: ${dlRes.status}`);
+        continue;
+      }
+
+      const blob = await dlRes.blob();
+      const fileName =
+        asset.file.fileName ||
+        `${asset.id}.${asset.file.contentType.split('/')[1]}`;
+
+      const formData = new FormData();
+      formData.append(
+        'file',
+        new File([blob], fileName, { type: asset.file.contentType })
+      );
+      formData.append('title', asset.title);
+
+      const upRes = await fetch(`${targetUrl}/api/admin/media`, {
+        method: 'POST',
+        headers: { Cookie: cookie },
+        body: formData
+      });
+
+      if (!upRes.ok) {
+        warn(`  Upload failed: ${await upRes.text()}`);
+        continue;
+      }
+
+      const { url: newUrl } = (await upRes.json()) as { url: string };
+      ok(`  → ${newUrl}`);
+      results.push({ id: asset.id, newUrl });
+    } catch (e) {
+      warn(`  Error: ${e}`);
+    }
+  }
+
+  log(`\n✅ Migrated: ${results.length}/${seed.assets.length}`);
+
+  // Generate and apply URL update SQL
+  if (results.length > 0) {
+    const sql = results
+      .map(r => `UPDATE _assets SET url = '${r.newUrl}' WHERE id = '${r.id}';`)
+      .join('\n');
+
+    const sqlPath = resolve(root, 'db/migrate-urls.sql');
+    writeFileSync(sqlPath, sql);
+
+    // Auto-apply to local or remote D1
+    const toml = readFileSync(resolve(root, 'wrangler.toml'), 'utf-8');
+    const dbNameMatch = toml.match(/database_name\s*=\s*"([^"]+)"/);
+    const dbName = dbNameMatch?.[1] ?? 'my-db';
+    const target = isRemote ? '--remote' : '--local';
+
+    log(`\nUpdating ${isRemote ? 'remote' : 'local'} database URLs...`);
+    run(`npx wrangler d1 execute ${dbName} ${target} --file=${sqlPath}`, {
+      cwd: root
+    });
+
+    ok('Media migration complete!');
+  }
+}
+
+// ── Typegen ─────────────────────────────────────────────────────────
+
+function fieldTypeToTs(
+  fieldType: string,
+  meta: { required: boolean; refContentType?: string; options?: string[] }
+): string {
+  switch (fieldType) {
+    case 'text':
+    case 'longText':
+    case 'url':
+    case 'date':
+      return 'string';
+    case 'richText':
+      return 'Record<string, unknown>';
+    case 'image':
+      return '{ id: string; url: string; title?: string; width?: number; height?: number }';
+    case 'boolean':
+      return 'boolean';
+    case 'number':
+      return 'number';
+    case 'select':
+      return meta.options?.map(o => `'${o}'`).join(' | ') ?? 'string';
+    case 'reference':
+      return meta.refContentType
+        ? `${capitalize(meta.refContentType)}Entry`
+        : 'Record<string, unknown>';
+    case 'references':
+      return meta.refContentType
+        ? `${capitalize(meta.refContentType)}Entry[]`
+        : 'Record<string, unknown>[]';
+    default:
+      return 'unknown';
+  }
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+async function cmdTypegen() {
+  header('koguma typegen');
+  const root = findProjectRoot();
+
+  // Import site.config.ts
+  const configPath = resolve(root, 'site.config.ts');
+  if (!existsSync(configPath)) {
+    fail('site.config.ts not found in project root.');
+    process.exit(1);
+  }
+
+  log('Reading site.config.ts...');
+  const configModule = await import(configPath);
+  const config = configModule.default as {
+    contentTypes: {
+      id: string;
+      name: string;
+      fieldMeta: Record<
+        string,
+        {
+          fieldType: string;
+          required: boolean;
+          refContentType?: string;
+          options?: string[];
+        }
+      >;
+    }[];
+  };
+
+  if (!config.contentTypes?.length) {
+    fail('No content types found in site.config.ts');
+    process.exit(1);
+  }
+
+  // Generate .d.ts
+  const lines: string[] = [
+    '/**',
+    ' * Auto-generated by `koguma typegen`',
+    ' * Do not edit manually.',
+    ' */',
+    '',
+    '// ── System fields ── common to all entries',
+    'interface KogumaSystemFields {',
+    '  id: string;',
+    '  created_at: string;',
+    '  updated_at: string;',
+    '  status: "draft" | "published";',
+    '  publishAt: string | null;',
+    '}',
+    ''
+  ];
+
+  // Generate interfaces for each content type
+  const typeNames: string[] = [];
+  for (const ct of config.contentTypes) {
+    const typeName = capitalize(ct.id) + 'Entry';
+    typeNames.push(typeName);
+
+    lines.push(`// ── ${ct.name} ──`);
+    lines.push(`export interface ${typeName} extends KogumaSystemFields {`);
+
+    for (const [fieldId, meta] of Object.entries(ct.fieldMeta)) {
+      const tsType = fieldTypeToTs(meta.fieldType, meta);
+      const optional = meta.required ? '' : '?';
+      lines.push(`  ${fieldId}${optional}: ${tsType};`);
+    }
+
+    lines.push('}');
+    lines.push('');
+  }
+
+  // Generate client interface
+  lines.push('// ── Koguma Client ──');
+  lines.push('export interface KogumaClient {');
+
+  for (const ct of config.contentTypes) {
+    const typeName = capitalize(ct.id) + 'Entry';
+    lines.push(`  /** ${ct.name} */`);
+    lines.push(`  get(type: '${ct.id}', id: string): Promise<${typeName}>;`);
+    lines.push(
+      `  list(type: '${ct.id}'): Promise<{ entries: ${typeName}[] }>;`
+    );
+    lines.push(
+      `  create(type: '${ct.id}', data: Partial<${typeName}>): Promise<${typeName}>;`
+    );
+    lines.push(
+      `  update(type: '${ct.id}', id: string, data: Partial<${typeName}>): Promise<${typeName}>;`
+    );
+    lines.push(`  delete(type: '${ct.id}', id: string): Promise<void>;`);
+  }
+
+  lines.push('}');
+  lines.push('');
+
+  // Content type union
+  lines.push(
+    `export type ContentType = ${config.contentTypes.map(ct => `'${ct.id}'`).join(' | ')};`
+  );
+  lines.push('');
+
+  const output = lines.join('\n');
+  const outPath = resolve(root, 'koguma.d.ts');
+  writeFileSync(outPath, output);
+
+  ok(
+    `Generated ${CYAN}koguma.d.ts${RESET} with ${typeNames.length} type(s): ${typeNames.join(', ')}`
+  );
+}
+
+// ── Migrate ─────────────────────────────────────────────────────────
+
+async function cmdMigrate() {
+  header('koguma migrate');
+  const root = findProjectRoot();
+
+  // Import site.config.ts
+  const configPath = resolve(root, 'site.config.ts');
+  if (!existsSync(configPath)) {
+    fail('site.config.ts not found.');
+    process.exit(1);
+  }
+
+  log('Reading site.config.ts...');
+  const configModule = await import(configPath);
+  const config = configModule.default as {
+    contentTypes: {
+      id: string;
+      name: string;
+      fieldMeta: Record<
+        string,
+        { fieldType: string; required: boolean; refContentType?: string }
+      >;
+    }[];
+  };
+
+  // Get DB name from wrangler.toml
+  const toml = readFileSync(resolve(root, 'wrangler.toml'), 'utf-8');
+  const dbNameMatch = toml.match(/database_name\s*=\s*"([^"]+)"/);
+  const dbName = dbNameMatch?.[1] ?? 'my-db';
+
+  const isRemote = process.argv.includes('--remote');
+  const target = isRemote ? '--remote' : '--local';
+
+  // Get existing columns for each content type
+  log(`Inspecting ${isRemote ? 'REMOTE' : 'local'} database...`);
+  const existingColumns: Record<string, { name: string; type: string }[]> = {};
+
+  for (const ct of config.contentTypes) {
+    try {
+      const output = runCapture(
+        `npx wrangler d1 execute ${dbName} ${target} --command "SELECT name, type FROM pragma_table_info('${ct.id}')" --json`,
+        root
+      );
+      const parsed = JSON.parse(output);
+      // Wrangler D1 returns results in an array
+      const results = parsed?.[0]?.results ?? [];
+      existingColumns[ct.id] = results;
+    } catch {
+      warn(`Table '${ct.id}' does not exist yet.`);
+    }
+  }
+
+  // Detect drift
+  const { detectDrift } = await import('../src/db/migrate.ts');
+  const result = detectDrift(config.contentTypes as any, existingColumns);
+
+  // Display results
+  if (result.drift.length === 0 && result.warnings.length === 0) {
+    ok('Schema is up to date — no changes needed!');
+    return;
+  }
+
+  if (result.warnings.length > 0) {
+    console.log('');
+    for (const w of result.warnings) {
+      warn(w);
+    }
+  }
+
+  if (result.sql.length > 0) {
+    console.log(`\n${BOLD}Migration SQL:${RESET}`);
+    for (const s of result.sql) {
+      console.log(`  ${CYAN}${s}${RESET}`);
+    }
+
+    // Apply the SQL
+    const sqlFile = resolve(root, 'db/migration.sql');
+    writeFileSync(sqlFile, result.sql.join('\n'));
+    log(`\nWritten to ${CYAN}db/migration.sql${RESET}`);
+
+    log(`\nApplying migration to ${isRemote ? 'REMOTE' : 'local'} database...`);
+    run(`npx wrangler d1 execute ${dbName} ${target} --file=${sqlFile}`, {
+      cwd: root
+    });
+
+    ok('Migration applied!');
+  }
+}
+
+// ── Export ───────────────────────────────────────────────────────────
+
+async function cmdExport() {
+  header('koguma export');
+  const root = findProjectRoot();
+
+  // Import config
+  const configPath = resolve(root, 'site.config.ts');
+  const configModule = await import(configPath);
+  const config = configModule.default as {
+    contentTypes: {
+      id: string;
+      fieldMeta: Record<string, { fieldType: string }>;
+    }[];
+  };
+
+  // Get DB name
+  const toml = readFileSync(resolve(root, 'wrangler.toml'), 'utf-8');
+  const dbNameMatch = toml.match(/database_name\s*=\s*"([^"]+)"/);
+  const dbName = dbNameMatch?.[1] ?? 'my-db';
+
+  const isRemote = process.argv.includes('--remote');
+  const target = isRemote ? '--remote' : '--local';
+
+  const exportData: Record<
+    string,
+    { entries: unknown[]; joinTables: Record<string, unknown[]> }
+  > = {};
+
+  for (const ct of config.contentTypes) {
+    log(`Exporting ${CYAN}${ct.id}${RESET}...`);
+
+    // Export main table
+    try {
+      const output = runCapture(
+        `npx wrangler d1 execute ${dbName} ${target} --command "SELECT * FROM ${ct.id}" --json`,
+        root
+      );
+      const parsed = JSON.parse(output);
+      const entries = parsed?.[0]?.results ?? [];
+
+      // Export join tables
+      const joinTables: Record<string, unknown[]> = {};
+      for (const [fieldId, meta] of Object.entries(ct.fieldMeta)) {
+        if (meta.fieldType === 'references') {
+          const joinTable = `${ct.id}__${fieldId}`;
+          try {
+            const jtOutput = runCapture(
+              `npx wrangler d1 execute ${dbName} ${target} --command "SELECT * FROM ${joinTable}" --json`,
+              root
+            );
+            const jtParsed = JSON.parse(jtOutput);
+            joinTables[joinTable] = jtParsed?.[0]?.results ?? [];
+          } catch {
+            // Join table may not exist
+          }
+        }
+      }
+
+      exportData[ct.id] = { entries, joinTables };
+    } catch {
+      warn(`Could not export ${ct.id} — table may not exist.`);
+    }
+  }
+
+  const exportFile = resolve(
+    root,
+    `koguma-export-${new Date().toISOString().slice(0, 10)}.json`
+  );
+  const payload = {
+    version: 1,
+    exportedAt: new Date().toISOString(),
+    source: isRemote ? 'remote' : 'local',
+    contentTypes: exportData
+  };
+  writeFileSync(exportFile, JSON.stringify(payload, null, 2));
+
+  const entryCount = Object.values(exportData).reduce(
+    (sum, ct) => sum + ct.entries.length,
+    0
+  );
+  ok(
+    `Exported ${entryCount} entries to ${CYAN}${basename(exportFile)}${RESET}`
+  );
+}
+
+// ── Import ──────────────────────────────────────────────────────────
+
+async function cmdImport() {
+  header('koguma import');
+  const root = findProjectRoot();
+
+  const inputFile = process.argv[3];
+  if (!inputFile) {
+    fail('Usage: koguma import <file.json> [--remote]');
+    process.exit(1);
+  }
+
+  const filePath = resolve(root, inputFile);
+  if (!existsSync(filePath)) {
+    fail(`File not found: ${inputFile}`);
+    process.exit(1);
+  }
+
+  const payload = JSON.parse(readFileSync(filePath, 'utf-8'));
+  if (payload.version !== 1) {
+    fail(`Unsupported export version: ${payload.version}`);
+    process.exit(1);
+  }
+
+  // Get DB name
+  const toml = readFileSync(resolve(root, 'wrangler.toml'), 'utf-8');
+  const dbNameMatch = toml.match(/database_name\s*=\s*"([^"]+)"/);
+  const dbName = dbNameMatch?.[1] ?? 'my-db';
+
+  const isRemote = process.argv.includes('--remote');
+  const target = isRemote ? '--remote' : '--local';
+
+  let totalEntries = 0;
+
+  for (const [typeId, data] of Object.entries(
+    payload.contentTypes as Record<
+      string,
+      {
+        entries: Record<string, unknown>[];
+        joinTables: Record<string, Record<string, unknown>[]>;
+      }
+    >
+  )) {
+    log(
+      `Importing ${CYAN}${typeId}${RESET} (${data.entries.length} entries)...`
+    );
+
+    for (const entry of data.entries) {
+      const cols = Object.keys(entry);
+      const vals = Object.values(entry).map(v => {
+        if (v === null) return 'NULL';
+        if (typeof v === 'number') return String(v);
+        return `'${String(v).replace(/'/g, "''")}'`;
+      });
+
+      const sql = `INSERT OR REPLACE INTO ${typeId} (${cols.join(', ')}) VALUES (${vals.join(', ')})`;
+      run(
+        `npx wrangler d1 execute ${dbName} ${target} --command "${sql.replace(/"/g, '\\"')}"`,
+        { cwd: root, silent: true }
+      );
+      totalEntries++;
+    }
+
+    // Import join tables
+    for (const [jtName, rows] of Object.entries(data.joinTables)) {
+      for (const row of rows) {
+        const cols = Object.keys(row);
+        const vals = Object.values(row).map(v => {
+          if (v === null) return 'NULL';
+          if (typeof v === 'number') return String(v);
+          return `'${String(v).replace(/'/g, "''")}'`;
+        });
+
+        const sql = `INSERT OR REPLACE INTO ${jtName} (${cols.join(', ')}) VALUES (${vals.join(', ')})`;
+        run(
+          `npx wrangler d1 execute ${dbName} ${target} --command "${sql.replace(/"/g, '\\"')}"`,
+          { cwd: root, silent: true }
+        );
+      }
+    }
+  }
+
+  ok(
+    `Imported ${totalEntries} entries from ${CYAN}${basename(inputFile)}${RESET}`
+  );
+}
+
+function cmdHelp() {
+  console.log(`
+${BOLD}🐻 Koguma CLI${RESET} ${DIM}v0.4.0${RESET}
+
+${BOLD}Usage:${RESET} koguma <command>
+
+${BOLD}Commands:${RESET}
+  ${CYAN}init${RESET}            Create D1 database and R2 bucket, patch wrangler.toml
+  ${CYAN}secret${RESET}          Set the admin password on Cloudflare
+  ${CYAN}build${RESET}           Build the admin dashboard bundle
+  ${CYAN}seed${RESET}            Seed the database from db/seed.sql
+  ${CYAN}typegen${RESET}         Generate koguma.d.ts typed interfaces
+  ${CYAN}migrate${RESET}         Detect schema drift and apply ALTER TABLE changes
+  ${CYAN}export${RESET}          Export all content to JSON
+  ${CYAN}import${RESET}          Import content from JSON file
+  ${CYAN}migrate-media${RESET}   Download images and upload to R2
+  ${CYAN}deploy${RESET}          Build admin + frontend, then deploy via wrangler
+
+${BOLD}Options:${RESET}
+  ${DIM}koguma seed --remote${RESET}                           Seed the production database
+  ${DIM}koguma migrate --remote${RESET}                        Migrate the production database
+  ${DIM}koguma export --remote${RESET}                         Export from production
+  ${DIM}koguma import data.json --remote${RESET}               Import to production
+  ${DIM}koguma migrate-media --remote https://...${RESET}      Migrate to production R2
+
+${BOLD}First deploy:${RESET}
+  ${DIM}$${RESET} koguma init                       ${DIM}# Create D1 + R2${RESET}
+  ${DIM}$${RESET} koguma secret                     ${DIM}# Set admin password${RESET}
+  ${DIM}$${RESET} koguma seed --remote              ${DIM}# Seed production DB${RESET}
+  ${DIM}$${RESET} koguma deploy                     ${DIM}# Build + deploy${RESET}
+`);
+}
+
+// ── Dispatch ────────────────────────────────────────────────────────
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'init':
+    await cmdInit();
+    break;
+  case 'secret':
+    await cmdSecret();
+    break;
+  case 'build':
+    await cmdBuild();
+    break;
+  case 'seed':
+    await cmdSeed();
+    break;
+  case 'typegen':
+    await cmdTypegen();
+    break;
+  case 'migrate':
+    await cmdMigrate();
+    break;
+  case 'export':
+    await cmdExport();
+    break;
+  case 'import':
+    await cmdImport();
+    break;
+  case 'migrate-media':
+    await cmdMigrateMedia();
+    break;
+  case 'deploy':
+    await cmdDeploy();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    cmdHelp();
+    break;
+  default:
+    fail(`Unknown command: ${command}`);
+    cmdHelp();
+    process.exit(1);
+}