koguma 0.6.4 → 0.6.6

package/cli/index.ts

@@ -17,6 +17,13 @@ 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 {
+  buildInsertSql,
+  wrapForShell,
+  buildAssetIndex,
+  processSeedEntry,
+  buildImportSql
+} from '../src/db/sql.ts';
 
 // ── Helpers ─────────────────────────────────────────────────────────
 
@@ -472,13 +479,9 @@ async function cmdBuild() {
 async function cmdSeed() {
   header('koguma seed');
   const root = findProjectRoot();
+  const seedTs = resolve(root, 'db/seed.ts');
   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*"([^"]+)"/);
@@ -487,14 +490,97 @@ async function cmdSeed() {
   const isRemote = process.argv.includes('--remote');
   const target = isRemote ? '--remote' : '--local';
 
-  log(
-    `Seeding ${isRemote ? 'REMOTE' : 'local'} database: ${CYAN}${dbName}${RESET}`
-  );
-  run(`bunx wrangler d1 execute ${dbName} ${target} --file=${seedSql}`, {
-    cwd: root
-  });
+  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 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
+      );
+      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');
+    }
+
+    // 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;
+      }
+
+      log(`Seeding ${CYAN}${typeId}${RESET} (${entries.length} entries)...`);
 
-  ok(`Database seeded (${isRemote ? 'remote' : 'local'})!`);
+      for (const entry of entries) {
+        const { processed, resolutions } = processSeedEntry(
+          entry,
+          ct.fieldMeta,
+          assetIndex,
+          markdownToKoguma,
+          kogumaToLexical
+        );
+
+        for (const r of resolutions) {
+          ok(`  ${r}`);
+        }
+
+        const sql = buildInsertSql(typeId, processed);
+        run(
+          `bunx wrangler d1 execute ${dbName} ${target} --command "${wrapForShell(sql)}"`,
+          { cwd: root, silent: true }
+        );
+        totalEntries++;
+      }
+    }
+
+    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);
+  }
 }
 
 async function cmdDeploy() {
@@ -672,9 +758,9 @@ function fieldTypeToTs(
     case 'date':
       return 'string';
     case 'richText':
-      return 'Record<string, unknown>';
+      return 'KogumaDocument';
     case 'image':
-      return '{ id: string; url: string; title?: string; width?: number; height?: number }';
+      return 'KogumaAsset';
     case 'boolean':
       return 'boolean';
     case 'number':
@@ -689,6 +775,14 @@ function fieldTypeToTs(
       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';
   }
@@ -739,6 +833,8 @@ async function cmdTypegen() {
     ' * Do not edit manually.',
     ' */',
     '',
+    'import type { KogumaDocument, KogumaAsset } from "koguma/types";',
+    '',
     '// ── System fields ── common to all entries',
     'interface KogumaSystemFields {',
     '  id: string;',
@@ -856,7 +952,8 @@ async function cmdMigrate() {
       const results = parsed?.[0]?.results ?? [];
       existingColumns[ct.id] = results;
     } catch {
-      warn(`Table '${ct.id}' does not exist yet.`);
+      warn(`Table '${ct.id}' does not exist yet — will create it.`);
+      existingColumns[ct.id] = [];
     }
   }
 
@@ -1119,16 +1216,9 @@ async function cmdImport() {
     );
 
     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(', ')})`;
+      const sql = buildInsertSql(typeId, entry);
       run(
-        `bunx wrangler d1 execute ${dbName} ${target} --command "${sql.replace(/"/g, '\\"')}"`,
+        `bunx wrangler d1 execute ${dbName} ${target} --command "${wrapForShell(sql)}"`,
         { cwd: root, silent: true }
       );
       totalEntries++;
@@ -1137,16 +1227,9 @@ async function cmdImport() {
     // 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(', ')})`;
+        const sql = buildInsertSql(jtName, row);
         run(
-          `bunx wrangler d1 execute ${dbName} ${target} --command "${sql.replace(/"/g, '\\"')}"`,
+          `bunx wrangler d1 execute ${dbName} ${target} --command "${wrapForShell(sql)}"`,
           { cwd: root, silent: true }
         );
       }
@@ -1158,37 +1241,469 @@ async function cmdImport() {
   );
 }
 
+// ── Shared auth helper ──────────────────────────────────────────────
+
+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);
+  }
+  return cookieMatch[0];
+}
+
+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(/\/$/, '');
+}
+
+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';
+}
+
+// ── Pull ────────────────────────────────────────────────────────────
+
+async function cmdPull() {
+  header('koguma 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 }
+      >;
+    }[];
+  };
+
+  // 2. Export remote content
+  log('\nStep 2: Exporting remote content...');
+  const exportData: Record<
+    string,
+    { entries: unknown[]; joinTables: Record<string, unknown[]> }
+  > = {};
+
+  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 ?? [];
+
+      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
+          }
+        }
+      }
+
+      exportData[ct.id] = { entries, joinTables };
+      ok(`${ct.id}: ${entries.length} entries`);
+    } catch {
+      warn(`Could not export ${ct.id} 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`);
+  } 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 }
+    );
+  }
+
+  // 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 }
+      );
+    }
+    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 }
+        );
+      }
+    }
+  }
+
+  // 4. Download R2 media
+  log('\nStep 4: Downloading remote 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');
+  } 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';
+
+    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
+        try {
+          const { unlinkSync } = await import('fs');
+          unlinkSync(tmpPath);
+        } catch {
+          /* ignore */
+        }
+        ok(`  → local R2`);
+      } catch (e) {
+        warn(`  Error: ${e}`);
+      }
+    }
+  }
+
+  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
+      );
+      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] = [];
+    }
+  }
+
+  const { detectDrift } = await import('../src/db/migrate.ts');
+  const driftResult = detectDrift(config.contentTypes as any, existingColumns);
+
+  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');
+  }
+
+  // 2. Export local content
+  log('\nStep 2: Exporting local content...');
+  const exportData: Record<
+    string,
+    { entries: unknown[]; joinTables: Record<string, unknown[]> }
+  > = {};
+
+  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 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 {
+            /* */
+          }
+        }
+      }
+
+      exportData[ct.id] = { entries, joinTables };
+      ok(`${ct.id}: ${entries.length} entries`);
+    } catch {
+      warn(`Could not export ${ct.id} from local`);
+    }
+  }
+
+  // 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');
+  }
+
+  // 3. Import content to remote
+  log('\nStep 3: Importing content to remote...');
+
+  // 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 }
+    );
+  }
+
+  // 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 }
+        );
+      }
+    }
+  }
+
+  // 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}`);
+    }
+  }
+
+  // 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');
+}
+
+function cmdTail() {
+  const root = findProjectRoot();
+  const extra = process.argv.slice(3).join(' ');
+  run(`bunx wrangler tail ${extra}`.trim(), { cwd: root });
+}
+
+// ── Help ────────────────────────────────────────────────────────────
+
 function cmdHelp() {
   console.log(`
-${BOLD}🐻 Koguma CLI${RESET} ${DIM}v0.5.0${RESET}
+${BOLD}🐻 Koguma CLI${RESET} ${DIM}v0.6.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}schema${RESET}          Generate correct DDL from site.config.ts → db/schema.sql
+${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 and apply ALTER TABLE changes
+  ${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
-  ${CYAN}migrate-media${RESET}   Download images and upload to R2
+
+${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}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}
+${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}
 `);
 }
 
@@ -1230,6 +1745,21 @@ switch (command) {
   case 'deploy':
     await cmdDeploy();
     break;
+  case 'pull':
+    await cmdPull();
+    break;
+  case 'push':
+    await cmdPush();
+    break;
+  case 'dev':
+    cmdDev();
+    break;
+  case 'login':
+    cmdLogin();
+    break;
+  case 'tail':
+    cmdTail();
+    break;
   case 'help':
   case '--help':
   case '-h':