okno 1.0.0-alpha.2 → 1.0.0-alpha.21

package/package.json

@@ -2,51 +2,82 @@
 	"name": "okno",
 	"description": "Git-backed CMS with live editing for any Vite framework",
 	"author": "Gabriel Uhlíř",
-	"version": "1.0.0-alpha.2",
+	"version": "1.0.0-alpha.21",
 	"homepage": "https://okno.build",
 	"type": "module",
 	"types": "./dist/index.d.ts",
 	"main": "./dist/index.js",
 	"module": "./dist/index.js",
+	"bin": {
+		"okno": "./dist/cli.js"
+	},
 	"exports": {
 		".": {
-			"import": "./src/index.ts",
+			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
 		},
 		"./vite": {
-			"import": "./src/vite/index.ts",
+			"types": "./dist/vite/index.d.ts",
 			"default": "./dist/vite/index.js"
 		},
 		"./editor": {
-			"import": "./editor/index.ts",
+			"types": "./dist/editor/index.d.ts",
 			"default": "./dist/editor/index.js"
+		},
+		"./boot": {
+			"types": "./dist/boot.d.ts",
+			"default": "./dist/boot.js"
 		}
 	},
-	"files": ["dist"],
+	"files": [
+		"dist",
+		"src/runtime",
+		"skills"
+	],
 	"scripts": {
 		"dev": "vite build --watch",
-		"build": "vite build && tsc || true"
+		"dev:watch": "vite build --watch --no-emptyOutDir",
+		"dev:types": "tsc -w --emitDeclarationOnly --preserveWatchOutput",
+		"build:js": "vite build",
+		"build": "vite build && tsc",
+		"check": "tsc --noEmit",
+		"pub": "bun run publish.js"
 	},
 	"dependencies": {
+		"@clack/prompts": "^0.7.0",
+		"@modelcontextprotocol/sdk": "^1.12.0",
+		"zod": "^3.23.8",
+		"@internationalized/date": "^3.12.2",
+		"@tiptap/core": "^3.27.1",
+		"@tiptap/extension-image": "3.27.1",
+		"@tiptap/extension-table": "3.27.1",
+		"@tiptap/extension-text-align": "^3",
+		"@tiptap/pm": "^3.27.1",
+		"@tiptap/starter-kit": "^3.27.1",
+		"acorn": "^8.11.3",
 		"bits-ui": "^2.18.0",
 		"runed": "^0.23.0",
-		"simple-git": "^3.28.0",
-		"svelte": "^5.0.0",
+		"simple-git": "^3.32.0",
+		"svelte": "^5.55.0",
 		"svelte-dnd-action": "^0.9.69"
 	},
 	"devDependencies": {
-		"@lucide/svelte": "*",
+		"@hugeicons-pro/core-bulk-rounded": "*",
+		"@hugeicons-pro/core-solid-rounded": "*",
+		"@hugeicons-pro/core-stroke-rounded": "*",
+		"@hugeicons-pro/core-stroke-standard": "*",
+		"@hugeicons/svelte": "*",
 		"@sveltejs/vite-plugin-svelte": "^5.0.0",
 		"@tailwindcss/vite": "^4.0.0",
 		"@types/node": "^20.19.13",
 		"tailwindcss": "^4.0.0",
 		"tailwindcss-animate": "^1.0.7",
 		"typescript": "^5.9.2",
-		"vite": "6.x"
+		"vite": "^6.4.3"
 	},
 	"peerDependencies": {
 		"svelte": "^5.0.0",
-		"vite": "^5.0.0 || ^6.0.0"
+		"vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
 	},
 	"keywords": [
 		"cms",

package/skills/connect-okno/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: connect-okno
+description: >
+  Model and build content with okno, the Git-backed CMS. Load this whenever you
+  are designing an okno schema, deciding how to structure content (pages,
+  collections, globals, blocks, references), adding entries through the okno MCP,
+  or wiring content into templates with the spread-to-edit pattern. Use it when a
+  user asks to "build/add/connect content with okno", set up a blog/articles/
+  authors/categories, define a content model, or render okno content in Astro/
+  SvelteKit/Nuxt/Vite. Teaches the mental model and when to use which primitive —
+  not just recipes.
+metadata:
+  author: okno
+  version: "1.0.0"
+---
+
+# Connect okno
+
+okno is a **Git-backed CMS with live, in-page editing**. Content is plain `.ts`
+files in the project's repo. There is no database. The editor injects onto the
+real, deployed page — you spread a field onto the element that renders it, and
+that element becomes editable in place.
+
+Your job with this skill is to **model content well** and **wire it into
+templates** so every value is editable. Modeling is the part that compounds: a
+good model makes the editor obvious and the templates trivial; a bad one fights
+you forever. Spend your judgment there.
+
+## The golden rules
+
+1. **You cannot publish.** Every write (`write_entry`, `write_schema`) lands as a
+   *draft* on the project's working branch. A human reviews and publishes
+   (a merge). Never imply you deployed content live.
+2. **`get_schema` first, always.** `write_schema` replaces the entire schema.
+   Read it, merge your change into the whole object, write it all back. Never
+   send a partial schema — you will delete everything you omitted.
+3. **Model before you fill.** Decide pages/collections/globals/blocks first,
+   write the schema, *then* add entries. Entries must match the schema.
+
+## The workflow
+
+```
+get_schema                 → learn the current content model
+(decide the model)         → use the decision frameworks below
+write_schema(full object)  → create/extend pages, collections, globals, blocks
+write_entry(path, fields)  → add the actual content, one entry per call
+(wire templates)           → spread fields onto elements (see "Rendering")
+(human publishes)          → not you
+```
+
+Entry paths are relative to the `okno/` dir:
+`pages/home.ts`, `collections/articles/<slug>.ts`, `globals/navbar.ts`.
+
+---
+
+## The four primitives
+
+| Primitive | What it is | One of, or many? | Example |
+|-----------|-----------|------------------|---------|
+| **page** | A singleton with a fixed route | exactly one | Home, About, Pricing |
+| **collection** | A repeatable type; every entry shares a shape and has a slug | many | Articles, Authors, Products |
+| **global** | A singleton value read across the *whole* site | exactly one, everywhere | Navbar, Footer, SEO/Meta |
+| **block** | A reusable *field shape* embedded into a page/collection | as many placements as you drop | Hero, Card, FAQ item, Nav link |
+
+Everything else (`reference`, `group`, the field types) is how you connect and
+shape these four.
+
+---
+
+## Decision frameworks
+
+These are the questions that actually come up. Answer them in order.
+
+### 1. Page or collection?
+
+> **Is this one specific thing, or many things that share a shape?**
+
+- **One specific thing** → a **page**. There is exactly one Home, one About. It
+  has its own route. Its fields are flat (no slug needed).
+- **Many things, same shape** → a **collection**. Articles, team members,
+  products. Each entry gets a `slug` field and the collection gets a `url`
+  template (`/blog/[slug]`). You list them and link to them.
+
+If you find yourself making `about`, `about-2`, `about-team`… stop — that's a
+collection.
+
+### 2. Collection + reference, or a block? (the important one)
+
+Both let you have "several of something". The difference is **identity**.
+
+> **Does this thing have its own identity — a life outside the page it appears on?**
+
+- **Yes → collection + reference.** It's an *entity*: it has its own URL, you
+  list it, you link to it, the *same instance* is reused in several places, and
+  editing it once updates it everywhere. Authors, categories, products, articles.
+  This is normalized data — one source of truth, pointed at by `reference`.
+
+  *Author is a collection. An article references its author. Change the author's
+  bio once → every article reflects it.*
+
+- **No → block.** It's *composition inside one entry*: page-building sections,
+  cards, a hero, FAQ rows. It exists only as part of its parent, it is not reused
+  elsewhere as the same instance, and it has no standalone URL. Each placement
+  **owns its own values** — copy, not link. This is denormalized, local content.
+
+  *A landing page's feature cards are a block (`multiple`). They only matter on
+  that page; nobody links to "card #2".*
+
+Rule of thumb — ask **"Would I ever link to it, list it on its own, or reuse the
+exact same instance in two places?"**
+Yes → collection+reference. No → block.
+
+Tie-breaker: if two pages must show the *same, synced* thing, it's a collection.
+If each page wants its *own copy* to edit freely, it's a block.
+
+### 3. Global or page?
+
+> **Does the same value appear on every page?**
+
+- **Same everywhere → global.** Navbar, footer, social links, SEO/Meta defaults,
+  brand. Edit once, the whole site updates. Globals are imported anywhere.
+- **Specific to one route → page.** Home's hero, the About story.
+
+### 4. Group or block?
+
+Both nest fields. The difference is **repetition**.
+
+- **`group`** — a *fixed, single* cluster of related fields, just for organizing:
+  an address (`street`, `city`, `zip`), a CTA (`label`, `url`). One of them, not
+  a list. Use it to keep related fields together.
+- **`block` (`multiple: true`)** — a *repeatable* list of composed instances:
+  sections, cards, rows. Use it whenever the editor needs "add another".
+
+(Need only an editor-side section heading, not nesting? Use a **`divider`** —
+it's purely presentational; fields after it stay flat.)
+
+### 5. Which field type for a value?
+
+| Need | Type |
+|------|------|
+| Short text (title, label, name) | `string` |
+| Long prose with formatting, links, images inline | `richtext` |
+| A picture / video / file | `media` (`accept`, `multiple?`) |
+| A URL with link text + external handling | `link` |
+| A point to another collection entry | `reference` (`collection`, `multiple?`) |
+| A fixed set of choices | `enum` (`options`) |
+| On/off | `boolean` |
+| A number / a date | `number` / `date` |
+| A CSS color (theming) | `color` |
+| URL-safe id derived from another field | `slug` (`from`) — **required on collections** |
+| A repeatable composed section | `block` (`multiple`) |
+| A fixed cluster of related fields | `group` |
+| Editor-only section heading | `divider` |
+
+Prefer **`richtext`** for body copy (it carries its own formatting) and
+**`string`** for anything you'll style yourself or compare/sort on.
+
+---
+
+## Conventions (what the Starter scaffolds)
+
+`okno init` scaffolds a **Starter**: `Meta`, `Navbar`, `Footer` globals and a
+`Home` page, ready to edit. You don't need to recreate them — but understand
+*why* they're globals (rule 3: same on every page), so you place new things
+correctly:
+
+- **`Meta`** (global) — `title`, `description`, `shareImage` (media), `favicon`
+  (media). Site-wide SEO/OG defaults, rendered into `<head>`.
+- **`Navbar`** (global) — `logo`, `links` (block `multiple`), `cta` (link).
+- **`Footer`** (global) — `text`, `links` (block `multiple`).
+
+A page can still *override* a Meta value with its own field; the global is the
+default. Per-page SEO = a page field that falls back to `Meta`.
+
+---
+
+## Rendering: the spread-to-edit pattern
+
+Import content from the virtual modules, then **spread the field onto the element
+that renders it**. The spread adds the `data-okno` boundary the editor needs; the
+child renders the value. Same value, two jobs, zero duplication.
+
+```ts
+import { home } from "okno:pages"
+import { articles } from "okno:collections"
+import { navbar, meta } from "okno:globals"
+```
+
+By value kind:
+
+```astro
+<!-- string / number: spread + render -->
+<h1 {...home.title}>{home.title}</h1>
+
+<!-- richtext: spread + set:html (it's an HTML string) -->
+<article {...home.body} set:html={home.body}></article>
+
+<!-- media: spread maps src/alt/dimensions onto the element -->
+<img {...home.cover} alt="" />
+
+<!-- link: spread maps url→href (+target/rel if external); child is the text -->
+<a {...home.cta}>{home.cta}</a>
+
+<!-- block array: {...item.slot} marks array membership (add/remove/reorder),
+     field spreads stay bare -->
+{home.cards.map((card) => (
+  <article {...card.slot}>
+    <h3 {...card.title}>{card.title}</h3>
+    <p {...card.subtitle}>{card.subtitle}</p>
+  </article>
+))}
+
+<!-- globals render the same way, anywhere -->
+<nav>{navbar.links.map((l) => <a {...l.link}>{l.link}</a>)}</nav>
+```
+
+> **The `.slot` rule.** Any time you iterate an okno array — a `multiple` block
+> field OR a `multiple` reference — spread `{...item.slot}` onto the element that
+> wraps each item. It marks the array-membership boundary (`data-okno-item`) the
+> editor needs to add, remove, and reorder items live. Field spreads inside stay
+> bare; `.slot` goes on the wrapper. Forget it and the content still renders, but
+> live structural edits silently break. (Scalar fields never take `.slot` — it
+> only exists on array items.)
+
+### References resolve to full items
+
+The build plugin replaces a stored reference id with the **full referenced
+item**, and its `data-okno` points at *that item*. So editing through a reference
+edits the entity, not the page:
+
+```astro
+<!-- single reference: home.author is the whole author entry -->
+<span {...home.author.name}>{home.author.name}</span>
+
+<!-- multiple reference: each is a full article; .slot marks membership -->
+{home.featured.map((a) => (
+  <a href={`/blog/${a.slug}`} {...a.slot}>
+    <img {...a.cover} alt="" />
+    <h3 {...a.title}>{a.title}</h3>
+  </a>
+))}
+```
+
+Resolution is **one level deep** (cycle-safe): an article resolves its `author`,
+but that author's *own* references are not re-resolved. Don't rely on
+`article.author.someOtherReference` being an object.
+
+### Live edits (optional)
+
+Wrapped values expose `.on()` — subscribe to patch the DOM without a reload:
+
+```ts
+home.title.on((v) => { document.querySelector("h1")!.textContent = String(v) })
+```
+
+### Production editor
+
+The editor auto-injects in dev. For the deployed build to ship it, the layout
+must import the boot module once:
+
+```astro
+<script>import "okno/boot"</script>
+```
+
+### Deploying
+
+okno produces static output — host it anywhere. On a git-connected host
+(Cloudflare Pages, Netlify, Vercel) build command is `bun run build` (or
+`npm run build`), output dir `dist`. Two rules specific to okno:
+
+- **Build only the production branch** (`main`). okno publishes by merging into
+  it, so every publish auto-rebuilds your live site — that pairing is the point.
+- **Disable builds/previews for the `okno` branch.** It's the drafts branch okno
+  commits to on *save* (the only branch okno writes to). Building it deploys
+  nothing useful, and because its infra can lag the production branch it will
+  often *fail* the build. On Cloudflare: Settings → Builds → Branch control →
+  build the production branch only (no preview deployments).
+
+---
+
+## Routing — the `url` field
+
+Every page and collection declares where it lives on the live site, via a `url`
+in the schema. This is the bridge that lets the editor map a browser URL back to
+the entry behind it (so editing works on the deployed page), and it drives the
+"open on site" links. **Set it to match your framework's actual route** — okno
+stores the mapping; your framework still owns the file that renders it.
+
+- **Pages — a literal path.** `home` → `url: "/"`, `about` → `url: "/about"`.
+- **Collections — a pattern with `[token]` segments.** Each `[token]` pulls a
+  slug from the item. `url: "/blog/[slug]"` uses the item's own slug;
+  `url: "/[category]/[slug]"` pulls `[category]` from a referenced item's slug
+  and `[slug]` from the item — so a collection can route under its category.
+
+```ts
+// schema.ts
+articles: {
+  name: "Articles",
+  fields: { /* …, */ slug: { type: "slug", from: "title" } },
+  url: "/blog/[slug]",          // ← matches src/pages/blog/[slug].astro
+}
+```
+
+The framework side stays ordinary. In Astro you still write the dynamic route
+and enumerate items in `getStaticPaths`, keyed by the same slug the `url`
+pattern uses:
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import { articles } from "okno:collections"
+export const getStaticPaths = () =>
+  articles.map((a) => ({ params: { slug: String(a.slug) }, props: { article: a } }))
+const { article } = Astro.props
+---
+<h1 {...article.title}>{article.title}</h1>
+```
+
+Rule of thumb: **the schema `url` pattern and the framework route file must agree**
+(`/blog/[slug]` ↔ `blog/[slug].astro`). The `slug` field is required on every
+collection precisely because it's what fills the `[token]`.
+
+---
+
+## Authoring entries (MCP)
+
+- One `write_entry` per entry. `content` is the fields object, matching the
+  schema. `created`/`updated` stamps are managed for you — don't set them.
+- **Collections need a slug.** The entry's filename is the slug:
+  `collections/articles/why-git.ts` → slug `why-git`.
+- **References store ids (slugs), not objects.** `category: "engineering"`,
+  `featured: ["why-git", "spread-to-edit"]`. The build resolves them.
+- **Media is `{ src, alt, width?, height? }`.** Point `src` at a file under
+  `okno/files/...` or an absolute URL.
+- **Localized fields** carry per-locale values; default locale first. Only fields
+  marked `localized` vary by locale.
+
+## A worked model — a blog
+
+> "Articles, with authors and categories, featured on the homepage."
+
+- **Authors** → collection (entities, listed, reused) — `name`, `slug`, `role`,
+  `bio`, `avatar`.
+- **Categories** → collection (entities, you filter/link by them) — `title`,
+  `slug`, `description`.
+- **Articles** → collection — `cover`, `title`, `slug`, `excerpt`, `content`
+  (richtext), `category` (reference → category), `author` (reference → author).
+- **Home** → page — `headline`, `description`, `image`, `featured` (reference →
+  articles, `multiple`).
+- **Navbar / Footer / Meta** → globals (from the Starter).
+
+Why no blocks here? Nothing is page-local composition — authors and categories
+have identity and are reused, so they're collections joined by references. Add a
+block only when you build a *page* out of arbitrary stacked sections.
+
+---
+
+## Checklist
+
+- [ ] `get_schema` read before any `write_schema`
+- [ ] Every collection has a `slug` field (`from` a title/name)
+- [ ] Entities reused/linked → collections+references; page-local composition → blocks
+- [ ] Site-wide values → globals (Meta/Navbar/Footer)
+- [ ] Each page/collection has a `url`; collection patterns (`/blog/[slug]`) match the framework route file
+- [ ] Templates spread every field; richtext via `set:html`; `.slot` on every iterated array item
+- [ ] Layout imports `okno/boot` for the prod editor
+- [ ] Told the user that publishing is their step, not yours

package/src/runtime/wrap.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test"
+import { __oknoResolveRefs } from "./wrap"
+
+describe("__oknoResolveRefs", () => {
+	test("single ref happy path", () => {
+		const raw = { author: "jane" }
+		const fields = { author: { type: "reference", collection: "authors" } }
+		const collections = { authors: [{ slug: "jane", name: "Jane" }] }
+		const result = __oknoResolveRefs(raw, fields, collections) as any
+		expect(result.author).toEqual({
+			__oknoRef: { path: "authors.jane", data: { slug: "jane", name: "Jane" } },
+		})
+	})
+
+	test("array refs with a missing id filtered out", () => {
+		const raw = { authors: ["jane", "unknown"] }
+		const fields = { authors: { type: "reference", collection: "authors" } }
+		const collections = { authors: [{ slug: "jane", name: "Jane" }] }
+		const result = __oknoResolveRefs(raw, fields, collections) as any
+		expect(result.authors).toHaveLength(1)
+		expect(result.authors[0].__oknoRef.path).toBe("authors.jane")
+	})
+
+	test("item with toJSON method — data is toJSON output, match by toJSON slug", () => {
+		const item = {
+			_raw: { slug: "bob", name: "Bob" },
+			toJSON() {
+				return this._raw
+			},
+		}
+		const raw = { author: "bob" }
+		const fields = { author: { type: "reference", collection: "people" } }
+		const collections = { people: [item] }
+		const result = __oknoResolveRefs(raw, fields, collections) as any
+		expect(result.author.__oknoRef.data).toEqual({ slug: "bob", name: "Bob" })
+		expect(result.author.__oknoRef.path).toBe("people.bob")
+	})
+
+	test("dash/underscore fallback — def.collection dashed, collections key underscored", () => {
+		const raw = { post: "hello" }
+		const fields = { post: { type: "reference", collection: "blog-posts" } }
+		const collections = { blog_posts: [{ slug: "hello", title: "Hello World" }] }
+		const result = __oknoResolveRefs(raw, fields, collections) as any
+		expect(result.post.__oknoRef.path).toBe("blog-posts.hello")
+		expect(result.post.__oknoRef.data).toEqual({ slug: "hello", title: "Hello World" })
+	})
+
+	test("non-reference field passes through untouched", () => {
+		const raw = { title: "Hello", author: "jane" }
+		const fields = {
+			title: { type: "text" },
+			author: { type: "reference", collection: "authors" },
+		}
+		const collections = { authors: [{ slug: "jane", name: "Jane" }] }
+		const result = __oknoResolveRefs(raw, fields, collections) as any
+		expect(result.title).toBe("Hello")
+	})
+
+	test("null id returns null (single ref)", () => {
+		const raw = { author: null }
+		const fields = { author: { type: "reference", collection: "authors" } }
+		const collections = { authors: [{ slug: "jane", name: "Jane" }] }
+		const result = __oknoResolveRefs(raw, fields, collections) as any
+		expect(result.author).toBeNull()
+	})
+
+	test("empty string id returns null", () => {
+		const raw = { author: "" }
+		const fields = { author: { type: "reference", collection: "authors" } }
+		const collections = { authors: [{ slug: "jane", name: "Jane" }] }
+		const result = __oknoResolveRefs(raw, fields, collections) as any
+		expect(result.author).toBeNull()
+	})
+
+	test("unknown id returns null (single ref)", () => {
+		const raw = { author: "nobody" }
+		const fields = { author: { type: "reference", collection: "authors" } }
+		const collections = { authors: [{ slug: "jane", name: "Jane" }] }
+		const result = __oknoResolveRefs(raw, fields, collections) as any
+		expect(result.author).toBeNull()
+	})
+})