@webjsdev/cli 0.10.29 → 0.10.30

package/lib/create.js

@@ -667,6 +667,7 @@ function tune<T extends { exec(sql: string): unknown }>(client: T): T {
 
 async function open() {
   if ((globalThis as { Bun?: unknown }).Bun) {
+    // @ts-expect-error bun:sqlite is a Bun builtin with no Node typings
     const { Database } = await import('bun:sqlite');
     const { drizzle } = await import('drizzle-orm/bun-sqlite');
     return drizzle({ client: tune(new Database(url)), relations: schema.relations });

package/package.json

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

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

@@ -145,7 +145,9 @@ self-review loop.
   a `.server.{js,ts}` file; the framework rewrites that import into an RPC
   stub for the browser. `lib/` holds both server-only infra
   (the DB in `db/*.server.ts`) and browser-safe utilities (`lib/utils/cn.ts` with
-  `cn`); follow the same rule per file.
+  `cn`); follow the same rule per file. A TYPE-ONLY `import type { Todo } from
+  '#db/schema.server.ts'` is the exception, fine in a page or component because
+  the stripper erases it before it reaches the browser.
 - Keep pages and layouts as pure carriers so their modules stay out of the
   network tab. A page/layout never hydrates; the framework drops its module
   from the browser as long as its only browser job is registering the

package/templates/.cursorrules

@@ -114,7 +114,7 @@ self-review loop.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
 - **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
-- Server-only code (the DB driver `pg`, 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. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra 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.
+- Server-only code (the DB driver `pg`, 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. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra 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. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported. For those, 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) 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.

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

@@ -110,7 +110,7 @@ each change must include.
 - Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `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. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults in the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - 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 (a DB driver like pg, 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. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
+- Server-only code (a DB driver like pg, 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. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported; use plain template-literal expressions instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
 - Task: import { Task, TaskStatus } from '@webjsdev/core/task'

package/templates/AGENTS.md

@@ -1166,7 +1166,11 @@ composition, so a nested shell ends up dropped by the HTML parser.
    `lib/utils/cn.ts` with `cn`, design-
    system helpers). Server-only `lib/*` files must only be imported
    from `.server.ts`/`route.ts`/`middleware.ts`; browser-safe `lib/*`
-   files (like `lib/utils/cn.ts`) can be imported anywhere.
+   files (like `lib/utils/cn.ts`) can be imported anywhere. A TYPE-ONLY
+   import is the exception: `import type { Todo } from
+   '#db/schema.server.ts'` is fine in a page or component, because the
+   TypeScript stripper erases it before it reaches the browser, so
+   sharing a derived row type is safe and is not flagged.
 3. Event / property / boolean holes in `` html`` `` are unquoted:
    `@click=${fn}`, not `@click="${fn}"`.
 4. Component state lives in signals. Import `signal` from

package/templates/CONVENTIONS.md

@@ -401,7 +401,7 @@ modules/
 - One exported function per server action/query file
 - Server actions need BOTH the `.server.{js,ts}` extension AND a `'use server'` directive at the top. Extension alone marks a server-only utility (source-protected, not RPC-callable). Directive alone is a lint violation (`use-server-needs-extension`).
 - 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 a DB driver (`pg`) 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. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra 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."
+- **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of a DB driver (`pg`) 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. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra 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." A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - 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).
 - **Keep pages and layouts as pure carriers, so their modules stay out of the network tab.** A page/layout never hydrates; the framework drops its module from the browser as long as its only browser-relevant job is registering the components it imports. It starts shipping its own module (invisible in tests) the moment its closure does any OTHER client work. So do not give a page/layout module-scope client work (a top-level call, a `window` / `document` / `customElements` access, a bare side-effect import, or a `@webjsdev/core/client-router` import: routing is automatic), and do not import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in `.server.{js,ts}`. Self-check: `page.ts` / `layout.ts` should not appear in the browser's network tab.

package/templates/test/hello/browser/hello.test.js

@@ -51,11 +51,17 @@ suite('Example browser tests', () => {
     await assertNoA11yViolations(el);
   });
 
-  // Replace with your component tests:
-  // test('my-widget renders correctly', async () => {
-  //   await import('../../components/my-widget.ts');
-  //   const el = await ssrFixture(html`<my-widget></my-widget>`);
-  //   assert.ok(el.shadowRoot ?? el.firstElementChild);
-  //   await assertNoA11yViolations(el);   // opt-in a11y check
+  // Your REAL `.ts` app components load here. `webjs test --browser` serves
+  // them through the webjs dev pipeline (TypeScript stripped, any `.server.ts`
+  // action import rewritten to an RPC stub, `#` aliases resolved), so a
+  // component that talks to the server works in a real browser, not just a
+  // node test. Point the import at a component your app actually has:
+  //
+  // test('todo-list adds a row optimistically', async () => {
+  //   await import('../../../components/todo-list.ts');  // imports create-todo.server.ts
+  //   const el = await ssrFixture(html`<todo-list></todo-list>`);
+  //   el.querySelector('button')?.click();               // fires the action RPC
+  //   // assert on the DOM, then optionally:
+  //   await assertNoA11yViolations(el);
   // });
 });

package/templates/test/hello/e2e/hello.test.ts

@@ -1,12 +1,14 @@
-/**
- * Example E2E test: replace with tests for your user flows.
- *
- * Run:  WEBJS_E2E=1 webjs test
- * Or:   WEBJS_E2E=1 node --test test/**/e2e/**/*.test.ts
- *
- * Requires: puppeteer-core + chromium installed.
- *   npm i -D puppeteer-core
- */
+// Example E2E test: replace with tests for your user flows.
+//
+// Run:  WEBJS_E2E=1 webjs test
+//       (or point node --test at your e2e test files directly)
+//
+// Requires: puppeteer-core + chromium installed.
+//   npm i -D puppeteer-core
+//
+// Note: this header uses line comments on purpose. A JSDoc block comment
+// here cannot contain a glob like test/**/e2e/ because the ** followed by /
+// closes the block comment early and breaks TypeScript stripping.
 import { test, describe, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';

package/templates/test/hello/hello.test.ts

@@ -1,9 +1,7 @@
-/**
- * Example unit test: replace with tests for your modules.
- *
- * Run:  webjs test
- * Or:   node --test test/**/*.test.ts
- */
+// Example unit test: replace with tests for your modules.
+//
+// Run:  webjs test
+// Or:   node --test 'test/**/*.test.ts'
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { html } from '@webjsdev/core';

package/templates/web-test-runner.config.js

@@ -1,12 +1,8 @@
 /**
  * Web Test Runner configuration.
  *
- * Runs browser tests (components, directives, interactions) in real
- * Chromium via Playwright. Server tests (actions, queries) use node:test.
- *
- * Tests are organised by feature. Each feature folder may have a
- * `browser/` subfolder containing real-browser tests; the glob below
- * picks them up wherever they live.
+ * Runs browser tests (components, directives, interactions) in real Chromium
+ * via Playwright. Server tests (actions, queries) use node:test.
  *
  *   test/<feature>/<file>.test.ts             ← node tests
  *   test/<feature>/browser/<file>.test.js     ← this runner
@@ -15,15 +11,94 @@
  *   webjs test              # runs both server + browser tests
  *   webjs test --browser    # browser tests only
  *   webjs test --server     # server tests only
+ *
+ * A webjs browser test imports the REAL app: a `.ts` component that imports a
+ * `'use server'` action. Plain web-test-runner serves raw TypeScript with no
+ * transform, so that never loads. This config proxies every module request to
+ * the webjs dev pipeline via `createBrowserTestHandler`, so the browser gets
+ * the SAME output as `webjs dev`: TypeScript stripped, a `.server.ts` import
+ * rewritten to a typed RPC stub, `#`-alias imports resolved, `@webjsdev/core`
+ * served, and the importmap injected. (#806)
  */
 import { playwrightLauncher } from '@web/test-runner-playwright';
+import { createBrowserTestHandler } from '@webjsdev/server/testing';
+import { resolve } from 'node:path';
+import { Readable } from 'node:stream';
+
+// One webjs handler for the app, warmed once and shared. Top-level await so the
+// importmap is ready before `testRunnerHtml` is called for the first test file.
+const webjs = await createBrowserTestHandler(resolve('.'));
 
 export default {
+  // Browser tests are `.js` (web-test-runner serves them through its own test
+  // framework); the components + modules they import are `.ts`, served
+  // transformed by the webjs middleware below.
   files: ['test/**/browser/**/*.test.js'],
-  nodeResolve: true,
-  browsers: [
-    playwrightLauncher({ product: 'chromium' }),
+  // webjs's importmap resolves `@webjsdev/core`, the `#` app aliases, and
+  // vendors, so web-test-runner must NOT rewrite bare specifiers to
+  // node_modules paths.
+  nodeResolve: false,
+  // Inject the webjs importmap so a bare / `#`-aliased import in a served module
+  // resolves in the browser exactly as it does under `webjs dev`.
+  testRunnerHtml: (testFrameworkImport) =>
+    `<!DOCTYPE html>
+<html>
+  <head>${webjs.importmapHtml()}</head>
+  <body>
+    <script type="module" src="${testFrameworkImport}"></script>
+  </body>
+</html>`,
+  middleware: [
+    async (ctx, next) => {
+      // web-test-runner owns: its own internals (/__web-test-runner,
+      // /__web-dev-server, /__wds), the TEST FILES themselves (it wraps each
+      // for the test framework), and the DOCUMENT navigation (the test-runner
+      // HTML page, `Sec-Fetch-Dest: document`). If webjs served the page, WTR's
+      // test bootstrap would never load and the session would time out. NOTE:
+      // match the WTR/WDS prefixes specifically, NOT a broad `/__web`, because
+      // webjs's own paths are `/__webjs/...` and MUST be proxied below.
+      if (
+        ctx.path.startsWith('/__web-test-runner') ||
+        ctx.path.startsWith('/__web-dev-server') ||
+        ctx.path.startsWith('/__wds') ||
+        /\.test\.(js|mjs)$/.test(ctx.path) ||
+        (ctx.get('sec-fetch-dest') || '') === 'document'
+      ) {
+        return next();
+      }
+      // The dev live-reload SSE has no meaning in a test run; short-circuit it
+      // so it neither hangs nor logs a 404.
+      if (ctx.path === '/__webjs/events') {
+        ctx.status = 204;
+        return;
+      }
+      // Everything else (a `.ts` component, a `.server.ts` action, the `#`
+      // alias, `/__webjs/core/*`, vendors) goes through the webjs dev pipeline.
+      // A GET/HEAD has no body; a POST (a browser test firing an action RPC)
+      // carries one. `ctx.req` is a Node IncomingMessage, so wrap it in a web
+      // ReadableStream (the same `Readable.toWeb` the server's own request
+      // bridge uses), NOT pass the raw Node stream.
+      const hasBody = ctx.method !== 'GET' && ctx.method !== 'HEAD';
+      const req = new Request(`http://localhost${ctx.originalUrl || ctx.url}`, {
+        method: ctx.method,
+        headers: ctx.headers,
+        body: hasBody ? Readable.toWeb(ctx.req) : undefined,
+        duplex: 'half',
+      });
+      const res = await webjs.handle(req);
+      // A 404 means webjs does not own this path; let web-test-runner try.
+      if (res.status === 404) return next();
+      ctx.status = res.status;
+      // Copy headers, but handle Set-Cookie separately: `Headers.forEach`
+      // comma-joins multiple Set-Cookie into one malformed value, so use
+      // `getSetCookie()` and append each (an action driving a multi-cookie auth
+      // flow would otherwise lose a cookie in the browser).
+      res.headers.forEach((value, key) => { if (key.toLowerCase() !== 'set-cookie') ctx.set(key, value); });
+      for (const cookie of res.headers.getSetCookie?.() ?? []) ctx.append('set-cookie', cookie);
+      ctx.body = Buffer.from(await res.arrayBuffer());
+    },
   ],
+  browsers: [playwrightLauncher({ product: 'chromium' })],
   testFramework: {
     config: {
       ui: 'tdd',