create-patties 0.0.8 → 0.0.10

package/README.md

@@ -9,7 +9,7 @@ bunx create-patties@latest my-app
 
 Runs an interactive prompt (project name, agent overlay, demo template,
 runtime target, deploy target), then scaffolds, installs, and gets you
-to `bun dev` in one shot.
+to `bunx patties dev` in one shot.
 
 ## Options
 

package/bin/create-patties.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env bun
+export {};
+
 if (typeof Bun === "undefined") {
 	console.error(
 		"create-patties requires Bun. Install Bun first: https://bun.sh",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-patties",
-	"version": "0.0.8",
+	"version": "0.0.10",
 	"type": "module",
 	"description": "Scaffolder for new Patties projects.",
 	"bin": {
@@ -16,6 +16,11 @@
 		"README.md",
 		"CHANGELOG.md"
 	],
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check ."
+	},
 	"engines": {
 		"bun": ">=1.0.0"
 	}

package/src/index.ts

@@ -12,6 +12,32 @@ import {
 } from "./prompts.ts";
 import { renderTemplatesInTree } from "./readme.ts";
 
+// Step logger — visible progress so the user can see what scaffolding does.
+// Honors NO_COLOR; degrades gracefully on non-TTY streams.
+function colorOn(): boolean {
+	if (process.env.NO_COLOR) return false;
+	return Boolean((process.stdout as NodeJS.WriteStream).isTTY);
+}
+const COL = colorOn();
+const c = {
+	dim: (s: string) => (COL ? `\x1b[2m${s}\x1b[0m` : s),
+	green: (s: string) => (COL ? `\x1b[32m${s}\x1b[0m` : s),
+	cyan: (s: string) => (COL ? `\x1b[36m${s}\x1b[0m` : s),
+	bold: (s: string) => (COL ? `\x1b[1m${s}\x1b[0m` : s),
+};
+function step(msg: string): void {
+	process.stdout.write(`  ${c.green("✓")} ${msg}\n`);
+}
+function pending(msg: string): void {
+	process.stdout.write(`  ${c.dim("…")} ${msg}\n`);
+}
+function header(msg: string): void {
+	process.stdout.write(`\n${c.bold(c.cyan("▲"))} ${msg}\n\n`);
+}
+function fmtMs(ms: number): string {
+	return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+
 interface Args {
 	name?: string;
 	template: AgentTemplate;
@@ -86,22 +112,33 @@ export async function run(argv: string[]): Promise<number> {
 
 	probeTools();
 
+	header(`create-patties — scaffolding ${c.bold(args.name)}`);
+
 	await Bun.$`mkdir -p ${targetDir}`.quiet();
+	step(`created directory ${c.dim(targetDir)}`);
+
 	await Bun.$`cp -R ${baseDir}/. ${targetDir}`.quiet();
+	step(`copied base template ${c.dim("(default)")}`);
 
 	await renameTemplateFiles(targetDir);
 	await writePackageJson(targetDir, args.name);
+	step(`wrote package.json ${c.dim(`(name: ${args.name})`)}`);
 	await patchPattiesConfig(targetDir, args);
+	step(`patched patties.config.ts ${c.dim(`(target: ${args.target})`)}`);
 
 	if (args.template !== "none") {
 		const overlay = resolve(TEMPLATES_ROOT, `_${args.template}`);
 		if (existsSync(overlay)) {
 			await Bun.$`cp -R ${overlay}/. ${targetDir}`.quiet();
+			step(`applied agent overlay ${c.dim(`(${args.template})`)}`);
 		}
 	}
 
 	if (args.scaffold === "blank") {
 		await applyBlankScaffold(targetDir);
+		step("applied blank scaffold (no demo)");
+	} else {
+		step("included interactive todo demo");
 	}
 
 	await renderTemplatesInTree(targetDir, {
@@ -111,9 +148,28 @@ export async function run(argv: string[]): Promise<number> {
 		deploy: args.deploy,
 		scaffold: args.scaffold,
 	});
+	const manifestName =
+		args.template === "codex"
+			? "AGENTS.md"
+			: args.template === "claude"
+				? "CLAUDE.md"
+				: "manifest";
+	step(`rendered template variables (README, ${manifestName}, …)`);
 
 	if (args.install) {
-		await Bun.$`bun install`.cwd(targetDir).quiet().nothrow();
+		pending("installing dependencies (bun install)…");
+		const t0 = performance.now();
+		const proc = await Bun.$`bun install`.cwd(targetDir).quiet().nothrow();
+		const dt = performance.now() - t0;
+		if (proc.exitCode === 0) {
+			step(`installed dependencies ${c.dim(`(${fmtMs(dt)})`)}`);
+		} else {
+			step(
+				`bun install exited with code ${proc.exitCode} — you may need to retry it manually`,
+			);
+		}
+	} else {
+		step(`skipped ${c.dim("`bun install`")} (--no-install)`);
 	}
 
 	let gitSkippedReason: string | undefined;
@@ -125,14 +181,15 @@ export async function run(argv: string[]): Promise<number> {
 				.cwd(targetDir)
 				.quiet()
 				.nothrow();
+			step("initialized git and committed");
 		} else {
 			gitSkippedReason = "git-missing";
 		}
 	}
 
 	const nextSteps = args.git
-		? `\n  cd ${args.name}\n  bun dev\n`
-		: `\n  cd ${args.name}\n  bun dev\n\n  # when you're ready to track this in git:\n  git init && git add -A && git commit -m "initial commit"\n`;
+		? `\n  cd ${args.name}\n  bunx patties dev\n`
+		: `\n  cd ${args.name}\n  bunx patties dev\n\n  # when you're ready to track this in git:\n  git init && git add -A && git commit -m "initial commit"\n`;
 	process.stdout.write(`\n✓ created ${args.name}\n${nextSteps}`);
 	if (gitSkippedReason === "git-missing") {
 		stderr("create-patties: `git` not found — skipping `git init`.");
@@ -294,10 +351,18 @@ async function patchPattiesConfig(dir: string, args: Args): Promise<void> {
 	const path = `${dir}/patties.config.ts`;
 	if (!(await Bun.file(path).exists())) return;
 	const current = await Bun.file(path).text();
-	const next = current.replace(
+	let next = current.replace(
 		/target:\s*"(bun|edge)"/,
 		`target: "${args.target}"`,
 	);
+	// Point the agent manifest at the file the chosen agent already reads.
+	// Default (claude / none) leaves the framework default ("CLAUDE.md").
+	if (args.template === "codex" && !/agentsMd:/.test(next)) {
+		next = next.replace(
+			/target:\s*"(bun|edge)",?\n/,
+			(m) => `${m.replace(/,?\n$/, ",\n")}\tagentsMd: { path: "AGENTS.md" },\n`,
+		);
+	}
 	if (next !== current) await Bun.write(path, next);
 }
 

package/templates/_claude/.claude/rules/islands.md

@@ -7,25 +7,39 @@ parts of a page that need browser-side interactivity (`useState`,
 - **Where they live:** `app/islands/*.tsx`. Files outside this
   directory are server-only and never ship to the browser.
 - **How to mark one:** start the file with `"use client";` and
-  default-export a React component. The framework will register it,
-  bundle the client code, and inject the hydration script when the
-  component is rendered from a route.
-- **How to use one:** import the component from a route file:
+  default-export a React component. The framework auto-registers it,
+  bundles its client code, and serves the chunk under
+  `/_patties/client/*` (in dev via `setupDevClient`; in production via
+  `patties build`).
+- **How to use one:** import the component from a route file and
+  wrap each use-site in `<Island name="…">…</Island>` from
+  `patties/render`. The wrapper emits the `data-island` marker + props
+  sibling that the client runtime scans for — without it the markup
+  SSRs fine but never hydrates.
+
   ```tsx
+  import { Island } from "patties/render";
   import TodoApp from "../islands/TodoApp.tsx";
 
   export default function Index(): JSX.Element {
-    return <main><TodoApp /></main>;
+    return (
+      <main>
+        <Island name="TodoApp">
+          <TodoApp />
+        </Island>
+      </main>
+    );
   }
   ```
-- **Today's gap (`bun dev`):** dev mode SSRs the island but does not
-  yet ship the client bundle. Click handlers are dead under `bun
-  dev`. To exercise interactivity right now, run `bun run build &&
-  bun start`. Full dev-mode hydration lands with framework spec 18.
 - **Naming:** the island's auto-registered name is the file path
   relative to `app/islands/` with slashes replaced by dashes and the
   extension stripped (e.g. `app/islands/forms/Signup.tsx` →
-  `forms-Signup`). Default exports are the only export consulted.
+  `forms-Signup`). Pass the same string as `<Island name="…">`. Default
+  exports are the only export consulted.
+- **Dev mode hydrates.** `patties dev` builds islands in
+  `--mode development` (no minify), serves them, and the client runtime
+  hydrates each `[data-island]` marker. HMR reloads the page on island
+  changes.
 - **Don't put non-island helpers in `app/islands/`.** Every `.tsx`
   in there is treated as a hydratable component. Put shared
   presentational components in `app/components/` or co-locate them

package/templates/_claude/.claude/rules/optional-ai.md

@@ -11,5 +11,6 @@ must still install and run without `@anthropic-ai/sdk` present.
 - Do not move `@anthropic-ai/sdk` into `dependencies` unless your app
   genuinely requires it at boot. Even then, prefer keeping it as a
   peer + `bun add @anthropic-ai/sdk` step.
-- The auto-generated `AGENTS.md` references AI types, but does not
-  require a live SDK at import time.
+- The auto-generated manifest (default `CLAUDE.md`; configurable via
+  `config.agentsMd.path`) references AI types, but does not require a
+  live SDK at import time.

package/templates/_claude/.claude/skills/patties-cli/SKILL.md

@@ -15,15 +15,14 @@ ad-hoc Bun invocations.
 ### `patties dev` — start the dev server
 
 ```sh
-bun dev          # equivalent to `patties dev`
+bunx patties dev # the canonical invocation (bun dev runs the same thing via the package.json script)
 patties dev --port 4000
 patties dev --host 0.0.0.0
 ```
 
 Starts the dev server with HMR over WebSocket. Reads `patties.config.ts`
-for `target`, `port`, env, and secrets. SSR-only today — full island
-hydration in dev lands with framework spec 18. To exercise interactivity
-right now, build and start instead.
+for `target`, `port`, env, and secrets. Islands are bundled and hydrated
+in dev — the same code path users see in production, minus minification.
 
 ### `patties build` — produce a production bundle
 
@@ -35,8 +34,9 @@ patties build --compile           # bun target only; single-binary
 ```
 
 Outputs to `.patties/` by default. The server entry is at
-`.patties/server/server-entry.js`. Build also regenerates `AGENTS.md` at
-the project root.
+`.patties/server/server-entry.js`. Build also regenerates the agent
+manifest section (default `CLAUDE.md`; configurable via
+`config.agentsMd.path`).
 
 ### `patties start` — run the production bundle
 
@@ -45,8 +45,7 @@ bun start        # equivalent to `patties start`
 ```
 
 Runs the last `patties build` output. If no build exists, prints an
-error directing you to `patties build` first. Use this (after `bun run
-build`) to verify island hydration today, since dev mode only SSRs.
+error directing you to `patties build` first.
 
 ### `patties deploy` — build then dispatch to a deploy plugin
 
@@ -90,10 +89,10 @@ the dev server reads `config.secrets`.
 **First-run sanity check after scaffolding:**
 ```sh
 bun install
-bun dev          # opens http://localhost:3000
+bunx patties dev # opens http://localhost:3000 — SSR + island hydration
 ```
 
-**Verify an island actually hydrates today (workaround until spec 18):**
+**Verify the production bundle:**
 ```sh
 bun run build
 bun start

package/templates/_claude/CLAUDE.md

@@ -16,6 +16,13 @@ The CLI surface (`patties dev/build/start/deploy/secret`) lives in the
 `patties-cli` skill at `.claude/skills/patties-cli/SKILL.md` — it loads
 automatically when CLI work is in scope.
 
-The live inventory of routes, islands, agents, tools, and jobs is in
-`AGENTS.md` (regenerated by `patties build`). Trust `AGENTS.md` for
-inventory questions; trust the rules files for conventions.
+The live inventory of routes, islands, agents, tools, and jobs is spliced
+into this file between `<!-- patties:manifest-start -->` and
+`<!-- patties:manifest-end -->` — regenerated on every `patties dev/build`
+while everything else here is preserved. Trust that section for inventory
+questions; trust the rules files for conventions. Change the target file
+with `config.agentsMd.path` in `patties.config.ts` if you'd rather the
+manifest live elsewhere.
+
+<!-- patties:manifest-start -->
+<!-- patties:manifest-end -->

package/templates/_codex/.codex/rules/islands.md

@@ -7,25 +7,39 @@ parts of a page that need browser-side interactivity (`useState`,
 - **Where they live:** `app/islands/*.tsx`. Files outside this
   directory are server-only and never ship to the browser.
 - **How to mark one:** start the file with `"use client";` and
-  default-export a React component. The framework will register it,
-  bundle the client code, and inject the hydration script when the
-  component is rendered from a route.
-- **How to use one:** import the component from a route file:
+  default-export a React component. The framework auto-registers it,
+  bundles its client code, and serves the chunk under
+  `/_patties/client/*` (in dev via `setupDevClient`; in production via
+  `patties build`).
+- **How to use one:** import the component from a route file and
+  wrap each use-site in `<Island name="…">…</Island>` from
+  `patties/render`. The wrapper emits the `data-island` marker + props
+  sibling that the client runtime scans for — without it the markup
+  SSRs fine but never hydrates.
+
   ```tsx
+  import { Island } from "patties/render";
   import TodoApp from "../islands/TodoApp.tsx";
 
   export default function Index(): JSX.Element {
-    return <main><TodoApp /></main>;
+    return (
+      <main>
+        <Island name="TodoApp">
+          <TodoApp />
+        </Island>
+      </main>
+    );
   }
   ```
-- **Today's gap (`bun dev`):** dev mode SSRs the island but does not
-  yet ship the client bundle. Click handlers are dead under `bun
-  dev`. To exercise interactivity right now, run `bun run build &&
-  bun start`. Full dev-mode hydration lands with framework spec 18.
 - **Naming:** the island's auto-registered name is the file path
   relative to `app/islands/` with slashes replaced by dashes and the
   extension stripped (e.g. `app/islands/forms/Signup.tsx` →
-  `forms-Signup`). Default exports are the only export consulted.
+  `forms-Signup`). Pass the same string as `<Island name="…">`. Default
+  exports are the only export consulted.
+- **Dev mode hydrates.** `patties dev` builds islands in
+  `--mode development` (no minify), serves them, and the client runtime
+  hydrates each `[data-island]` marker. HMR reloads the page on island
+  changes.
 - **Don't put non-island helpers in `app/islands/`.** Every `.tsx`
   in there is treated as a hydratable component. Put shared
   presentational components in `app/components/` or co-locate them

package/templates/_codex/.codex/rules/patties-cli.md

@@ -1,8 +1,3 @@
----
-name: patties-cli
-description: Use when running, building, deploying, or managing secrets for a Patties app. Covers `patties dev`, `patties build`, `patties start`, `patties deploy`, and `patties secret`. Trigger phrases include "start the dev server", "build the app", "deploy", "set a secret", "run patties".
----
-
 # patties CLI
 
 `patties` is the project's CLI. It's installed via the `patties` dependency
@@ -15,15 +10,14 @@ ad-hoc Bun invocations.
 ### `patties dev` — start the dev server
 
 ```sh
-bun dev          # equivalent to `patties dev`
+bunx patties dev # the canonical invocation (bun dev runs the same thing via the package.json script)
 patties dev --port 4000
 patties dev --host 0.0.0.0
 ```
 
 Starts the dev server with HMR over WebSocket. Reads `patties.config.ts`
-for `target`, `port`, env, and secrets. SSR-only today — full island
-hydration in dev lands with framework spec 18. To exercise interactivity
-right now, build and start instead.
+for `target`, `port`, env, and secrets. Islands are bundled and hydrated
+in dev — the same code path users see in production, minus minification.
 
 ### `patties build` — produce a production bundle
 
@@ -35,8 +29,10 @@ patties build --compile           # bun target only; single-binary
 ```
 
 Outputs to `.patties/` by default. The server entry is at
-`.patties/server/server-entry.js`. Build also regenerates `AGENTS.md` at
-the project root.
+`.patties/server/server-entry.js`. Build also regenerates the agent
+manifest section. For Codex projects, set `config.agentsMd.path =
+"AGENTS.md"` in `patties.config.ts` so the manifest lands in the file
+Codex reads from.
 
 ### `patties start` — run the production bundle
 
@@ -45,8 +41,7 @@ bun start        # equivalent to `patties start`
 ```
 
 Runs the last `patties build` output. If no build exists, prints an
-error directing you to `patties build` first. Use this (after `bun run
-build`) to verify island hydration today, since dev mode only SSRs.
+error directing you to `patties build` first.
 
 ### `patties deploy` — build then dispatch to a deploy plugin
 
@@ -90,10 +85,10 @@ the dev server reads `config.secrets`.
 **First-run sanity check after scaffolding:**
 ```sh
 bun install
-bun dev          # opens http://localhost:3000
+bunx patties dev # opens http://localhost:3000 — SSR + island hydration
 ```
 
-**Verify an island actually hydrates today (workaround until spec 18):**
+**Verify the production bundle:**
 ```sh
 bun run build
 bun start

package/templates/_codex/AGENTS.md

@@ -18,11 +18,9 @@ Built with Patties — a Bun-native full-stack meta-framework.
 
 ## Live inventory
 
-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.
+The section between the markers below is regenerated by `patties dev`
+and `patties build` from the actual contents of `app/`. Everything
+outside the markers is preserved across regenerations.
 
-<!-- patties:generated -->
-<!-- The block below is rewritten by `patties build`. Do not edit by hand. -->
-<!-- /patties:generated -->
+<!-- patties:manifest-start -->
+<!-- patties:manifest-end -->

package/templates/default/README-template.md

@@ -17,27 +17,18 @@ An interactive todo demo:
 
 ```sh
 bun install      # if you used --no-install
-bun dev          # → http://localhost:3000
+bunx patties 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.
+Dev mode SSRs the page and hydrates the island, so the todo buttons work
+immediately. HMR reloads the browser when you edit a route or island.
 
 ## 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.
+   placeholder, save, and try it — the bundle rebuilds on the next request.
 
 ## Remove the demo when you're ready
 
@@ -73,18 +64,15 @@ A minimal hello-world Patties app:
 
 ```sh
 bun install      # if you used --no-install
-bun dev          # → http://localhost:3000
+bunx patties dev # → http://localhost:3000
 ```
 
 ## 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`.
+`useEffect`. Import it from a route file under `app/routes/` and wrap the
+use site in `<Island name="MyIsland">…</Island>` (from `patties/render`)
+so the SSR markers are emitted and the client runtime hydrates it.
 <!-- /if -->
 
 ## Project layout
@@ -156,9 +144,10 @@ Launch a session with `claude` in this directory.
 ## 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 -->`.
+Codex CLI and other AGENTS.md-aware tools. Patties regenerates the
+inventory section between `<!-- patties:manifest-start -->` and
+`<!-- patties:manifest-end -->` on every `patties dev/build` — everything
+outside those markers is yours to edit.
 
 Launch a session with `codex` in this directory.
 <!-- /if -->

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

@@ -1,5 +1,11 @@
+import { Island } from "patties/render";
 import TodoApp from "../islands/TodoApp.tsx";
 
+export const meta = {
+	title: "Welcome to Patties",
+	description: "A Bun-native full-stack meta-framework.",
+};
+
 export default function Index(): JSX.Element {
 	return (
 		<main>
@@ -8,7 +14,9 @@ export default function Index(): JSX.Element {
 				This page is server-rendered. The list below is a client island —{" "}
 				<code>app/islands/TodoApp.tsx</code> — hydrated in the browser.
 			</p>
-			<TodoApp />
+			<Island name="TodoApp">
+				<TodoApp />
+			</Island>
 			<hr />
 			<p>
 				<small>

package/templates/default/app/server.ts

@@ -1,4 +1,4 @@
-import type { DevServer } from "patties/dev";
+import { type DevServer, setupDevClient } from "patties/dev";
 import { createRenderer } from "patties/render";
 import { createRouter } from "patties/router";
 import { startServer } from "patties/server";
@@ -11,7 +11,10 @@ interface StartOpts {
 }
 
 export default async function start(opts: StartOpts): Promise<void> {
-	const renderer = createRenderer({ dev: true });
+	// Bundle islands and serve their chunks under `/_patties/client/*`.
+	// `manifest` tells the renderer which <script> to inject so islands hydrate.
+	const devClient = await setupDevClient({ appDir: opts.appDir });
+	const renderer = createRenderer({ manifest: devClient.manifest, dev: true });
 	const router = await createRouter({ appDir: opts.appDir, renderer });
 
 	startServer({
@@ -19,7 +22,7 @@ export default async function start(opts: StartOpts): Promise<void> {
 		hostname: opts.host,
 		dev: true,
 		devServer: opts.devServer,
-		routes: router.routes,
+		routes: { ...devClient.routes, ...router.routes },
 		fallback: router.fallback,
 	});
 }