koguma 0.6.6 → 2.0.0

package/cli/index.ts

@@ -3,1708 +3,972 @@
  * 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
+ *   koguma init           — Create D1/R2 resources, scaffold project
+ *   koguma dev            — Run local dev server
+ *   koguma push           — Build + deploy to production
+ *   koguma pull           — Download production content
+ *   koguma gen-types      — Generate koguma.d.ts
+ *   koguma tidy           — Sync content/ dirs with config + validate
  *
- * All commands auto-detect the project root by looking for wrangler.toml.
+ * All commands auto-detect the project root by looking for koguma.toml.
  */
 
-import { execSync } from 'child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { resolve, dirname, basename } from 'path';
-import { generateSchema } from '../src/db/schema.ts';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
+import { resolve, dirname, extname } from 'path';
+
+import { ANSI, log, ok, warn, fail, header } from './log.ts';
+import { run } from './exec.ts';
+import {
+  CLI_VERSION,
+  CONFIG_FILE,
+  SITE_CONFIG_FILE,
+  CONTENT_DIR,
+  DB_DIR,
+  KOGUMA_DIR
+} from './constants.ts';
+import { readConfig, writeConfig, deriveNames } from './config.ts';
+import { preflight } from './preflight.ts';
+import {
+  scaffoldNewProject,
+  scaffoldContentDir,
+  syncContentDirsWithConfig,
+  TEMPLATES
+} from './scaffold.ts';
+import { runTypegen } from './typegen.ts';
+import { authenticate, getRemoteUrl } from './auth.ts';
+import {
+  checkWranglerAuth,
+  applySchema,
+  d1Query,
+  d1InsertRow,
+  d1InsertBatch,
+  applySchemaAsync,
+  d1InsertBatchAsync,
+  d1ExecuteBatchSqlAsync,
+  r2PutLocal,
+  r2PutLocalAsync,
+  wranglerDev,
+  wranglerDeploy,
+  createD1Database,
+  ensureR2Bucket,
+  type D1Target
+} from './wrangler.ts';
 import {
-  buildInsertSql,
-  wrapForShell,
-  buildAssetIndex,
-  processSeedEntry,
-  buildImportSql
-} from '../src/db/sql.ts';
+  prepareContentForSync,
+  writeContentDir,
+  validateContent,
+  type ContentTypeInfo
+} from './content.ts';
+import { startDevSync, DEV_SYNC_ENV_VAR, killStalePortHolder } from './dev-sync.ts';
+import { buildInsertSql, wrapForShell } from '../src/db/sql.ts';
+import { intro, outro, handleCancel, p, BRAND } from './ui.ts';
 
 // ── 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) */
+/** Find the project root (directory containing koguma.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;
+    if (existsSync(resolve(dir, CONFIG_FILE))) return dir;
     const parent = dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  fail('Could not find wrangler.toml — run this from your project directory.');
+  p.log.error(
+    `Could not find ${CONFIG_FILE} — run this from your project directory.\n` +
+      `  Run ${BRAND.ACCENT}koguma init${BRAND.RESET} to create a new project.`
+  );
   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()'
+/** Read koguma.toml and derive conventional names */
+function getProjectNames(root: string) {
+  const config = readConfig(root);
+  return deriveNames(config.name);
 }
 
-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;
+/** Load site.config.ts content types */
+async function loadSiteConfig(
+  root: string
+): Promise<{ contentTypes: ContentTypeInfo[] }> {
+  const configPath = resolve(root, SITE_CONFIG_FILE);
+  const configModule = await import(configPath);
+  return configModule.default as { contentTypes: ContentTypeInfo[] };
 }
 
-// ── Commands ────────────────────────────────────────────────────────
-
-async function cmdInit() {
-  header('koguma init');
+/** Run content validation and print warnings */
+async function runValidation(root: string): Promise<void> {
+  const contentDir = resolve(root, CONTENT_DIR);
+  if (!existsSync(contentDir)) return;
 
-  // 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'));
+  const configPath = resolve(root, SITE_CONFIG_FILE);
+  if (!existsSync(configPath)) return;
 
-  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(`bunx 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: bunx 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('bunx wrangler r2 bucket list', root);
-    if (buckets.includes(bucketName)) {
-      ok(`R2 bucket already exists: ${DIM}${bucketName}${RESET}`);
-    } else {
-      runCapture(`bunx wrangler r2 bucket create ${bucketName}`, root);
-      ok(`Created R2 bucket: ${DIM}${bucketName}${RESET}`);
+    const config = await loadSiteConfig(root);
+    const warnings = validateContent(contentDir, config.contentTypes);
+    for (const w of warnings) {
+      p.log.warn(`${w.file}: ${w.message}`);
     }
-  } catch {
-    fail(
-      "Failed to check/create R2 bucket. Make sure you're logged into Cloudflare."
-    );
+  } catch (e) {
+    p.log.warn(`Validation failed: ${e}`);
   }
-
-  // ── 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');
+/** Sync content/ files → local D1 entries (used by dev + push) */
+async function syncContentToLocalD1(
+  root: string,
+  dbName: string,
+  s?: ReturnType<typeof p.spinner>
+): Promise<number> {
+  const contentDir = resolve(root, CONTENT_DIR);
+  if (!existsSync(contentDir)) return 0;
 
-  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 });
-  }
+  const configPath = resolve(root, SITE_CONFIG_FILE);
+  if (!existsSync(configPath)) return 0;
 
-  // Build Vite app
-  log('Building admin dashboard...');
-  run('bun run build', { cwd: adminDir });
+  try {
+    const config = await loadSiteConfig(root);
 
-  // Generate bundle
-  log('Generating admin bundle...');
-  const scriptPath = resolve(kogumaRoot, 'scripts/bundle-admin.ts');
-  run(`bun run ${scriptPath}`, { cwd: kogumaRoot });
+    // Run validation before sync
+    const warnings = validateContent(contentDir, config.contentTypes);
+    for (const w of warnings) {
+      warn(`${w.file}: ${w.message}`);
+    }
 
-  ok('Admin bundle ready!');
-}
+    // Ensure schema exists
+    if (s) s.message('Applying schema...');
+    await applySchemaAsync(root, dbName, '--local');
 
-async function cmdSeed() {
-  header('koguma seed');
-  const root = findProjectRoot();
-  const seedTs = resolve(root, 'db/seed.ts');
-  const seedSql = resolve(root, 'db/seed.sql');
-
-  // 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';
-
-  if (existsSync(seedTs)) {
-    // ── seed.ts path — structured seeding with smart field resolution ──
-    log(`Using ${CYAN}db/seed.ts${RESET} (structured seed)`);
-    const seedModule = await import(seedTs);
-    const seedData = seedModule.default as Record<
-      string,
-      Record<string, unknown>[]
-    >;
-
-    // Import config for field metadata
-    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; required: boolean }>;
-      }[];
-    };
-    const ctMap = new Map(config.contentTypes.map(ct => [ct.id, ct]));
+    // Build asset ID map from content/media/ filenames
+    const mediaDir = resolve(contentDir, 'media');
+    const assetIdMap = new Map<string, string>();
+    const assetSql: string[] = [];
+    const mediaUploads: { filePath: string; key: string }[] = [];
 
-    // Build asset title→id lookup
-    log('Loading asset index...');
-    let assetIndex = buildAssetIndex([]);
-    try {
-      const output = runCapture(
-        `bunx wrangler d1 execute ${dbName} ${target} --command "SELECT id, title FROM _assets" --json`,
-        root
+    if (existsSync(mediaDir)) {
+      const mediaFiles = readdirSync(mediaDir).filter(
+        f => !f.startsWith('.') && !f.startsWith('_')
       );
-      const parsed = JSON.parse(output);
-      const assets = parsed?.[0]?.results ?? [];
-      assetIndex = buildAssetIndex(assets);
-      ok(`Loaded ${assetIndex.titleMap.size} asset mappings`);
-    } catch {
-      warn('No _assets table found — image title resolution disabled');
+      const mimeTypes: Record<string, string> = {
+        '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+      };
+
+      for (const file of mediaFiles) {
+        const ext = extname(file).toLowerCase();
+        const id = `media-${file.replace(/\.\w+$/, '')}`;
+        const key = `${id}${ext}`;
+
+        assetIdMap.set(file, id);
+        mediaUploads.push({ filePath: resolve(mediaDir, file), key });
+        assetSql.push(buildInsertSql('assets', {
+          id,
+          data: JSON.stringify({
+            title: file,
+            url: `/api/media/${key}`,
+            content_type: mimeTypes[ext] ?? 'application/octet-stream',
+            width: null, height: null, file_size: null
+          })
+        }));
+      }
     }
 
-    // Lazy-load markdown converter
-    const { markdownToKoguma } =
-      await import('../src/rich-text/markdown-to-koguma.ts');
-    const { kogumaToLexical } =
-      await import('../src/rich-text/koguma-to-lexical.ts');
-
-    let totalEntries = 0;
-
-    for (const [typeId, entries] of Object.entries(seedData)) {
-      const ct = ctMap.get(typeId);
-      if (!ct) {
-        warn(`Content type '${typeId}' not found in site.config.ts — skipping`);
-        continue;
+    // Sync content/ files → D1 entries
+    const prepared = prepareContentForSync(contentDir, config.contentTypes);
+    const entrySql: string[] = [];
+    for (const { contentType, rowData } of prepared) {
+      const {
+        id, slug, status, publish_at, publishAt,
+        created_at: _ca, updated_at: _ua, content_type: _ct,
+        ...fields
+      } = rowData;
+
+      // Resolve media filenames → asset IDs
+      const ct = config.contentTypes.find(c => c.id === contentType);
+      if (ct && assetIdMap.size > 0) {
+        for (const [fieldId, meta] of Object.entries(ct.fieldMeta)) {
+          if (meta.fieldType === 'image' && typeof fields[fieldId] === 'string') {
+            fields[fieldId] = assetIdMap.get(fields[fieldId] as string) ?? fields[fieldId];
+          } else if (meta.fieldType === 'images' && Array.isArray(fields[fieldId])) {
+            fields[fieldId] = (fields[fieldId] as string[]).map(
+              v => assetIdMap.get(v) ?? v
+            );
+          }
+        }
       }
 
-      log(`Seeding ${CYAN}${typeId}${RESET} (${entries.length} entries)...`);
-
-      for (const entry of entries) {
-        const { processed, resolutions } = processSeedEntry(
-          entry,
-          ct.fieldMeta,
-          assetIndex,
-          markdownToKoguma,
-          kogumaToLexical
-        );
+      entrySql.push(buildInsertSql('entries', {
+        id: id as string,
+        content_type: contentType,
+        slug: (slug as string | undefined) ?? null,
+        data: JSON.stringify(fields),
+        status: (status as string | undefined) ?? 'draft',
+        ...(publish_at !== undefined ? { publish_at } : {}),
+        ...(publishAt !== undefined ? { publish_at: publishAt } : {})
+      }));
+    }
 
-        for (const r of resolutions) {
-          ok(`  ${r}`);
-        }
+    // Single batch: assets + entries written to one SQL file
+    const allStatements = [...assetSql, ...entrySql];
+    if (allStatements.length > 0) {
+      if (s) s.message(`Syncing ${entrySql.length} entries + ${assetSql.length} assets...`);
+      await d1ExecuteBatchSqlAsync(root, dbName, '--local', allStatements);
+    }
 
-        const sql = buildInsertSql(typeId, processed);
-        run(
-          `bunx wrangler d1 execute ${dbName} ${target} --command "${wrapForShell(sql)}"`,
-          { cwd: root, silent: true }
-        );
-        totalEntries++;
+    // Upload media files to local R2
+    if (mediaUploads.length > 0) {
+      if (s) s.message(`Uploading ${mediaUploads.length} media files...`);
+      const { bucketName } = deriveNames(readConfig(root).name);
+      for (const { filePath, key } of mediaUploads) {
+        await r2PutLocalAsync(root, bucketName, key, filePath);
       }
     }
-
-    ok(`Seeded ${totalEntries} entries (${isRemote ? 'remote' : 'local'})!`);
-  } else if (existsSync(seedSql)) {
-    // ── seed.sql path — legacy SQL seeding ──
-    log(
-      `Seeding ${isRemote ? 'REMOTE' : 'local'} database: ${CYAN}${dbName}${RESET}`
-    );
-    run(`bunx wrangler d1 execute ${dbName} ${target} --file=${seedSql}`, {
-      cwd: root
-    });
-    ok(`Database seeded (${isRemote ? 'remote' : 'local'})!`);
-  } else {
-    fail(
-      'No seed file found. Create db/seed.ts (structured) or db/seed.sql (raw SQL).'
-    );
-    process.exit(1);
+    return prepared.length;
+  } catch (e) {
+    if (s) s.stop('Content sync failed');
+    warn(`Content sync failed: ${e}`);
+    return 0;
   }
 }
 
-async function cmdDeploy() {
-  header('koguma deploy');
+// ── Commands ────────────────────────────────────────────────────────
 
-  // Build admin first
-  await cmdBuild();
+/**
+ * koguma init — Full project setup.
+ *
+ * Interactive flow: project name → template → scaffold → Cloudflare setup.
+ *
+ * CI mode (KOGUMA_CI=1): Uses env vars instead of interactive prompts:
+ *   KOGUMA_PROJECT_NAME — project name (default: directory name)
+ *   KOGUMA_TEMPLATE     — template name: Blog|Portfolio|Docs|Blank (default: Blog)
+ *   Skips Cloudflare setup and dependency install.
+ */
+async function cmdInit(): Promise<void> {
+  intro('init');
 
-  // Build frontend
-  const root = findProjectRoot();
-  log('\nBuilding frontend...');
-  run('bun run build', { cwd: root });
+  const cwd = process.cwd();
+  const hasConfig = existsSync(resolve(cwd, CONFIG_FILE));
+  const ciMode = process.env.KOGUMA_CI === '1';
 
-  // Deploy
-  log('\nDeploying to Cloudflare...');
-  run('bunx wrangler deploy', { cwd: root });
+  let root: string;
 
-  ok('Deployed! 🎉');
-}
+  if (!hasConfig) {
+    const dirName = cwd.split('/').pop() ?? 'my-koguma-site';
 
-async function cmdSecret() {
-  header('koguma secret');
-  const root = findProjectRoot();
-  log('Setting KOGUMA_SECRET (your admin password)...');
-  run('bunx wrangler secret put KOGUMA_SECRET', { cwd: root });
-  ok('Secret set!');
-}
+    let projectName: string;
+    let template: (typeof TEMPLATES)[number];
 
-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);
-  }
+    if (ciMode) {
+      // ── CI mode: use env vars ──
+      projectName = process.env.KOGUMA_PROJECT_NAME || dirName;
+      const templateName = process.env.KOGUMA_TEMPLATE || 'Blog';
+      template = TEMPLATES.find(t => t.name === templateName) ?? TEMPLATES[0]!;
+      p.log.info(`CI mode: ${projectName} (${template.name})`);
+    } else {
+      // ── Interactive mode ──
+      const nameResult = await p.text({
+        message: 'Project name',
+        placeholder: dirName,
+        defaultValue: dirName,
+        validate(value) {
+          if (!value || value.length === 0) return 'Project name is required';
+          if (!/^[a-z0-9-]+$/i.test(value))
+            return 'Use only letters, numbers, and hyphens';
+        }
+      });
+      if (handleCancel(nameResult)) return;
+      projectName = nameResult as string;
+
+      const templateChoice = await p.select({
+        message: 'Pick a template',
+        options: TEMPLATES.map(t => ({
+          value: t.name,
+          label: t.name,
+          hint: t.description
+        }))
+      });
+      if (handleCancel(templateChoice)) return;
+      template =
+        TEMPLATES.find(t => t.name === templateChoice) ?? TEMPLATES[0]!;
+    }
 
-  // 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';
+    // Scaffold files
+    const s = p.spinner();
+    s.start('Scaffolding project files...');
 
-  if (isRemote && !targetUrl) {
-    fail('Usage: koguma migrate-media --remote https://your-site.workers.dev');
-    process.exit(1);
-  }
+    const {
+      root: scaffoldRoot,
+      createdFiles,
+      skippedFiles
+    } = scaffoldNewProject(projectName, template);
+    root = scaffoldRoot;
 
-  log(`Target: ${CYAN}${targetUrl}${RESET}`);
+    s.stop('Project scaffolded');
 
-  // 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);
-  }
+    for (const f of createdFiles) {
+      p.log.success(`Created ${f}`);
+    }
+    for (const f of skippedFiles) {
+      p.log.warn(`${f} already exists, skipped`);
+    }
 
-  // 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);
+    // Install dependencies (skip in CI mode)
+    if (!ciMode) {
+      const si = p.spinner();
+      si.start('Installing dependencies...');
+      try {
+        run('bun install', { cwd: root });
+        si.stop('Dependencies installed');
+      } catch {
+        si.stop('Dependency install failed');
+        p.log.warn("Run 'bun install' manually");
+      }
+    }
+  } else {
+    root = findProjectRoot();
+    p.log.info('Existing project detected');
   }
-  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}`);
 
+  // ── Scaffold content/ dirs from real config if available ──
+  const siteConfigPath = resolve(root, SITE_CONFIG_FILE);
+  if (existsSync(siteConfigPath)) {
     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 });
+      const siteConfig = await loadSiteConfig(root);
+      scaffoldContentDir(root, siteConfig.contentTypes);
     } catch (e) {
-      warn(`  Error: ${e}`);
+      p.log.warn(`Could not scaffold content dirs: ${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(`bunx 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 'KogumaDocument';
-    case 'image':
-      return 'KogumaAsset';
-    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>[]';
-    case 'youtube':
-    case 'instagram':
-    case 'email':
-    case 'phone':
-    case 'color':
-      return 'string';
-    case 'images':
-      return 'string[]';
-    default:
-      return 'unknown';
+  // ── Cloudflare setup (skip in CI mode) ──
+  if (ciMode) {
+    outro('Project scaffolded! Run `koguma dev` to start. 🐻');
+    return;
   }
-}
 
-function capitalize(s: string): string {
-  return s.charAt(0).toUpperCase() + s.slice(1);
-}
-
-async function cmdTypegen() {
-  header('koguma typegen');
-  const root = findProjectRoot();
+  const setupNow = await p.confirm({
+    message: 'Set up Cloudflare resources now? (D1, R2, secret)',
+    initialValue: true
+  });
+  if (handleCancel(setupNow)) return;
 
-  // 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);
+  if (!setupNow) {
+    p.log.info('Skipped Cloudflare setup. Run `koguma init` again when ready.');
+    outro('Project ready! Run `koguma dev` to start. 🐻');
+    return;
   }
 
-  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[];
-        }
-      >;
-    }[];
-  };
+  const config = readConfig(root);
+  const projectName = config.name || 'my-project';
+  const { dbName, bucketName } = deriveNames(projectName);
 
-  if (!config.contentTypes?.length) {
-    fail('No content types found in site.config.ts');
-    process.exit(1);
+  // Step 1: Wrangler login
+  const sAuth = p.spinner();
+  sAuth.start('Checking Cloudflare authentication...');
+  try {
+    checkWranglerAuth(root);
+    sAuth.stop('Logged in to Cloudflare');
+  } catch {
+    sAuth.stop('Not logged in');
+    p.log.step('Opening Cloudflare login...');
+    run('bunx wrangler login');
+    p.log.success('Logged in');
   }
 
-  // Generate .d.ts
-  const lines: string[] = [
-    '/**',
-    ' * Auto-generated by `koguma typegen`',
-    ' * Do not edit manually.',
-    ' */',
-    '',
-    'import type { KogumaDocument, KogumaAsset } from "koguma/types";',
-    '',
-    '// ── 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};`);
+  // Step 2: D1 database
+  const sDb = p.spinner();
+  if (config.databaseId) {
+    p.log.success(`D1 database: ${dbName} (${config.databaseId})`);
+  } else {
+    sDb.start(`Creating D1 database: ${dbName}...`);
+    const dbId = createD1Database(root, dbName);
+    if (dbId) {
+      writeConfig(root, { name: projectName, databaseId: dbId });
+      sDb.stop(`Created D1 database: ${dbName}`);
+    } else {
+      sDb.stop('D1 creation failed');
+      p.log.error("Make sure you're logged in: bunx wrangler login");
     }
-
-    lines.push('}');
-    lines.push('');
   }
 
-  // Generate client interface
-  lines.push('// ── Koguma Client ──');
-  lines.push('export interface KogumaClient {');
+  // Step 3: R2 bucket
+  const sR2 = p.spinner();
+  sR2.start(`Checking R2 bucket: ${bucketName}...`);
+  if (ensureR2Bucket(root, bucketName)) {
+    sR2.stop(`R2 bucket ready: ${bucketName}`);
+  } else {
+    sR2.stop('R2 creation failed');
+    p.log.error("Make sure you're logged in: bunx wrangler login");
+  }
 
-  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}>;`
+  // Step 4: Admin secret
+  p.log.step('Setting KOGUMA_SECRET (your admin password)...');
+  try {
+    run('bunx wrangler secret put KOGUMA_SECRET', { cwd: root });
+    p.log.success('Secret set');
+  } catch {
+    p.log.warn(
+      'Could not set secret. Set it later:\n  bunx wrangler secret put KOGUMA_SECRET'
     );
-    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);
+  // Step 5: Apply schema
+  const sSchema = p.spinner();
+  const updatedConfig = readConfig(root);
+  if (updatedConfig.databaseId) {
+    const updatedDbName = deriveNames(updatedConfig.name).dbName;
+    sSchema.start('Applying database schema...');
+    applySchema(root, updatedDbName, '--remote');
+    applySchema(root, updatedDbName, '--local');
+    sSchema.stop('Schema applied to remote + local D1');
+  } else {
+    p.log.warn('Skipping schema — no database_id configured');
+  }
 
-  ok(
-    `Generated ${CYAN}koguma.d.ts${RESET} with ${typeNames.length} type(s): ${typeNames.join(', ')}`
-  );
+  outro('Init complete! Run `koguma dev` to start. 🐻');
 }
 
-// ── Migrate ─────────────────────────────────────────────────────────
-
-async function cmdMigrate() {
-  header('koguma migrate');
+/**
+ * koguma dev — Local development.
+ *
+ * Syncs content/ → local D1, generates types, starts bidirectional
+ * sync (file watcher + webhook server), then starts wrangler dev.
+ */
+async function cmdDev(): Promise<void> {
+  intro('dev');
   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 }[]> = {};
+  preflight(root, { needsSiteConfig: true });
 
-  for (const ct of config.contentTypes) {
-    try {
-      const output = runCapture(
-        `bunx 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 — will create it.`);
-      existingColumns[ct.id] = [];
-    }
-  }
+  const { dbName } = getProjectNames(root);
 
-  // Detect drift
-  const { detectDrift } = await import('../src/db/migrate.ts');
-  const result = detectDrift(config.contentTypes as any, existingColumns);
-
-  // Also ensure _assets table exists
+  // ── Auto-tidy content/ directories ──
+  const sTidy = p.spinner();
+  sTidy.start('Syncing content directories...');
   try {
-    const output = runCapture(
-      `bunx wrangler d1 execute ${dbName} ${target} --command "SELECT name FROM pragma_table_info('_assets')" --json`,
-      root
-    );
-    const parsed = JSON.parse(output);
-    const results = parsed?.[0]?.results ?? [];
-    if (results.length === 0) {
-      result.sql.unshift(
-        `CREATE TABLE IF NOT EXISTS _assets (\n` +
-          `  id TEXT PRIMARY KEY,\n` +
-          `  title TEXT NOT NULL DEFAULT '',\n` +
-          `  description TEXT DEFAULT '',\n` +
-          `  url TEXT NOT NULL,\n` +
-          `  content_type TEXT DEFAULT '',\n` +
-          `  width INTEGER,\n` +
-          `  height INTEGER,\n` +
-          `  file_size INTEGER,\n` +
-          `  created_at TEXT DEFAULT (datetime('now')),\n` +
-          `  updated_at TEXT DEFAULT (datetime('now'))\n` +
-          `);`
-      );
-    }
-  } catch {
-    result.sql.unshift(
-      `CREATE TABLE IF NOT EXISTS _assets (\n` +
-        `  id TEXT PRIMARY KEY,\n` +
-        `  title TEXT NOT NULL DEFAULT '',\n` +
-        `  description TEXT DEFAULT '',\n` +
-        `  url TEXT NOT NULL,\n` +
-        `  content_type TEXT DEFAULT '',\n` +
-        `  width INTEGER,\n` +
-        `  height INTEGER,\n` +
-        `  file_size INTEGER,\n` +
-        `  created_at TEXT DEFAULT (datetime('now')),\n` +
-        `  updated_at TEXT DEFAULT (datetime('now'))\n` +
-        `);`
-    );
+    const config = await loadSiteConfig(root);
+    syncContentDirsWithConfig(root, config.contentTypes);
+    sTidy.stop('Content directories synced');
+  } catch (e) {
+    sTidy.stop('Content tidy failed');
+    warn(`${e}`);
+  }
+
+  // ── Auto-sync content/ → local D1 ──
+  const sSync = p.spinner();
+  sSync.start('Syncing content files...');
+  const syncCount = await syncContentToLocalD1(root, dbName);
+  sSync.stop(`Synced ${syncCount} content entries`);
+
+  // ── Auto-generate types ──
+  const sTypes = p.spinner();
+  sTypes.start('Generating types...');
+  try {
+    const typeNames = await runTypegen(root, { silent: true });
+    sTypes.stop(`Generated koguma.d.ts — ${typeNames.length} type(s)`);
+  } catch (e) {
+    sTypes.stop('Type generation failed');
+    warn(`${e}`);
   }
 
-  // Display results
-  if (result.sql.length === 0 && result.warnings.length === 0) {
-    ok('Schema is up to date — no changes needed!');
-    return;
-  }
+  // ── Start bidirectional dev sync ──
+  const sDevSync = p.spinner();
+  sDevSync.start('Starting dev sync...');
+  let devSync: ReturnType<typeof startDevSync> | null = null;
+  try {
+    const config = await loadSiteConfig(root);
+    devSync = startDevSync(root, dbName, config.contentTypes, { silent: true });
+    sDevSync.stop('Dev sync active (file watcher + sync server)');
+  } catch (e) {
+    sDevSync.stop('Dev sync failed');
+    warn(`${e}`);
+  }
+
+  // ── Cleanup on exit ──
+  const cleanup = () => {
+    devSync?.stop();
+    process.exit(0);
+  };
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
 
-  if (result.warnings.length > 0) {
-    console.log('');
-    for (const w of result.warnings) {
-      warn(w);
+  // ── Show admin password ──
+  const devVarsPath = resolve(root, KOGUMA_DIR, '.dev.vars');
+  if (existsSync(devVarsPath)) {
+    const dvContent = readFileSync(devVarsPath, 'utf-8');
+    const secretMatch = dvContent.match(/KOGUMA_SECRET=(.+)/);
+    if (secretMatch) {
+      p.log.info(
+        `Admin password: ${BRAND.ACCENT}${secretMatch[1]!.trim()}${BRAND.RESET} ${BRAND.DIM}(${KOGUMA_DIR}/.dev.vars)${BRAND.RESET}`
+      );
     }
   }
 
-  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}`);
+  // ── Kill stale wrangler/workerd from previous runs ──
+  killStalePortHolder(8787);
 
-    log(`\nApplying migration to ${isRemote ? 'REMOTE' : 'local'} database...`);
-    run(`bunx wrangler d1 execute ${dbName} ${target} --file=${sqlFile}`, {
-      cwd: root
-    });
+  console.log(
+    `\n  ${ANSI.BRAND_TEAL}${ANSI.BOLD}🐻 Starting dev server...${ANSI.RESET}\n`
+  );
 
-    ok('Migration applied!');
+  // ── Start dev server (takes over stdout) ──
+  const extra = process.argv.slice(3).join(' ');
+  try {
+    await wranglerDev(
+      root,
+      extra,
+      devSync ? { [DEV_SYNC_ENV_VAR]: devSync.syncUrl } : undefined
+    );
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    // Extract actionable wrangler error if present
+    const wranglerError = msg.match(/\[ERROR\]\s*(.+)/)?.[1] || msg;
+    p.log.error(`Wrangler failed: ${wranglerError}`);
+    p.outro('Dev server stopped due to an error.');
+  } finally {
+    // Always clean up devSync and exit immediately.
+    // Without this, the devSync HTTP server keeps Node alive for ~15-20s.
+    devSync?.stop();
+    process.exit(0);
   }
 }
 
-// ── Schema ──────────────────────────────────────────────────────────
-
-async function cmdSchema() {
-  header('koguma schema');
+/**
+ * koguma push — Ship to production.
+ *
+ * Content sync → build admin → deploy → sync data + media to remote.
+ */
+async function cmdPush(): Promise<void> {
+  intro('push');
   const root = findProjectRoot();
+  const remoteUrl = getRemoteUrl();
 
-  const configPath = resolve(root, 'site.config.ts');
-  if (!existsSync(configPath)) {
-    fail('site.config.ts not found in project root.');
-    process.exit(1);
-  }
+  preflight(root, {
+    needsSiteConfig: true,
+    needsAuth: true,
+    needsSecret: true
+  });
 
-  log('Reading site.config.ts...');
-  const configModule = await import(configPath);
-  const config = configModule.default as {
-    contentTypes: {
-      id: string;
-      fieldMeta: Record<string, { fieldType: string; required: boolean }>;
-    }[];
-  };
+  const { dbName, bucketName } = getProjectNames(root);
 
-  if (!config.contentTypes?.length) {
-    fail('No content types found in site.config.ts');
-    process.exit(1);
+  // ── Confirmation ──
+  const confirmed = await p.confirm({
+    message: `Push local content to ${BRAND.ACCENT}${remoteUrl}${BRAND.RESET}?`,
+    initialValue: true
+  });
+  if (handleCancel(confirmed)) return;
+  if (!confirmed) {
+    outro('Push cancelled.');
+    return;
   }
 
-  const schema = generateSchema(config.contentTypes as any);
+  // ── Step 1: Apply schema to remote ──
+  const s1 = p.spinner();
+  s1.start('Applying schema to remote...');
+  applySchema(root, dbName, '--remote');
+  s1.stop('Remote schema applied');
 
-  // Print to stdout
-  console.log('');
-  console.log(schema.sql);
-  console.log('');
+  // ── Step 2: Sync content/ → local D1 ──
+  const s2 = p.spinner();
+  s2.start('Syncing content/ to local D1...');
+  await syncContentToLocalD1(root, dbName, s2);
+  s2.stop('Local content synced');
 
-  // Also write to db/schema.sql
-  const dbDir = resolve(root, 'db');
-  if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
-  const outPath = resolve(dbDir, 'schema.sql');
-  writeFileSync(outPath, schema.sql + '\n');
-
-  ok(
-    `Written to ${CYAN}db/schema.sql${RESET} (${schema.tables.length} tables, ${schema.indexes.length} indexes)`
-  );
-  log(
-    `\n  ${DIM}Use this as the basis for your seed.sql to avoid schema drift.${RESET}`
-  );
-}
-
-// ── Export ───────────────────────────────────────────────────────────
-
-async function cmdExport() {
-  header('koguma export');
-  const root = findProjectRoot();
+  // ── Step 3: Export local content ──
+  const s3 = p.spinner();
+  s3.start('Exporting local content...');
 
-  // 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(
-        `bunx 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(
-              `bunx 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.`);
-    }
+  let localEntries: Record<string, unknown>[] = [];
+  try {
+    localEntries = d1Query(root, dbName, '--local', 'SELECT * FROM entries');
+  } catch {
+    p.log.warn('Could not export entries from local');
   }
 
-  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}`
+  let localAssets: Record<string, unknown>[] = [];
+  try {
+    localAssets = d1Query(root, dbName, '--local', 'SELECT * FROM assets');
+  } catch {
+    p.log.warn('Could not export assets from local');
+  }
+  s3.stop(
+    `Exported ${localEntries.length} entries + ${localAssets.length} assets`
   );
-}
 
-// ── 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);
+  // ── Step 4: Import to remote ──
+  const total = localEntries.length + localAssets.length;
+  if (total > 0) {
+    const prog = p.progress({ max: total });
+    prog.start('Importing content to remote...');
+
+    let done = 0;
+    for (const asset of localAssets) {
+      d1InsertRow(root, dbName, '--remote', 'assets', asset);
+      done++;
+      prog.advance(done, `Importing... (${done}/${total})`);
+    }
+    for (const entry of localEntries) {
+      d1InsertRow(root, dbName, '--remote', 'entries', entry);
+      done++;
+      prog.advance(done, `Importing... (${done}/${total})`);
+    }
+    prog.stop(
+      `Synced ${localEntries.length} entries + ${localAssets.length} assets to remote`
+    );
   }
 
-  const filePath = resolve(root, inputFile);
-  if (!existsSync(filePath)) {
-    fail(`File not found: ${inputFile}`);
-    process.exit(1);
-  }
+  // ── Step 5: Upload media to remote ──
+  if (localAssets.length > 0) {
+    const cookie = await authenticate(remoteUrl, root);
+    const sProg = p.progress({ max: localAssets.length });
+    sProg.start('Uploading media to remote...');
 
-  const payload = JSON.parse(readFileSync(filePath, 'utf-8'));
-  if (payload.version !== 1) {
-    fail(`Unsupported export version: ${payload.version}`);
-    process.exit(1);
-  }
+    let uploaded = 0;
+    for (const asset of localAssets) {
+      const assetData =
+        typeof asset.data === 'string'
+          ? JSON.parse(asset.data)
+          : (asset.data as Record<string, string>);
+      const assetUrl = assetData.url ?? '';
+      const assetTitle = assetData.title ?? '';
+      const contentType = assetData.content_type ?? 'application/octet-stream';
+      const key = assetUrl.replace('/api/media/', '');
 
-  // 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';
+      try {
+        const dlRes = await fetch(`http://localhost:8787${assetUrl}`);
+        if (!dlRes.ok) {
+          uploaded++;
+          sProg.advance(uploaded);
+          continue;
+        }
 
-  const isRemote = process.argv.includes('--remote');
-  const target = isRemote ? '--remote' : '--local';
+        const blob = await dlRes.blob();
+        const formData = new FormData();
+        formData.append('file', new File([blob], key, { type: contentType }));
+        formData.append('title', assetTitle || key);
 
-  let totalEntries = 0;
+        const upRes = await fetch(`${remoteUrl}/api/admin/media`, {
+          method: 'POST',
+          headers: { Cookie: cookie },
+          body: formData
+        });
 
-  for (const [typeId, data] of Object.entries(
-    payload.contentTypes as Record<
-      string,
-      {
-        entries: Record<string, unknown>[];
-        joinTables: Record<string, Record<string, unknown>[]>;
+        if (!upRes.ok) {
+          warn(`Upload failed for ${assetTitle}: ${await upRes.text()}`);
+        }
+      } catch (e) {
+        warn(`Error uploading ${assetTitle}: ${e}`);
       }
-    >
-  )) {
-    log(
-      `Importing ${CYAN}${typeId}${RESET} (${data.entries.length} entries)...`
-    );
-
-    for (const entry of data.entries) {
-      const sql = buildInsertSql(typeId, entry);
-      run(
-        `bunx wrangler d1 execute ${dbName} ${target} --command "${wrapForShell(sql)}"`,
-        { cwd: root, silent: true }
+      uploaded++;
+      sProg.advance(
+        uploaded,
+        `Uploading media... (${uploaded}/${localAssets.length})`
       );
-      totalEntries++;
-    }
-
-    // Import join tables
-    for (const [jtName, rows] of Object.entries(data.joinTables)) {
-      for (const row of rows) {
-        const sql = buildInsertSql(jtName, row);
-        run(
-          `bunx wrangler d1 execute ${dbName} ${target} --command "${wrapForShell(sql)}"`,
-          { cwd: root, silent: true }
-        );
-      }
     }
+    sProg.stop(`Uploaded ${uploaded} media assets`);
   }
 
-  ok(
-    `Imported ${totalEntries} entries from ${CYAN}${basename(inputFile)}${RESET}`
-  );
-}
-
-// ── Shared auth helper ──────────────────────────────────────────────
+  // ── Step 6: Build + Deploy ──
+  const sBuild = p.spinner();
+  sBuild.start('Building admin dashboard...');
 
-async function authenticate(targetUrl: string, root: string): Promise<string> {
-  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);
-  }
-
-  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 kogumaRoot = findKogumaRoot();
+  const adminDir = resolve(kogumaRoot, 'admin');
+  if (existsSync(adminDir)) {
+    if (!existsSync(resolve(adminDir, 'node_modules'))) {
+      run('bun install', { cwd: adminDir });
+    }
+    run('bun run build', { cwd: adminDir });
+    const scriptPath = resolve(kogumaRoot, 'scripts/bundle-admin.ts');
+    run(`bun run ${scriptPath}`, { cwd: kogumaRoot });
   }
-  return cookieMatch[0];
-}
+  sBuild.stop('Admin bundle ready');
 
-function getRemoteUrl(): string {
-  const idx = process.argv.indexOf('--remote');
-  const url = idx >= 0 ? process.argv[idx + 1] : undefined;
-  if (!url || url.startsWith('-')) {
-    fail('Usage: koguma <command> --remote https://your-site.workers.dev');
-    process.exit(1);
-  }
-  return url.replace(/\/$/, '');
-}
+  const sDeploy = p.spinner();
+  sDeploy.start('Building frontend & deploying...');
+  run('bun run build', { cwd: root });
+  wranglerDeploy(root);
+  sDeploy.stop('Deployed to Cloudflare');
+
+  // ── Remind about production secret ──
+  p.log.warn(
+    `Make sure KOGUMA_SECRET is set on your Cloudflare Worker:\n` +
+      `  ${BRAND.DIM}bunx wrangler secret put KOGUMA_SECRET${BRAND.RESET}\n` +
+      `  ${BRAND.DIM}Without it, the admin login won't work in production.${BRAND.RESET}`
+  );
 
-function getDbName(root: string): string {
-  const toml = readFileSync(resolve(root, 'wrangler.toml'), 'utf-8');
-  const match = toml.match(/database_name\s*=\s*"([^"]+)"/);
-  return match?.[1] ?? 'my-db';
+  outro('Push complete! Remote now mirrors local. 🎉');
 }
 
-// ── Pull ────────────────────────────────────────────────────────────
-
-async function cmdPull() {
-  header('koguma pull');
+/**
+ * koguma pull — Download remote content.
+ *
+ * Exports remote D1 → imports to local → writes content/ files.
+ */
+async function cmdPull(): Promise<void> {
+  intro('pull');
   const root = findProjectRoot();
   const remoteUrl = getRemoteUrl();
-  const dbName = getDbName(root);
 
-  // 1. Migrate local schema
-  log('Step 1: Migrating local schema...');
-  // Re-use migrate logic inline (avoid process.argv mutation)
-  const configPath = resolve(root, '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 }
-      >;
-    }[];
-  };
+  preflight(root, { needsAuth: true, needsSecret: true });
 
-  // 2. Export remote content
-  log('\nStep 2: Exporting remote content...');
-  const exportData: Record<
-    string,
-    { entries: unknown[]; joinTables: Record<string, unknown[]> }
-  > = {};
+  const { dbName, bucketName } = getProjectNames(root);
 
-  for (const ct of config.contentTypes) {
-    try {
-      const output = runCapture(
-        `bunx wrangler d1 execute ${dbName} --remote --command "SELECT * FROM ${ct.id}" --json`,
-        root
-      );
-      const parsed = JSON.parse(output);
-      const entries = parsed?.[0]?.results ?? [];
+  // ── Step 1: Apply schema to local ──
+  const s1 = p.spinner();
+  s1.start('Applying schema to local...');
+  applySchema(root, dbName, '--local');
+  s1.stop('Local schema applied');
 
-      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(
-              `bunx wrangler d1 execute ${dbName} --remote --command "SELECT * FROM ${joinTable}" --json`,
-              root
-            );
-            const jtParsed = JSON.parse(jtOutput);
-            joinTables[joinTable] = jtParsed?.[0]?.results ?? [];
-          } catch {
-            // Join table may not exist
-          }
-        }
-      }
+  // ── Step 2: Export remote content ──
+  const s2 = p.spinner();
+  s2.start('Exporting remote content...');
 
-      exportData[ct.id] = { entries, joinTables };
-      ok(`${ct.id}: ${entries.length} entries`);
-    } catch {
-      warn(`Could not export ${ct.id} from remote`);
-    }
+  let remoteEntries: Record<string, unknown>[] = [];
+  try {
+    remoteEntries = d1Query(root, dbName, '--remote', 'SELECT * FROM entries');
+  } catch {
+    p.log.warn('Could not export entries from remote');
   }
 
-  // Also export _assets
   let remoteAssets: Record<string, unknown>[] = [];
   try {
-    const output = runCapture(
-      `bunx wrangler d1 execute ${dbName} --remote --command "SELECT * FROM _assets" --json`,
-      root
-    );
-    const parsed = JSON.parse(output);
-    remoteAssets = parsed?.[0]?.results ?? [];
-    ok(`_assets: ${remoteAssets.length} assets`);
+    remoteAssets = d1Query(root, dbName, '--remote', 'SELECT * FROM assets');
   } catch {
-    warn('Could not export _assets from remote');
-  }
-
-  // 3. Import content into local
-  log('\nStep 3: Importing content to local...');
-
-  // Import _assets first
-  for (const asset of remoteAssets) {
-    const sql = buildInsertSql('_assets', asset);
-    run(
-      `bunx wrangler d1 execute ${dbName} --local --command "${wrapForShell(sql)}"`,
-      { cwd: root, silent: true }
-    );
+    p.log.warn('Could not export assets from remote');
   }
+  s2.stop(
+    `Found ${remoteEntries.length} entries + ${remoteAssets.length} assets`
+  );
 
-  // Import content types
-  for (const [typeId, data] of Object.entries(exportData)) {
-    for (const entry of data.entries as Record<string, unknown>[]) {
-      const sql = buildInsertSql(typeId, entry);
-      run(
-        `bunx wrangler d1 execute ${dbName} --local --command "${wrapForShell(sql)}"`,
-        { cwd: root, silent: true }
-      );
+  // ── Step 3: Import to local ──
+  const total = remoteEntries.length + remoteAssets.length;
+  if (total > 0) {
+    const prog = p.progress({ max: total });
+    prog.start('Importing to local D1...');
+
+    let done = 0;
+    for (const asset of remoteAssets) {
+      d1InsertRow(root, dbName, '--local', 'assets', asset);
+      done++;
+      prog.advance(done, `Importing... (${done}/${total})`);
     }
-    for (const [jtName, rows] of Object.entries(data.joinTables)) {
-      for (const row of rows as Record<string, unknown>[]) {
-        const sql = buildInsertSql(jtName, row);
-        run(
-          `bunx wrangler d1 execute ${dbName} --local --command "${wrapForShell(sql)}"`,
-          { cwd: root, silent: true }
-        );
-      }
+    for (const entry of remoteEntries) {
+      d1InsertRow(root, dbName, '--local', 'entries', entry);
+      done++;
+      prog.advance(done, `Importing... (${done}/${total})`);
     }
+    prog.stop(
+      `Imported ${remoteEntries.length} entries + ${remoteAssets.length} assets to local`
+    );
   }
 
-  // 4. Download R2 media
-  log('\nStep 4: Downloading remote media...');
+  // ── Step 4: Download R2 media ──
   const cookie = await authenticate(remoteUrl, root);
 
   const mediaRes = await fetch(`${remoteUrl}/api/admin/media`, {
     headers: { Cookie: cookie }
   });
+
   if (!mediaRes.ok) {
-    warn('Could not list remote media');
+    p.log.warn('Could not list remote media');
   } else {
     const { assets } = (await mediaRes.json()) as {
       assets: { id: string; url: string; title: string }[];
     };
-    log(`Found ${assets.length} remote assets`);
 
-    const bucketMatch = readFileSync(
-      resolve(root, 'wrangler.toml'),
-      'utf-8'
-    ).match(/bucket_name\s*=\s*"([^"]+)"/);
-    const bucketName = bucketMatch?.[1] ?? 'media';
+    if (assets.length > 0) {
+      const prog = p.progress({ max: assets.length });
+      prog.start('Downloading remote media...');
 
-    for (const asset of assets) {
-      const key = asset.url.replace('/api/media/', '');
-      log(`⬇ ${asset.title}`);
-      try {
-        const dlRes = await fetch(`${remoteUrl}${asset.url}`);
-        if (!dlRes.ok) {
-          warn(`  Download failed: ${dlRes.status}`);
-          continue;
-        }
-        const buf = Buffer.from(await dlRes.arrayBuffer());
-        const tmpPath = resolve(root, `db/.media-tmp-${key}`);
-        writeFileSync(tmpPath, buf);
-        run(
-          `bunx wrangler r2 object put ${bucketName}/${key} --file=${tmpPath} --local`,
-          { cwd: root, silent: true }
-        );
-        // Clean up temp file
+      let downloaded = 0;
+      for (const asset of assets) {
+        const key = asset.url.replace('/api/media/', '');
         try {
-          const { unlinkSync } = await import('fs');
-          unlinkSync(tmpPath);
-        } catch {
-          /* ignore */
+          const dlRes = await fetch(`${remoteUrl}${asset.url}`);
+          if (!dlRes.ok) {
+            downloaded++;
+            prog.advance(downloaded);
+            continue;
+          }
+          const buf = Buffer.from(await dlRes.arrayBuffer());
+          const tmpPath = resolve(root, DB_DIR, `.media-tmp-${key}`);
+          writeFileSync(tmpPath, buf);
+          r2PutLocal(root, bucketName, key, tmpPath);
+          try {
+            const { unlinkSync } = await import('fs');
+            unlinkSync(tmpPath);
+          } catch {
+            /* ignore cleanup failure */
+          }
+        } catch (e) {
+          warn(`Error downloading ${asset.title}: ${e}`);
         }
-        ok(`  → local R2`);
-      } catch (e) {
-        warn(`  Error: ${e}`);
+        downloaded++;
+        prog.advance(
+          downloaded,
+          `Downloading... (${downloaded}/${assets.length})`
+        );
       }
+      prog.stop(`Downloaded ${assets.length} media assets`);
     }
   }
 
-  ok('Pull complete! Local now mirrors remote.');
-}
-
-// ── Push ────────────────────────────────────────────────────────────
-
-async function cmdPush() {
-  header('koguma push');
-  const root = findProjectRoot();
-  const remoteUrl = getRemoteUrl();
-  const dbName = getDbName(root);
-
-  // 1. Migrate remote schema
-  log('Step 1: Migrating remote schema...');
-  const configPath = resolve(root, '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 }
-      >;
-    }[];
-  };
-
-  // Run migrate --remote
-  const existingColumns: Record<string, { name: string; type: string }[]> = {};
-  for (const ct of config.contentTypes) {
-    try {
-      const output = runCapture(
-        `bunx wrangler d1 execute ${dbName} --remote --command "SELECT name, type FROM pragma_table_info('${ct.id}')" --json`,
-        root
+  // ── Step 5: Write content/ files ──
+  const s5 = p.spinner();
+  s5.start('Writing content/ files...');
+  try {
+    const configPath = resolve(root, SITE_CONFIG_FILE);
+    if (existsSync(configPath)) {
+      const config = await loadSiteConfig(root);
+      const contentDir = resolve(root, CONTENT_DIR);
+      const count = writeContentDir(
+        contentDir,
+        remoteEntries,
+        config.contentTypes
       );
-      const parsed = JSON.parse(output);
-      existingColumns[ct.id] = parsed?.[0]?.results ?? [];
-    } catch {
-      warn(`Table '${ct.id}' does not exist on remote — will create it.`);
-      existingColumns[ct.id] = [];
+      s5.stop(`Wrote ${count} content files to content/`);
+    } else {
+      s5.stop(`${SITE_CONFIG_FILE} not found — skipped content/ generation`);
     }
+  } catch (e) {
+    s5.stop('Content file generation failed');
+    p.log.warn(`${e}`);
   }
 
-  const { detectDrift } = await import('../src/db/migrate.ts');
-  const driftResult = detectDrift(config.contentTypes as any, existingColumns);
+  outro('Pull complete! Local now mirrors remote. 🐻');
+}
 
-  if (driftResult.sql.length > 0) {
-    const sqlFile = resolve(root, 'db/migration.sql');
-    writeFileSync(sqlFile, driftResult.sql.join('\n'));
-    run(`bunx wrangler d1 execute ${dbName} --remote --file=${sqlFile}`, {
-      cwd: root
-    });
-    ok('Remote schema migrated');
-  } else {
-    ok('Remote schema is up to date');
-  }
+/**
+ * koguma gen-types — One-shot type generation.
+ *
+ * Generates koguma.d.ts from site.config.ts without starting a dev server.
+ */
+async function cmdGenTypes(): Promise<void> {
+  intro('gen-types');
+  const root = findProjectRoot();
 
-  // 2. Export local content
-  log('\nStep 2: Exporting local content...');
-  const exportData: Record<
-    string,
-    { entries: unknown[]; joinTables: Record<string, unknown[]> }
-  > = {};
+  preflight(root, { needsSiteConfig: true });
 
-  for (const ct of config.contentTypes) {
-    try {
-      const output = runCapture(
-        `bunx wrangler d1 execute ${dbName} --local --command "SELECT * FROM ${ct.id}" --json`,
-        root
-      );
-      const parsed = JSON.parse(output);
-      const entries = parsed?.[0]?.results ?? [];
+  const s = p.spinner();
+  s.start('Generating types from site.config.ts...');
+  await runTypegen(root);
+  s.stop('koguma.d.ts generated');
 
-      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(
-              `bunx wrangler d1 execute ${dbName} --local --command "SELECT * FROM ${joinTable}" --json`,
-              root
-            );
-            const jtParsed = JSON.parse(jtOutput);
-            joinTables[joinTable] = jtParsed?.[0]?.results ?? [];
-          } catch {
-            /* */
-          }
-        }
-      }
+  outro('Types are up to date. 🐻');
+}
 
-      exportData[ct.id] = { entries, joinTables };
-      ok(`${ct.id}: ${entries.length} entries`);
-    } catch {
-      warn(`Could not export ${ct.id} from local`);
-    }
-  }
+/**
+ * koguma tidy — Sync content/ structure with config.
+ *
+ * Creates missing dirs, updates _example files, orphans removed types.
+ * With --dry flag, shows what would happen without making changes.
+ */
+async function cmdTidy(): Promise<void> {
+  const dryRun = process.argv.includes('--dry');
+  intro(dryRun ? 'tidy --dry' : 'tidy');
+  const root = findProjectRoot();
 
-  // Also export _assets
-  let localAssets: Record<string, unknown>[] = [];
-  try {
-    const output = runCapture(
-      `bunx wrangler d1 execute ${dbName} --local --command "SELECT * FROM _assets" --json`,
-      root
-    );
-    const parsed = JSON.parse(output);
-    localAssets = parsed?.[0]?.results ?? [];
-    ok(`_assets: ${localAssets.length} assets`);
-  } catch {
-    warn('Could not export _assets from local');
-  }
+  preflight(root, { needsSiteConfig: true });
 
-  // 3. Import content to remote
-  log('\nStep 3: Importing content to remote...');
+  const config = await loadSiteConfig(root);
 
-  // Import _assets first
-  for (const asset of localAssets) {
-    const sql = buildInsertSql('_assets', asset);
-    run(
-      `bunx wrangler d1 execute ${dbName} --remote --command "${wrapForShell(sql)}"`,
-      { cwd: root, silent: true }
-    );
+  if (dryRun) {
+    p.log.info('Dry run — no changes will be made.');
   }
 
-  // Import content types
-  for (const [typeId, data] of Object.entries(exportData)) {
-    for (const entry of data.entries as Record<string, unknown>[]) {
-      const sql = buildInsertSql(typeId, entry);
-      run(
-        `bunx wrangler d1 execute ${dbName} --remote --command "${wrapForShell(sql)}"`,
-        { cwd: root, silent: true }
-      );
-    }
-    for (const [jtName, rows] of Object.entries(data.joinTables)) {
-      for (const row of rows as Record<string, unknown>[]) {
-        const sql = buildInsertSql(jtName, row);
-        run(
-          `bunx wrangler d1 execute ${dbName} --remote --command "${wrapForShell(sql)}"`,
-          { cwd: root, silent: true }
-        );
+  // Run config-drift sync
+  const s = p.spinner();
+  s.start('Checking content/ directories...');
+  const actions = syncContentDirsWithConfig(root, config.contentTypes, dryRun);
+  s.stop('Directory check complete');
+
+  if (dryRun) {
+    if (actions.length === 0) {
+      p.log.success('Content directories are in sync with config.');
+    } else {
+      p.log.step('Planned actions:');
+      for (const action of actions) {
+        const detail = action.detail ? ` (${action.detail})` : '';
+        switch (action.type) {
+          case 'create_dir':
+          case 'create_example':
+            p.log.success(`+ ${action.path}`);
+            break;
+          case 'update_example':
+            p.log.info(`~ ${action.path}`);
+            break;
+          case 'delete_dir':
+            p.log.error(`- ${action.path}${detail}`);
+            break;
+          case 'orphan_dir':
+            p.log.warn(`→ ${action.path}${detail}`);
+            break;
+          case 'restore_dir':
+            p.log.success(`← ${action.path}${detail}`);
+            break;
+        }
       }
     }
+  } else if (actions.length === 0) {
+    p.log.success('Content directories already in sync.');
   }
 
-  // 4. Upload local media to remote
-  log('\nStep 4: Uploading local media to remote...');
-  const cookie = await authenticate(remoteUrl, root);
-
-  for (const asset of localAssets as {
-    id: string;
-    url: string;
-    title: string;
-    content_type: string;
-  }[]) {
-    const key = (asset.url as string).replace('/api/media/', '');
-    log(`⬆ ${asset.title}`);
-    try {
-      // Download from local wrangler dev
-      const dlRes = await fetch(`http://localhost:8787${asset.url}`);
-      if (!dlRes.ok) {
-        warn(`  Local download failed: ${dlRes.status}`);
-        continue;
-      }
-
-      const blob = await dlRes.blob();
-      const fileName = key;
-      const formData = new FormData();
-      formData.append(
-        'file',
-        new File([blob], fileName, {
-          type: asset.content_type ?? 'application/octet-stream'
-        })
-      );
-      formData.append('title', asset.title ?? fileName);
-
-      const upRes = await fetch(`${remoteUrl}/api/admin/media`, {
-        method: 'POST',
-        headers: { Cookie: cookie },
-        body: formData
-      });
-
-      if (!upRes.ok) {
-        warn(`  Upload failed: ${await upRes.text()}`);
-        continue;
-      }
-      ok(`  → remote R2`);
-    } catch (e) {
-      warn(`  Error: ${e}`);
+  // Run validation
+  const contentDir = resolve(root, CONTENT_DIR);
+  const warnings = validateContent(contentDir, config.contentTypes);
+  if (warnings.length === 0) {
+    p.log.success('No validation warnings.');
+  } else {
+    p.log.step('Validation warnings:');
+    for (const w of warnings) {
+      p.log.warn(`${w.file}: ${w.message}`);
     }
   }
 
-  // 5. Deploy
-  log('\nStep 5: Deploying...');
-  await cmdDeploy();
-
-  ok('Push complete! Remote now mirrors local.');
-}
-
-// ── Wrangler wrappers ───────────────────────────────────────────────
-
-function cmdDev() {
-  const root = findProjectRoot();
-  const extra = process.argv.slice(3).join(' ');
-  run(`bunx wrangler dev ${extra}`.trim(), { cwd: root });
-}
-
-function cmdLogin() {
-  run('bunx wrangler login');
-}
+  // Exit code for CI
+  if (dryRun && (actions.length > 0 || warnings.length > 0)) {
+    process.exit(1);
+  }
 
-function cmdTail() {
-  const root = findProjectRoot();
-  const extra = process.argv.slice(3).join(' ');
-  run(`bunx wrangler tail ${extra}`.trim(), { cwd: root });
+  outro(dryRun ? 'Dry run complete.' : 'Tidy complete. 🐻');
 }
 
 // ── Help ────────────────────────────────────────────────────────────
 
-function cmdHelp() {
-  console.log(`
-${BOLD}🐻 Koguma CLI${RESET} ${DIM}v0.6.0${RESET}
-
-${BOLD}Usage:${RESET} koguma <command>
-
-${BOLD}Development:${RESET}
-  ${CYAN}dev${RESET}             Start local dev server (wrangler dev)
-  ${CYAN}login${RESET}           Authenticate with Cloudflare
-  ${CYAN}tail${RESET}            Stream live logs from production
-
-${BOLD}Schema & Types:${RESET}
-  ${CYAN}schema${RESET}          Generate DDL from site.config.ts → db/schema.sql
-  ${CYAN}typegen${RESET}         Generate koguma.d.ts typed interfaces
-  ${CYAN}migrate${RESET}         Detect schema drift, apply CREATE/ALTER TABLE
-
-${BOLD}Content:${RESET}
-  ${CYAN}seed${RESET}            Seed database from db/seed.ts or db/seed.sql
-  ${CYAN}export${RESET}          Export all content to JSON
-  ${CYAN}import${RESET}          Import content from JSON file
-
-${BOLD}Media:${RESET}
-  ${CYAN}migrate-media${RESET}   Download external images and upload to R2
-
-${BOLD}Sync:${RESET}
-  ${CYAN}pull${RESET}            Download remote content + media → local
-  ${CYAN}push${RESET}            Upload local content + media → remote + deploy
-
-${BOLD}Deploy:${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}deploy${RESET}          Build admin + frontend, then deploy via wrangler
-
-${BOLD}Examples:${RESET}
-  ${DIM}$${RESET} koguma dev                                    ${DIM}# Local dev server${RESET}
-  ${DIM}$${RESET} koguma migrate --remote                       ${DIM}# Migrate production DB${RESET}
-  ${DIM}$${RESET} koguma pull --remote https://my-site.dev       ${DIM}# Sync remote → local${RESET}
-  ${DIM}$${RESET} koguma push --remote https://my-site.dev       ${DIM}# Sync local → remote${RESET}
-  ${DIM}$${RESET} koguma seed --remote                           ${DIM}# Seed production DB${RESET}
-`);
+function cmdHelp(): void {
+  intro();
+
+  p.note(
+    [
+      `${BRAND.ACCENT}init${BRAND.RESET}            Set up a new project ${BRAND.DIM}(scaffold, login, D1, R2, secret)${BRAND.RESET}`,
+      `${BRAND.ACCENT}dev${BRAND.RESET}             Start local dev server ${BRAND.DIM}with auto-sync + typegen${BRAND.RESET}`,
+      `${BRAND.ACCENT}push${BRAND.RESET}            Build, deploy, and sync content to remote`,
+      `${BRAND.ACCENT}pull${BRAND.RESET}            Download remote content + media to local`,
+      `${BRAND.ACCENT}gen-types${BRAND.RESET}       Generate ${BRAND.DIM}koguma.d.ts${BRAND.RESET} typed interfaces`,
+      `${BRAND.ACCENT}tidy${BRAND.RESET}            Sync content/ dirs with config + validate`,
+      `${BRAND.ACCENT}tidy --dry${BRAND.RESET}      Preview tidy changes without writing`
+    ].join('\n'),
+    'Commands'
+  );
+
+  p.note(
+    [
+      `${BRAND.DIM}$${BRAND.RESET} koguma init`,
+      `${BRAND.DIM}$${BRAND.RESET} koguma dev`,
+      `${BRAND.DIM}$${BRAND.RESET} koguma push --remote https://my-site.dev`,
+      `${BRAND.DIM}$${BRAND.RESET} koguma pull --remote https://my-site.dev`,
+      `${BRAND.DIM}$${BRAND.RESET} koguma gen-types`,
+      `${BRAND.DIM}$${BRAND.RESET} koguma tidy --dry`
+    ].join('\n'),
+    'Examples'
+  );
 }
 
 // ── Dispatch ────────────────────────────────────────────────────────
@@ -1715,50 +979,20 @@ 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 'schema':
-    await cmdSchema();
-    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 'pull':
-    await cmdPull();
+  case 'dev':
+    await cmdDev();
     break;
   case 'push':
     await cmdPush();
     break;
-  case 'dev':
-    cmdDev();
+  case 'pull':
+    await cmdPull();
     break;
-  case 'login':
-    cmdLogin();
+  case 'gen-types':
+    await cmdGenTypes();
     break;
-  case 'tail':
-    cmdTail();
+  case 'tidy':
+    await cmdTidy();
     break;
   case 'help':
   case '--help':
@@ -1767,7 +1001,7 @@ switch (command) {
     cmdHelp();
     break;
   default:
-    fail(`Unknown command: ${command}`);
+    p.log.error(`Unknown command: ${command}`);
     cmdHelp();
     process.exit(1);
 }