@webjsdev/cli 0.10.14 → 0.10.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.14",
+  "version": "0.10.16",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/rules/workflow.md

@@ -96,7 +96,7 @@ self-review loop.
 ## Framework rules
 
 - No build step: ES modules served directly.
-- **Erasable TypeScript only.** Node 24+ strips types via
+- **Erasable TypeScript only.** The runtime (Node 24+ or Bun) strips types via
   `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position
   preservation, no sourcemap). The scaffold's `tsconfig.json` sets
   `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace`
@@ -144,14 +144,18 @@ self-review loop.
   `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in
   `firstUpdated`) instead of Lit's `classMap` / `styleMap` / `ref` / `when` /
   `choose` / `guard`.
-- Use Context for cross-component data, Task for async data in components.
+- Use Context for cross-component data. For async data in a component, prefer
+  an `async render()` (`const u = await getUser(this.uid)`, awaited at SSR so
+  the data is in the first paint); keep `Task` for genuinely client-only data.
 - **Progressive enhancement is the default.** Pages AND every web component
   are SSR'd to real HTML. Write components so the first paint is the right
   content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback`
   is never called on the server, so anything there only runs after
   hydration. Initial data for components comes from the page function
-  (server-side fetch plus pass as attribute/property), NOT from `fetch` calls
-  in `connectedCallback`. For write-paths, prefer `<form action=...>` plus
+  (server-side fetch plus pass as attribute/property) OR from an `async
+  render()` in the component itself (preferred over prop-drilling;
+  `renderFallback()` is the optional re-fetch loading state, never first
+  paint), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` plus
   server action over `fetch` plus click handler. The framework upgrades plain
   forms to partial-swap submissions automatically.
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>`

package/templates/.cursorrules

@@ -102,13 +102,13 @@ self-review loop.
 ## Framework rules
 
 - No build step: source files are served as ES modules
-- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
+- **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css`) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag.
 - Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
 - Server-only code (@prisma/client, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.
 - Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
-- **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
+- **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property) OR from an `async render()` in the component itself (`const u = await getUser(this.uid)`, which SSR awaits so the data is in the first paint), NOT from `fetch` calls in `connectedCallback`. Prefer the co-located `async render()` over prop-drilling; `renderFallback()` is the optional re-fetch loading state (never first paint), and a `Task` is for genuinely client-only data. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Because layouts persist across navigation, put shared chrome (sidenav, header) in `layout.ts` and page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.
 - See AGENTS.md for the complete directive decision guide

package/templates/.github/copilot-instructions.md

@@ -98,10 +98,11 @@ each change must include.
 
 - No build step: source files are served as ES modules. Don't introduce
   build tools or bundlers in the critical path.
-- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
+- **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
 - Components: extend WebComponent, declare `static properties` (and `static styles` for shadow-DOM components), call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field.
+- Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
 - Server actions: *.server.ts files with one exported async function each.
 - Server-only code (@prisma/client, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
 - Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions and lifecycle hooks instead.

package/templates/AGENTS.md

@@ -86,7 +86,8 @@ node_modules/@webjsdev/
                     auth, sessions, cache, rate-limit, WebSocket
     src/ssr.js                ← how metadata becomes <head> tags
     src/router.js             ← file convention → route table
-    src/actions.js            ← .server.ts scanner, RPC, expose()
+    src/actions.js            ← .server.ts scanner, RPC stubs, action endpoint
+    src/action-route.js       ← route() adapter (action over REST via route.ts)
     src/auth.js, session.js, cache.js, rate-limit.js, csrf.js
   cli/             webjs CLI (dev / start / build / test / check / create / db)
   intellisense/    tsserver plugin: go-to-definition + diagnostic suppression
@@ -392,6 +393,23 @@ In Docker / Railway, prefer `npm start` (or `node node_modules/.bin/npm
 start`) as the CMD over `node ... webjs.js start ...`. The npm form
 fires `prestart`; the direct binary form skips it.
 
+### Running on Bun instead of Node
+
+webjs runs on **Node 24+ or Bun**. The same `package.json` scripts work on
+either; to run under Bun, force it with `--bun` so the server executes on Bun
+rather than the `webjs` bin's Node shebang:
+
+```sh
+bun install
+bun --bun run dev      # or: bun --bun run start
+```
+
+On Node the `.ts` type-stripping is the built-in `module.stripTypeScriptTypes`;
+on Bun (which has no built-in) it comes from `amaro` automatically, so the same
+source serves identically. SSR action-result seeding (an internal hydration
+optimization) is off on Bun (it needs `module.registerHooks`), which only means
+an async-render component re-fetches once on hydration, no behavior change.
+
 **Containerized deploy ships with the scaffold.** `Dockerfile`,
 `compose.yaml`, and `.dockerignore` are scaffolded at the app root. The
 Dockerfile pins `node:24-alpine` (the same Node major CI uses), installs
@@ -677,7 +695,9 @@ Practical consequences for agents writing webjs code.
 | Lit pattern | What breaks in webjs | Webjs equivalent |
 |---|---|---|
 | Fetch in `connectedCallback` / `firstUpdated` | Empty first paint (neither hook runs in SSR) | Fetch in the page function, pass as props |
-| `Task` for initial-paint data | SSR ships the pending state, flashes to resolved on hydration | Page function fetch, pass as props (`Task` is fine for client-time async) |
+| `Task` for initial-paint data | SSR ships the pending state, flashes to resolved on hydration | Page function fetch, pass as props, OR an `async render()` in the component (`Task` is fine for client-time async) |
+| Expecting a sync `render()` only | webjs allows `async render() { const d = await getData(); ... }`; SSR bakes the data into the first paint | Use it for request-time server data; `renderFallback()` is the re-fetch loading UI (never first paint); error isolation is automatic |
+| Assuming an `async render()` always ships its module | A bare one (no other client signal) is ELIDED, so it costs zero JS and skips the on-hydration re-fetch, first paint unchanged | Rely on it for a fetch-and-display leaf. `static refresh = true` keeps the on-load refresh, `static shadow = true` always ships |
 | `window.X` / `document.X` in constructor or `render()` | SSR crash | Move to `connectedCallback` |
 | Top-level `import` of a browser-only library | SSR crash | Dynamic `import()` inside `connectedCallback` |
 | Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | `declare student: Student` plus constructor default |
@@ -812,6 +832,14 @@ here is for the "submit → server processes → render new page" flow.)
 
 ### 4. `<webjs-frame id="...">` for non-layout swap regions
 
+`<webjs-frame>` is webjs's take on **Turbo Frames** (Hotwire Turbo), so
+`<turbo-frame>` muscle memory transfers directly: a lazy, URL-addressable
+region that swaps on its own, driven by a link/form targeting its id. Use it
+for a region that loads or refreshes INDEPENDENTLY of a full navigation
+(a self-refreshing widget, a `loading="lazy"` below-the-fold region, a
+URL-addressable panel); it ships zero component JS. Its route can itself use
+`<webjs-suspense>` so a lazy frame's slow data streams in behind a fallback.
+
 For a widget that should swap on click but isn't a route boundary
 (e.g. a tab strip inside a page), wrap it:
 
@@ -880,6 +908,14 @@ over the outcome (e.g. `location.assign(e.detail.url)`).
 
 ### 5. Stream actions for surgical element-level updates
 
+`<webjs-stream>` is webjs's take on **Turbo Streams** (Hotwire Turbo); the
+action set (`append` / `prepend` / `before` / `after` / `replace` / `update` /
+`remove`) mirrors `<turbo-stream>`, so that muscle memory transfers directly.
+It is the ONLY surgical single-element update primitive AND the live-channel
+applier (`connectWS` / `broadcast` -> `renderStream`); a region swap or a
+`<webjs-frame>` reload redraws a whole region, so reach for `<webjs-stream>`
+when only one element changes.
+
 When a region swap is too coarse (append ONE comment, remove ONE row, bump a
 count, insert a toast), a server response can declare per-element actions as
 plain HTML, a `<webjs-stream action target>` wrapping one `<template>`:
@@ -1107,10 +1143,11 @@ composition, so a nested shell ends up dropped by the HTML parser.
    browser-only). Never fetch initial data in `connectedCallback` /
    `firstUpdated`. Fetch in the page function (server) and pass it as
    a prop. See *Component pattern* above.
-8. **Erasable TypeScript only.** Node 24+ strips types via
-   `module.stripTypeScriptTypes` (whitespace replacement, byte-exact
-   line and column position preservation, no sourcemap shipped to the
-   browser). Your `tsconfig.json` sets `erasableSyntaxOnly: true`, so
+8. **Erasable TypeScript only.** The runtime strips types at the runtime
+   layer (Node 24+'s built-in `module.stripTypeScriptTypes`, or `amaro`
+   on Bun, which is byte-identical), with whitespace replacement so
+   line and column positions are byte-exact and no sourcemap ships to
+   the browser. Your `tsconfig.json` sets `erasableSyntaxOnly: true`, so
    the TS compiler rejects: `enum`, `namespace` with values,
    constructor parameter properties, legacy decorators with
    `emitDecoratorMetadata`, and `import = require`. Use the erasable

package/templates/CONVENTIONS.md

@@ -387,6 +387,7 @@ modules/
 - Components must call `Class.register('tag')`
 - **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of `@prisma/client` or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. `lib/` holds both server-only infra (`lib/prisma.server.ts`) and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files."
 - Routes (`app/**/page.ts`, `app/**/route.ts`) must be thin: import logic from modules
+- **Fetch server data in the component that needs it, with an `async render()`, not by prop-drilling.** A leaf component can write `const u = await getUser(this.uid)` directly in `render()`; SSR awaits it so the data is in the first paint, and the client uses stale-while-revalidate on a re-fetch. Reach for `renderFallback()` only to show a re-fetch loading state, and `Task` / signals only for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). Do not put `await getData()` in a page / layout when a leaf component can own it (page fetches run sequentially, a route-level waterfall).
 
 ---
 
@@ -907,27 +908,37 @@ SSR content is visible immediately. Only the JS download is deferred.
 
 ---
 
-## expose(): REST endpoints from server actions
+## REST endpoints from server actions (route.ts)
 
 <!-- OVERRIDE -->
-Tag a server action to also be reachable over HTTP. The file MUST be a `.server.{js,ts}` file: `expose()` is server-only and the bare `@webjsdev/core` specifier resolves to the browser entry which excludes it, so importing from a client-bound file silently reads `undefined`.
+A server action is RPC-callable from components. To ALSO reach the same
+function over plain HTTP (mobile apps, webhooks, third parties), put it behind
+a `route.ts` handler. The action stays a normal `'use server'` function; the
+route imports and calls it.
 
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
-import { expose } from '@webjsdev/core';
-export const createPost = expose('POST /api/posts', async ({ title, body }) => {
+export async function createPost({ title, body }) {
   return prisma.post.create({ data: { title, body } });
-});
+}
+```
+
+```ts
+// app/api/posts/route.ts
+import { route } from '@webjsdev/server';
+import { createPost } from '../../../modules/posts/actions/create-post.server.ts';
+// The route() adapter merges query + route params + JSON body into one input
+// object and JSON-responds the result. Pass { validate } to guard the input.
+export const POST = route(createPost);
 ```
 
-The same function works via RPC (from components) and HTTP (for external
-callers). Use `expose()` when mobile apps, webhooks, or third parties need
-to call your action. For internal-only actions, plain server actions are
-simpler and CSRF-protected.
+A hand-written `route.ts` (a `POST(req)` that reads the body and calls the
+action) is always available for full control (custom headers, streaming).
 
-**Security:** `expose()`d endpoints are NOT CSRF-protected. Authenticate
-via bearer tokens, API keys, or auth middleware.
+**Security:** a `route.ts` REST endpoint is NOT CSRF-protected (only the RPC
+path is). Authenticate every mutating endpoint via bearer tokens, API keys, or
+auth middleware.
 
 ---
 
@@ -1043,7 +1054,7 @@ export async function createPost(input: {
 
 <!-- OVERRIDE -->
 - TypeScript with explicit `.ts` extensions in imports
-- **Erasable TypeScript only.** The framework strips types via Node 24+'s built-in `module.stripTypeScriptTypes` (whitespace replacement, byte-exact line + column preservation, no sourcemap shipped). Your `tsconfig.json` sets `erasableSyntaxOnly: true`, so the compiler rejects: `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Write the erasable equivalents:
+- **Erasable TypeScript only.** The runtime strips types at the runtime layer (Node 24+'s built-in `module.stripTypeScriptTypes`, or `amaro` on Bun, byte-identical) with whitespace replacement, so line + column positions are byte-exact and no sourcemap ships. Your `tsconfig.json` sets `erasableSyntaxOnly: true`, so the compiler rejects: `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Write the erasable equivalents:
   ```ts
   // Not allowed
   enum Color { Red, Green, Blue }

package/templates/Dockerfile

@@ -3,11 +3,14 @@
 # Works with a plain `docker build` / `docker compose up`, and is the same
 # artifact the webdeploy hosting tool (ubicloud + uncloud) builds and ships.
 #
-# webjs serves .ts directly via Node's built-in type-stripping, so there is
-# NO JavaScript build step. **Node 24+ is REQUIRED**: on older Node the runtime
-# falls back to esbuild, whose class-declaration transform breaks webjs's SSR
-# walker for multi-class component files. Do not lower this base image
-# below 24 (the same version the CI workflow and the framework pin).
+# webjs serves .ts directly by stripping types at the runtime layer, so there is
+# NO JavaScript build step (webjs is buildless end to end; there is no bundler or
+# esbuild fallback). This image runs the app on **Node 24+**, where the strip is
+# the built-in `module.stripTypeScriptTypes`. webjs ALSO runs on **Bun** (where
+# the strip comes from `amaro` automatically), so you can swap this base for an
+# `oven/bun` image and start the app with `bun --bun run start`. Do not lower the
+# Node base below 24 (the floor the CI workflow and the framework pin enforce),
+# since the built-in stripper and recursive fs.watch need it.
 #
 # Security headers are set by the framework, not the proxy. webjs emits
 # X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and