koguma 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Eric Langford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,297 @@
+<p align="center">
+  <img src="logo.svg" alt="Koguma" width="200" />
+</p>
+
+<h1 align="center">Koguma</h1>
+
+<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.
+
+---
+
+## Quickstart
+
+### 1. Install
+
+```bash
+bun add koguma
+# or
+npm install koguma
+```
+
+### 2. Define your content
+
+Create a `site.config.ts` in your project root:
+
+```ts
+import { defineConfig, contentType, group, field } from "koguma";
+
+export default defineConfig({
+  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"),
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+### 3. Create your worker
+
+Create a `worker.ts`:
+
+```ts
+import { createWorker } from 'koguma/worker';
+import config from './site.config';
+
+export default createWorker(config);
+```
+
+### 4. Configure Cloudflare
+
+Add to your `wrangler.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"
+```
+
+### 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
+```
+
+Your admin dashboard is at `/admin`. Your API is at `/api/content/:type`.
+
+---
+
+## Content Schema
+
+### 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)      |
+
+### Content Type Options
+
+```ts
+contentType("page", "Page", {
+  displayField: "title",    // Field shown in admin list view
+  singleton: true,           // Only one entry allowed (e.g. site settings)
+  groups: [ ... ],
+});
+```
+
+### Groups
+
+Groups organize fields into collapsible sections in the admin UI:
+
+```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)
+});
+```
+
+---
+
+## CLI Reference
+
+All commands auto-detect your project root by looking for `wrangler.toml`.
+
+| 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`                                             |
+
+---
+
+## API Routes
+
+### Public (no auth)
+
+| Method | Route                    | Description                             |
+| ------ | ------------------------ | --------------------------------------- |
+| `GET`  | `/api/content/:type`     | List all entries of a content type      |
+| `GET`  | `/api/content/:type/:id` | Get a single entry (with resolved refs) |
+| `GET`  | `/api/media/:key`        | Serve a media file from R2              |
+
+### Admin (auth required)
+
+| Method   | Route                  | Description                         |
+| -------- | ---------------------- | ----------------------------------- |
+| `POST`   | `/api/auth/login`      | Login with `{ password }`           |
+| `POST`   | `/api/auth/logout`     | Clear session                       |
+| `GET`    | `/api/auth/me`         | Check authentication                |
+| `GET`    | `/api/admin/schema`    | Content type schemas (for admin UI) |
+| `GET`    | `/api/admin/:type`     | List entries                        |
+| `GET`    | `/api/admin/:type/:id` | Get entry                           |
+| `POST`   | `/api/admin/:type`     | Create entry                        |
+| `PUT`    | `/api/admin/:type/:id` | Update entry                        |
+| `DELETE` | `/api/admin/:type/:id` | Delete entry                        |
+| `GET`    | `/api/admin/media`     | List media assets                   |
+| `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).
+
+---
+
+## Package Exports
+
+```ts
+import { defineConfig, contentType, group, field, 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';
+```
+
+---
+
+## Local Development
+
+```bash
+# Create .dev.vars with your local admin password
+echo "KOGUMA_SECRET=your-password" > .dev.vars
+
+# Start wrangler dev
+npx wrangler dev
+
+# Admin dashboard is at http://localhost:8787/admin
+# API is at http://localhost:8787/api/content/:type
+```
+
+---
+
+## Architecture
+
+```
+Your Project
+├── site.config.ts     ← Content type definitions
+├── worker.ts          ← Entry point (imports koguma/worker)
+├── wrangler.toml      ← Cloudflare config (D1 + R2 bindings)
+├── .dev.vars          ← Local secrets (KOGUMA_SECRET)
+└── db/
+    ├── seed.sql       ← Database schema + seed data
+    └── seed.json      ← Raw content data
+
+Koguma (this package)
+├── src/
+│   ├── config/        ← Schema definitions (defineConfig, field types)
+│   ├── api/           ← Hono router (CRUD + media + auth)
+│   ├── db/            ← D1 queries and schema generation
+│   ├── 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)
+├── admin/             ← Vite + React admin dashboard source
+└── cli/               ← CLI commands (init, build, seed, deploy)
+```
+
+---
+
+## 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