brustjs 0.1.0-alpha

package/runtime/cli/new.ts

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+const TEMPLATE_DIR = join(import.meta.dir, 'templates', 'minimal')
+
+const NAME_RE = /^[a-z0-9][a-z0-9_-]*$/
+const MAX_NAME_LEN = 50
+
+export interface ParsedNewArgs {
+  projectName: string
+  targetDir: string
+}
+
+export function parseArgs(args: string[]): ParsedNewArgs {
+  let name: string | undefined
+  let dir: string | undefined
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (a === '--dir') {
+      dir = args[++i]
+      if (!dir) throw new Error('brust new: --dir requires a value')
+    } else if (a.startsWith('--dir=')) {
+      dir = a.slice('--dir='.length)
+    } else if (a.startsWith('-')) {
+      throw new Error(`brust new: unknown flag "${a}"`)
+    } else if (name === undefined) {
+      name = a
+    } else {
+      throw new Error(`brust new: unexpected positional argument "${a}"`)
+    }
+  }
+
+  if (!name) {
+    throw new Error('brust new: missing project name. Usage: brust new <name> [--dir <path>]')
+  }
+  if (name.length > MAX_NAME_LEN) {
+    throw new Error(`brust new: project name too long (max ${MAX_NAME_LEN} chars)`)
+  }
+  if (!NAME_RE.test(name)) {
+    throw new Error(
+      `brust new: invalid project name "${name}" — use lowercase letters, digits, hyphens, underscores; must start with a letter or digit`,
+    )
+  }
+
+  const cwd = process.cwd()
+  const targetDir = dir ? (isAbsolute(dir) ? dir : resolve(cwd, dir)) : resolve(cwd, name)
+
+  return { projectName: name, targetDir }
+}
+
+export interface BrustRef {
+  kind: 'file' | 'version'
+  spec: string // JSON-encoded string value (e.g. "file:/abs" or "^0.1.0")
+}
+
+function hasSourceMarkers(dir: string): boolean {
+  // Post-2026-05-28 workspace refactor: brust source layout is
+  //   <root>/Cargo.toml         (workspace)
+  //   <root>/crates/brust/      (the brust cdylib crate)
+  //   <root>/runtime/cli/...
+  // Pre-refactor layout had `<root>/src/` instead of `<root>/crates/brust/`;
+  // we no longer check `<root>/src` because the workspace root never has one.
+  return (
+    existsSync(join(dir, 'Cargo.toml')) &&
+    existsSync(join(dir, 'crates/brust/src')) &&
+    existsSync(join(dir, 'runtime/cli/index.ts'))
+  )
+}
+
+export function resolveBrustRef(startDir: string = import.meta.dir): BrustRef {
+  let dir = startDir
+  while (true) {
+    const pkgPath = join(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+        if (pkg.name === 'brustjs') {
+          if (hasSourceMarkers(dir)) {
+            return { kind: 'file', spec: `file:${dir}` }
+          }
+          const version = typeof pkg.version === 'string' ? pkg.version : '0.0.0'
+          return { kind: 'version', spec: `^${version}` }
+        }
+      } catch {
+        // malformed package.json — keep walking
+      }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) {
+      throw new Error('brust new: cannot locate the brust package — is your installation intact?')
+    }
+    dir = parent
+  }
+}
+
+export interface CopyTemplateOpts {
+  templateDir: string
+  targetDir: string
+  substitutions: Record<string, string>
+}
+
+export async function copyTemplate(opts: CopyTemplateOpts): Promise<void> {
+  if (!existsSync(opts.templateDir)) {
+    throw new Error(
+      `brust new: template directory not found at ${opts.templateDir}; this is a brust installation bug`,
+    )
+  }
+  await copyDir(opts.templateDir, opts.targetDir, opts.substitutions)
+}
+
+async function copyDir(src: string, dst: string, subs: Record<string, string>): Promise<void> {
+  await mkdir(dst, { recursive: true })
+  const entries = await readdir(src, { withFileTypes: true })
+  for (const ent of entries) {
+    const srcPath = join(src, ent.name)
+    const dstName = renameForEmit(ent.name)
+    const dstPath = join(dst, dstName)
+    if (ent.isDirectory()) {
+      await copyDir(srcPath, dstPath, subs)
+    } else if (ent.isFile()) {
+      const isTmpl = ent.name.endsWith('.tmpl')
+      if (isTmpl) {
+        const raw = await readFile(srcPath, 'utf8')
+        const out = applySubstitutions(raw, subs)
+        await writeFile(dstPath, out)
+      } else {
+        const buf = await readFile(srcPath)
+        await writeFile(dstPath, buf)
+      }
+    }
+  }
+}
+
+function renameForEmit(name: string): string {
+  if (name.endsWith('.tmpl')) return name.slice(0, -'.tmpl'.length)
+  if (name === '_gitignore') return '.gitignore'
+  return name
+}
+
+function applySubstitutions(text: string, subs: Record<string, string>): string {
+  let out = text
+  for (const [key, value] of Object.entries(subs)) {
+    out = out.split(key).join(value)
+  }
+  return out
+}
+
+export async function runNew(args: string[]): Promise<void> {
+  let parsed: ParsedNewArgs
+  try {
+    parsed = parseArgs(args)
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e))
+    process.exit(1)
+  }
+
+  const { projectName, targetDir } = parsed
+
+  const targetExisted = existsSync(targetDir)
+  if (targetExisted) {
+    const entries = await readdir(targetDir)
+    if (entries.length > 0) {
+      console.error(`brust new: target directory "${targetDir}" is not empty`)
+      process.exit(1)
+    }
+  }
+
+  let brustRef: BrustRef
+  try {
+    brustRef = resolveBrustRef()
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e))
+    process.exit(1)
+  }
+
+  try {
+    await copyTemplate({
+      templateDir: TEMPLATE_DIR,
+      targetDir,
+      substitutions: {
+        __PROJECT_NAME__: projectName,
+        __BRUST_DEP__: JSON.stringify(brustRef.spec),
+      },
+    })
+  } catch (e) {
+    if (!targetExisted) {
+      await rm(targetDir, { recursive: true, force: true }).catch(() => {})
+    }
+    console.error(`brust new: failed to scaffold (${e instanceof Error ? e.message : String(e)})`)
+    process.exit(1)
+  }
+
+  printNextSteps(projectName, targetDir)
+}
+
+function printNextSteps(name: string, targetDir: string): void {
+  const cwd = process.cwd()
+  const displayPath = targetDir.startsWith(cwd + '/')
+    ? './' + targetDir.slice(cwd.length + 1)
+    : targetDir
+  console.log(`Created ${name} at ${targetDir}\n`)
+  console.log(`Next:`)
+  console.log(`  cd ${displayPath}`)
+  console.log(`  bun install`)
+  console.log(`  bun run dev`)
+}

package/runtime/cli/templates/minimal/README.md.tmpl

@@ -0,0 +1,16 @@
+# __PROJECT_NAME__
+
+Scaffolded with `brust new`.
+
+## Develop
+
+    bun install
+    bun run dev
+
+Open http://127.0.0.1:3000.
+
+## Build
+
+    bun run build
+
+Outputs a standalone `dist/` you can ship — `bun run dist/index.js` boots the server.

package/runtime/cli/templates/minimal/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.brust/
+dist/
+brust.toml

package/runtime/cli/templates/minimal/app.css

@@ -0,0 +1,6 @@
+@import "tailwindcss";
+@source "./**/*.{tsx,ts}";
+
+@theme {
+  --color-brand: #2563eb;
+}

package/runtime/cli/templates/minimal/components/Counter.tsx

@@ -0,0 +1,13 @@
+import { useState } from 'react'
+
+export default function Counter({ start = 0, label = 'count' }: { start?: number; label?: string }) {
+  const [n, setN] = useState(start)
+  return (
+    <button
+      onClick={() => setN(n + 1)}
+      className="px-3 py-1.5 bg-brand text-white rounded text-sm hover:opacity-90 transition-opacity"
+    >
+      {label}: {n}
+    </button>
+  )
+}

package/runtime/cli/templates/minimal/components/Layout.tsx

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react'
+
+export default function Layout({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>{title}</title>
+      </head>
+      <body className="bg-white text-gray-900 font-sans">
+        <main className="max-w-3xl mx-auto px-5 py-8">{children}</main>
+      </body>
+    </html>
+  )
+}

package/runtime/cli/templates/minimal/index.ts

@@ -0,0 +1,4 @@
+import { brust } from 'brustjs'
+import { routes } from './routes'
+
+await brust.run({ routes, entry: import.meta.url })

package/runtime/cli/templates/minimal/package.json.tmpl

@@ -0,0 +1,21 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "brustjs dev",
+    "build": "brustjs build"
+  },
+  "dependencies": {
+    "brustjs": __BRUST_DEP__,
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^6.0.3"
+  }
+}

package/runtime/cli/templates/minimal/pages/Home.tsx.tmpl

@@ -0,0 +1,16 @@
+import { Island } from 'brustjs'
+import Layout from '../components/Layout'
+import Counter from '../components/Counter'
+
+export default function Home() {
+  return (
+    <Layout title="__PROJECT_NAME__">
+      <h1 className="text-3xl font-bold mb-4">Welcome to brust</h1>
+      <p className="mb-4 text-gray-700">
+        Edit <code className="bg-gray-100 px-1 rounded">pages/Home.tsx</code> and save —
+        <code className="bg-gray-100 px-1 rounded ml-1">brustjs dev</code> will reload.
+      </p>
+      <Island component={Counter} props={{ start: 0, label: 'clicks' }} hydrate="load" />
+    </Layout>
+  )
+}

package/runtime/cli/templates/minimal/routes.tsx

@@ -0,0 +1,6 @@
+import { defineRoutes } from 'brust/routes'
+import Home from './pages/Home'
+
+export const routes = defineRoutes([
+  { path: '/', Component: Home },
+])

package/runtime/cli/templates/minimal/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "types": ["bun"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  }
+}

package/runtime/client/index.ts

@@ -0,0 +1,121 @@
+/** Browser-only client helpers. This module is loaded by hydrated island
+ * bundles. It intentionally does NOT import from runtime/routes.ts or
+ * runtime/index.ts — those pull in React and server-side surface that the
+ * client doesn't need.
+ */
+
+export class BrustActionError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly payload: unknown,
+  ) {
+    super(message)
+    this.name = 'BrustActionError'
+  }
+}
+
+/** Untyped server-fn shape used as the generic constraint. The client never
+ * sees BrustRequest, so we type the leading req as `any` here — the helper
+ * strips it from the call site via DropReq<F>. */
+export type ServerFn = (req: any, ...args: any[]) => Promise<any>
+
+/** Drop the leading `req` arg from F's parameter list. */
+type DropReq<F> = F extends (req: any, ...args: infer A) => infer R ? (...args: A) => R : never
+
+/** Build a typed RPC stub for an action.
+ *
+ * Usage:
+ *   import type * as srv from '../actions'
+ *   const createNote = action<typeof srv.createNote>('createNote')
+ *   const { id } = await createNote('hello')  // typed Promise<{ id: string }>
+ *
+ * @param id  The action id — matches the named export from a `'use server'`
+ *            file discovered by `brust.scanActions()`. Use `withMiddleware`
+ *            to attach per-action middleware on the server side.
+ */
+export function action<F extends ServerFn>(id: string): DropReq<F> {
+  return (async (...args: unknown[]) => {
+    const res = await fetch(`/_brust/action/${encodeURIComponent(id)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(args),
+    })
+    const text = await res.text()
+    if (!res.ok) {
+      const parsed = safeParse(text)
+      const message =
+        parsed &&
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        'error' in parsed &&
+        parsed.error &&
+        typeof parsed.error === 'object' &&
+        'message' in parsed.error &&
+        typeof parsed.error.message === 'string'
+          ? parsed.error.message
+          : text || 'action failed'
+      throw new BrustActionError(message, res.status, parsed ?? text)
+    }
+    return text ? JSON.parse(text) : undefined
+  }) as DropReq<F>
+}
+
+function safeParse(s: string): unknown | null {
+  try {
+    return JSON.parse(s)
+  } catch {
+    return null
+  }
+}
+
+type FormActionFn<F> = F extends (req: any, fd: FormData) => infer R ? (fd: FormData) => R : never
+
+/** Build a typed RPC stub for a form-receiving action.
+ *
+ * The server handler MUST be declared with signature
+ * `(req: BrustRequest, fd: FormData) => Promise<R>`. The framework parses
+ * the request's multipart or form-urlencoded body server-side and passes
+ * a FormData instance to the handler.
+ *
+ * Usage:
+ *   import type * as srv from '../actions'
+ *   const uploadAvatar = formAction<typeof srv.uploadAvatar>('uploadAvatar')
+ *   const result = await uploadAvatar(new FormData(form))
+ *
+ * @param id  The action id — matches the named export from a `'use server'`
+ *            file discovered by `brust.scanActions()`.
+ */
+export function formAction<F extends (req: any, fd: FormData) => unknown>(
+  id: string,
+): FormActionFn<F> {
+  return (async (fd: FormData) => {
+    if (!(fd instanceof FormData)) {
+      throw new TypeError('formAction expects a FormData argument')
+    }
+    // DO NOT set Content-Type manually. fetch() auto-sets
+    // 'multipart/form-data; boundary=<random>' when body is a FormData;
+    // overriding loses the boundary and the server can't parse the body.
+    const res = await fetch(`/_brust/action/${encodeURIComponent(id)}`, {
+      method: 'POST',
+      body: fd,
+    })
+    const text = await res.text()
+    if (!res.ok) {
+      const parsed = safeParse(text)
+      const message =
+        parsed &&
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        'error' in parsed &&
+        parsed.error &&
+        typeof parsed.error === 'object' &&
+        'message' in parsed.error &&
+        typeof parsed.error.message === 'string'
+          ? parsed.error.message
+          : text || 'action failed'
+      throw new BrustActionError(message, res.status, parsed ?? text)
+    }
+    return text ? JSON.parse(text) : undefined
+  }) as FormActionFn<F>
+}

package/runtime/config.ts

@@ -0,0 +1,148 @@
+import os from 'node:os'
+import path from 'node:path'
+import { parse as parseToml } from 'smol-toml'
+
+export interface BrustConfig {
+  /** TCP port to bind on. Default 3000. */
+  port: number
+  /** Bun Worker count for render dispatch. Default `availableParallelism()`. */
+  workers: number
+  /** Cache capacity (entries). Undefined → Rust default of 1000. */
+  cacheMaxEntries?: number
+}
+
+export class BrustConfigError extends Error {
+  constructor(
+    message: string,
+    public readonly file: string | null,
+  ) {
+    super(message)
+    this.name = 'BrustConfigError'
+  }
+}
+
+const DEFAULT_PORT = 3000
+// One worker per CPU. Bumping the multiplier above 1 was tuned for I/O-bound
+// renders; on CPU-bound React work (typical) it over-subscribes and amplifies
+// p99 tail. Users with Suspense-heavy / await-heavy renders can override via
+// BRUST_WORKERS or workers.count in brust.toml.
+const defaultWorkers = (): number => os.availableParallelism()
+
+const CONFIG_BASENAME = 'brust.toml'
+
+/**
+ * Resolve Brust configuration. Precedence (low → high): defaults < TOML < env.
+ *
+ * - Defaults: { port: 3000, workers: availableParallelism() }
+ * - TOML: brust.toml at `cwd` (missing file is fine — only a present file with
+ *   wrong shape is an error).
+ * - Env: BRUST_PORT and BRUST_WORKERS override either source.
+ */
+export async function loadConfig(cwd: string = process.cwd()): Promise<BrustConfig> {
+  let fromToml: Partial<BrustConfig> = {}
+  const tomlPath = path.join(cwd, CONFIG_BASENAME)
+
+  const file = Bun.file(tomlPath)
+  if (await file.exists()) {
+    let parsed: unknown
+    try {
+      parsed = parseToml(await file.text())
+    } catch (e) {
+      throw new BrustConfigError(`failed to parse ${tomlPath}: ${(e as Error).message}`, tomlPath)
+    }
+    fromToml = extractFromToml(parsed, tomlPath)
+  }
+
+  const fromEnv = extractFromEnv()
+
+  const port = fromEnv.port ?? fromToml.port ?? DEFAULT_PORT
+  const workers = fromEnv.workers ?? fromToml.workers ?? defaultWorkers()
+
+  return { port, workers, cacheMaxEntries: fromToml.cacheMaxEntries }
+}
+
+function extractFromToml(parsed: unknown, file: string): Partial<BrustConfig> {
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new BrustConfigError(`${file}: top level must be a table`, file)
+  }
+  const root = parsed as Record<string, unknown>
+  const out: Partial<BrustConfig> = {}
+
+  if ('server' in root) {
+    const server = root.server
+    if (server === null || typeof server !== 'object') {
+      throw new BrustConfigError(`${file}: [server] must be a table`, file)
+    }
+    const port = (server as Record<string, unknown>).port
+    if (port !== undefined) {
+      if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new BrustConfigError(
+          `${file}: server.port must be an integer in 1..65535 (got ${JSON.stringify(port)})`,
+          file,
+        )
+      }
+      out.port = port
+    }
+  }
+
+  if ('workers' in root) {
+    const workers = root.workers
+    if (workers === null || typeof workers !== 'object') {
+      throw new BrustConfigError(`${file}: [workers] must be a table`, file)
+    }
+    const count = (workers as Record<string, unknown>).count
+    if (count !== undefined) {
+      if (typeof count !== 'number' || !Number.isInteger(count) || count < 1) {
+        throw new BrustConfigError(
+          `${file}: workers.count must be a positive integer (got ${JSON.stringify(count)})`,
+          file,
+        )
+      }
+      out.workers = count
+    }
+  }
+
+  if ('cache' in root) {
+    const cache = root.cache
+    if (cache === null || typeof cache !== 'object') {
+      throw new BrustConfigError(`${file}: [cache] must be a table`, file)
+    }
+    const maxEntries = (cache as Record<string, unknown>).max_entries
+    if (maxEntries !== undefined) {
+      if (typeof maxEntries !== 'number' || !Number.isInteger(maxEntries) || maxEntries < 1) {
+        throw new BrustConfigError(
+          `${file}: cache.max_entries must be a positive integer (got ${JSON.stringify(maxEntries)})`,
+          file,
+        )
+      }
+      out.cacheMaxEntries = maxEntries
+    }
+  }
+
+  return out
+}
+
+function extractFromEnv(): Partial<BrustConfig> {
+  const out: Partial<BrustConfig> = {}
+  if (process.env.BRUST_PORT) {
+    const n = parseInt(process.env.BRUST_PORT, 10)
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+      throw new BrustConfigError(
+        `BRUST_PORT must be an integer in 1..65535 (got ${JSON.stringify(process.env.BRUST_PORT)})`,
+        null,
+      )
+    }
+    out.port = n
+  }
+  if (process.env.BRUST_WORKERS) {
+    const n = parseInt(process.env.BRUST_WORKERS, 10)
+    if (!Number.isInteger(n) || n < 1) {
+      throw new BrustConfigError(
+        `BRUST_WORKERS must be a positive integer (got ${JSON.stringify(process.env.BRUST_WORKERS)})`,
+        null,
+      )
+    }
+    out.workers = n
+  }
+  return out
+}

package/runtime/css/build.ts

@@ -0,0 +1,54 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { compile } from '@tailwindcss/node'
+import { Scanner } from '@tailwindcss/oxide'
+
+/** The directory that contains this file — runtime/css/. Two dirname() steps
+ * reach the brust repo root where node_modules/tailwindcss is installed. */
+const BRUST_ROOT = path.resolve(import.meta.dir, '..', '..')
+
+/** Absolute path to tailwindcss/index.css inside brust's own node_modules.
+ * Used by the customCssResolver so that `@import "tailwindcss"` always
+ * resolves via brust's bundled copy regardless of where the entry CSS lives. */
+const TAILWINDCSS_INDEX = path.join(BRUST_ROOT, 'node_modules', 'tailwindcss', 'index.css')
+
+export interface BuildCssOptions {
+  /** Absolute path to the entry CSS file (typically <scanRoot>/app.css). */
+  entry: string
+  /** Absolute path to the output directory. Created if missing. */
+  outDir: string
+}
+
+export interface CssBuildResult {
+  outDir: string
+  files: string[]
+}
+
+export async function buildCss(opts: BuildCssOptions): Promise<CssBuildResult> {
+  const sourceCss = await readFile(opts.entry, 'utf-8')
+
+  const compiler = await compile(sourceCss, {
+    // base: the entry CSS's directory so that @source globs resolve
+    // relative to the entry file (e.g. @source "./**/*.tsx" scans
+    // the same folder the CSS lives in).
+    base: path.dirname(opts.entry),
+    onDependency: () => {}, // unused — no watch
+    // Redirect `@import "tailwindcss"` to brust's own bundled copy so
+    // resolution succeeds even when tailwindcss is not installed in the
+    // entry directory (e.g. a tmp dir in tests).
+    customCssResolver: async (id: string) => {
+      if (id === 'tailwindcss') return TAILWINDCSS_INDEX
+      return undefined
+    },
+  })
+
+  const scanner = new Scanner({ sources: compiler.sources })
+  const candidates = scanner.scan()
+
+  const output = compiler.build(candidates)
+
+  await mkdir(opts.outDir, { recursive: true })
+  await writeFile(path.join(opts.outDir, 'app.css'), output, 'utf-8')
+
+  return { outDir: opts.outDir, files: ['app.css'] }
+}