npm - @bractjs/bractjs - Versions diffs - 0.1.0 - Mend

@bractjs/bractjs 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (85) hide show

package/LICENSE +21 -0
package/README.md +586 -0
package/bin/cli.ts +101 -0
package/package.json +58 -0
package/src/__tests__/fixtures/app/root.tsx +9 -0
package/src/__tests__/fixtures/app/routes/_index.tsx +20 -0
package/src/__tests__/integration.test.ts +66 -0
package/src/__tests__/loader.test.ts +89 -0
package/src/__tests__/matcher.test.ts +69 -0
package/src/__tests__/meta.test.ts +81 -0
package/src/__tests__/scanner.test.ts +58 -0
package/src/__tests__/session.test.ts +103 -0
package/src/build/bundler.ts +75 -0
package/src/build/defines.ts +16 -0
package/src/build/directives.ts +67 -0
package/src/build/env-plugin.ts +56 -0
package/src/build/hash.ts +56 -0
package/src/build/manifest.ts +60 -0
package/src/client/ClientRouter.tsx +122 -0
package/src/client/components/Await.tsx +26 -0
package/src/client/components/Form.tsx +67 -0
package/src/client/components/Image.tsx +79 -0
package/src/client/components/Link.tsx +42 -0
package/src/client/components/LiveReload.tsx +16 -0
package/src/client/components/Outlet.tsx +64 -0
package/src/client/components/Scripts.tsx +12 -0
package/src/client/entry.tsx +49 -0
package/src/client/form-utils.ts +12 -0
package/src/client/hooks/useActionData.ts +14 -0
package/src/client/hooks/useFetcher.ts +51 -0
package/src/client/hooks/useLoaderData.ts +14 -0
package/src/client/hooks/useNavigation.ts +12 -0
package/src/client/hooks/useParams.ts +14 -0
package/src/client/nav-utils.ts +35 -0
package/src/client/prefetch.ts +32 -0
package/src/client/route-cache.ts +20 -0
package/src/client/router.tsx +54 -0
package/src/client/types.ts +23 -0
package/src/codegen/route-codegen.ts +99 -0
package/src/dev/error-overlay.ts +33 -0
package/src/dev/hmr-client.ts +43 -0
package/src/dev/hmr-module-handler.ts +47 -0
package/src/dev/hmr-server.ts +51 -0
package/src/dev/rebuilder.ts +95 -0
package/src/dev/server.ts +38 -0
package/src/dev/watcher.ts +32 -0
package/src/image/cache.ts +75 -0
package/src/image/handler.ts +82 -0
package/src/image/optimizer.ts +76 -0
package/src/image/types.ts +27 -0
package/src/index.ts +51 -0
package/src/middleware/authGuard.ts +37 -0
package/src/middleware/cors.ts +36 -0
package/src/middleware/requestLogger.ts +15 -0
package/src/server/action-handler.ts +35 -0
package/src/server/action-registry.ts +41 -0
package/src/server/env.ts +29 -0
package/src/server/index.ts +8 -0
package/src/server/layout.ts +92 -0
package/src/server/loader.ts +80 -0
package/src/server/matcher.ts +99 -0
package/src/server/meta.ts +92 -0
package/src/server/middleware.ts +47 -0
package/src/server/render.ts +65 -0
package/src/server/request-handler.ts +142 -0
package/src/server/response.ts +17 -0
package/src/server/scanner.ts +68 -0
package/src/server/serve.ts +131 -0
package/src/server/session.ts +111 -0
package/src/server/static.ts +40 -0
package/src/shared/context.ts +37 -0
package/src/shared/deferred.ts +55 -0
package/src/shared/error-boundary.tsx +58 -0
package/src/shared/errors.ts +49 -0
package/src/shared/route-types.ts +51 -0
package/templates/new-app/app/root.tsx +20 -0
package/templates/new-app/app/routes/_index.tsx +31 -0
package/templates/new-app/app/routes/about.tsx +21 -0
package/templates/new-app/bractjs.config.ts +14 -0
package/templates/new-app/package.json +20 -0
package/types/config.d.ts +25 -0
package/types/index.d.ts +109 -0
package/types/middleware.d.ts +19 -0
package/types/route.d.ts +41 -0
package/types/session.d.ts +32 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 YOUR_NAME
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,586 @@
+# BractJS
+> Production-grade SSR framework for Bun + React 19.
+> File-based routing · Parallel loaders · Streaming SSR · Built-in HMR · Server Actions
+---
+## Quick Start
+```sh
+# Requires Bun — https://bun.sh
+bunx bractjs new my-app
+cd my-app
+bun run dev
+# → http://localhost:3000
+```
+> **From source (pre-publish):** clone the repo, then `bun run bin/cli.ts new my-app`.
+---
+## File-Based Routing
+Place files inside `app/routes/`. BractJS scans them at startup.
+| File | URL |
+|------|-----|
+| `routes/_index.tsx` | `/` |
+| `routes/about.tsx` | `/about` |
+| `routes/blog/_index.tsx` | `/blog` |
+| `routes/blog/[id].tsx` | `/blog/:id` |
+| `routes/docs/[...slug].tsx` | `/docs/*` (catch-all) |
+| `routes/blog/layout.tsx` | wraps all `/blog/*` routes |
+`app/root.tsx` is the outermost layout (always rendered). Match priority per segment: **static > dynamic > catch-all**.
+---
+## Route Module API
+Every file in `app/routes/` can export any combination of these:
+```tsx
+import type { LoaderArgs, ActionArgs, MetaArgs } from "bractjs";
+import { redirect } from "bractjs";
+// Runs on every GET — return value becomes useLoaderData()
+export async function loader({ request, params, context }: LoaderArgs) {
+  const post = await db.post.findById(params.id);
+  if (!post) throw new Response("Not Found", { status: 404 });
+  return { post };
+}
+export type LoaderData = Awaited<ReturnType<typeof loader>>;
+// Runs on POST / PUT / DELETE
+export async function action({ params, formData }: ActionArgs) {
+  await db.post.update(params.id, { title: formData.get("title") as string });
+  return redirect("/blog");
+}
+// SSR <title> and <meta> tags
+export function meta({ loaderData }: MetaArgs<LoaderData>) {
+  return [
+    { title: loaderData.post.title },
+    { name: "description", content: loaderData.post.excerpt },
+  ];
+}
+// Error boundary for this route segment
+export function ErrorBoundary({ error }: { error: Error }) {
+  return <p>Error: {error.message}</p>;
+}
+// The page component (required)
+export default function BlogPost() {
+  const { post } = useLoaderData<LoaderData>();
+  return <article><h1>{post.title}</h1></article>;
+}
+```
+---
+## Root Layout (`app/root.tsx`)
+Required. Provides the `<html>` document shell.
+```tsx
+import { Scripts, LiveReload, Outlet } from "bractjs";
+export function meta() {
+  return [{ title: "My App" }, { name: "viewport", content: "width=device-width, initial-scale=1" }];
+}
+export default function Root() {
+  return (
+    <html lang="en">
+      <head>{/* BractJS injects <title> and <meta> tags here */}</head>
+      <body>
+        <Outlet />     {/* current route tree */}
+        <Scripts />    {/* client bundle */}
+        <LiveReload /> {/* dev-only HMR — no-op in production */}
+      </body>
+    </html>
+  );
+}
+```
+---
+## Deferred / Streaming Data
+`defer()` streams slow data without blocking the initial HTML response.
+```tsx
+import { defer } from "bractjs";
+import { Await } from "bractjs";
+import { Suspense } from "react";
+export async function loader({ params }: LoaderArgs) {
+  return defer({
+    post: await db.post.findById(params.id),  // awaited — in initial HTML
+    comments: db.comments.forPost(params.id), // Promise — streamed later
+  });
+}
+export default function BlogPost() {
+  const { post, comments } = useLoaderData<LoaderData>();
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <Suspense fallback={<p>Loading comments…</p>}>
+        <Await resolve={comments}>
+          {(c) => <CommentList comments={c} />}
+        </Await>
+      </Suspense>
+    </article>
+  );
+}
+```
+---
+## Client Primitives
+### `<Link>`
+Soft-navigates without a full reload. `prefetch="hover"` preloads the route chunk + loader data on mouse-enter.
+```tsx
+import { Link } from "bractjs";
+<Link to="/blog/42">Read Post</Link>
+<Link to="/about" prefetch="hover">About</Link>
+```
+### `<Form>`
+Fetch-based submission. Re-runs the current route's loader after the action completes.
+```tsx
+import { Form } from "bractjs";
+<Form method="post" action="/blog/new">
+  <input name="title" />
+  <button type="submit">Create</button>
+</Form>
+```
+### `<Outlet>`
+Renders the matched child route inside a layout.
+```tsx
+export default function BlogLayout() {
+  return (
+    <div>
+      <nav>Blog</nav>
+      <Outlet />
+    </div>
+  );
+}
+```
+---
+## Hooks
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useLoaderData<T>()` | `T` | Loader return value for the current route |
+| `useActionData<T>()` | `T \| null` | Most recent action return value |
+| `useParams<T>()` | `T` | URL dynamic params (generic for typed params) |
+| `useNavigation()` | `{ state }` | `"idle"` \| `"loading"` \| `"submitting"` |
+| `useFetcher()` | `{ data, state, load, submit }` | Background fetch without navigation |
+```tsx
+import { useLoaderData, useNavigation, useFetcher } from "bractjs";
+const { post } = useLoaderData<LoaderData>();
+const { state } = useNavigation();
+if (state === "loading") return <Spinner />;
+const fetcher = useFetcher();
+fetcher.load("/api/suggestions?q=bun");
+```
+---
+## Image Optimization
+`<Image>` serves responsively-sized, format-converted images through a built-in `/_image` endpoint. Requires [ImageMagick](https://imagemagick.org) (`magick` or `convert`) — falls back to serving the original if not installed.
+```tsx
+import { Image } from "bractjs";
+// Basic — lazy, WebP, 80% quality, responsive srcset
+<Image src="/public/hero.jpg" alt="Hero" width={1200} height={600} />
+// Above-the-fold — eager load + fetchpriority=high
+<Image src="/public/hero.jpg" alt="Hero" width={1200} priority />
+// Custom format / quality / fit
+<Image
+  src="/public/photo.jpg"
+  alt="Photo"
+  width={800}
+  format="avif"
+  quality={70}
+  fit="contain"
+  sizes="(max-width: 640px) 100vw, 50vw"
+/>
+```
+The component generates a `srcset` across up to 7 breakpoints (320 → 1920 px). Optimized images are cached in memory (LRU, 200 slots) and on disk (`.bract-image-cache/`, survives restarts). Both layers respond with `Cache-Control: immutable`.
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Path under `/public/` |
+| `alt` | `string` | — | Alt text (required) |
+| `width` | `number` | — | Intrinsic width |
+| `height` | `number` | — | Intrinsic height |
+| `quality` | `number` | `80` | 1–100 |
+| `format` | `"webp" \| "avif" \| "jpeg" \| "png"` | `"webp"` | Output format |
+| `fit` | `"cover" \| "contain" \| "fill"` | `"cover"` | Resize mode |
+| `priority` | `boolean` | `false` | Disable lazy loading, set `fetchpriority=high` |
+| `sizes` | `string` | `"100vw"` | HTML `sizes` attribute |
+---
+## Typed Routes (Codegen)
+Run `bractjs codegen` to generate `app/route-types.gen.ts` from your route files. This runs automatically during `bractjs build`.
+```sh
+bractjs codegen            # reads ./app, writes ./app/route-types.gen.ts
+bractjs codegen ./app ./app/route-types.gen.ts  # explicit paths
+```
+**Generated file provides:**
+```ts
+// Every URL pattern as a string literal union
+export type AppRoutes = "/" | "/blog/:id" | "/org/:orgId/repo/:repoId";
+// Per-route typed params
+export type RouteParams<T extends AppRoutes> =
+  T extends "/blog/:id" ? { id: string } :
+  T extends "/org/:orgId/repo/:repoId" ? { orgId: string; repoId: string } :
+  Record<never, never>;
+// Typed loader / action args
+export type TypedLoaderArgs<T extends AppRoutes> = { request: Request; params: RouteParams<T>; context: Record<string, unknown> };
+export type TypedActionArgs<T extends AppRoutes> = TypedLoaderArgs<T> & { formData: FormData };
+// Type-safe route builder
+export const routes = {
+  "/": () => "/",
+  "/blog/:id": (params: { id: string }) => `/blog/${params.id}`,
+} as const;
+```
+**Usage:**
+```ts
+// Typed loader — params.id is string, not string | undefined
+import type { TypedLoaderArgs, RouteParams } from "../route-types.gen.ts";
+export async function loader({ params }: TypedLoaderArgs<"/blog/:id">) {
+  return db.post.findById(params.id); // ✓ typed
+}
+// Typed params hook
+const { id } = useParams<RouteParams<"/blog/:id">>();
+// Type-safe navigation
+import { routes } from "../route-types.gen.ts";
+routes["/blog/:id"]({ id: "123" });         // → "/blog/123"
+routes["/does-not-exist"]();                 // ✗ TypeScript error
+```
+---
+## Server Actions & Client Components
+### `"use server"` — Server Actions
+Add `"use server"` as the first line of a file to mark its exports as Server Actions. On the client, calls are automatically serialized to `POST /_action?id=<hash>`. On the server, the real function runs.
+```ts
+// app/actions.ts
+"use server";
+export async function createPost(formData: FormData) {
+  const title = formData.get("title") as string;
+  await db.insert(posts).values({ title });
+  return { ok: true };
+}
+export async function deletePost(id: string) {
+  await db.delete(posts).where(eq(posts.id, id));
+}
+```
+```tsx
+// app/routes/new.tsx — import used normally; on client it becomes a fetch proxy
+import { createPost } from "../actions.ts";
+export default function NewPost() {
+  return (
+    <form action={createPost}>
+      <input name="title" />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+Server actions accept `FormData` (sent as `multipart/form-data`) or JSON-serializable argument arrays. Unknown action IDs return 404 — there is no way to call a function that was not registered at startup.
+### `"use client"` — Client-Only Components
+Add `"use client"` to mark a component as browser-only. During server builds the module is stubbed to `null` to prevent browser API (`window`, `document`, `localStorage`) crashes.
+```tsx
+// app/components/Counter.tsx
+"use client";
+import { useState } from "react";
+export function Counter() {
+  const [n, setN] = useState(0);
+  return <button onClick={() => setN(n + 1)}>Count: {n}</button>;
+}
+```
+---
+## Middleware
+Middleware runs before routing. Register on the module-level `pipeline` singleton.
+```ts
+import { pipeline, requestLogger, cors, authGuard } from "bractjs";
+pipeline
+  .use(requestLogger())
+  .use(cors({ origin: "https://myapp.com" }))
+  .use(authGuard({ session }));
+```
+| Middleware | Description |
+|---|---|
+| `requestLogger()` | Logs method, path, status, duration |
+| `cors(options)` | Sets CORS headers, handles `OPTIONS` preflight |
+| `authGuard(options)` | Reads session, attaches `context.user`, returns 401 if unauthenticated |
+**Custom middleware:**
+```ts
+import type { MiddlewareFn } from "bractjs";
+const trace: MiddlewareFn = async (ctx, next) => {
+  ctx.context.requestId = crypto.randomUUID();
+  return next();
+};
+```
+`ctx.context` is threaded into every `loader` and `action` as the `context` argument.
+---
+## Sessions
+```ts
+import { createCookieSession } from "bractjs";
+const session = createCookieSession({
+  name: "__session",
+  secrets: [Bun.env.SESSION_SECRET],  // rotate: prepend new secret, keep old ones
+  maxAge: 60 * 60 * 24 * 7,           // 1 week
+  secure: true,
+  sameSite: "lax",
+});
+export async function loader({ request }: LoaderArgs) {
+  const s = await session.getSession(request.headers.get("Cookie"));
+  return { user: s.get("user") };
+}
+export async function action({ request }: ActionArgs) {
+  const s = await session.getSession(request.headers.get("Cookie"));
+  s.set("user", { id: 1, name: "Alice" });
+  return redirect("/dashboard", {
+    headers: { "Set-Cookie": await session.commitSession(s) },
+  });
+}
+```
+Cookies are signed with HMAC-SHA256 using `crypto.subtle`. Tampered cookies are silently rejected and return an empty session.
+> Generate a secret: `openssl rand -base64 32`
+---
+## Environment Variables
+| Convention | Behavior |
+|---|---|
+| `*.server.ts` / `*.server.tsx` | Import blocked in client bundles at build time — hard error |
+| Keys in `clientEnv` | Replaced with string literals in client bundle |
+| All other `process.env.*` | Become `"undefined"` in client bundles |
+```ts
+// db.server.ts — never reaches the browser
+export const db = new Database(Bun.env.DATABASE_URL);
+```
+---
+## Configuration Reference
+All fields are optional. BractJS works with zero configuration.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `port` | `number` | `3000` | TCP port |
+| `appDir` | `string` | `"./app"` | Directory containing `routes/` and `root.tsx` |
+| `publicDir` | `string` | `"./public"` | Static assets (served with no-cache) |
+| `buildDir` | `string` | `"./build"` | Output for `bractjs build` |
+| `imageCacheDir` | `string` | `".bract-image-cache"` | Disk cache for optimized images |
+| `sourcemap` | `string` | `"external"` | `"none"` \| `"inline"` \| `"external"` |
+| `minify` | `boolean` | `true` | Minify client bundles |
+| `clientEnv` | `string[]` | `[]` | `process.env` keys exposed to the client |
+---
+## CLI
+| Command | Description |
+|---------|-------------|
+| `bractjs new <name>` | Scaffold a new app into `<name>/` |
+| `bractjs dev` | Start dev server with HMR on port 3000 |
+| `bractjs build` | Dual server + client build with content-hashed output |
+| `bractjs start` | Serve the production build |
+| `bractjs codegen [app] [out]` | Generate typed route types into `app/route-types.gen.ts` |
+---
+## App Directory Structure
+```
+my-app/
+├── app/
+│   ├── root.tsx              # required — <html> shell
+│   ├── route-types.gen.ts    # generated by bractjs codegen
+│   ├── actions.ts            # "use server" actions
+│   └── routes/
+│       ├── _index.tsx        # → /
+│       ├── about.tsx         # → /about
+│       ├── blog/
+│       │   ├── layout.tsx    # layout for /blog/*
+│       │   ├── _index.tsx    # → /blog
+│       │   └── [id].tsx      # → /blog/:id
+│       └── docs/
+│           └── [...slug].tsx # → /docs/*
+├── public/
+│   └── favicon.ico
+└── build/                    # generated — do not edit
+    ├── server/
+    ├── client/
+    └── route-manifest.json
+```
+---
+## Architecture
+```
+Request
+  └─ Middleware pipeline
+       └─ /_action  → Server Action registry → fn(...args)
+       └─ /_image   → ImageMagick transform → LRU cache → Response
+       └─ Route trie (static > param > catch-all)
+            └─ Layout chain (root → layout → route)
+                 └─ Parallel loaders (Promise.all)
+                      └─ renderToReadableStream → streaming Response
+```
+Client:
+```
+hydrateRoot(document)
+  └─ ClientRouter (RouterContext + NavigationContext)
+       └─ Outlet → React.lazy route chunk
+            └─ useLoaderData / useParams / useNavigation / …
+```
+Build pipeline (`bractjs build`):
+```
+1. codegen        → app/route-types.gen.ts
+2. server bundle  → Bun.build (target: bun)   + useClientStubPlugin
+3. client bundle  → Bun.build (target: browser, splitting) + useServerProxyPlugin
+4. content-hash   → rename outputs, write route-manifest.json
+```
+---
+## Package Structure
+```
+bractjs/
+├── src/
+│   ├── server/      # SSR, routing, loaders, actions, sessions, action-registry
+│   ├── client/      # hydrateRoot, contexts, hooks, Link/Form/Image components
+│   ├── build/       # Bun.build orchestration, manifest, hashing, directives
+│   ├── codegen/     # route-types.gen.ts generator
+│   ├── image/       # /_image handler, ImageMagick optimizer, LRU cache
+│   ├── dev/         # watcher, HMR server + client, error overlay
+│   ├── shared/      # types, errors, deferred, context
+│   └── middleware/  # requestLogger, cors, authGuard
+├── bin/cli.ts
+├── types/           # TypeScript declaration files
+└── templates/
+    └── new-app/     # scaffold template
+```
+---
+## Why BractJS
+- **Bun-native** — `Bun.serve`, `Bun.build`, `Bun.file`, `Bun.Glob`, `Bun.watch`. No Node.js.
+- **Zero framework deps** — only peer dependencies are `react` and `react-dom`.
+- **Streaming SSR** — `renderToReadableStream()` with `defer()` for slow data.
+- **File-based routing** — drop a file in `app/routes/`, it's a route.
+- **Full-stack** — loaders, actions, sessions, server actions, and middleware in one package.
+- **Typed routes** — codegen produces per-route param types and a type-safe route builder.
+---
+## Status
+**v0.1.0 complete.** All core phases shipped:
+- File-based routing with trie matcher and layout chains
+- Streaming SSR (`renderToReadableStream`) with `defer()` and `<Await>`
+- Client hydration, soft navigation, `popstate`, prefetch
+- HMR with module-level swap (no full reload)
+- Cookie sessions with HMAC-SHA256 and secret rotation
+- Middleware pipeline with `requestLogger`, `cors`, `authGuard`
+- Production build with content-hashed assets and code splitting
+Post-v0.1.0 features also shipped:
+- `<Image>` with on-demand ImageMagick optimization and LRU cache
+- Typed routes codegen (`AppRoutes`, `RouteParams<T>`, `TypedLoaderArgs<T>`, `routes` builder)
+- `"use server"` / `"use client"` directive system with `/_action` endpoint
+Remaining on the roadmap: Edge runtime (Cloudflare Workers), CSS modules, i18n routing, streaming `useFetcher()`.
+---
+## License
+MIT

package/bin/cli.ts ADDED Viewed

@@ -0,0 +1,101 @@
+#!/usr/bin/env bun
+import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+export {}; // make this file a module
+const command = process.argv[2];
+// ── new <app-name> ──────────────────────────────────────────────────────────
+async function scaffoldNew(appName: string): Promise<void> {
+  if (!appName) {
+    console.error("Usage: bractjs new <app-name>");
+    process.exit(1);
+  }
+  const appDir = resolve(process.cwd(), appName);
+  if (existsSync(appDir)) {
+    console.error(`Directory "${appName}" already exists.`);
+    process.exit(1);
+  }
+  const templateDir = join(import.meta.dirname, "../templates/new-app");
+  // Absolute path to the bractjs package itself — used as a file: dep before npm publish
+  const bractPackageDir = resolve(import.meta.dirname, "..");
+  console.log(`Creating ${appName}...`);
+  // Recursively copy template files, substituting {{APP_NAME}} and {{BRACT_PATH}}
+  await copyDir(templateDir, appDir, appName, bractPackageDir);
+  // Install dependencies
+  console.log("Installing dependencies...");
+  const result = Bun.spawnSync(["bun", "install"], { cwd: appDir, stdio: ["inherit", "inherit", "inherit"] });
+  if (result.exitCode !== 0) {
+    console.error("bun install failed.");
+    process.exit(result.exitCode ?? 1);
+  }
+  console.log(`\n✓ Created ${appName}\n`);
+  console.log("Next steps:");
+  console.log(`  cd ${appName}`);
+  console.log("  bun run dev");
+}
+async function copyDir(src: string, dest: string, appName: string, bractPath: string): Promise<void> {
+  const glob = new Bun.Glob("**/*");
+  for await (const rel of glob.scan({ cwd: src, onlyFiles: true })) {
+    const srcPath = join(src, rel);
+    const destPath = join(dest, rel);
+    // Ensure parent directory exists
+    const parentDir = destPath.slice(0, destPath.lastIndexOf("/"));
+    await Bun.write(destPath, ""); // creates parent dirs
+    let content = await Bun.file(srcPath).text();
+    content = content.replaceAll("{{APP_NAME}}", appName);
+    content = content.replaceAll("{{BRACT_PATH}}", bractPath);
+    await Bun.write(destPath, content);
+  }
+}
+// ── dispatch ────────────────────────────────────────────────────────────────
+switch (command) {
+  case "new":
+    await scaffoldNew(process.argv[3]);
+    break;
+  case "dev":
+    await import("../src/dev/server.ts");
+    break;
+  case "build": {
+    const { runBuild } = await import("../src/build/bundler.ts");
+    await runBuild({ port: 3000, appDir: "./app", publicDir: "./public", buildDir: "./build", manifest: { clientEntry: "", routes: {} } });
+    break;
+  }
+  case "start": {
+    const { createServer } = await import("../src/server/serve.ts");
+    createServer({ port: 3000, buildDir: "./build" });
+    break;
+  }
+  case "codegen": {
+    const { writeRouteTypes } = await import("../src/codegen/route-codegen.ts");
+    const appDir = resolve(process.cwd(), process.argv[3] ?? "./app");
+    const outPath = process.argv[4] ? resolve(process.cwd(), process.argv[4]) : undefined;
+    await writeRouteTypes(appDir, outPath);
+    break;
+  }
+  default:
+    console.log(
+      "Usage: bractjs <command>\n" +
+        "  new      <app-name>    Scaffold a new BractJS app\n" +
+        "  dev                    Start dev server with HMR\n" +
+        "  build                  Build for production\n" +
+        "  start                  Start production server\n" +
+        "  codegen  [app] [out]   Generate typed route types",
+    );
+    process.exit(1);
+}