koguma 0.6.6 → 2.0.0

package/cli/typegen.ts

@@ -0,0 +1,190 @@
+/**
+ * cli/typegen.ts — Generate koguma.d.ts from site.config.ts.
+ *
+ * Pure logic: reads config → produces type declarations string.
+ * The file I/O is handled by the caller.
+ */
+
+import { existsSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { ok, fail, log, ANSI } from './log.ts';
+import { SITE_CONFIG_FILE, TYPEGEN_OUTPUT } from './constants.ts';
+
+// ── TypeScript type mapping ────────────────────────────────────────
+
+interface FieldMeta {
+  fieldType: string;
+  required: boolean;
+  refContentType?: string;
+  options?: string[];
+}
+
+const SIMPLE_STRING_TYPES = new Set([
+  'text',
+  'longText',
+  'url',
+  'date',
+  'markdown',
+  'youtube',
+  'instagram',
+  'email',
+  'phone',
+  'color'
+]);
+
+/**
+ * Map a Koguma field type to its TypeScript representation.
+ */
+export function fieldTypeToTs(fieldType: string, meta: FieldMeta): string {
+  if (SIMPLE_STRING_TYPES.has(fieldType)) return 'string';
+
+  switch (fieldType) {
+    case 'image':
+      return 'KogumaAsset';
+    case 'images':
+      return 'string[]';
+    case 'boolean':
+      return 'boolean';
+    case 'number':
+      return 'number';
+    case 'select':
+      return meta.options?.map(o => `'${o}'`).join(' | ') ?? 'string';
+    case 'reference':
+      return meta.refContentType
+        ? `${capitalize(meta.refContentType)}Entry`
+        : 'Record<string, unknown>';
+    case 'references':
+      return meta.refContentType
+        ? `${capitalize(meta.refContentType)}Entry[]`
+        : 'Record<string, unknown>[]';
+    default:
+      return 'unknown';
+  }
+}
+
+export function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// ── Type declaration generation ────────────────────────────────────
+
+interface ContentTypeConfig {
+  id: string;
+  name: string;
+  fieldMeta: Record<string, FieldMeta>;
+}
+
+/**
+ * Generate the full koguma.d.ts content string from content type configs.
+ */
+export function generateTypeDeclarations(
+  contentTypes: ContentTypeConfig[]
+): string {
+  const lines: string[] = [
+    '/**',
+    ' * Auto-generated by `koguma gen-types`',
+    ' * Do not edit manually.',
+    ' */',
+    '',
+    'import type { 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;',
+    '}',
+    ''
+  ];
+
+  const typeNames: string[] = [];
+
+  for (const ct of contentTypes) {
+    const typeName = capitalize(ct.id) + 'Entry';
+    typeNames.push(typeName);
+
+    lines.push(`// ── ${ct.name} ──`);
+    lines.push(`export interface ${typeName} extends KogumaSystemFields {`);
+
+    for (const [fieldId, meta] of Object.entries(ct.fieldMeta)) {
+      const tsType = fieldTypeToTs(meta.fieldType, meta);
+      const optional = meta.required ? '' : '?';
+      lines.push(`  ${fieldId}${optional}: ${tsType};`);
+    }
+
+    lines.push('}');
+    lines.push('');
+  }
+
+  // Client interface
+  lines.push('// ── Koguma Client ──');
+  lines.push('export interface KogumaClient {');
+
+  for (const ct of contentTypes) {
+    const typeName = capitalize(ct.id) + 'Entry';
+    lines.push(`  /** ${ct.name} */`);
+    lines.push(`  get(type: '${ct.id}', id: string): Promise<${typeName}>;`);
+    lines.push(
+      `  list(type: '${ct.id}'): Promise<{ entries: ${typeName}[] }>;`
+    );
+    lines.push(
+      `  create(type: '${ct.id}', data: Partial<${typeName}>): Promise<${typeName}>;`
+    );
+    lines.push(
+      `  update(type: '${ct.id}', id: string, data: Partial<${typeName}>): Promise<${typeName}>;`
+    );
+    lines.push(`  delete(type: '${ct.id}', id: string): Promise<void>;`);
+  }
+
+  lines.push('}');
+  lines.push('');
+
+  // Content type union
+  lines.push(
+    `export type ContentType = ${contentTypes.map(ct => `'${ct.id}'`).join(' | ')};`
+  );
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ── CLI command ────────────────────────────────────────────────────
+
+/**
+ * Load site.config.ts and write koguma.d.ts.
+ */
+export async function runTypegen(
+  root: string,
+  opts?: { silent?: boolean }
+): Promise<string[]> {
+  const configPath = resolve(root, SITE_CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    fail(`${SITE_CONFIG_FILE} not found in project root.`);
+    process.exit(1);
+  }
+
+  if (!opts?.silent) log(`Reading ${SITE_CONFIG_FILE}...`);
+  const configModule = await import(configPath);
+  const config = configModule.default as {
+    contentTypes: ContentTypeConfig[];
+  };
+
+  if (!config.contentTypes?.length) {
+    fail(`No content types found in ${SITE_CONFIG_FILE}`);
+    process.exit(1);
+  }
+
+  const output = generateTypeDeclarations(config.contentTypes);
+  const outPath = resolve(root, TYPEGEN_OUTPUT);
+  writeFileSync(outPath, output);
+
+  const typeNames = config.contentTypes.map(ct => capitalize(ct.id) + 'Entry');
+  if (!opts?.silent) {
+    ok(
+      `Generated ${ANSI.CYAN}${TYPEGEN_OUTPUT}${ANSI.RESET} with ${typeNames.length} type(s): ${typeNames.join(', ')}`
+    );
+  }
+  return typeNames;
+}

package/cli/ui.ts

@@ -0,0 +1,55 @@
+/**
+ * cli/ui.ts — Brand colors and Clack wrappers for Koguma CLI.
+ *
+ * Provides Koguma-branded intro/outro and color constants derived
+ * from the admin dashboard theme (theme-override.css).
+ */
+
+import * as p from '@clack/prompts';
+import { CLI_VERSION } from './constants.ts';
+
+// ── Brand colors (24-bit ANSI) ─────────────────────────────────────
+//
+// Teal:  #2dd4bf → RGB(45,212,191)   primary/headings
+// Red:   #ff4d4d → RGB(255,77,77)    accent/errors
+// Text:  #0f172a → RGB(15,23,42)     dark slate
+
+export const BRAND = {
+  /** Teal primary (RGB 45,212,191) — #2dd4bf */
+  PRIMARY: '\x1b[38;2;45;212;191m',
+  /** Red accent (RGB 255,77,77) — #ff4d4d */
+  ACCENT: '\x1b[38;2;255;77;77m',
+  /** Dim slate (RGB 113,124,149) */
+  DIM: '\x1b[38;2;113;124;149m',
+  /** Bold */
+  BOLD: '\x1b[1m',
+  /** Reset */
+  RESET: '\x1b[0m'
+} as const;
+
+// ── Branded Clack wrappers ─────────────────────────────────────────
+
+/** Show a branded intro banner. */
+export function intro(command?: string): void {
+  const label = command
+    ? `${BRAND.PRIMARY}${BRAND.BOLD}🐻 koguma ${command}${BRAND.RESET} ${BRAND.DIM}${CLI_VERSION}${BRAND.RESET}`
+    : `${BRAND.PRIMARY}${BRAND.BOLD}🐻 koguma${BRAND.RESET} ${BRAND.DIM}${CLI_VERSION}${BRAND.RESET}`;
+  p.intro(label);
+}
+
+/** Show a branded outro message. */
+export function outro(message: string): void {
+  p.outro(`${BRAND.PRIMARY}${message}${BRAND.RESET}`);
+}
+
+/** Handle Clack cancellation — show message and exit. */
+export function handleCancel(value: unknown): value is symbol {
+  if (p.isCancel(value)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+  return false;
+}
+
+// Re-export Clack for convenience
+export { p };

package/cli/wrangler.ts

@@ -0,0 +1,367 @@
+/**
+ * cli/wrangler.ts — Wrangler command wrappers.
+ *
+ * Provides typed helpers for D1 and R2 operations, centralizing
+ * the --config flag, --local/--remote targeting, and JSON parsing.
+ */
+
+import { existsSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve } from 'path';
+import { INIT_SQL } from '../src/db/init.ts';
+import { buildInsertSql, wrapForShell } from '../src/db/sql.ts';
+import { ensureWranglerConfig } from './config.ts';
+import { run, runCapture, runAsync } from './exec.ts';
+import { ok, warn, fail, log } from './log.ts';
+import { DB_DIR, MIGRATION_FILE } from './constants.ts';
+
+// ── Preflight checks ───────────────────────────────────────────────
+
+/**
+ * Verify that `wrangler` can authenticate with Cloudflare.
+ * Gives a clear, actionable error message if not logged in.
+ */
+export function checkWranglerAuth(root: string): void {
+  try {
+    runCapture('bunx wrangler whoami', root);
+  } catch {
+    fail(
+      "Not logged in to Cloudflare. Run 'bunx wrangler login' first, " +
+        "or run 'koguma init' which handles login for you."
+    );
+    process.exit(1);
+  }
+}
+
+// ── Config-aware wrangler execution ────────────────────────────────
+
+/**
+ * Build the --config flag string. Writes .wrangler.toml if needed.
+ */
+function configFlag(root: string): string {
+  const configPath = ensureWranglerConfig(root);
+  return `--config ${configPath}`;
+}
+
+// ── D1 operations ──────────────────────────────────────────────────
+
+export type D1Target = '--local' | '--remote';
+
+/**
+ * Execute a SQL command against D1.
+ */
+export function d1Execute(
+  root: string,
+  dbName: string,
+  target: D1Target,
+  command: string
+): void {
+  run(
+    `bunx wrangler d1 execute ${dbName} ${target} ${configFlag(root)} --command "${wrapForShell(command)}"`,
+    { cwd: root, silent: true }
+  );
+}
+
+/**
+ * Execute a SQL file against D1.
+ */
+export function d1ExecuteFile(
+  root: string,
+  dbName: string,
+  target: D1Target,
+  filePath: string
+): void {
+  run(
+    `bunx wrangler d1 execute ${dbName} ${target} ${configFlag(root)} --file=${filePath}`,
+    { cwd: root, silent: true }
+  );
+}
+
+/**
+ * Execute a SQL query against D1 and return parsed JSON results.
+ */
+export function d1Query(
+  root: string,
+  dbName: string,
+  target: D1Target,
+  query: string
+): Record<string, unknown>[] {
+  const output = runCapture(
+    `bunx wrangler d1 execute ${dbName} ${target} ${configFlag(root)} --command "${query}" --json`,
+    root
+  );
+  const parsed = JSON.parse(output);
+  return parsed?.[0]?.results ?? [];
+}
+
+/**
+ * Apply the INIT_SQL schema to D1 (idempotent — uses IF NOT EXISTS).
+ */
+export function applySchema(
+  root: string,
+  dbName: string,
+  target: D1Target
+): void {
+  const dbDir = resolve(root, DB_DIR);
+  if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
+
+  const sqlFile = resolve(dbDir, MIGRATION_FILE);
+  writeFileSync(sqlFile, INIT_SQL);
+  d1ExecuteFile(root, dbName, target, sqlFile);
+}
+
+/**
+ * Insert a row into a D1 table via INSERT OR REPLACE.
+ */
+export function d1InsertRow(
+  root: string,
+  dbName: string,
+  target: D1Target,
+  table: string,
+  row: Record<string, unknown>
+): void {
+  const sql = buildInsertSql(table, row);
+  d1Execute(root, dbName, target, sql);
+}
+
+/**
+ * Batch-insert multiple rows via a single --file execution.
+ * Dramatically faster than calling d1InsertRow per entry.
+ */
+export function d1InsertBatch(
+  root: string,
+  dbName: string,
+  target: D1Target,
+  table: string,
+  rows: Record<string, unknown>[]
+): void {
+  if (rows.length === 0) return;
+
+  const dbDir = resolve(root, DB_DIR);
+  if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
+
+  const sqlFile = resolve(dbDir, 'batch-sync.sql');
+  const statements = rows.map(row => buildInsertSql(table, row) + ';');
+  writeFileSync(sqlFile, statements.join('\n'));
+  d1ExecuteFile(root, dbName, target, sqlFile);
+}
+
+// ── Async versions (non-blocking, spinner-friendly) ─────────────────
+
+/**
+ * Apply schema asynchronously (non-blocking for spinner animation).
+ */
+export async function applySchemaAsync(
+  root: string,
+  dbName: string,
+  target: D1Target
+): Promise<void> {
+  const dbDir = resolve(root, DB_DIR);
+  if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
+
+  const sqlFile = resolve(dbDir, MIGRATION_FILE);
+  writeFileSync(sqlFile, INIT_SQL);
+  await runAsync(
+    `bunx wrangler d1 execute ${dbName} ${target} ${configFlag(root)} --file=${sqlFile}`,
+    { cwd: root, silent: true }
+  );
+}
+
+/**
+ * Batch-insert rows asynchronously (non-blocking for spinner animation).
+ */
+export async function d1InsertBatchAsync(
+  root: string,
+  dbName: string,
+  target: D1Target,
+  table: string,
+  rows: Record<string, unknown>[]
+): Promise<void> {
+  if (rows.length === 0) return;
+
+  const dbDir = resolve(root, DB_DIR);
+  if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
+
+  const sqlFile = resolve(dbDir, 'batch-sync.sql');
+  const statements = rows.map(row => buildInsertSql(table, row) + ';');
+  writeFileSync(sqlFile, statements.join('\n'));
+  await runAsync(
+    `bunx wrangler d1 execute ${dbName} ${target} ${configFlag(root)} --file=${sqlFile}`,
+    { cwd: root, silent: true }
+  );
+}
+
+/**
+ * Execute pre-built SQL statements as a batch file (async, non-blocking).
+ * Unlike d1InsertBatchAsync, this takes raw SQL strings — useful when
+ * inserting into multiple tables in a single batch.
+ */
+export async function d1ExecuteBatchSqlAsync(
+  root: string,
+  dbName: string,
+  target: D1Target,
+  statements: string[]
+): Promise<void> {
+  if (statements.length === 0) return;
+
+  const dbDir = resolve(root, DB_DIR);
+  if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
+
+  const sqlFile = resolve(dbDir, 'batch-sync.sql');
+  writeFileSync(sqlFile, statements.map(s => s.endsWith(';') ? s : s + ';').join('\n'));
+  await runAsync(
+    `bunx wrangler d1 execute ${dbName} ${target} ${configFlag(root)} --file=${sqlFile}`,
+    { cwd: root, silent: true }
+  );
+}
+
+/**
+ * Put an object into a local R2 bucket.
+ */
+export function r2PutLocal(
+  root: string,
+  bucketName: string,
+  key: string,
+  filePath: string
+): void {
+  run(
+    `bunx wrangler r2 object put ${bucketName}/${key} ${configFlag(root)} --file=${filePath} --local`,
+    { cwd: root, silent: true }
+  );
+}
+
+/**
+ * Put an object into a local R2 bucket (async, non-blocking).
+ */
+export async function r2PutLocalAsync(
+  root: string,
+  bucketName: string,
+  key: string,
+  filePath: string
+): Promise<void> {
+  await runAsync(
+    `bunx wrangler r2 object put ${bucketName}/${key} ${configFlag(root)} --file=${filePath} --local`,
+    { cwd: root, silent: true }
+  );
+}
+
+// ── Wrangler dev / deploy ──────────────────────────────────────────
+
+/**
+ * Start wrangler dev server with piped output.
+ * Filters wrangler's noisy banner and shows koguma-branded messages.
+ * Returns a Promise that resolves when wrangler exits.
+ */
+export function wranglerDev(
+  root: string,
+  extraArgs: string,
+  env?: Record<string, string>
+): Promise<number> {
+  return new Promise(resolve => {
+    const envVars = { ...process.env, ...(env ?? {}) };
+    const args = ['wrangler', 'dev', ...configFlag(root).split(' ')];
+    if (extraArgs.trim()) args.push(...extraArgs.trim().split(' '));
+
+    const { spawn } = require('child_process');
+    const child = spawn('bunx', args, {
+      cwd: root,
+      env: envVars,
+      stdio: ['inherit', 'pipe', 'pipe'] // stdin passthrough, capture stdout/stderr
+    });
+
+    // Lines to suppress from wrangler output
+    const suppressPatterns = [
+      /⛅️\s*wrangler/, // wrangler banner
+      /─{3,}/, // separator lines
+      /Your Worker has access/, // bindings header
+      /Binding\s+Resource/, // bindings table header
+      /env\./, // binding rows (e.g. "env.DB", "env.MEDIA")
+      /Using secrets defined in/, // .dev.vars notice
+      /╭.*╮/, // keyboard shortcuts box top
+      /│.*\[b\].*\[c\].*\[x\]/, // keyboard shortcuts content
+      /╰.*╯/, // keyboard shortcuts box bottom
+      /\[wrangler:/, // [wrangler:inf] prefixed messages (handled separately below)
+      /^\s*$/ // blank lines
+    ];
+
+    const shouldSuppress = (line: string): boolean =>
+      suppressPatterns.some(p => p.test(line));
+
+    const handleOutput = (data: Buffer, isErr: boolean) => {
+      const text = data.toString();
+      for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+
+        // Rebrand the "Ready" message before suppress check
+        if (trimmed.includes('Ready on http')) {
+          const urlMatch = trimmed.match(/(https?:\/\/[^\s]+)/);
+          const url = urlMatch?.[1] ?? 'http://localhost:8787';
+          ok(`Server ready → ${url}`);
+          continue;
+        }
+
+        if (shouldSuppress(line)) continue;
+
+        if (trimmed.includes('Starting local server')) continue;
+        if (trimmed.includes('Shutting down')) continue;
+
+        // Forward everything else (request logs, errors, warnings)
+        if (isErr) {
+          warn(trimmed);
+        } else {
+          log(trimmed);
+        }
+      }
+    };
+
+    child.stdout.on('data', (data: Buffer) => handleOutput(data, false));
+    child.stderr.on('data', (data: Buffer) => handleOutput(data, true));
+
+    // Forward SIGINT to wrangler
+    const forwardSignal = () => child.kill('SIGINT');
+    process.on('SIGINT', forwardSignal);
+    process.on('SIGTERM', forwardSignal);
+
+    child.on('close', (code: number | null) => {
+      process.removeListener('SIGINT', forwardSignal);
+      process.removeListener('SIGTERM', forwardSignal);
+      resolve(code ?? 0);
+    });
+  });
+}
+
+/**
+ * Deploy via wrangler.
+ */
+export function wranglerDeploy(root: string): void {
+  run(`bunx wrangler deploy ${configFlag(root)}`, { cwd: root });
+}
+
+// ── D1 / R2 resource creation ──────────────────────────────────────
+
+/**
+ * Create a D1 database and return the database_id (or null on failure).
+ */
+export function createD1Database(root: string, dbName: string): string | null {
+  try {
+    const output = runCapture(`bunx wrangler d1 create ${dbName}`, root);
+    const idMatch = output.match(/database_id\s*=\s*"([^"]+)"/);
+    return idMatch?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ensure an R2 bucket exists. Returns true if it exists or was created.
+ */
+export function ensureR2Bucket(root: string, bucketName: string): boolean {
+  try {
+    const buckets = runCapture('bunx wrangler r2 bucket list', root);
+    if (buckets.includes(bucketName)) return true;
+    runCapture(`bunx wrangler r2 bucket create ${bucketName}`, root);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koguma",
-  "version": "0.6.6",
+  "version": "2.0.0",
   "description": "🐻 A little CMS with big heart — schema-driven, runs on Cloudflare's free tier",
   "type": "module",
   "license": "MIT",
@@ -22,7 +22,7 @@
   },
   "packageManager": "bun@1.3.10",
   "scripts": {
-    "dev": "concurrently --kill-others \"bun run --cwd admin dev\" \"bunx wrangler dev --config examples/alpine/wrangler.toml\"",
+    "dev": "concurrently --kill-others \"bun run --cwd admin dev\" \"bun run cli/index.ts dev\"",
     "test": "bunx turbo run test:run",
     "test:run": "bun test",
     "build:admin": "bunx turbo run build:admin:run",
@@ -34,8 +34,7 @@
     "./worker": "./src/worker.ts",
     "./client": "./src/client/index.ts",
     "./react": "./src/react/index.ts",
-    "./types": "./src/config/types.ts",
-    "./db": "./src/db/schema.ts"
+    "./types": "./src/config/types.ts"
   },
   "bin": {
     "koguma": "./cli/index.ts"
@@ -47,6 +46,10 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "gray-matter": "^4.0.3",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
     "zod": "^4.3.6"
   },
   "peerDependencies": {