koguma 0.6.5 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center"><strong>A little CMS with big heart</strong> — schema-driven content management that runs entirely on Cloudflare's free tier.</p>
 
-Koguma gives you a headless CMS with a beautiful admin dashboard, all powered by **Cloudflare Workers + D1 + R2**. Define your content types in code, and Koguma handles the rest — database schema, API routes, admin UI, and media storage.
+Koguma gives you a headless CMS with a beautiful admin dashboard, all powered by **Cloudflare Workers + D1 + R2**. Define your content types in code, and Koguma handles the rest — API routes, admin UI, media storage, and a file-based `content/` directory for version-controlled content.
 
 ---
 
@@ -25,27 +25,25 @@ npm install koguma
 Create a `site.config.ts` in your project root:
 
 ```ts
-import { defineConfig, contentType, group, field } from "koguma";
+import { defineConfig, contentType, field } from 'koguma';
 
 export default defineConfig({
-  siteName: "My Site",
+  siteName: 'My Site',
   contentTypes: [
-    contentType("blogPost", "Blog Post", {
-      displayField: "title",
-      groups: [
-        group({ id: "content", name: "Content", fields: {
-          title: field.shortText("Title"),
-          slug: field.shortText("Slug"),
-          body: field.richText("Body"),
-          heroImage: field.image("Hero Image"),
-        }),
-        group({ id: "meta", name: "Metadata", fields: {
-          author: field.shortText("Author"),
-          publishedAt: field.shortText("Published Date"),
-        }),
-      ],
-    }),
-  ],
+    contentType({
+      id: 'post',
+      name: 'Blog Post',
+      displayField: 'title',
+      fields: {
+        title: field.text('Title').required(),
+        slug: field.text('Slug').required(),
+        body: field.markdown('Body'),
+        heroImage: field.image('Hero Image'),
+        published: field.boolean('Published').default(false),
+        date: field.date('Published Date')
+      }
+    })
+  ]
 });
 ```
 
@@ -60,37 +58,26 @@ import config from './site.config';
 export default createWorker(config);
 ```
 
-### 4. Configure Cloudflare
+### 4. Configure
 
-Add to your `wrangler.toml`:
+Create `koguma.toml`:
 
 ```toml
 name = "my-site"
-main = "worker.ts"
-compatibility_date = "2025-09-27"
-compatibility_flags = ["nodejs_compat"]
-
-[assets]
-directory = "./dist"
-binding = "ASSETS"
-
-[[d1_databases]]
-binding = "DB"
-database_name = "my-site-db"
-database_id = ""  # filled by `koguma init`
-
-[[r2_buckets]]
-binding = "MEDIA"
-bucket_name = "my-site-media"
+database_id = ""    # filled by `koguma init`
 ```
 
+That's it — two lines. Everything else is derived by convention:
+
+- D1 database → `my-site-db`
+- R2 bucket → `my-site-media`
+- Worker name → `my-site`
+
 ### 5. Deploy
 
 ```bash
-koguma init          # Create D1 + R2 on Cloudflare
-koguma secret        # Set your admin password
-koguma seed --remote # Seed the production database
-koguma deploy        # Build + deploy everything
+koguma init    # Scaffold project, create D1 + R2 on Cloudflare
+koguma push    # Build + deploy + sync content
 ```
 
 Your admin dashboard is at `/admin`. Your API is at `/api/content/:type`.
@@ -101,56 +88,89 @@ Your admin dashboard is at `/admin`. Your API is at `/api/content/:type`.
 
 ### Field Types
 
-| Field                             | Usage                  | Stored As              |
-| --------------------------------- | ---------------------- | ---------------------- |
-| `field.shortText(label)`          | Titles, slugs, URLs    | `TEXT`                 |
-| `field.longText(label)`           | Descriptions, bios     | `TEXT`                 |
-| `field.richText(label)`           | Rich formatted content | `JSON` (document tree) |
-| `field.number(label)`             | Counts, order          | `REAL`                 |
-| `field.boolean(label)`            | Toggles                | `INTEGER` (0/1)        |
-| `field.image(label)`              | Image from R2 media    | `TEXT` (asset ID)      |
-| `field.reference(label, typeId)`  | Link to another entry  | `TEXT` (entry ID)      |
-| `field.references(label, typeId)` | Array of entry links   | `JSON` (ID array)      |
+| Field                            | Usage                  | Stored As                |
+| -------------------------------- | ---------------------- | ------------------------ |
+| `field.text(label)`              | Titles, slugs, URLs    | `TEXT`                   |
+| `field.longText(label)`          | Descriptions, bios     | `TEXT`                   |
+| `field.markdown(label)`          | Rich formatted content | `TEXT` (markdown string) |
+| `field.number(label)`            | Counts, order          | `number` in JSON         |
+| `field.boolean(label)`           | Toggles                | `boolean` in JSON        |
+| `field.date(label)`              | Timestamps             | `string` (ISO 8601)      |
+| `field.select(label, {options})` | Dropdowns              | `string`                 |
+| `field.url(label)`               | URLs                   | `string`                 |
+| `field.email(label)`             | Email addresses        | `string`                 |
+| `field.phone(label)`             | Phone numbers          | `string`                 |
+| `field.color(label)`             | Hex colours            | `string`                 |
+| `field.youtube(label)`           | YouTube video IDs      | `string`                 |
+| `field.instagram(label)`         | Instagram handles      | `string`                 |
+| `field.image(label)`             | Image from R2 media    | `string` (asset ID)      |
+| `field.images(label)`            | Array of images        | `string[]` (asset IDs)   |
+| `field.ref(typeId, label)`       | Link to another entry  | `string` (entry ID)      |
+| `field.refs(typeId, label)`      | Array of entry links   | `string[]` (entry IDs)   |
+
+All fields stored inside a JSON `data` blob in the `entries` table — no per-field columns, no migrations.
 
 ### Content Type Options
 
 ```ts
-contentType("page", "Page", {
-  displayField: "title",    // Field shown in admin list view
+contentType({
+  id: "page",
+  name: "Page",
+  displayField: "title",
   singleton: true,           // Only one entry allowed (e.g. site settings)
-  groups: [ ... ],
+  fields: { ... },
 });
 ```
 
-### Groups
+---
 
-Groups organize fields into collapsible sections in the admin UI:
+## CLI Reference
 
-```ts
-group({ id: "details", name: "Details", helpText: "Main content fields", collapsed: false, fields: {
-  title: field.shortText("Title"),
-  body: field.richText("Body"),
-}, {
-  helpText: "Main content fields",
-  collapsed: false,          // Start expanded (default)
-});
+All commands auto-detect your project root by looking for `koguma.toml`.
+
+| Command            | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `koguma init`      | Interactive project setup — scaffold, create D1 + R2, set secret  |
+| `koguma dev`       | Auto-sync `content/` → local D1, generate types, start dev server |
+| `koguma push`      | Build + deploy + sync content to remote                           |
+| `koguma pull`      | Download remote content + media → local `content/` files          |
+| `koguma gen-types` | Generate `koguma.d.ts` typed interfaces                           |
+| `koguma tidy`      | Validate `content/` against config, sync dirs, check fields       |
+
+---
+
+## Content Directory
+
+Koguma uses a `content/` directory for file-based content that lives in your git repo:
+
+```
+content/
+├── post/                        # folder = content type ID
+│   ├── hello-world.md           # file = one entry
+│   └── our-mission.md
+├── siteSettings/
+│   └── index.yml                # singletons use index.yml
+└── media/                       # optional local images
+    └── hero-banner.jpg
 ```
 
+**Markdown files with frontmatter:**
+
+```markdown
+---
+title: Our Mission
+slug: our-mission
+heroImage: hero-banner.jpg
+published: true
+date: 2026-03-01
 ---
 
-## CLI Reference
+## Who We Are
 
-All commands auto-detect your project root by looking for `wrangler.toml`.
+Rich text body, stored as markdown.
+```
 
-| Command                             | Description                                                                                |
-| ----------------------------------- | ------------------------------------------------------------------------------------------ |
-| `koguma init`                       | Create D1 database and R2 bucket on Cloudflare, patch `wrangler.toml` with the database ID |
-| `koguma secret`                     | Set `KOGUMA_SECRET` (admin password) as a Cloudflare secret                                |
-| `koguma build`                      | Build the admin dashboard (Vite) and generate the `_bundle.ts`                             |
-| `koguma seed`                       | Run `db/seed.sql` against local D1                                                         |
-| `koguma seed --remote`              | Run `db/seed.sql` against production D1                                                    |
-| `koguma migrate-media --remote URL` | Download images from source, upload to R2, update D1 URLs                                  |
-| `koguma deploy`                     | Build admin + frontend, then `wrangler deploy`                                             |
+**Git is your version history.** No custom versioning table needed.
 
 ---
 
@@ -181,26 +201,6 @@ All commands auto-detect your project root by looking for `wrangler.toml`.
 | `POST`   | `/api/admin/media`     | Upload media (multipart form)       |
 | `DELETE` | `/api/admin/media/:id` | Delete media                        |
 
-### Response Format
-
-```json
-// GET /api/content/blogPost
-{
-  "entries": [
-    {
-      "id": "abc-123",
-      "title": "Hello World",
-      "heroImage": {
-        "id": "img-456",
-        "url": "/api/media/img-456.jpg",
-        "title": "Hero",
-        "content_type": "image/jpeg"
-      }
-    }
-  ]
-}
-```
-
 References and images are automatically resolved to nested objects in the public API (up to 2 levels deep).
 
 ---
@@ -208,12 +208,11 @@ References and images are automatically resolved to nested objects in the public
 ## Package Exports
 
 ```ts
-import { defineConfig, contentType, group, field, Infer } from 'koguma';
+import { defineConfig, contentType, group, field, type Infer } from 'koguma';
 import { createWorker } from 'koguma/worker';
 import { createClient } from 'koguma/client';
-import { useKoguma } from 'koguma/react';
-import type { RichTextDocument, RichTextNode } from 'koguma/types';
-import { generateSchema } from 'koguma/db';
+import { Markdown, useEntry, useEntries } from 'koguma/react';
+import type { KogumaAsset, EntryReference } from 'koguma/types';
 ```
 
 ---
@@ -224,8 +223,8 @@ import { generateSchema } from 'koguma/db';
 # Create .dev.vars with your local admin password
 echo "KOGUMA_SECRET=your-password" > .dev.vars
 
-# Start wrangler dev
-npx wrangler dev
+# Start dev server (auto-syncs content/, generates types)
+koguma dev
 
 # Admin dashboard is at http://localhost:8787/admin
 # API is at http://localhost:8787/api/content/:type
@@ -239,59 +238,30 @@ npx wrangler dev
 Your Project
 ├── site.config.ts     ← Content type definitions
 ├── worker.ts          ← Entry point (imports koguma/worker)
-├── wrangler.toml      ← Cloudflare config (D1 + R2 bindings)
+├── koguma.toml        ← Project config (name + database_id)
 ├── .dev.vars          ← Local secrets (KOGUMA_SECRET)
-└── db/
-    ├── seed.sql       ← Database schema + seed data
-    └── seed.json      ← Raw content data
+└── content/           ← Version-controlled content files
+    ├── post/
+    │   └── hello-world.md
+    └── siteSettings/
+        └── index.yml
 
 Koguma (this package)
 ├── src/
 │   ├── config/        ← Schema definitions (defineConfig, field types)
 │   ├── api/           ← Hono router (CRUD + media + auth)
-│   ├── db/            ← D1 queries and schema generation
+│   ├── db/            ← D1 queries (JSON document store)
 │   ├── auth/          ← HMAC-signed cookie sessions
 │   ├── media/         ← R2 upload/serve/delete
 │   ├── admin/         ← Dashboard HTML shell + JS/CSS bundle
 │   ├── client/        ← Fetch client for consuming the API
-│   └── react/         ← React hooks (useKoguma)
+│   └── react/         ← React hooks + <Markdown> component
 ├── admin/             ← Vite + React admin dashboard source
-└── cli/               ← CLI commands (init, build, seed, deploy)
+└── cli/               ← CLI commands (init, dev, push, pull, gen-types, tidy)
 ```
 
 ---
 
-## Roadmap
-
-### v0.2 — Admin Power-ups
-
-- [ ] **Rich text editor** — replace JSON textarea with Tiptap WYSIWYG (bold, italic, headings, links, lists, inline images)
-- [ ] **Media picker** — browse/upload media from within entry editor, image preview thumbnails
-- [ ] **Entry list search & sort** — filter by display field, sortable columns, pagination
-- [ ] **Unsaved changes warning** — dirty form detection, Cmd+S to save
-- [ ] **Breadcrumb navigation** — show current path in the editor toolbar
-
-### v0.3 — Content Workflow
-
-- [ ] **Draft / publish** — entries have `status: draft | published`, public API filters by default
-- [ ] **Content versioning** — save revision history, view diffs, one-click rollback
-- [ ] **Field validation** — required fields, min/max length, regex, custom validators
-
-### v0.4 — Auth & Multi-site
-
-- [ ] **Multi-user auth** — user accounts, roles (admin/editor/viewer), audit log
-- [ ] **Multi-site support** — single install, per-site config and content isolation
-
-### v0.5 — DX & Media
-
-- [ ] **Image optimization** — auto-resize, WebP/AVIF conversion, responsive srcset
-- [ ] **Webhooks** — fire on content changes, configurable URLs, retry logic
-- [ ] **CLI: export/import** — dump and restore content as JSON
-- [ ] **CLI: schema diff & migrate** — detect config ↔ DB drift, apply changes safely
-- [ ] **Typed SDK** — auto-generate TypeScript types from `site.config.ts`
-
----
-
 ## License
 
 MIT

package/cli/auth.ts

@@ -0,0 +1,101 @@
+/**
+ * cli/auth.ts — Authentication helpers for remote Koguma operations.
+ *
+ * Handles reading KOGUMA_SECRET from .dev.vars and authenticating
+ * against a remote Koguma instance via the admin API.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { fail } from './log.ts';
+
+const SECRET_ENV_VAR = 'KOGUMA_SECRET';
+const DEV_VARS_FILE = '.dev.vars';
+const SESSION_COOKIE_NAME = 'koguma_session';
+
+// ── Secret resolution ──────────────────────────────────────────────
+
+/**
+ * Read KOGUMA_SECRET from the project's .dev.vars file.
+ * Exits with an actionable error if not found.
+ */
+export function requireSecret(root: string): string {
+  const devVarsPath = resolve(root, DEV_VARS_FILE);
+  if (!existsSync(devVarsPath)) {
+    fail(
+      `${DEV_VARS_FILE} not found. Create it with:\n` +
+        `    echo '${SECRET_ENV_VAR}=your-password' > ${DEV_VARS_FILE}`
+    );
+    process.exit(1);
+  }
+
+  const content = readFileSync(devVarsPath, 'utf-8');
+  const match = content.match(new RegExp(`${SECRET_ENV_VAR}=(.+)`));
+  const password = match?.[1]?.trim();
+
+  if (!password) {
+    fail(
+      `${SECRET_ENV_VAR} not found in ${DEV_VARS_FILE}. Add it:\n` +
+        `    echo '${SECRET_ENV_VAR}=your-password' >> ${DEV_VARS_FILE}`
+    );
+    process.exit(1);
+  }
+
+  return password;
+}
+
+// ── Remote authentication ──────────────────────────────────────────
+
+/**
+ * Authenticate against a remote Koguma instance.
+ * Returns the session cookie string for use in subsequent requests.
+ */
+export async function authenticate(
+  remoteUrl: string,
+  root: string
+): Promise<string> {
+  const password = requireSecret(root);
+
+  const loginRes = await fetch(`${remoteUrl}/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(
+    new RegExp(`${SESSION_COOKIE_NAME}=[^;]+`)
+  );
+
+  if (!cookieMatch) {
+    fail(
+      'Authentication failed — check your KOGUMA_SECRET.\n' +
+        `  Tried: ${remoteUrl}/api/auth/login`
+    );
+    process.exit(1);
+  }
+
+  return cookieMatch[0];
+}
+
+// ── Remote URL parsing ─────────────────────────────────────────────
+
+/**
+ * Extract the --remote URL from process.argv.
+ * Exits with usage info if missing or malformed.
+ */
+export function getRemoteUrl(): string {
+  const idx = process.argv.indexOf('--remote');
+  const url = idx >= 0 ? process.argv[idx + 1] : undefined;
+
+  if (!url || url.startsWith('-')) {
+    fail(
+      'Missing remote URL.\n' +
+        '  Usage: koguma <command> --remote https://your-site.workers.dev'
+    );
+    process.exit(1);
+  }
+
+  return url.replace(/\/$/, '');
+}

package/cli/config.ts

@@ -0,0 +1,149 @@
+/**
+ * cli/config.ts — koguma.toml + .wrangler.toml generation
+ *
+ * koguma.toml has two fields:
+ *   name = "my-blog"
+ *   database_id = ""        # filled by koguma init
+ *
+ * Everything else is derived from the name:
+ *   D1 database name → {name}-db
+ *   R2 bucket        → {name}-media
+ *   Worker name      → {name}
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export interface KogumaProjectConfig {
+  name: string;
+  databaseId: string;
+}
+
+export interface DerivedNames {
+  workerName: string;
+  dbName: string;
+  bucketName: string;
+}
+
+// ── Derive conventional names from project name ────────────────────
+
+export function deriveNames(name: string): DerivedNames {
+  return {
+    workerName: name,
+    dbName: `${name}-db`,
+    bucketName: `${name}-media`
+  };
+}
+
+// ── Read / Write koguma.toml ────────────────────────────────────────
+
+export function readConfig(root: string): KogumaProjectConfig {
+  const path = resolve(root, 'koguma.toml');
+  if (!existsSync(path)) {
+    throw new Error(`koguma.toml not found in ${root}`);
+  }
+  const raw = readFileSync(path, 'utf-8');
+
+  const nameMatch = raw.match(/^name\s*=\s*"([^"]*)"/m);
+  const dbIdMatch = raw.match(/^database_id\s*=\s*"([^"]*)"/m);
+
+  return {
+    name: nameMatch?.[1] ?? '',
+    databaseId: dbIdMatch?.[1] ?? ''
+  };
+}
+
+export function writeConfig(root: string, config: KogumaProjectConfig): void {
+  const path = resolve(root, 'koguma.toml');
+  const content = `name = "${config.name}"\ndatabase_id = "${config.databaseId}"\n`;
+  writeFileSync(path, content);
+}
+
+// ── Generate transient .koguma/ contents ───────────────────────────
+
+export function generateWranglerToml(config: KogumaProjectConfig): string {
+  const { workerName, dbName, bucketName } = deriveNames(config.name);
+
+  // Paths are relative to .koguma/ where this config lives
+  return `# Auto-generated by koguma — do not edit
+name = "${workerName}"
+main = "worker.ts"
+compatibility_date = "2024-11-01"
+compatibility_flags = ["nodejs_compat"]
+
+[assets]
+directory = "./dashboard-public"
+binding = "ASSETS"
+
+# ── D1 Database ──
+[[d1_databases]]
+binding = "DB"
+database_name = "${dbName}"
+database_id = "${config.databaseId}"
+
+# ── R2 Media Storage ──
+[[r2_buckets]]
+binding = "MEDIA"
+bucket_name = "${bucketName}"
+`;
+}
+
+function generateWorkerEntry(): string {
+  return `// Auto-generated by koguma — do not edit
+import { createWorker } from 'koguma/worker';
+import config from '../site.config';
+
+export default createWorker(config);
+`;
+}
+
+export function ensureWranglerConfig(root: string): string {
+  const config = readConfig(root);
+  const kogumaDir = resolve(root, '.koguma');
+
+  // Create .koguma/ and .koguma/dashboard-public/
+  mkdirSync(kogumaDir, { recursive: true });
+  const dashDir = resolve(kogumaDir, 'dashboard-public');
+  if (!existsSync(dashDir)) {
+    mkdirSync(dashDir, { recursive: true });
+  }
+
+  // Write wrangler.toml
+  const wranglerPath = resolve(kogumaDir, 'wrangler.toml');
+  writeFileSync(wranglerPath, generateWranglerToml(config));
+
+  // Write worker.ts entry point
+  const workerPath = resolve(kogumaDir, 'worker.ts');
+  writeFileSync(workerPath, generateWorkerEntry());
+
+  // Write .dev.vars with a local dev secret (only if not already present,
+  // so users can override with their own password)
+  const devVarsPath = resolve(kogumaDir, '.dev.vars');
+  if (!existsSync(devVarsPath)) {
+    writeFileSync(devVarsPath, 'KOGUMA_SECRET=koguma-dev-local\n');
+  }
+
+  return wranglerPath;
+}
+
+// ── Find project root ──────────────────────────────────────────────
+
+export function findProjectRoot(): string {
+  let dir = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(resolve(dir, 'koguma.toml'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    'Could not find koguma.toml — run this from your project directory.'
+  );
+}
+
+// ── Scaffold koguma.toml for new projects ──────────────────────────
+
+export function generateKogumaToml(projectName: string): string {
+  return `name = "${projectName}"\ndatabase_id = ""\n`;
+}

package/cli/constants.ts

@@ -0,0 +1,38 @@
+/**
+ * cli/constants.ts — Shared constants for the Koguma CLI.
+ *
+ * Eliminates magic strings scattered across modules.
+ */
+
+/** CLI version string */
+export const CLI_VERSION = 'v2.0.0';
+
+/** Project config file name */
+export const CONFIG_FILE = 'koguma.toml';
+
+/** Auto-generated directory (gitignored) */
+export const KOGUMA_DIR = '.koguma';
+
+/** Generated wrangler config inside KOGUMA_DIR */
+export const WRANGLER_CONFIG_FILE = `${KOGUMA_DIR}/wrangler.toml`;
+
+/** Generated worker entry point inside KOGUMA_DIR */
+export const WORKER_ENTRY = `${KOGUMA_DIR}/worker.ts`;
+
+/** Dashboard static assets directory inside KOGUMA_DIR */
+export const DASHBOARD_DIR = `${KOGUMA_DIR}/dashboard-public`;
+
+/** Generated TypeScript declarations */
+export const TYPEGEN_OUTPUT = 'koguma.d.ts';
+
+/** Site configuration module */
+export const SITE_CONFIG_FILE = 'site.config.ts';
+
+/** Content directory name */
+export const CONTENT_DIR = 'content';
+
+/** Temporary SQL directory (inside .koguma — transient, gitignored) */
+export const DB_DIR = `${KOGUMA_DIR}/db`;
+
+/** Temporary migration file within DB_DIR */
+export const MIGRATION_FILE = 'migration.sql';