create-june 0.0.1

package/README.md

@@ -0,0 +1,26 @@
+# create-june
+
+Scaffold a [June](https://june.build) app — **the agent-native React framework**.
+
+```bash
+npm create june my-app
+# or: bun create june my-app
+```
+
+One `route()` definition serves every audience:
+
+| humans | agents |
+| --- | --- |
+| streamed HTML, nested layouts, loading/error boundaries | the same routes as `.md` / `.json` |
+| hover prerender + view transitions, zero client JS | `llms.txt`, `sitemap.xml`, MCP tools at `/mcp` |
+
+The scaffold also ships an `AGENTS.md` (conventions for coding agents),
+plain-SQL migrations (the data layer's source of truth), and markdown content
+served to agents **verbatim** — the authored file, not a lossy conversion.
+
+> ⚠ **Pre-release.** The `june` framework package is not on npm yet; this
+> scaffold tracks the framework's development and currently runs inside the
+> [june repository](https://github.com/junebuild/june). Watch
+> [june.build](https://june.build) for the runnable release.
+
+MIT

package/bin.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// create-june — scaffold a June app (the agent-native React framework).
+// Non-interactive by design (CI/C3-friendly): `npm create june my-app` just works.
+import { cpSync, existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+
+const args = process.argv.slice(2).filter((a) => !a.startsWith("-"));
+const target = args[0] ?? "june-app";
+const dest = resolve(process.cwd(), target);
+const TEMPLATE = join(import.meta.dirname, "template");
+
+if (existsSync(dest)) {
+  console.error(`✗ ${target} already exists — refusing to overwrite.`);
+  process.exit(1);
+}
+if (!existsSync(TEMPLATE)) {
+  console.error("✗ template missing from package — please file an issue.");
+  process.exit(1);
+}
+
+cpSync(TEMPLATE, dest, { recursive: true });
+
+// Stamp the app name into every scaffolded file that mentions it.
+const name = basename(dest);
+const stamp = (dir) => {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) stamp(p);
+    else {
+      const text = readFileSync(p, "utf8");
+      if (text.includes("__APP_NAME__")) {
+        writeFileSync(p, text.replaceAll("__APP_NAME__", name));
+      }
+    }
+  }
+};
+stamp(dest);
+
+console.log(`
+✓ Created ${name}/
+
+  June is the agent-native React framework: one route() definition serves
+  humans (streamed HTML) AND agents (.md / .json / llms.txt / MCP tools).
+
+  ⚠ PRE-RELEASE: the \`june\` framework package is not on npm yet — this
+  scaffold shows the conventions and follows the framework's development.
+  Watch https://june.build and https://github.com/junebuild/june for the
+  runnable release. (The scaffold runs today inside the june repository.)
+
+  Explore:
+    ${target}/app/          routes, layouts, boundaries
+    ${target}/content/      markdown posts (served verbatim to agents as .md)
+    ${target}/db/           plain-SQL migrations (the data layer's truth)
+    ${target}/AGENTS.md     conventions for coding agents
+`);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "create-june",
+  "version": "0.0.1",
+  "description": "Scaffold a June app — the agent-native React framework. Every route serves humans (streamed HTML) and agents (markdown/JSON/MCP) from one definition.",
+  "type": "module",
+  "bin": {
+    "create-june": "./bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "template"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "prepublishOnly": "node scripts/sync-template.mjs"
+  },
+  "keywords": [
+    "june",
+    "react",
+    "rsc",
+    "framework",
+    "scaffold",
+    "agent",
+    "mcp",
+    "dual-audience"
+  ],
+  "homepage": "https://june.build",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/junebuild/june.git"
+  },
+  "license": "MIT"
+}

package/template/AGENTS.md

@@ -0,0 +1,60 @@
+# __APP_NAME__ — guide for coding agents
+
+You are working in a June app. June is dual-audience: routes serve humans (HTML)
+and agents (JSON/markdown/manifests) from ONE definition. This file is the
+agent-facing twin of README.md.
+
+## Commands
+- `bun run dev` — start the dev server (hot reload)
+- From the framework repo root: `bun test src/june` (framework tests), `bun run typecheck`
+
+## How to add things
+
+**A page** — create `app/<path>/page.tsx` exporting a `route()`:
+```tsx
+import { route } from "june/route";
+export default route({
+  async load(ctx) { return { /* data */ }; },        // ctx.params from [segments]
+  view: (data) => <main>…</main>,                     // HTML projection
+  json: (data) => data,                               // /path.json
+  md: (data) => "# …",                                // /path.md
+});
+```
+Conventions per directory: `layout.tsx` (wraps), `loading.tsx` (Suspense
+fallback for load()), `error.tsx` (recovery when load()/view() throws),
+`not-found.tsx`, `[param]/`, `[...rest]/` (params.rest = "a/b/c"), `(group)/`
+(invisible in URL), `_dir` (never routes).
+
+**A schema change** — write a NEW file `db/migrations/000N_name.sql` (plain
+SQLite SQL; DDL + backfill together; never edit an applied migration). It is
+applied on next boot, in filename order. The SQL you write is exactly what runs
+— there is no generator.
+
+**A blog post / content** — drop a markdown file in `content/posts/`:
+```md
+---
+title: My post
+date: 2026-06-12
+description: One line.
+tags: [a, b]
+---
+Body in plain markdown.
+```
+It appears in `/blog` (list, from frontmatter) and `/blog/<filename>` (rendered).
+The `.md` projection serves YOUR FILE verbatim — never edit rendered output;
+edit the source file. Keep frontmatter flat (`key: value`, `[a, b]` lists only).
+
+**An action/tool** — add a `defineAction({ id, description, input, run })` in
+`app/actions.ts`. It becomes: a UI server action AND an MCP tool on `/mcp` AND
+an entry in agent manifests. Write intent-shaped tools, not raw CRUD; return
+high-signal shapes, not row dumps.
+
+## Verify your work (oracles)
+- `GET /llms.txt` lists every route; `GET <route>.json` shows the data the view uses.
+- `POST /mcp` `{"method":"tools/list"}` shows your tools; `tools/call` executes one.
+- Writes to a table auto-invalidate route caches tagged `table:<name>` — no manual wiring.
+
+## Rules
+- Don't bypass `route()` projections with ad-hoc endpoints — agents discover routes, not handlers.
+- Don't edit applied migrations; add a new one.
+- Keep `view` human-shaped and `json`/`md` agent-shaped; they share `load()` so they can't drift.

package/template/README.md

@@ -0,0 +1,41 @@
+# __APP_NAME__
+
+A [June](../../README.md) app — dual-audience by default: every route serves
+humans (streamed HTML) *and* agents (JSON / markdown / agent manifests) from one
+definition.
+
+```bash
+bun run dev
+```
+
+| try | what you get |
+| --- | --- |
+| `/posts` | streamed HTML inside nested layouts (loading boundary while data loads) |
+| `/posts.json` | the same route as JSON |
+| `/posts/hello-june.md` | the same post as markdown |
+| `/llms.txt` | the agent's map of this site (auto-derived) |
+| `/mcp` | your server actions as MCP tools (`createPost`) |
+
+## Structure
+
+```
+june.config.ts            agent surface switches (everything defaults ON)
+dev.ts                    boot: serve(app/) + register actions
+db/
+  migrations/0001_*.sql   SQL is the structural truth — applied in order on boot
+app/
+  layout.tsx              root layout (wraps every page)
+  page.tsx                route(): view + md projections
+  not-found.tsx           404, rendered inside the layout chain
+  models/post.ts          domain model (june/db sqlite) + migration runner
+  actions.ts              server action == MCP tool (one definition)
+  posts/
+    loading.tsx           Suspense fallback while load() runs
+    page.tsx              route(): view + json + md, cached, tag-invalidated
+    [slug]/
+      page.tsx            dynamic segment
+      error.tsx           recovery UI when load() throws
+```
+
+Conventions reference: `docs/app-router.md`. Data-layer philosophy (why
+migrations are plain SQL): `docs/data-philosophy.md`.

package/template/app/actions.ts

@@ -0,0 +1,28 @@
+// A server action that is ALSO an agent tool: the UI posts it, /mcp lists and
+// executes it, the agent manifest advertises it. One definition, every surface.
+import { defineAction } from "june/agent";
+import { Posts } from "./models/post";
+
+export const createPost = defineAction({
+  id: "createPost",
+  description: "Publish a new post with a unique slug, a title, and a markdown body.",
+  input: {
+    type: "object",
+    properties: {
+      slug: { type: "string", description: "URL slug, e.g. my-first-post" },
+      title: { type: "string", description: "Post title" },
+      body: { type: "string", description: "Markdown body" },
+    },
+    required: ["slug", "title"],
+  },
+  async run(input: { slug: string; title: string; body?: string }) {
+    // Writing `posts` auto-invalidates every cache entry tagged table:posts —
+    // the /posts list cache below drops without manual wiring.
+    return Posts.insert({
+      slug: input.slug,
+      title: input.title,
+      body: input.body ?? "",
+      published: 1,
+    });
+  },
+});

package/template/app/blog/[slug]/page.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import { join } from "node:path";
+import { route } from "june/route";
+import { entry } from "june/content";
+
+const POSTS = join(import.meta.dirname, "../../../content/posts");
+
+export default route({
+  metadata: ({ post }) => ({
+    title: String(post.data.title ?? post.slug),
+    description: String(post.data.description ?? ""),
+    openGraph: { type: "article" },
+  }),
+  async load(ctx) {
+    const post = entry(POSTS, ctx.params.slug);
+    if (!post) throw new Error(`No post "${ctx.params.slug}"`);
+    return { post };
+  },
+  view: ({ post }) => (
+    <article>
+      <h1>{String(post.data.title)}</h1>
+      <p><small>{String(post.data.date)}</small></p>
+      <div dangerouslySetInnerHTML={{ __html: post.html }} />
+      <p><a href="/blog">← all posts</a></p>
+    </article>
+  ),
+  // THE differentiator: the .md projection is the AUTHORED FILE, verbatim.
+  md: ({ post }) => post.original,
+  json: ({ post }) => ({ slug: post.slug, ...post.data, body: post.body }),
+});

package/template/app/blog/page.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import { join } from "node:path";
+import { route } from "june/route";
+import { collection } from "june/content";
+
+const POSTS = join(import.meta.dirname, "../../content/posts");
+
+export default route({
+  metadata: { title: "Blog", description: "Posts — rendered for humans, verbatim markdown for agents." },
+  load: () => ({ posts: collection(POSTS) }),
+  view: ({ posts }) => (
+    <main>
+      <h1>Blog</h1>
+      <ul>
+        {posts.map((p) => (
+          <li key={p.slug} style={{ marginBottom: 8 }}>
+            <a href={`/blog/${p.slug}`}>{String(p.data.title)}</a>
+            <br />
+            <small>{String(p.data.date)} — {String(p.data.description ?? "")}</small>
+          </li>
+        ))}
+      </ul>
+    </main>
+  ),
+  json: ({ posts }) => ({
+    posts: posts.map((p) => ({ slug: p.slug, ...p.data })),
+  }),
+  md: ({ posts }) =>
+    "# Blog\n\n" + posts.map((p) => `- [${p.data.title}](/blog/${p.slug}) — ${p.data.date}`).join("\n") + "\n",
+});

package/template/app/layout.tsx

@@ -0,0 +1,14 @@
+import React from "react";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div data-layout="root">
+      <nav style={{ display: "flex", gap: 16, padding: "14px 20px", borderBottom: "1px solid #e4e2da" }}>
+        <a href="/" style={{ fontWeight: 600 }}>__APP_NAME__</a>
+        <a href="/posts">Posts</a>
+        <a href="/llms.txt">llms.txt</a>
+      </nav>
+      {children}
+    </div>
+  );
+}

package/template/app/models/post.ts

@@ -0,0 +1,35 @@
+// Domain model — a model is a domain concern, not a route concern. Both
+// /posts and /posts/[slug] import it.
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { sql, type Table } from "june/db";
+
+export type Post = {
+  id: number;
+  slug: string;
+  title: string;
+  body: string;
+  published: number;
+  created_at: string;
+};
+
+const root = join(import.meta.dirname, "../..");
+const db = sql.load(join(root, "db/app.db"));
+
+// db/migrations/*.sql is the structural truth (docs/data-philosophy.md):
+// applied in filename order, tracked in _migrations. No diff engine — the SQL
+// you read is the SQL that ran.
+const dir = join(root, "db/migrations");
+db.db.run("CREATE TABLE IF NOT EXISTS _migrations (name TEXT PRIMARY KEY)");
+for (const f of readdirSync(dir).filter((f) => f.endsWith(".sql")).sort()) {
+  const applied = db.db.query("SELECT 1 FROM _migrations WHERE name = ?").get(f);
+  if (applied) continue;
+  db.db.transaction(() => {
+    // exec(), not run(): migration files are MULTI-statement (DDL + seed DML);
+    // prepare()-based run executes only the first statement on node:sqlite.
+    db.db.exec(readFileSync(join(dir, f), "utf8"));
+    db.db.run("INSERT INTO _migrations (name) VALUES (?)", [f]);
+  })();
+}
+
+export const Posts = db.posts as Table<Post>;

package/template/app/not-found.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+
+export default function NotFound({ pathname }: { pathname: string }) {
+  return (
+    <main data-boundary="not-found">
+      <h1>Not found</h1>
+      <p>
+        Nothing lives at <code>{pathname}</code>. Try <a href="/posts">/posts</a>.
+      </p>
+    </main>
+  );
+}

package/template/app/page.tsx

@@ -0,0 +1,18 @@
+import React from "react";
+import { route } from "june/route";
+
+export default route({
+  view: () => (
+    <main>
+      <h1>__APP_NAME__</h1>
+      <p>A June app. Humans get this page; agents get the same routes as data:</p>
+      <ul>
+        <li><code>/posts.json</code> — the list as JSON</li>
+        <li><code>/posts/hello-june.md</code> — a post as markdown</li>
+        <li><code>/llms.txt</code> · <code>/mcp</code> — discovery + tools</li>
+      </ul>
+    </main>
+  ),
+  md: () =>
+    "# __APP_NAME__\n\nA June app. Routes speak HTML to humans and JSON/markdown/manifests to agents.\n",
+});

package/template/app/posts/[slug]/error.tsx

@@ -0,0 +1,15 @@
+import React from "react";
+
+export default function PostError({ error }: { error: unknown }) {
+  return (
+    <main data-boundary="error">
+      <h1>Could not load this post</h1>
+      <p>
+        <code>{String((error as Error)?.message ?? error)}</code>
+      </p>
+      <p>
+        <a href="/posts">Back to all posts</a>
+      </p>
+    </main>
+  );
+}

package/template/app/posts/[slug]/page.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import { route } from "june/route";
+import { Posts } from "../../models/post";
+
+export default route({
+  metadata: ({ post }) => ({ title: post.title, openGraph: { type: "article" } }),
+  async load(ctx) {
+    const post = await Posts.findBy({ slug: ctx.params.slug, published: 1 });
+    if (!post) throw new Error(`No post named "${ctx.params.slug}"`);
+    return { post };
+  },
+  view: ({ post }) => (
+    <article>
+      <h1>{post.title}</h1>
+      <p>{post.body}</p>
+      <p>
+        <small>{post.created_at}</small> · <a href="/posts">all posts</a>
+      </p>
+    </article>
+  ),
+  json: ({ post }) => post,
+  md: ({ post }) => `# ${post.title}\n\n${post.body}\n`,
+});

package/template/app/posts/loading.tsx

@@ -0,0 +1,5 @@
+import React from "react";
+
+export default function Loading() {
+  return <p data-boundary="loading">Loading posts…</p>;
+}

package/template/app/posts/page.tsx

@@ -0,0 +1,26 @@
+import React from "react";
+import { route } from "june/route";
+import { Posts } from "../models/post";
+
+export default route({
+  metadata: { title: "Posts", description: "All published posts." },
+  async load() {
+    return { posts: await Posts.where({ published: 1 }).all() };
+  },
+  view: ({ posts }) => (
+    <main>
+      <h1>Posts</h1>
+      <ul>
+        {posts.map((p) => (
+          <li key={p.id}>
+            <a href={`/posts/${p.slug}`}>{p.title}</a>
+          </li>
+        ))}
+      </ul>
+    </main>
+  ),
+  json: ({ posts }) => ({ posts: posts.map(({ id, slug, title }) => ({ id, slug, title })) }),
+  md: ({ posts }) => "# Posts\n\n" + posts.map((p) => `- [${p.title}](/posts/${p.slug})`).join("\n") + "\n",
+  // Cached until a write to `posts` invalidates the tag (e.g. the createPost tool).
+  cache: { ttl: 60, tags: ["table:posts"] },
+});

package/template/content/posts/2026-06-09-writing-with-agents.md

@@ -0,0 +1,9 @@
+---
+title: Writing with agents
+date: 2026-06-09
+description: Notes on a blog whose first reader is a crawler with taste.
+tags: [agents]
+---
+
+Half the readers of this blog will be machines. June treats that as a feature:
+every post advertises itself in `llms.txt` and serves clean markdown.

package/template/content/posts/2026-06-10-hello-content.md

@@ -0,0 +1,17 @@
+---
+title: Content as files, audiences as projections
+date: 2026-06-10
+description: One markdown file. Humans get rendered HTML; agents get the file itself.
+tags: [content, dual-audience]
+---
+
+This post is a plain markdown file in `content/posts/`.
+
+- You are reading the **rendered HTML** projection.
+- An agent fetching this URL with `.md` gets the **authored file, verbatim** —
+  frontmatter included. No lossy HTML-to-markdown conversion.
+
+```ts
+// the whole route:
+const post = entry(POSTS, ctx.params.slug);
+```

package/template/db/migrations/0001_create_posts.sql

@@ -0,0 +1,15 @@
+-- SQL migrations are the structural truth (see docs/data-philosophy.md).
+-- DDL + seed (DML) co-located, applied in order, tracked in _migrations.
+CREATE TABLE posts (
+  id INTEGER PRIMARY KEY,
+  slug TEXT NOT NULL UNIQUE,
+  title TEXT NOT NULL,
+  body TEXT NOT NULL DEFAULT '',
+  published INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT INTO posts (slug, title, body, published) VALUES
+  ('hello-june', 'Hello, June', 'This post was created by db/migrations/0001 — plain SQL is the structural truth.', 1),
+  ('dual-audience', 'Dual-audience by default', 'Every route here also speaks JSON, markdown, and agent manifests. Try /posts.json or /posts/hello-june.md.', 1),
+  ('draft-notes', 'Draft notes', 'Unpublished drafts stay out of every list and projection.', 0);

package/template/dev.ts

@@ -0,0 +1,14 @@
+import { join } from "node:path";
+import { serve } from "june/server";
+import config from "./june.config";
+import "./app/actions"; // register actions (= agent tools) before the first request
+
+const server = serve({
+  appDir: join(import.meta.dirname, "app"),
+  pageConvention: true,
+  agent: config.agent,
+});
+
+console.log(`__APP_NAME__ on http://localhost:${server.port}`);
+console.log("human:  /  /posts  /posts/hello-june");
+console.log("agent:  /posts.json  /posts/hello-june.md  /llms.txt  /mcp");

package/template/june.config.ts

@@ -0,0 +1,22 @@
+import { defineJune } from "june/config";
+
+// Dual-audience is ON by default — this file exists to turn things off, not on.
+//   agent.discovery  llms.txt, sitemap.xml, api-catalog, Link header
+//   agent.mcp        the /mcp endpoint (your actions as tools)
+//   agent.webmcp     in-page tools for browser-resident agents
+export default defineJune({
+  // Site-wide <head> defaults; per-route `metadata` merges over these.
+  site: { name: "__APP_NAME__", titleTemplate: "%s — __APP_NAME__" },
+  agent: { enabled: true, discovery: true, mcp: true, webmcp: true },
+  // Hover-intent speculation (these ARE the defaults — shown so you can see
+  // and change them). Agent surfaces (*.md/*.json/*.txt/*.xml//mcp) are always
+  // excluded. Heavy pages? prerender: "conservative" (mousedown) or false.
+  speculation: { prerender: "moderate", prefetch: "moderate", exclude: [] },
+  // Cross-document View Transitions: MPA navigations cross-fade, zero JS.
+  // (Also a default — visible here so you can turn it off.)
+  viewTransitions: true,
+  // Early Hints (RFC 8297): list critical assets to preload while the server
+  // renders, e.g. "</fonts/inter.woff2>; rel=preload; as=font; crossorigin".
+  // CF upgrades the Link header to a real 103; June's Node host emits 103 itself.
+  earlyHints: [],
+});

package/template/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --hot dev.ts"
+  },
+  "dependencies": {
+    "react": "^19.0.0"
+  }
+}