create-patties 0.0.6 → 0.0.8

package/templates/_codex/AGENTS.md

@@ -1,48 +1,28 @@
-# {{PROJECT_NAME}}
+# {{name}}
 
-Built with Patties — Bun-native full-stack meta-framework.
+Built with Patties — a Bun-native full-stack meta-framework.
 
-> This file is read by Codex CLI and other AGENTS.md-aware tools. Patties also
-> auto-regenerates a live inventory `AGENTS.md` on `patties build` — trust the
-> generated inventory for routes/islands/agents/tools, and this file for rules
-> and conventions.
+> Codex reads this file. The conventions below are split into focused
+> files under `.codex/rules/`; treat the links here as authoritative —
+> open each one when its topic is in scope for the task at hand.
 
-## Stack
+## Conventions
 
-Bun runtime · `Bun.serve({ routes })` dispatcher · React renderer (`react-dom/server` + `react-dom/client`) · `{{DEPLOY_TARGET}}` deploy.
+- [Bun-native](.codex/rules/bun-native.md) — reach for Bun primitives, not Node-era replacements.
+- [Web-standards boundary](.codex/rules/web-standards-boundary.md) — handlers use standard Request / Response; `PattiesContext` stays thin.
+- [Filesystem routing](.codex/rules/filesystem-routing.md) — how `app/routes/` becomes URLs.
+- [Islands](.codex/rules/islands.md) — when and how to use `app/islands/*.tsx`.
+- [Build-time discovery](.codex/rules/build-time-discovery.md) — discovery happens at build time, not at request time.
+- [Optional AI dependency](.codex/rules/optional-ai.md) — keep `@anthropic-ai/sdk` import-disjoint from non-AI code paths.
+- [Patties CLI](.codex/rules/patties-cli.md) — `patties dev / build / start / deploy / secret`.
 
-## File conventions
+## Live inventory
 
-| Path | Becomes |
-|---|---|
-| `app/routes/index.tsx` | `/` |
-| `app/routes/about.tsx` | `/about` |
-| `app/routes/hotels/[city].tsx` | `/hotels/:city` |
-| `app/routes/api/revenue.ts` | `/api/revenue` |
-| `app/islands/counter.tsx` | interactive island `Counter` |
-| `app/agents/booking.ts` | agent `booking` |
-| `app/tools/search.ts` | MCP tool `search` |
-| `app/middleware.ts` | global middleware |
-| `patties.config.ts` | framework config |
+The block below is regenerated by `patties build` from the actual
+contents of `app/`. Hand-edited content above the
+`<!-- patties:generated -->` marker is preserved across regenerations;
+everything below it is owned by the generator.
 
-Files starting with `_` are private and never routed. The URL prefix `/__patties_*` and output directory `/_patties/*` are reserved.
-
-## Critical rules
-
-1. Never import from `"next"`.
-2. Never use Node.js `http`, `fs.watch`, or `chokidar`. Use `Bun.serve` and `bun --watch`.
-3. Never use webpack or vite. Use `Bun.build`.
-4. Use React for rendering. Server: `react-dom/server.renderToReadableStream`. Client: `react-dom/client.hydrateRoot`. Never `renderToPipeableStream` or `renderToString`. Never `hono/jsx` or `hono/jsx/dom`.
-5. `tsconfig.json` sets `"jsx": "react-jsx"` and `"jsxImportSource": "react"` — no manual `import React` in user code.
-6. All routes are plain `(req: Request, ctx: PattiesContext) => Response | Promise<Response>`. Never import from `"hono"`.
-7. Islands live in `app/islands/` — no exceptions.
-8. API routes export named `GET`, `POST`, `PUT`, `DELETE` functions. Default exports are reserved for page components.
-9. Middleware default-exports a `Middleware = (req, ctx, next) => Promise<Response>`. Never `MiddlewareHandler` from Hono.
-10. Use Bun primitives for I/O: `Bun.file`, `Bun.write`, `Bun.spawn`, `Bun.CryptoHasher`, `Bun.env`, `Bun.password`, `bun:sqlite`, `Bun.sql`, `Bun.RedisClient`, `Bun.S3Client`. `node:fs` only when no Bun built-in exists.
-
-## How to run
-
-- `bun install`
-- `bun dev` — start the dev server
-- `bun build` — build for production
-- `bun test`
+<!-- patties:generated -->
+<!-- The block below is rewritten by `patties build`. Do not edit by hand. -->
+<!-- /patties:generated -->

package/templates/default/README-template.md

@@ -1,16 +1,170 @@
-# Patties app
+# {{name}}
 
-Bun-native full-stack app. Generated by `create-patties`.
+Built with [Patties](https://github.com/bihaviour-ai/bun-patties-framework) — a
+Bun-native full-stack meta-framework.
 
-## Develop
+<!-- if:scaffold=demo -->
+## What you got
 
+An interactive todo demo:
+
+- `app/routes/index.tsx` — server-rendered page that mounts the island.
+- `app/islands/TodoApp.tsx` — `useState`-based todo list, hydrated in the
+  browser.
+- `app/server.ts` — dev entry that wires the router into `Bun.serve`.
+
+## Run it
+
+```sh
+bun install      # if you used --no-install
+bun dev          # → http://localhost:3000
+```
+
+> **Heads up — dev mode currently only does SSR.** The todo list will render
+> but the buttons won't react to clicks under `bun dev`. To see the island
+> hydrate and the demo actually work, build and serve:
+>
+> ```sh
+> bun run build
+> bun start
+> ```
+>
+> Full dev-mode hydration is tracked under framework spec 18 and will land
+> in a future Patties release — at that point `bun dev` will be enough.
+
+## Try editing
+
+1. Open `app/routes/index.tsx`, change the heading text, save. The browser
+   reloads (HMR).
+2. Open `app/islands/TodoApp.tsx`, change the initial todo list or input
+   placeholder, save, rebuild with `bun run build && bun start`, and try it.
+
+## Remove the demo when you're ready
+
+The todo demo exists to show you state hydration. When you start your real
+app, delete it:
+
+```sh
+rm app/islands/TodoApp.tsx
 ```
-bun install
-bun dev
+
+Then replace `app/routes/index.tsx` with whatever your landing page should
+be — a minimal version:
+
+```tsx
+export default function Index(): JSX.Element {
+	return <main><h1>Hello from {{name}}</h1></main>;
+}
+```
+
+If you don't need any islands at all, you can also delete the empty
+`app/islands/` directory. You can re-scaffold without the demo at any time
+using `bunx create-patties@latest <new-name> --blank`.
+<!-- /if -->
+<!-- if:scaffold=blank -->
+## What you got
+
+A minimal hello-world Patties app:
+
+- `app/routes/index.tsx` — server-rendered landing page.
+- `app/server.ts` — dev entry that wires the router into `Bun.serve`.
+
+## Run it
+
+```sh
+bun install      # if you used --no-install
+bun dev          # → http://localhost:3000
 ```
 
-## Build
+## Add your first interactive feature
+
+Create `app/islands/` and drop in a component that uses `useState` or
+`useEffect`. Import it from a route file under `app/routes/`. Islands hydrate
+on the client; everything else runs server-only.
+
+> Note: full dev-mode island hydration is tracked under framework spec 18
+> and lands in a future Patties release. Until then, build + start to see
+> islands react: `bun run build && bun start`.
+<!-- /if -->
 
+## Project layout
+
+```
+app/
+  routes/        # filesystem-routed pages and API handlers
+  islands/       # interactive client components
+  server.ts      # dev entry — wires the router into Bun.serve
+patties.config.ts
+package.json
+tsconfig.json
 ```
+
+## Build for production
+
+```sh
 bun run build
 ```
+
+Build artifacts land in `.patties/`. Run the server bundle with:
+
+```sh
+bun .patties/server/server-entry.js
+```
+
+<!-- if:deploy=cloudflare -->
+## Deploy
+
+This project is configured for **Cloudflare** deployment. See the
+`@patties/deploy-cloudflare` plugin docs for the next steps.
+<!-- /if -->
+<!-- if:deploy=vercel -->
+## Deploy
+
+This project is configured for **Vercel** deployment. See the
+`@patties/deploy-vercel` plugin docs for the next steps.
+<!-- /if -->
+<!-- if:deploy=deno -->
+## Deploy
+
+This project is configured for **Deno Deploy**. See the
+`@patties/deploy-deno` plugin docs for the next steps.
+<!-- /if -->
+<!-- if:deploy=netlify -->
+## Deploy
+
+This project is configured for **Netlify Edge**. See the
+`@patties/deploy-netlify` plugin docs for the next steps.
+<!-- /if -->
+<!-- if:deploy=bun -->
+## Deploy
+
+This project ships as a standalone Bun bundle. Run `bun run build` then
+deploy the contents of `.patties/` to any host that runs Bun.
+<!-- /if -->
+
+<!-- if:agent=claude -->
+## Claude Code is set up
+
+`CLAUDE.md` at the project root describes the framework conventions for Claude
+Code. `.claude/settings.json` allow-lists the commands you'll typically need
+(`bun`, `bunx`, `patties`). `.claude/hooks/biome-check.sh` runs Biome after
+every edit if you install it (`bun add -d @biomejs/biome`).
+
+Launch a session with `claude` in this directory.
+<!-- /if -->
+<!-- if:agent=codex -->
+## Codex is set up
+
+`AGENTS.md` at the project root describes the framework conventions for
+Codex CLI and other AGENTS.md-aware tools. Patties regenerates this file on
+`patties build` while preserving sections you mark with
+`<!-- patties:user --> ... <!-- /patties:user -->`.
+
+Launch a session with `codex` in this directory.
+<!-- /if -->
+
+## Learn more
+
+- Patties docs: https://bun-patties.com
+- Bun: https://bun.sh
+- React 19: https://react.dev

package/templates/default/app/islands/TodoApp.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import { useState } from "react";
+
+interface Todo {
+	id: number;
+	text: string;
+	done: boolean;
+}
+
+export default function TodoApp(): JSX.Element {
+	const [todos, setTodos] = useState<Todo[]>([
+		{ id: 1, text: "edit app/routes/index.tsx", done: false },
+		{ id: 2, text: "edit app/islands/TodoApp.tsx", done: false },
+		{ id: 3, text: "delete this demo when you're ready", done: false },
+	]);
+	const [draft, setDraft] = useState("");
+
+	function add(): void {
+		const text = draft.trim();
+		if (!text) return;
+		setTodos([...todos, { id: Date.now(), text, done: false }]);
+		setDraft("");
+	}
+
+	function toggle(id: number): void {
+		setTodos(todos.map((t) => (t.id === id ? { ...t, done: !t.done } : t)));
+	}
+
+	function remove(id: number): void {
+		setTodos(todos.filter((t) => t.id !== id));
+	}
+
+	return (
+		<section aria-label="Todo demo">
+			<form
+				onSubmit={(e) => {
+					e.preventDefault();
+					add();
+				}}
+			>
+				<input
+					type="text"
+					value={draft}
+					onChange={(e) => setDraft(e.target.value)}
+					placeholder="What needs doing?"
+					aria-label="New todo"
+				/>
+				<button type="submit">Add</button>
+			</form>
+			<ul>
+				{todos.map((t) => (
+					<li key={t.id}>
+						<label>
+							<input
+								type="checkbox"
+								checked={t.done}
+								onChange={() => toggle(t.id)}
+							/>
+							<span
+								style={{ textDecoration: t.done ? "line-through" : "none" }}
+							>
+								{t.text}
+							</span>
+						</label>
+						<button
+							type="button"
+							onClick={() => remove(t.id)}
+							aria-label="Remove"
+						>
+							×
+						</button>
+					</li>
+				))}
+			</ul>
+			<p>
+				<small>
+					{todos.filter((t) => !t.done).length} of {todos.length} remaining
+				</small>
+			</p>
+		</section>
+	);
+}

package/templates/default/app/routes/index.tsx

@@ -1,10 +1,21 @@
-import Counter from "../islands/Counter.tsx";
+import TodoApp from "../islands/TodoApp.tsx";
 
 export default function Index(): JSX.Element {
 	return (
 		<main>
-			<h1>Hello from Patties</h1>
-			<Counter />
+			<h1>Welcome to Patties</h1>
+			<p>
+				This page is server-rendered. The list below is a client island —{" "}
+				<code>app/islands/TodoApp.tsx</code> — hydrated in the browser.
+			</p>
+			<TodoApp />
+			<hr />
+			<p>
+				<small>
+					When you're ready to start your real app, see the "Remove the demo"
+					section of <code>README.md</code>.
+				</small>
+			</p>
 		</main>
 	);
 }

package/templates/default/app/server.ts

@@ -0,0 +1,25 @@
+import type { DevServer } from "patties/dev";
+import { createRenderer } from "patties/render";
+import { createRouter } from "patties/router";
+import { startServer } from "patties/server";
+
+interface StartOpts {
+	devServer: DevServer;
+	port: number;
+	host: string;
+	appDir: string;
+}
+
+export default async function start(opts: StartOpts): Promise<void> {
+	const renderer = createRenderer({ dev: true });
+	const router = await createRouter({ appDir: opts.appDir, renderer });
+
+	startServer({
+		port: opts.port,
+		hostname: opts.host,
+		dev: true,
+		devServer: opts.devServer,
+		routes: router.routes,
+		fallback: router.fallback,
+	});
+}

package/templates/default/app/islands/Counter.tsx

@@ -1,12 +0,0 @@
-"use client";
-
-import { useState } from "react";
-
-export default function Counter(): JSX.Element {
-	const [n, setN] = useState(0);
-	return (
-		<button type="button" onClick={() => setN(n + 1)}>
-			clicked {n} times
-		</button>
-	);
-}