brustjs 0.1.10-alpha → 0.1.12-alpha

package/README.md

@@ -73,6 +73,7 @@ route apiece.
 ```
 brustjs dev   <entry>             # dev mode: watcher + WS reload + browser auto-reload
 brustjs build <entry> --out-dir D # prebuilt ./dist/ — run from the project (bun run dist/index.js)
+                  --target <auto|all|TARGET[,…]> # which native binary to bundle (default: auto = host platform)
 brustjs new   <name>              # scaffold a project (partial — see Status)
 ```
 
@@ -84,13 +85,18 @@ brustjs new   <name>              # scaffold a project (partial — see Status)
   `renderToString` runs once per key, then serves a frozen pair from Rust.
 - **`native: true` routes** — JSX compiled to a jinja template at build time and
   rendered Rust-side (`minijinja`), skipping React on the server entirely.
-- **Server actions** (`"use server"`) → per-action endpoints; client helper rewrites
-  form/`fetch` targets.
+- **Typed actions** — `defineActions().get/post/put/patch/delete/head(path, ctx => R, { body, query })`
+  on the server; `client<typeof actions>()` is an Eden-Treaty-style proxy that
+  infers the whole API from the server types (no codegen) and returns
+  `{ data, error, status, headers }` (never throws). Standard Schema (zod)
+  validation, JSON / urlencoded / multipart bodies.
 - **SSE & WebSockets** as first-class route shapes.
 - Nested routes + dynamic params, per-route typed loaders, request-scoped middleware,
-  forms/multipart, SPA-style navigation, in-process LRU response cache + island ISR cache, Tailwind v4 + CSS Modules.
-- **Agent-first** — server fns and routes expose MCP tool/resource schemas at
-  `/_brust/mcp` so agents drive the app without scraping.
+  SPA-style navigation, in-process LRU response cache + island ISR cache, Tailwind v4 + CSS Modules.
+- **Agent-first** — `defineActions` endpoints become MCP **tools** and route
+  loaders become **resources** at `/_brust/mcp`; `tools/call` runs through the
+  same validation + middleware as an HTTP request, so agents drive the app
+  without scraping.
 
 ## Performance
 
@@ -119,9 +125,9 @@ bench/ · docs/ · architecture.md
 ## Status
 
 Alpha, solo-developed. Linux is tier-1 (io_uring; glibc + musl, 6 prebuilt platform
-binaries). Known partials: `brustjs dev` TS reload is a full worker-respawn reload
-(not state-preserving HMR), islands + `.module.css`. Tailwind
-is opt-in — the scaffold adds it as a project dependency; `@import "tailwindcss"`
+binaries). Known partials: `brustjs dev` reload is a full worker-respawn (not
+state-preserving HMR) — TS, islands, and `.module.css` all reload that way.
+Tailwind is opt-in — the scaffold adds it as a project dependency; `@import "tailwindcss"`
 resolves from your own `node_modules`. Deployment note: the io_uring server needs `io_uring_*`
 syscalls permitted — a default-seccomp container (Docker/k8s) must allow them or run
 `--security-opt seccomp=unconfined`. Roadmap and limitations in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brustjs",
-  "version": "0.1.10-alpha",
+  "version": "0.1.12-alpha",
   "description": "Bun + Rust SSR framework — React on the server, Rust everywhere else (napi cdylib + per-worker SharedArrayBuffer).",
   "license": "MIT",
   "repository": {
@@ -40,12 +40,12 @@
     "typescript": "^6.0.3"
   },
   "optionalDependencies": {
-    "brustjs-darwin-x64": "0.1.10-alpha",
-    "brustjs-darwin-arm64": "0.1.10-alpha",
-    "brustjs-linux-x64-gnu": "0.1.10-alpha",
-    "brustjs-linux-arm64-gnu": "0.1.10-alpha",
-    "brustjs-linux-x64-musl": "0.1.10-alpha",
-    "brustjs-linux-arm64-musl": "0.1.10-alpha"
+    "brustjs-darwin-x64": "0.1.12-alpha",
+    "brustjs-darwin-arm64": "0.1.12-alpha",
+    "brustjs-linux-x64-gnu": "0.1.12-alpha",
+    "brustjs-linux-arm64-gnu": "0.1.12-alpha",
+    "brustjs-linux-x64-musl": "0.1.12-alpha",
+    "brustjs-linux-arm64-musl": "0.1.12-alpha"
   },
   "peerDependencies": {
     "react": "^19.2.6",
@@ -59,7 +59,8 @@
     "happy-dom": "^20.9.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "zod": "^4.4.3"
   },
   "type": "module",
   "types": "./runtime/index.d.ts",

package/runtime/actions.ts

@@ -1,65 +1,7 @@
-import type { BrustRequest, Middleware } from './routes.ts'
-
-/** Server-side action handler. First arg is ALWAYS BrustRequest; the client
- * stub strips it from the call site. Subsequent args are JSON-decoded from
- * the request body (which MUST be a JSON array). */
-export type ActionFn<Args extends unknown[] = unknown[], R = unknown> = (
-  req: BrustRequest,
-  ...args: Args
-) => Promise<R>
-
-/** Registration shape passed to brust.registerActions. */
-export interface ActionDef<F extends ActionFn = ActionFn> {
-  /** Stable id; must match the id used by `action<F>(id)` on the client.
-   * Charset: [A-Za-z0-9_-]+ (enforced both in TS and in Rust). */
-  id: string
-  /** Handler. Receives req + JSON-decoded args. */
-  fn: F
-  /** Per-action middleware chain. Same Middleware type used by routes. */
-  middleware?: Middleware[]
-}
-
-/** Mirrors is_safe_action_id in src/lib.rs and src/server.rs.
- * Allowed: [A-Za-z0-9_-]+ only, max 128 chars. */
-export function isValidActionId(id: string): boolean {
-  if (id.length === 0 || id.length > 128) return false
-  return /^[A-Za-z0-9_-]+$/.test(id)
-}
-
-const BRUST_MW_KEY = '__brustMiddleware'
-
-/** Attach a middleware chain to a server-action function. The function is
- * returned unchanged so the TypeScript signature is preserved verbatim —
- * callers can still write `typeof srv.deleteNote` on the client.
- *
- * Throws TypeError if `mws` isn't an array of functions.
- * Throws Error if called twice on the same fn (compose mws in one call).
- */
-export function withMiddleware<F extends (...args: never[]) => unknown>(
-  mws: readonly Middleware[],
-  fn: F,
-): F {
-  if (!Array.isArray(mws) || mws.some((m) => typeof m !== 'function')) {
-    throw new TypeError('withMiddleware expects an array of middleware functions')
-  }
-  if ((fn as { [BRUST_MW_KEY]?: unknown })[BRUST_MW_KEY] !== undefined) {
-    throw new Error(
-      'withMiddleware called twice on the same function — compose middleware in a single call instead',
-    )
-  }
-  Object.defineProperty(fn, BRUST_MW_KEY, {
-    value: Object.freeze([...mws]),
-    enumerable: false,
-    writable: false,
-    configurable: false,
-  })
-  return fn
-}
-
-/** Read the middleware metadata installed by withMiddleware. Used by the
- * scanner to populate ActionDef.middleware. Returns undefined for plain
- * (un-wrapped) functions. */
-export function getActionMiddleware(fn: unknown): Middleware[] | undefined {
-  if (typeof fn !== 'function') return undefined
-  return (fn as { [BRUST_MW_KEY]?: Middleware[] })[BRUST_MW_KEY]
-}
+export type {
+  EndpointDef,
+  ActionContext,
+  EndpointOptions,
+  ActionsBuilder,
+} from './define-actions.ts'
+export { defineActions, isValidEndpointPath } from './define-actions.ts'

package/runtime/cli/build.ts

@@ -1,11 +1,7 @@
 import { existsSync } from 'node:fs'
-import { copyFile, mkdir, readdir, rm } from 'node:fs/promises'
+import { copyFile, cp, mkdir, readdir, rm } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import path, { isAbsolute, resolve } from 'node:path'
-import {
-  actionsPrebuiltPlugin,
-  writePrebuiltActionsFileWithMap,
-} from './actions-prebuilt-plugin.ts'
 import { emitNativeTemplates } from './native-routes-emit.ts'
 import { nativeShimPlugin } from './native-shim-plugin.ts'
 
@@ -59,14 +55,98 @@ async function collectNativeBinaries(): Promise<string[]> {
   return out
 }
 
+/** The 6 published platform targets (root package.json optionalDependencies),
+ * keyed by the napi binary infix `<platform>-<arch>[-<libc>]`. */
+export const VALID_TARGETS = [
+  'darwin-x64',
+  'darwin-arm64',
+  'linux-x64-gnu',
+  'linux-arm64-gnu',
+  'linux-x64-musl',
+  'linux-arm64-musl',
+] as const
+
+/** Host target infix — reuses the same detection as platformPackageName by
+ * stripping the `brustjs-` prefix. */
+export function hostTargetInfix(): string {
+  return platformPackageName().replace(/^brustjs-/, '')
+}
+
+function basenameTarget(absPath: string): string | null {
+  const b = absPath.replace(/^.*[/\\]/, '') // basename
+  const m = /^brust\.(.+)\.node$/.exec(b)
+  return m ? m[1] : null
+}
+
+/** Select which collected `brust.*.node` paths to copy for `target`.
+ * Pure: takes the collected absolute paths, returns selected paths + errors. */
+export function selectNativeBinaries(
+  collected: string[],
+  target: string,
+): { selected: string[]; errors: string[] } {
+  // Dedupe tokens here so `selected` never contains duplicate paths — the
+  // function's contract is a clean selection, independent of any caller-side
+  // copy-dedup (`--target darwin-arm64,darwin-arm64` must select once).
+  const tokens = [
+    ...new Set(
+      target
+        .split(',')
+        .map((t) => t.trim().toLowerCase())
+        .filter(Boolean),
+    ),
+  ]
+  const byTarget = new Map<string, string>() // infix → first abs path (dedupe)
+  for (const p of collected) {
+    const t = basenameTarget(p)
+    if (t && !byTarget.has(t)) byTarget.set(t, p)
+  }
+
+  if (tokens.length === 0) return { selected: [], errors: ['brust build: empty --target'] }
+
+  const hasAuto = tokens.includes('auto')
+  const hasAll = tokens.includes('all')
+  if ((hasAuto || hasAll) && tokens.length > 1) {
+    return {
+      selected: [],
+      errors: [
+        `brust build: --target "${target}" — auto/all cannot be combined with other targets`,
+      ],
+    }
+  }
+  if (hasAll) return { selected: [...byTarget.values()], errors: [] }
+
+  const wanted = hasAuto ? [hostTargetInfix()] : tokens
+  const selected: string[] = []
+  const errors: string[] = []
+  for (const t of wanted) {
+    if (!hasAuto && !VALID_TARGETS.includes(t as (typeof VALID_TARGETS)[number])) {
+      errors.push(
+        `brust build: unknown target "${t}" (valid: ${VALID_TARGETS.join(', ')}, or auto/all)`,
+      )
+      continue
+    }
+    const p = byTarget.get(t)
+    if (!p) {
+      errors.push(
+        `brust build: no native binary for target "${t}" — install brustjs-${t} or build it (bun --filter runtime run build)`,
+      )
+      continue
+    }
+    selected.push(p)
+  }
+  return { selected, errors }
+}
+
 interface ParsedArgs {
   entry: string // absolute path to the entry file
   outDir: string // absolute path to the output dir
+  target: string // --target value (default 'auto')
 }
 
 function parseArgs(args: string[]): ParsedArgs {
   let entry: string | undefined
   let outDir: string | undefined
+  let target = 'auto'
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
@@ -78,6 +158,18 @@ function parseArgs(args: string[]): ParsedArgs {
       }
     } else if (a.startsWith('--out-dir=')) {
       outDir = a.slice('--out-dir='.length)
+    } else if (a === '--target') {
+      target = args[++i]
+      if (!target) {
+        console.error('brust build: --target requires a value')
+        process.exit(1)
+      }
+    } else if (a.startsWith('--target=')) {
+      target = a.slice('--target='.length)
+      if (!target) {
+        console.error('brust build: --target= requires a value')
+        process.exit(1)
+      }
     } else if (a.startsWith('-')) {
       console.error(`brust build: unknown flag "${a}"`)
       process.exit(1)
@@ -107,11 +199,11 @@ function parseArgs(args: string[]): ParsedArgs {
       : resolve(cwd, outDir)
     : resolve(cwd, 'dist')
 
-  return { entry: entryPath, outDir: outPath }
+  return { entry: entryPath, outDir: outPath, target }
 }
 
 export async function runBuild(args: string[]): Promise<void> {
-  const { entry, outDir } = parseArgs(args)
+  const { entry, outDir, target } = parseArgs(args)
   const entryDir = path.dirname(entry)
 
   console.log(`[brust build] entry:  ${entry}`)
@@ -121,18 +213,11 @@ export async function runBuild(args: string[]): Promise<void> {
   await rm(outDir, { recursive: true, force: true })
   await mkdir(outDir, { recursive: true })
 
-  // 2. Scan actions + rediscover id→source mapping for the prebuilt plugin.
-  const { scanActions, collectExports } = await import('../scan-actions.ts')
-  const scan = await scanActions({ roots: [entryDir] })
-  console.log(
-    `[brust build] actions: discovered ${scan.actions.length} (${scan.actions.map((a) => a.id).join(', ') || '(none)'})`,
-  )
-
-  const idToSource = new Map<string, string>()
-  for (const file of scan.sourceFiles) {
-    const defs = await collectExports(file)
-    for (const def of defs) idToSource.set(def.id, file)
-  }
+  // 2. Actions need no build-time codegen. With `defineActions(...)`, actions
+  // are an EXPLICIT module the app entry imports and passes to
+  // `brust.run({ actions })` — the dist boot registers them through the normal
+  // `import { actions } from './actions'` path, no scan and no `_actions-prebuilt`
+  // file. (The old `'use server'` filesystem scanner is gone.)
 
   // routes.tsx is the scan target for both islands (§3) and the MCP manifest
   // (§4). Computed once here and reused below.
@@ -147,6 +232,18 @@ export async function runBuild(args: string[]): Promise<void> {
     const islandsOutDir = path.join(outDir, 'islands')
     const result = await buildIslands(islandMap, { outDir: islandsOutDir })
     console.log(`[brust build] islands: ${result.islandCount} chunk(s) → ${islandsOutDir}`)
+
+    // Mirror into cwd/.brust/islands so the NON-prebuilt source runtime
+    // (`bun run <entry>` directly, and `bun run dev`) — which reads
+    // cwd/.brust/islands (see runtime/islands/build.ts default outDir) — finds
+    // the same chunks after a build. The prebuilt dist reads <distDir>/islands;
+    // this keeps the dev/source path working without a separate bundle step.
+    // Mirrors the jinja mirror below. `.brust/` is a gitignored cache dir.
+    const localIslandsDir = path.join(process.cwd(), '.brust', 'islands')
+    if (path.resolve(localIslandsDir) !== path.resolve(islandsOutDir)) {
+      await rm(localIslandsDir, { recursive: true, force: true })
+      await cp(islandsOutDir, localIslandsDir, { recursive: true })
+    }
   } else {
     console.log('[brust build] islands: skipped (no <Island> usage)')
   }
@@ -157,11 +254,11 @@ export async function runBuild(args: string[]): Promise<void> {
     const { extractMcpManifest } = await import('../mcp/extractor.ts')
     const { routes } = await import(routesFile)
     loadedRoutes = routes
+    const actionsFile = path.join(entryDir, 'actions.ts')
     const manifest = await extractMcpManifest({
-      serverFiles: scan.sourceFiles,
+      actionsFile: existsSync(actionsFile) ? actionsFile : undefined,
       routesFile,
       sourceRoots: [entryDir],
-      actions: scan.actions,
       routes,
     })
     const manifestPath = path.join(outDir, 'mcp-manifest.json')
@@ -177,12 +274,11 @@ export async function runBuild(args: string[]): Promise<void> {
   // native: true route. Pipeline runs even if no native routes exist (writes
   // an empty manifest) so consumers can rely on the output dir's presence.
   {
-    // outDir must align with the runtime's loadJinjaOnce which reads from
-    // `process.cwd() + '.brust/jinja'`. Existing CSS pipeline uses cwd too
-    // (see boot log: "built CSS → <cwd>/.brust/css/app.css"). entryDir
-    // diverges when user runs `bun run dev <entry>` from a different dir;
-    // cwd is the single source of truth for both pipelines.
-    const jinjaDir = path.join(process.cwd(), '.brust/jinja')
+    // Emit jinja templates INTO the build output dir (`<outDir>/jinja`), next to
+    // the other pre-built artifacts (islands, css, mcp-manifest), so a dist-only
+    // deploy ships the templates. The prebuilt runtime reads them from
+    // `<BRUST_DIST_DIR>/jinja` (see index.ts loadJinjaOnce / configureJinjaDir).
+    const jinjaDir = path.join(outDir, 'jinja')
     // Spec §7 Component-source resolution: scan the routes module's source for
     // ImportDeclarations, NOT the app entry's. The app entry only imports the
     // routes module + brust; the page components are imported by routes.tsx.
@@ -197,6 +293,17 @@ export async function runBuild(args: string[]): Promise<void> {
     })
     const nativeCount = (loadedRoutes ?? []).filter((r: any) => r?.nativeTemplate).length
     console.log(`[brust build] jinja:   ${nativeCount} template(s) → ${jinjaDir}`)
+
+    // Also mirror into cwd/.brust/jinja so the NON-prebuilt source runtime
+    // (`bun run <entry>` directly, and `bun run dev`) — which reads
+    // cwd/.brust/jinja — finds the same templates after a build. The prebuilt
+    // dist reads <distDir>/jinja (above); this keeps the dev/source path working
+    // without a separate compile step. `.brust/` is a gitignored cache dir.
+    const localJinjaDir = path.join(process.cwd(), '.brust', 'jinja')
+    if (path.resolve(localJinjaDir) !== path.resolve(jinjaDir)) {
+      await rm(localJinjaDir, { recursive: true, force: true })
+      await cp(jinjaDir, localJinjaDir, { recursive: true })
+    }
   }
 
   // 4.5. CSS — Tailwind v4 if app.css is present.
@@ -244,11 +351,10 @@ export async function runBuild(args: string[]): Promise<void> {
     }
   }
 
-  // 5. Generate the prebuilt-actions file (always — empty list if no actions).
-  const prebuiltActionsPath = path.join(outDir, '_actions-prebuilt.ts')
-  await writePrebuiltActionsFileWithMap(prebuiltActionsPath, idToSource, REPO_ROOT)
-
-  // 6. Bun.build the server bundle with both plugins + banner.
+  // 5. Bun.build the server bundle with the native shim plugin + banner. No
+  // actions codegen: `defineActions(...)` actions register via the app entry's
+  // `import { actions } from './actions'` → `brust.run({ actions })` path, which
+  // the bundled entry already carries.
   const banner =
     `process.env.BRUST_PREBUILT = '1';\n` + `process.env.BRUST_DIST_DIR = import.meta.dir;\n`
 
@@ -274,7 +380,7 @@ export async function runBuild(args: string[]): Promise<void> {
     // point at non-existent files. Whitespace + syntax minification still apply.
     minify: { whitespace: true, syntax: true, identifiers: false },
     banner,
-    plugins: [nativeShimPlugin(REPO_ROOT), actionsPrebuiltPlugin(prebuiltActionsPath, REPO_ROOT)],
+    plugins: [nativeShimPlugin(REPO_ROOT)],
   })
 
   if (!result.success) {
@@ -284,26 +390,30 @@ export async function runBuild(args: string[]): Promise<void> {
   }
   console.log(`[brust build] bundle:  ${path.join(outDir, 'index.js')}`)
 
-  // 7. Copy the current-platform native binary.
+  // 7. Copy the selected-platform native binary(ies).
   const nativeDir = path.join(outDir, 'native')
   await mkdir(nativeDir, { recursive: true })
 
   // napi-rs names the binary `brust.<platform>-<arch>[-libc].node` (binaryName
   // "brust", from the root napi config). Source/CI builds leave it in runtime/;
-  // an installed project carries it in the brustjs-<platform> package. Copy
-  // every match from both — multi-platform (CI matrix) and single-platform
-  // (local/installed) layouts both Just Work.
+  // an installed project carries it in the brustjs-<platform> package. The
+  // --target flag (default "auto" = host platform) selects which to copy.
   const nativeBinaries = await collectNativeBinaries()
-  if (nativeBinaries.length === 0) {
+  const { selected, errors } = selectNativeBinaries(nativeBinaries, target)
+  if (errors.length > 0) {
+    for (const e of errors) console.error(e)
+    process.exit(1)
+  }
+  if (selected.length === 0) {
     console.error(
-      `brust build: no native binary found. Looked in ${path.join(REPO_ROOT, 'runtime')} and ` +
-        `the ${platformPackageName()} package. From source run \`bun --filter runtime run build\` ` +
-        `(or :debug) first; in an installed project ensure the platform package is present.`,
+      `brust build: no native binary found for target "${target}". Looked in ` +
+        `${path.join(REPO_ROOT, 'runtime')} and the ${platformPackageName()} package. ` +
+        `From source run \`bun --filter runtime run build\` first.`,
     )
     process.exit(1)
   }
   const seen = new Set<string>()
-  for (const src of nativeBinaries) {
+  for (const src of selected) {
     const name = path.basename(src)
     if (seen.has(name)) continue
     seen.add(name)

package/runtime/cli/help.ts

@@ -0,0 +1,125 @@
+// Dep-free CLI help/version rendering + a tiny ANSI color util. All functions
+// return strings (no console writes) so they're unit-testable. index.ts owns
+// the actual stdout/stderr + exit codes.
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+/** Read the brustjs package.json version. `help.ts` lives at
+ * <root>/runtime/cli/, so ../../package.json is <root>/package.json in both the
+ * source tree and an installed node_modules/brustjs layout. Never throws —
+ * returns "unknown" on any failure (version must not crash the CLI). */
+export function readVersion(): string {
+  try {
+    const p = path.join(import.meta.dir, '..', '..', 'package.json')
+    const pkg = JSON.parse(readFileSync(p, 'utf8')) as { version?: string }
+    return pkg.version ?? 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+function useColor(): boolean {
+  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+}
+function wrap(open: string, s: string): string {
+  return useColor() ? `\x1b[${open}m${s}\x1b[0m` : s
+}
+export const style = {
+  bold: (s: string) => wrap('1', s),
+  dim: (s: string) => wrap('2', s),
+  cyan: (s: string) => wrap('36', s),
+  green: (s: string) => wrap('32', s),
+  red: (s: string) => wrap('31', s),
+}
+
+interface CommandDef {
+  name: string
+  summary: string
+  usage: string
+  flags: { flag: string; desc: string }[]
+}
+
+export const COMMANDS: CommandDef[] = [
+  {
+    name: 'build',
+    summary: 'Compile a brust app to a self-contained dist/',
+    usage: 'brust build [entry] [options]',
+    flags: [
+      { flag: '[entry]', desc: 'Entry file (default ./index.ts)' },
+      { flag: '--out-dir <dir>', desc: 'Output directory (default ./dist)' },
+      {
+        flag: '--target <t>',
+        desc: 'Native target(s): auto | all | <platform>-<arch>[-<libc>][,…] (default auto)',
+      },
+    ],
+  },
+  {
+    name: 'dev',
+    summary: 'Run the dev server with hot reload',
+    usage: 'brust dev [entry] [options]',
+    flags: [
+      { flag: '[entry]', desc: 'Entry file (default ./index.ts)' },
+      { flag: '--port <n>', desc: 'Port to listen on' },
+    ],
+  },
+  {
+    name: 'new',
+    summary: 'Scaffold a new brust project',
+    usage: 'brust new <name> [options]',
+    flags: [
+      { flag: '<name>', desc: 'Project name (lowercase letters, digits, - _)' },
+      { flag: '--dir <path>', desc: 'Target directory (default ./<name>)' },
+    ],
+  },
+]
+
+function pad(s: string, w: number): string {
+  return s + ' '.repeat(Math.max(0, w - s.length))
+}
+
+export function renderVersion(): string {
+  return `brustjs ${readVersion()}`
+}
+
+export function renderRootHelp(): string {
+  const lines: string[] = []
+  lines.push(`${style.bold('brust')} ${style.dim(readVersion())} — the brust framework CLI`)
+  lines.push('')
+  lines.push(`${style.bold('Usage:')} brust <command> [options]`)
+  lines.push('')
+  const globals = [
+    { label: '-h, --help', desc: 'Show help (brust help <command> for details)' },
+    { label: '-v, --version', desc: 'Show the brustjs version' },
+  ]
+  // One shared column width across commands AND global flags so every
+  // description lines up in a single column.
+  const w = Math.max(...COMMANDS.map((c) => c.name.length), ...globals.map((g) => g.label.length))
+  lines.push(style.bold('Commands:'))
+  for (const c of COMMANDS) {
+    lines.push(`  ${style.cyan(pad(c.name, w))}  ${c.summary}`)
+  }
+  lines.push('')
+  lines.push(style.bold('Global:'))
+  for (const g of globals) {
+    lines.push(`  ${style.cyan(pad(g.label, w))}  ${g.desc}`)
+  }
+  lines.push('')
+  lines.push(style.dim('Run `brust help <command>` for command-specific options.'))
+  return lines.join('\n')
+}
+
+export function renderCommandHelp(name: string): string | null {
+  const c = COMMANDS.find((x) => x.name === name)
+  if (!c) return null
+  const lines: string[] = []
+  lines.push(`${style.bold('Usage:')} ${c.usage}`)
+  lines.push('')
+  lines.push(c.summary)
+  lines.push('')
+  lines.push(style.bold('Options:'))
+  const w = Math.max(...c.flags.map((f) => f.flag.length))
+  for (const f of c.flags) {
+    lines.push(`  ${style.cyan(pad(f.flag, w))}  ${f.desc}`)
+  }
+  return lines.join('\n')
+}

package/runtime/cli/index.ts

@@ -1,30 +1,65 @@
 #!/usr/bin/env bun
-const [, , subcommand, ...rest] = process.argv
+import { COMMANDS, renderCommandHelp, renderRootHelp, renderVersion } from './help.ts'
 
-switch (subcommand) {
-  case 'build': {
-    const { runBuild } = await import('./build.ts')
-    await runBuild(rest)
-    break
+const argv = process.argv.slice(2)
+const first = argv[0]
+const second = argv[1]
+
+// Derive from COMMANDS so the dispatch set and the help registry can never
+// drift (a name in KNOWN but absent from COMMANDS would print `null` as help).
+const KNOWN = new Set(COMMANDS.map((c) => c.name))
+
+function hasHelpFlag(args: string[]): boolean {
+  return args.includes('--help') || args.includes('-h')
+}
+
+if (first === '--version' || first === '-v' || first === 'version') {
+  console.log(renderVersion())
+  process.exit(0)
+}
+
+if (first === '--help' || first === '-h' || first === 'help') {
+  if (second && KNOWN.has(second)) {
+    console.log(renderCommandHelp(second))
+    process.exit(0)
   }
-  case 'dev': {
-    const { runDev } = await import('./dev.ts')
-    await runDev(rest)
-    break
+  if (second) {
+    console.error(`brust: unknown command "${second}".`)
+    console.error(renderRootHelp())
+    process.exit(1)
   }
-  case 'new': {
-    const { runNew } = await import('./new.ts')
-    await runNew(rest)
-    break
+  console.log(renderRootHelp())
+  process.exit(0)
+}
+
+if (first && KNOWN.has(first)) {
+  const rest = argv.slice(1)
+  if (hasHelpFlag(rest)) {
+    console.log(renderCommandHelp(first))
+    process.exit(0)
   }
-  default: {
-    if (!subcommand) {
-      console.error('brust: missing subcommand. Try: brust build | brust dev | brust new')
-    } else {
-      console.error(
-        `brust: unknown subcommand "${subcommand}". Try: brust build | brust dev | brust new`,
-      )
+  switch (first) {
+    case 'build': {
+      const { runBuild } = await import('./build.ts')
+      await runBuild(rest)
+      break
+    }
+    case 'dev': {
+      const { runDev } = await import('./dev.ts')
+      await runDev(rest)
+      break
+    }
+    case 'new': {
+      const { runNew } = await import('./new.ts')
+      await runNew(rest)
+      break
     }
-    process.exit(1)
   }
+} else if (!first) {
+  console.error(renderRootHelp())
+  process.exit(1)
+} else {
+  console.error(`brust: unknown command "${first}".`)
+  console.error('Run `brust --help` to see available commands.')
+  process.exit(1)
 }