create-patties 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# create-patties
+
+## 0.0.8
+
+### Patch Changes
+
+- 3b3f80d: Scaffolder DX overhaul (specs 09 + 10).
+
+  - **Tool probes** — fail fast with a clear message when `bun` is missing
+    from PATH; skip-and-warn when `git` is missing instead of silently
+    swallowing failures.
+  - **Interactive prompts** — when stdin is a TTY and flags were not passed,
+    prompt for project name, target, deploy, and agent. Add `--yes` / `-y`
+    to accept all defaults non-interactively.
+  - **`--agent` alias** — the spec-05 `--agent claude-code` form is kept as
+    a backwards-compatible alias for `--template claude`.
+  - **Expanded agent overlays** — `_claude` now ships
+    `.claude/settings.json` (with `bun`/`bunx`/`patties` permissions and a
+    Biome PostToolUse hook), `.claude/hooks/biome-check.sh` (no-ops when
+    Biome is not installed), and empty `.claude/agents/` /
+    `.claude/commands/` directories with README pointers. `_codex` now
+    ships a `.codex/README.md`.
+  - **Templated README** — `templates/default/README-template.md` is now a
+    real onboarding doc with `{{name}}` / `{{agent}}` / `{{target}}` /
+    `{{deploy}}` placeholders and HTML-comment conditional blocks. A
+    generic templating pass also interpolates `{{name}}` into CLAUDE.md
+    and AGENTS.md.
+
+  - **Todo demo template** — the default scaffold now ships a `TodoApp.tsx`
+    island and a route that mounts it. The README explains that buttons
+    don't react under `bun dev` today (dev hydration lands with framework
+    spec 18) and tells the user to `bun run build && bun start` to see the
+    island work; it also includes a "Remove the demo" section for when the
+    user is ready to start their real app.
+  - **`--blank` flag** — `bunx create-patties@latest <name> --blank`
+    (alias: `--empty`) scaffolds a hello-world page with no demo and no
+    `app/islands/` directory.
+  - **Demo prompt** — interactive flow asks "Include the interactive
+    todo demo? [Y/n]" right after the agent question.
+  - **Git is now opt-in** — `git init` no longer runs by default. Pass
+    `--git` to opt in. The success output reminds the user how to
+    initialise a repo when they're ready. `--no-git` is kept as a no-op
+    for back-compat.
+  - **`_claude` overlay restructured.** The empty `.claude/agents/` and
+    `.claude/commands/` placeholders are gone. Replaced with:
+    - `.claude/skills/patties-cli/SKILL.md` — a real skill teaching
+      Claude how to use the project CLI (`patties dev/build/start/deploy/secret`).
+    - `.claude/rules/` — scaffolded meta-framework knowledge:
+      `bun-native.md`, `web-standards-boundary.md`,
+      `filesystem-routing.md`, `islands.md`, `build-time-discovery.md`,
+      `optional-ai.md`. Mirrors the framework's own rules but tuned
+      for users of the framework.

package/README.md

@@ -0,0 +1,53 @@
+# create-patties
+
+The official scaffolder for [Patties](https://github.com/bihaviour-ai/bun-patties-framework) —
+a Bun-native full-stack meta-framework with React 19 rendering.
+
+```sh
+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.
+
+## Options
+
+```sh
+bunx create-patties@latest my-app \
+  --template claude|codex|none \
+  --target   bun|edge \
+  --deploy   cloudflare|vercel|deno|netlify|bun|none \
+  --blank \
+  --git \
+  --no-install \
+  --yes
+```
+
+| Flag | Default | What it does |
+|---|---|---|
+| `--template` | `claude` | Agent-platform overlay (`claude`, `codex`, or `none`). |
+| `--target` | `bun` | Runtime target written into `patties.config.ts`. |
+| `--deploy` | `none` | Records the intended deploy target. |
+| `--blank` / `--empty` | off | Skip the interactive todo demo; ship a hello-world page. |
+| `--git` | off | Run `git init` + initial commit (opt-in). |
+| `--no-install` | off | Skip `bun install`. |
+| `--yes` / `-y` | off | Accept all defaults; skip prompts. |
+
+`--agent claude-code` is retained as a back-compat alias for
+`--template claude`.
+
+## What you get
+
+A minimal Patties app with filesystem routing under `app/routes/`,
+optional client islands under `app/islands/`, and either the `_claude`
+or `_codex` agent overlay scaffolding conventions for your chosen
+coding agent.
+
+See [the Patties docs](https://bun-patties.com) for the full framework
+guide.
+
+## Requires
+
+Bun 1.0+. `bunx create-patties@latest` won't work under Node — install
+Bun first from [bun.sh](https://bun.sh).

package/bin/create-patties.ts

@@ -1,5 +1,11 @@
 #!/usr/bin/env bun
-import { run } from "../src/index.ts";
+if (typeof Bun === "undefined") {
+	console.error(
+		"create-patties requires Bun. Install Bun first: https://bun.sh",
+	);
+	process.exit(1);
+}
 
+const { run } = await import("../src/index.ts");
 const code = await run(process.argv.slice(2));
 process.exit(code);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-patties",
-	"version": "0.0.6",
+	"version": "0.0.8",
 	"type": "module",
 	"description": "Scaffolder for new Patties projects.",
 	"bin": {
@@ -13,6 +13,10 @@
 		"bin",
 		"src",
 		"templates",
-		"README.md"
-	]
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"engines": {
+		"bun": ">=1.0.0"
+	}
 }

package/src/index.ts

@@ -1,15 +1,30 @@
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
-
-type AgentTemplate = "claude" | "codex" | "none";
+import { hasGit, probeTools } from "./probes.ts";
+import {
+	type AgentTemplate,
+	isInteractive,
+	promptAgent,
+	promptDeploy,
+	promptName,
+	promptScaffold,
+	promptTarget,
+} from "./prompts.ts";
+import { renderTemplatesInTree } from "./readme.ts";
 
 interface Args {
 	name?: string;
 	template: AgentTemplate;
+	templateExplicit: boolean;
 	target: "bun" | "edge";
+	targetExplicit: boolean;
 	deploy: "cloudflare" | "vercel" | "deno" | "netlify" | "bun" | "none";
+	deployExplicit: boolean;
 	install: boolean;
 	git: boolean;
+	yes: boolean;
+	scaffold: "demo" | "blank";
+	scaffoldExplicit: boolean;
 }
 
 const TEMPLATES_ROOT = resolve(dirname(import.meta.dir), "templates");
@@ -18,10 +33,19 @@ const VALID_TEMPLATES: AgentTemplate[] = ["claude", "codex", "none"];
 
 export async function run(argv: string[]): Promise<number> {
 	const args = parseArgs(argv);
+	const interactive = !args.yes && isInteractive();
 
 	if (!args.name) {
-		printUsage();
-		return 2;
+		if (interactive) {
+			args.name = promptName(undefined, isValidName);
+			if (!args.name) {
+				stderr("✗ failed to read a valid project name");
+				return 2;
+			}
+		} else {
+			printUsage();
+			return 2;
+		}
 	}
 
 	if (!isValidName(args.name)) {
@@ -29,6 +53,15 @@ export async function run(argv: string[]): Promise<number> {
 		return 2;
 	}
 
+	if (interactive) {
+		if (!args.templateExplicit) args.template = promptAgent();
+		if (!args.scaffoldExplicit) args.scaffold = promptScaffold();
+		if (!args.targetExplicit) args.target = promptTarget();
+		if (args.target === "edge" && !args.deployExplicit) {
+			args.deploy = promptDeploy();
+		}
+	}
+
 	if (!VALID_TEMPLATES.includes(args.template)) {
 		stderr(
 			`✗ unknown --template "${args.template}" (expected: ${VALID_TEMPLATES.join(", ")})`,
@@ -51,6 +84,8 @@ export async function run(argv: string[]): Promise<number> {
 		return 1;
 	}
 
+	probeTools();
+
 	await Bun.$`mkdir -p ${targetDir}`.quiet();
 	await Bun.$`cp -R ${baseDir}/. ${targetDir}`.quiet();
 
@@ -65,22 +100,43 @@ export async function run(argv: string[]): Promise<number> {
 		}
 	}
 
+	if (args.scaffold === "blank") {
+		await applyBlankScaffold(targetDir);
+	}
+
+	await renderTemplatesInTree(targetDir, {
+		name: args.name,
+		agent: args.template,
+		target: args.target,
+		deploy: args.deploy,
+		scaffold: args.scaffold,
+	});
+
 	if (args.install) {
 		await Bun.$`bun install`.cwd(targetDir).quiet().nothrow();
 	}
 
+	let gitSkippedReason: string | undefined;
 	if (args.git) {
-		await Bun.$`git init`.cwd(targetDir).quiet().nothrow();
-		await Bun.$`git add -A`.cwd(targetDir).quiet().nothrow();
-		await Bun.$`git commit -m ${"chore: initial commit from create-patties"}`
-			.cwd(targetDir)
-			.quiet()
-			.nothrow();
+		if (hasGit()) {
+			await Bun.$`git init`.cwd(targetDir).quiet().nothrow();
+			await Bun.$`git add -A`.cwd(targetDir).quiet().nothrow();
+			await Bun.$`git commit -m ${"chore: initial commit from create-patties"}`
+				.cwd(targetDir)
+				.quiet()
+				.nothrow();
+		} else {
+			gitSkippedReason = "git-missing";
+		}
 	}
 
-	process.stdout.write(
-		`\n✓ created ${args.name}\n\n  cd ${args.name}\n  bun dev\n`,
-	);
+	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`;
+	process.stdout.write(`\n✓ created ${args.name}\n${nextSteps}`);
+	if (gitSkippedReason === "git-missing") {
+		stderr("create-patties: `git` not found — skipping `git init`.");
+	}
 	if (args.template === "claude") {
 		process.stdout.write(
 			"\nClaude Code is configured (CLAUDE.md). Run `claude` in the project to start a session.\n",
@@ -96,30 +152,66 @@ export async function run(argv: string[]): Promise<number> {
 function parseArgs(argv: string[]): Args {
 	const out: Args = {
 		template: "claude",
+		templateExplicit: false,
 		target: "bun",
+		targetExplicit: false,
 		deploy: "none",
+		deployExplicit: false,
 		install: true,
-		git: true,
+		git: false,
+		yes: false,
+		scaffold: "demo",
+		scaffoldExplicit: false,
+	};
+	const setTemplate = (raw: string) => {
+		out.template = aliasTemplate(raw);
+		out.templateExplicit = true;
 	};
 	for (let i = 0; i < argv.length; i++) {
 		const a = argv[i];
 		if (a === undefined) continue;
-		if (a === "--template") out.template = next(argv, ++i) as AgentTemplate;
-		else if (a.startsWith("--template="))
-			out.template = a.slice(11) as AgentTemplate;
-		else if (a === "--target") out.target = next(argv, ++i) as Args["target"];
-		else if (a.startsWith("--target="))
+		if (a === "--template") setTemplate(next(argv, ++i));
+		else if (a.startsWith("--template=")) setTemplate(a.slice(11));
+		// --agent: spec-05 alias kept for backwards compatibility.
+		else if (a === "--agent") setTemplate(next(argv, ++i));
+		else if (a.startsWith("--agent=")) setTemplate(a.slice(8));
+		else if (a === "--target") {
+			out.target = next(argv, ++i) as Args["target"];
+			out.targetExplicit = true;
+		} else if (a.startsWith("--target=")) {
 			out.target = a.slice(9) as Args["target"];
-		else if (a === "--deploy") out.deploy = next(argv, ++i) as Args["deploy"];
-		else if (a.startsWith("--deploy="))
+			out.targetExplicit = true;
+		} else if (a === "--deploy") {
+			out.deploy = next(argv, ++i) as Args["deploy"];
+			out.deployExplicit = true;
+		} else if (a.startsWith("--deploy=")) {
 			out.deploy = a.slice(9) as Args["deploy"];
-		else if (a === "--no-install") out.install = false;
+			out.deployExplicit = true;
+		} else if (a === "--no-install") out.install = false;
+		else if (a === "--git") out.git = true;
+		// --no-git: kept as a no-op for back-compat. Git is now opt-in
+		// (default off) so most users don't need either flag.
 		else if (a === "--no-git") out.git = false;
-		else if (!out.name && !a.startsWith("-")) out.name = a;
+		else if (a === "--yes" || a === "-y") out.yes = true;
+		else if (a === "--blank" || a === "--empty") {
+			out.scaffold = "blank";
+			out.scaffoldExplicit = true;
+		} else if (a === "--demo") {
+			out.scaffold = "demo";
+			out.scaffoldExplicit = true;
+		} else if (!out.name && !a.startsWith("-")) out.name = a;
 	}
 	return out;
 }
 
+// Translate spec-05 --agent values (claude-code/none) and current --template
+// values (claude/codex/none) into the unified AgentTemplate type.
+function aliasTemplate(raw: string): AgentTemplate {
+	if (raw === "claude-code") return "claude";
+	if (raw === "claude" || raw === "codex" || raw === "none") return raw;
+	return raw as AgentTemplate;
+}
+
 function next(argv: string[], i: number): string {
 	return argv[i] ?? "";
 }
@@ -144,6 +236,28 @@ async function renameTemplateFiles(dir: string): Promise<void> {
 	}
 }
 
+// --blank scaffold: drop the interactive demo and ship a single hello page.
+// We start from the same default template and prune so we keep exactly one
+// source-of-truth for things like patties.config.ts / tsconfig.json.
+async function applyBlankScaffold(dir: string): Promise<void> {
+	await Bun.$`rm -rf ${dir}/app/islands`.quiet();
+	await Bun.write(
+		`${dir}/app/routes/index.tsx`,
+		`export default function Index(): JSX.Element {
+	return (
+		<main>
+			<h1>Hello from {{name}}</h1>
+			<p>
+				This page is server-rendered by Patties. Add more files under{" "}
+				<code>app/routes/</code> to grow your app.
+			</p>
+		</main>
+	);
+}
+`,
+	);
+}
+
 async function writePackageJson(dir: string, name: string): Promise<void> {
 	const pkg = {
 		name,
@@ -202,11 +316,15 @@ Options:
   --target   <bun|edge>             Runtime target (default: bun)
   --deploy   <cloudflare|vercel|deno|netlify|bun|none>
   --no-install                      Skip 'bun install'
-  --no-git                          Skip 'git init'
+  --git                             Run 'git init' + initial commit (opt-in)
+  --yes, -y                         Accept all defaults, skip prompts
+  --blank, --empty                  Scaffold a hello-world page only (no demo)
+  --demo                            Scaffold the interactive todo demo (default)
 
 Examples:
   bunx create-patties@latest my-app
   bunx create-patties@latest my-app --template codex
-  bunx create-patties@latest my-app --template none --no-git
+  bunx create-patties@latest my-app --template none
+  bunx create-patties@latest my-app --git           # opt-in git init
 `);
 }

package/src/probes.ts

@@ -0,0 +1,28 @@
+// Tool probes for the scaffolder. See spec cli/10-scaffold-probes.
+//
+// `bun` is required to run the resulting project — if it is missing from PATH
+// at scaffold time, fail before any FS writes so the user does not end up with
+// half a project on disk.
+// `git` is optional — if it is missing, skip the `git init` step and warn at
+// the end of the scaffold rather than letting git fail mid-pipeline.
+
+export interface ProbeIO {
+	stderr?: (msg: string) => void;
+	exit?: (code: number) => never;
+}
+
+export function probeTools(io: ProbeIO = {}): void {
+	const stderr = io.stderr ?? ((m: string) => process.stderr.write(`${m}\n`));
+	const exit = io.exit ?? ((c: number) => process.exit(c) as never);
+
+	if (!Bun.which("bun")) {
+		stderr(
+			"create-patties: `bun` not found in PATH. Install Bun from https://bun.sh and re-run.",
+		);
+		exit(1);
+	}
+}
+
+export function hasGit(): boolean {
+	return Bun.which("git") !== null;
+}

package/src/prompts.ts

@@ -0,0 +1,98 @@
+// Interactive prompts for create-patties. See spec cli/09-create-patties-dx
+// items 3 + 5. Uses Bun's built-in prompt() — no new dependency.
+//
+// Non-TTY callers must supply the equivalent flags; the run loop only invokes
+// these helpers when stdin is a TTY and --yes was not passed.
+
+export type AgentTemplate = "claude" | "codex" | "none";
+export type Target = "bun" | "edge";
+export type Scaffold = "demo" | "blank";
+export type Deploy =
+	| "cloudflare"
+	| "vercel"
+	| "deno"
+	| "netlify"
+	| "bun"
+	| "none";
+
+export interface PromptIO {
+	prompt?: (q: string) => string | null;
+	stdout?: (msg: string) => void;
+	isTTY?: boolean;
+}
+
+const DEFAULT_NAME = "my-patties-app";
+
+export function isInteractive(io: PromptIO = {}): boolean {
+	if (io.isTTY !== undefined) return io.isTTY;
+	return Boolean(process.stdin.isTTY);
+}
+
+export function promptName(
+	current: string | undefined,
+	isValid: (name: string) => boolean,
+	io: PromptIO = {},
+): string | undefined {
+	if (current) return current;
+	const ask = io.prompt ?? prompt;
+	const out = io.stdout ?? ((m: string) => process.stdout.write(m));
+
+	for (let attempt = 0; attempt < 5; attempt++) {
+		const answer = (ask(`Project name: (${DEFAULT_NAME}) `) ?? "").trim();
+		const candidate = answer === "" ? DEFAULT_NAME : answer;
+		if (isValid(candidate)) return candidate;
+		out(
+			`✗ invalid project name: "${candidate}" — use lowercase letters, digits, _ or -\n`,
+		);
+	}
+	return undefined;
+}
+
+export function promptAgent(io: PromptIO = {}): AgentTemplate {
+	const ask = io.prompt ?? prompt;
+	const answer = (
+		ask("Which AI coding agent will you use? [claude/codex/none] (claude) ") ??
+		""
+	)
+		.trim()
+		.toLowerCase();
+	if (answer === "codex") return "codex";
+	if (answer === "none") return "none";
+	return "claude";
+}
+
+export function promptScaffold(io: PromptIO = {}): Scaffold {
+	const ask = io.prompt ?? prompt;
+	const answer = (ask("Include the interactive todo demo? [Y/n] (Y) ") ?? "")
+		.trim()
+		.toLowerCase();
+	if (answer === "n" || answer === "no" || answer === "blank") return "blank";
+	return "demo";
+}
+
+export function promptTarget(io: PromptIO = {}): Target {
+	const ask = io.prompt ?? prompt;
+	const answer = (ask("Runtime target? [bun/edge] (bun) ") ?? "")
+		.trim()
+		.toLowerCase();
+	return answer === "edge" ? "edge" : "bun";
+}
+
+export function promptDeploy(io: PromptIO = {}): Deploy {
+	const ask = io.prompt ?? prompt;
+	const answer = (
+		ask("Deploy plugin? [cloudflare/vercel/deno/netlify/bun/none] (none) ") ??
+		""
+	)
+		.trim()
+		.toLowerCase();
+	const valid: Deploy[] = [
+		"cloudflare",
+		"vercel",
+		"deno",
+		"netlify",
+		"bun",
+		"none",
+	];
+	return (valid as string[]).includes(answer) ? (answer as Deploy) : "none";
+}

package/src/readme.ts

@@ -0,0 +1,67 @@
+// README + template-file rendering. See spec cli/09-create-patties-dx item 2.
+//
+// `applyTemplate` does two passes:
+//   1. Strip/keep conditional blocks delimited by:
+//        <!-- if:KEY=VALUE -->...<!-- /if -->
+//      The block is kept iff `vars[KEY] === VALUE`.
+//   2. Replace `{{name}}`, `{{agent}}`, `{{target}}`, `{{deploy}}` placeholders
+//      with the corresponding `vars` entry.
+//
+// `renderTemplatesInTree` walks a scaffolded project and applies the template
+// to every text file we care about (README.md, *.md, *.json, *.ts, *.tsx).
+// Anything else is left untouched so we don't corrupt binary assets.
+
+export interface TemplateVars {
+	name: string;
+	agent: "claude" | "codex" | "none";
+	target: "bun" | "edge";
+	deploy: "cloudflare" | "vercel" | "deno" | "netlify" | "bun" | "none";
+	scaffold: "demo" | "blank";
+}
+
+const CONDITIONAL_RE =
+	/<!--\s*if:([a-zA-Z_]+)=([a-zA-Z0-9_-]+)\s*-->([\s\S]*?)<!--\s*\/if\s*-->\n?/g;
+
+const TEXT_EXT_RE =
+	/\.(md|mdx|json|jsonc|ts|tsx|js|jsx|sh|toml|yml|yaml|gitignore)$/;
+
+export function applyTemplate(source: string, vars: TemplateVars): string {
+	const stripped = source.replace(
+		CONDITIONAL_RE,
+		(_match, key: string, value: string, body: string) => {
+			const v = (vars as unknown as Record<string, string>)[key];
+			return v === value ? body : "";
+		},
+	);
+	return (
+		stripped
+			.replaceAll("{{name}}", vars.name)
+			.replaceAll("{{agent}}", vars.agent)
+			.replaceAll("{{target}}", vars.target)
+			.replaceAll("{{deploy}}", vars.deploy)
+			.replaceAll("{{scaffold}}", vars.scaffold)
+			// Legacy placeholders from earlier overlay revisions — kept so existing
+			// CLAUDE.md / AGENTS.md template text keeps interpolating.
+			.replaceAll("{{PROJECT_NAME}}", vars.name)
+			.replaceAll("{{DEPLOY_TARGET}}", vars.deploy)
+	);
+}
+
+export async function renderTemplatesInTree(
+	dir: string,
+	vars: TemplateVars,
+): Promise<void> {
+	const glob = new Bun.Glob("**/*");
+	for await (const rel of glob.scan({ cwd: dir, onlyFiles: true, dot: true })) {
+		if (!TEXT_EXT_RE.test(rel) && !rel.endsWith("README.md")) continue;
+		const path = `${dir}/${rel}`;
+		const file = Bun.file(path);
+		const text = await file.text();
+		if (!hasTemplateMarkers(text)) continue;
+		await Bun.write(path, applyTemplate(text, vars));
+	}
+}
+
+function hasTemplateMarkers(text: string): boolean {
+	return text.includes("{{") || text.includes("<!-- if:");
+}

package/templates/_claude/.claude/hooks/biome-check.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# PostToolUse hook: run Biome on the file Claude just touched.
+# No-ops cleanly when Biome is not installed so it's safe to ship by default.
+set -euo pipefail
+
+file="${CLAUDE_FILE_PATH:-${1:-}}"
+if [[ -z "${file}" ]]; then exit 0; fi
+case "${file}" in
+  *.ts|*.tsx|*.js|*.jsx|*.json|*.jsonc) ;;
+  *) exit 0 ;;
+esac
+
+if command -v biome >/dev/null 2>&1; then
+  biome check --write --no-errors-on-unmatched "${file}" || exit 2
+elif command -v bunx >/dev/null 2>&1; then
+  bunx --bun @biomejs/biome check --write --no-errors-on-unmatched "${file}" 2>/dev/null || exit 0
+fi

package/templates/_claude/.claude/rules/build-time-discovery.md

@@ -0,0 +1,17 @@
+# Build-time discovery rule
+
+Routes, islands, agents, and tools are discovered from the filesystem
+at **build time**, not at request time.
+
+- `patties build` scans `app/routes/`, `app/islands/`, `app/agents/`,
+  `app/tools/`, and `app/jobs/` and inlines the discovered tables into
+  the server bundle. The production server never calls `Bun.Glob` /
+  `scanRoutes` / `scanIslands`.
+- This is what makes Patties cold-start fast and adapter-portable
+  (edge runtimes that disallow filesystem access still work).
+- **Dev mode is the exception.** The dev server re-scans on file
+  change to drive HMR.
+- **Don't break the rule:** never write code that calls `Bun.Glob` or
+  reads `app/**` at request time. If you find yourself wanting to,
+  the answer is probably a build-time macro or a config option in
+  `patties.config.ts`.

package/templates/_claude/.claude/rules/bun-native.md

@@ -0,0 +1,28 @@
+# Bun-native rule
+
+This project runs on Bun. Reach for Bun primitives first; do not
+reintroduce Node-era replacements just because a familiar library
+provides them.
+
+- **HTTP server:** `Bun.serve`. The framework already wires it — do
+  not add Express / Fastify / Hono / `node:http`.
+- **Filesystem discovery:** `Bun.Glob`. Do not pull in `fast-glob`,
+  `globby`, or `chokidar`.
+- **Bundling:** `Bun.build`. The framework runs it for you at
+  `patties build`; you should not add Webpack / Rollup / esbuild /
+  Vite / tsup.
+- **File I/O:** `Bun.file(path).text()` / `.json()` / `.bytes()` and
+  `Bun.write(path, data)` before reaching for `node:fs`.
+- **Hashing / crypto:** `Bun.CryptoHasher`, `Bun.password`. Avoid
+  `crypto` / `bcrypt` unless you have a real reason.
+- **Databases:** `bun:sqlite`, `Bun.sql` (Postgres), `Bun.RedisClient`,
+  `Bun.S3Client` before reaching for npm wrappers.
+- **Environment:** `Bun.env`. The framework injects the public subset
+  declared in `patties.config.ts#env.public`; secrets live in the OS
+  keychain (see `patties-cli` skill).
+- **Tests:** `bun test`. Do not add Jest or Vitest.
+- **Package manager:** `bun` / `bunx`. Do not run `npm` / `npx` /
+  `yarn` / `pnpm` in this project.
+
+If you genuinely need a Node-only library, that's fine — Bun's Node
+compatibility is strong. But default to Bun primitives.