@webjsdev/cli 0.10.10 → 0.10.12

package/resources/agent-docs/typescript.md

@@ -0,0 +1,334 @@
+# TypeScript without a build step + full-stack type safety
+
+Files ending in `.ts` / `.mts` are supported everywhere `.js` / `.mjs`
+are. Same routing conventions, same server-action behaviour. No `tsc`
+run is part of the user-visible workflow, no separate build step:
+
+- **Editor** (VS Code) runs the TypeScript language server continuously. Red-squiggle on wrong types, including non-erasable syntax (see below).
+- **CI** (optional) runs `tsc --noEmit` against `tsconfig.json`. Type-check only. Also catches non-erasable syntax via `erasableSyntaxOnly`.
+- **Dev + prod server** (runtime, both directions): Node 24+'s built-in TypeScript type-stripping handles server-side `.ts` imports automatically (`process.features.typescript === 'strip'`). Browser-bound `.ts` requests go through `module.stripTypeScriptTypes` on the dev server, which performs whitespace replacement: every (line, column) in the source maps to the same position in the stripped output, so no sourcemap needs to be shipped and stack traces are byte-exact. The transform is cached by mtime (~microseconds per cache hit). Implementation backing: Node ships the [`amaro`](https://github.com/nodejs/amaro) package internally, which wraps SWC's WASM TypeScript transform in a position-preserving strip-only mode. If the framework ever needs to run on a non-Node runtime (Bun, Deno) we will install `amaro` directly or an equivalent position-preserving stripper (Sucrase preserves lines but not columns; SWC's strip mode also works).
+
+## TypeScript feature support: erasable only
+
+The framework uses Node 24+'s built-in `module.stripTypeScriptTypes`,
+which only supports **erasable TypeScript**: type annotations,
+`interface`, `type`, `declare`, generics, `import type`, `as` casts,
+and `satisfies`. Non-erasable syntax is rejected.
+
+Use the **erasable equivalents** instead:
+
+```ts
+// Not allowed (rejected at compile + runtime)
+enum Color { Red, Green, Blue }
+class Foo { constructor(public x: number) {} }
+namespace Util { export const helper = ...; }
+import = require('something');
+@legacyDecorator class C {}
+
+// Allowed (canonical erasable forms)
+const Color = { Red: 'Red', Green: 'Green', Blue: 'Blue' } as const;
+type Color = typeof Color[keyof typeof Color];
+
+class Foo {
+  x: number;
+  constructor(x: number) { this.x = x; }
+}
+
+const Util = { helper: ... };
+
+import { thing } from './thing.ts';
+```
+
+Enforce this at edit time by setting `erasableSyntaxOnly: true` in
+`tsconfig.json`. The TypeScript compiler then flags any non-erasable
+syntax as a red squiggle in the editor and `tsc --noEmit` error in CI.
+
+The `erasable-typescript-only` convention check verifies the flag is
+set. Run `webjs check` to confirm.
+
+### Fallback for third-party `.ts` dependencies
+
+If a third-party package ships `.ts` source using non-erasable
+syntax (rare; most npm packages publish compiled `.js`), the dev
+server fails at strip time and returns a 500 naming the file and
+pointing at the `no-non-erasable-typescript` lint rule. webjs is
+buildless end-to-end and has no bundler fallback. Your own code
+never hits this as long as `erasableSyntaxOnly` is set.
+
+If you manually turn `erasableSyntaxOnly` off and write non-erasable
+syntax in your own code, the dev server fails the same way. The
+`erasable-typescript-only` convention check warns when the flag is
+off so you catch the configuration drift before runtime.
+
+## Import convention
+
+Use explicit `.ts` extensions in imports. Node 24+'s built-in
+type-stripping and the dev server's HTTP handler both key on the
+file URL ending in `.ts` / `.mts`. For mixed codebases, `.js` imports
+that point at a `.ts` sibling also resolve in the dev server. Still
+prefer explicit `.ts`.
+
+```ts
+// modules/posts/queries/list-posts.server.ts
+import { prisma } from '../../../lib/prisma.js';         // JS file unchanged
+import { formatPost } from '../utils/slugify.ts';         // TS file
+```
+
+## Minimum viable `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noEmit": true,
+    "checkJs": true,
+    "allowJs": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "erasableSyntaxOnly": true
+  }
+}
+```
+
+The `erasableSyntaxOnly: true` line is the non-negotiable one. It
+aligns the TypeScript compiler's accepted syntax with what Node's
+strip-types accepts, so violations surface as editor diagnostics
+instead of a runtime 500.
+
+## Full-stack type safety
+
+### Server actions: type-safe automatically
+
+Calling a server action from a client component resolves at type-check
+time to the action's real source file. The dev server's runtime stub
+replacement is invisible to the type checker.
+
+```ts
+// modules/posts/actions/create-post.server.ts
+export async function createPost(
+  input: { title: string; body: string },
+): Promise<ActionResult<PostFormatted>> { /* … */ }
+
+// modules/posts/components/new-post.ts
+import { createPost } from '../actions/create-post.server.ts';
+const r = await createPost({ title, body });
+//        ^ Promise<ActionResult<PostFormatted>>
+if (r.success) r.data.title;   // ← PostFormatted.title: string
+```
+
+**Runtime matches types** because the RPC wire uses webjs's built-in
+ESM serializer: `Date` → `Date`, `Map` → `Map`, `BigInt` → `BigInt`.
+Supported: `Date`, `Map`, `Set`, `BigInt`, `Error`, `undefined`,
+`NaN`/`Infinity`/`-0`, `TypedArray`, `ArrayBuffer`, `DataView`, `Blob`,
+`File`, `FormData`, `Symbol.for(...)`, reference cycles. Class
+instances come through as plain objects, with prototypes lost and methods
+gone (matches React Server Actions).
+
+### API routes: opt in via content negotiation
+
+`route.ts` handlers use standard JSON by default so external consumers
+keep working. Opt into rich types for your own UI code:
+
+```ts
+// app/api/posts/route.ts: server
+import { json } from '@webjsdev/server';
+import { listPosts } from '../../../modules/posts/queries/list-posts.server.ts';
+
+export async function GET() {
+  return json(await listPosts());   // content-negotiates automatically
+}
+```
+
+```ts
+// caller: client
+import { richFetch } from '@webjsdev/core';
+const posts = await richFetch<Post[]>('/api/posts');
+// posts[0].createdAt is a Date here.
+```
+
+The `json()` helper reads the in-flight Request via AsyncLocalStorage:
+- `Accept: application/vnd.webjs+json` → encoded with the webjs serializer, served with `Content-Type: application/vnd.webjs+json` and `Vary: Accept`.
+- Otherwise → plain JSON.
+
+Request bodies parse with `readBody(req)` from `@webjsdev/server`.
+
+### Page metadata: the `Metadata` type
+
+A page or layout exports `metadata` (static) or `generateMetadata(ctx)`
+(request-scoped). Annotate the return with the exported `Metadata` type so
+a misspelled field or a wrong-typed value is a compile-time error, the
+same ergonomics as Next.js's `import type { Metadata } from 'next'`.
+
+```ts
+import type { Metadata, MetadataContext } from '@webjsdev/core';
+
+export const metadata: Metadata = {
+  title: 'Blog',
+  description: 'Latest posts',
+  openGraph: { type: 'website', image: '/og.png' },
+  twitter: { card: 'summary_large_image' },
+};
+
+export async function generateMetadata(ctx: MetadataContext): Promise<Metadata> {
+  return { title: `Post: ${ctx.params.slug}`, metadataBase: new URL(ctx.url).origin };
+}
+```
+
+`Metadata` covers every field the SSR pipeline reads (see
+`agent-docs/metadata.md`); each field is optional, and string-or-object
+fields (`title`, `viewport`, `robots`, `appleWebApp`, `icons`) are unions.
+It is a pure type in `packages/core/src/metadata.d.ts`, so it is erased at
+runtime with zero build cost. `MetadataContext` types the
+`generateMetadata` argument (`{ params, searchParams, url, actionData }`,
+where `actionData` is set only on a failed-page-action re-render).
+
+### Typed page / layout / route-handler props (`PageProps`, `LayoutProps`, `RouteHandlerContext`)
+
+A page default-export receives `{ params, searchParams, url, actionData }`; a
+layout receives the same plus `children`; a `route.{js,ts}` handler receives
+`(request, { params })`. Type each with the exported helpers so a typo in a
+param name or a wrong-typed field is a compile-time error.
+
+```ts
+import type { PageProps, LayoutProps, RouteHandlerContext } from '@webjsdev/core';
+
+// A static route: `params` is `Record<string, string>`.
+export default function About({ searchParams }: PageProps) { /* ... */ }
+
+// A dynamic route: pass the route literal to narrow `params`.
+export default function Post({ params }: PageProps<'/blog/[slug]'>) {
+  const slug = params.slug; // typed `string`
+  /* ... */
+}
+
+// A layout adds `children: TemplateResult`.
+export default function RootLayout({ children }: LayoutProps) { /* ... */ }
+
+// A route handler's 2nd arg.
+export async function GET(req: Request, ctx: RouteHandlerContext) {
+  return Response.json({ id: ctx.params.id });
+}
+```
+
+`PageProps<R>` / `LayoutProps<R>` / `RouteHandlerContext<R>` take an optional
+route literal `R`. With no `R` (or in an app that has not generated route
+types), `params` is `Record<string, string>`, the runtime default. With `R`
+set to a generated dynamic route, `params` narrows to its exact shape
+(`{ slug: string }`, `{ rest: string[] }`, `{ slug?: string[] }`). The shapes
+mirror what `packages/server/src/ssr.js` and `packages/server/src/api.js`
+actually pass, NOT Next.js's superset. Pure types in
+`packages/core/src/routes.d.ts`, erased at runtime with zero build cost.
+
+### The generated route union (`webjs types`) types `navigate()` and catches bad hrefs
+
+Run `webjs types` to generate `.webjs/routes.d.ts`, an opt-in overlay that
+augments `@webjsdev/core` with one key per route in `app/`. It narrows two
+things at tsserver time:
+
+- The `Route` href type: `navigate('/blog/anything')` is accepted,
+  `navigate('/nonexistent')` is a type error. (Until you generate the types,
+  `Route` is `string`, so `navigate()` is unconstrained, non-breaking for
+  JSDoc apps and un-generated apps alike.)
+- Per-route `params`: `PageProps<'/blog/[slug]'>['params']` becomes
+  `{ slug: string }`, derived from the generated `RouteParamMap`.
+
+```sh
+webjs types     # writes .webjs/routes.d.ts (count of routes printed)
+```
+
+`webjs dev` also emits it automatically at startup and re-emits after each
+route rebuild, so an editor always has fresh route types. The file is
+gitignored (regenerated per machine, like Next's `.next/types`); the scaffold
+`tsconfig.json` lists `.webjs/routes.d.ts` in `include` so tsserver picks it
+up. To opt in for an existing app, run `webjs types` once and ensure your
+`tsconfig.json` `include` lists `.webjs/routes.d.ts`.
+
+This is webjs's no-build equivalent of Next 15's `typedRoutes`, achieved via
+interface declaration-merging (`declare module '@webjsdev/core'`) rather than a
+bundler. The mechanism is `generateRouteTypes(appDir)` in
+`packages/server/src/route-types.js`, which reuses the one route enumerator
+(`buildRouteTable`). Output is deterministic (sorted keys), so re-running
+yields a byte-identical file.
+
+### The `webjs` package.json config block: `WebjsConfig` + JSON Schema
+
+The `webjs` object in `package.json` (the `elide` / `headers` / `redirects` /
+`trailingSlash` / `csp` knobs plus the ingress body-size and timeout caps) has
+two typed references, so a typo'd key is diagnosed instead of silently dropped:
+
+- **A JSON Schema**, `packages/server/webjs-config.schema.json` (shipped in the
+  `@webjsdev/server` package). The scaffold's `.vscode/settings.json` associates
+  it with the `webjs` property of `package.json`, so VS Code flags an unknown
+  key natively while you edit the JSON. `additionalProperties: false` on the
+  block is what turns a typo into an editor warning.
+- **The `WebjsConfig` type**, exported from `@webjsdev/core`, a typed reference
+  for an agent or human authoring the block (with `WebjsHeaderRule`,
+  `WebjsRedirectRule`, `WebjsCspConfig`, `WebjsTrailingSlash` for the nested
+  shapes).
+
+```ts
+import type { WebjsConfig } from '@webjsdev/core';
+
+const config: WebjsConfig = {
+  trailingSlash: 'never',
+  csp: true,
+  redirects: [{ source: '/old', destination: '/new' }],
+};
+```
+
+The schema and the type mirror what the server readers actually consume
+(`readElideEnabled`, `compileHeaderRules`, `compileRedirectRules` /
+`readTrailingSlashPolicy`, `readCspConfig`, `readBodyLimits` /
+`computeServerTimeouts`). Adding a `webjs.*` key means updating the schema, the
+type, AND the reader in lockstep, the one procedure documented in
+`packages/server/AGENTS.md`. A drift test
+(`packages/server/test/config/webjs-config-schema.test.js`) fails if the schema
+and the reader key set diverge.
+
+### Both runtime packages ship a type overlay
+
+Both `@webjsdev/core` AND `@webjsdev/server` ship a hand-authored `.d.ts`
+overlay plus a `types` export condition, so a `strict` + `nodenext` app
+resolves real types for either import with no TS7016 ("could not find a
+declaration file") error. The server overlay (`packages/server/index.d.ts`,
+with `src/check.d.ts` and `src/testing.d.ts` for the `./check` / `./testing`
+subpaths) types the full public surface (`createRequestHandler`, `startServer`,
+`cors`, `cache`, `createAuth`, `rateLimit`, `sitemap`, `Session`, `json`,
+`readBody`, the `revalidate*` family, the context helpers, the cache stores, the
+auth providers, the test harness, and the convention validator), reusing the
+core prop / metadata types rather than redefining them. The runtime stays plain
+`.js` + JSDoc; the overlay is types-only with zero runtime cost. A drift test
+keeps `index.d.ts` in lockstep with `index.js`'s runtime exports.
+
+### TypeScript is not required
+
+JS + JSDoc gets the same call-site type safety. The TypeScript language
+server reads `@typedef` / `@param` / `@returns` identically to `.ts`
+syntax. Add `"checkJs": true` to enforce types in editor + CI.
+
+## Editor plugin: `@webjsdev/ts-plugin`
+
+**Editor-only. Not required for the framework to run.** The runtime
+has no dependency on it.
+
+A single plugin. As of `@webjsdev/ts-plugin@0.4.0`, `ts-lit-plugin`
+is bundled internally, so list one entry:
+
+```jsonc
+"plugins": [
+  { "name": "@webjsdev/ts-plugin" }
+]
+```
+
+Gives you:
+- Type-check + diagnostics for attribute *values* inside `` html`` `` templates.
+- Go-to-definition from `<my-counter>` to the class registered via `MyCounter.register('my-counter')`.
+- Diagnostic suppression for "Unknown tag" / "Unknown attribute" on tags any webjs class registers.
+- Attribute auto-complete from `static properties = { … }` keys.
+- Attribute-value type-check: `<my-counter count=${expr}>` assignability-checks `typeof expr` against `declare count: T`.
+
+Both behaviours are gated on import-graph reachability: a tag is recognized only if the file registering it is reachable from the file you're editing.

package/templates/.dockerignore

@@ -6,10 +6,12 @@ node_modules
 # `.webjs/` is ignored EXCEPT for `.webjs/vendor/`, which holds the committed
 # importmap manifest (and optionally downloaded bundle bytes) the server needs
 # at boot without reaching api.jspm.io. DO NOT collapse to `**/.webjs`: parent
-# exclusion blocks child negations and the vendor files would never ship.
-.webjs/*
-!.webjs/vendor/
-!.webjs/vendor/**
+# exclusion blocks child negations and the vendor files would never ship. The
+# `**/` prefix matches `.webjs/` at any depth so a nested build context does
+# not ship the per-machine cache, mirroring the `.gitignore` pattern.
+**/.webjs/*
+!**/.webjs/vendor/
+!**/.webjs/vendor/**
 
 dist
 build

package/templates/AGENTS.md

@@ -14,7 +14,19 @@ now (`app/page.ts` printing "Hello from {{APP_NAME}}", the example `User`
 model in `prisma/schema.prisma`, the `theme-toggle` component, the
 example users module in api/saas templates) are **starting-point
 references, not the final product**. Your job is to replace them with
-the app the user actually asked for.
+the app the user actually asked for. That includes adapting
+`app/layout.ts`, not just the page. Set the real brand, replace the
+example `Home` nav, and pick a content-width container that fits. The
+default `<main class="max-w-[760px]">` is a reading column for prose and
+forms, so for a full-bleed app, dashboard, or board, widen the cap or
+remove it (keep the theme tokens). A wide layout left in the 760px
+reading column overflows into a horizontal scrollbar. This is ENFORCED:
+the example `app/page.ts` and `app/layout.ts` carry a
+`webjs-scaffold-placeholder` marker comment, and `webjs check` fails
+while any marker remains, so this freshly scaffolded app fails the check
+until you replace the example content (or deliberately keep it) and
+delete the marker line. The delivered app must contain only what the
+user asked for, never leftover scaffold code.
 
 **Non-negotiables for every webjs app:**
 
@@ -449,15 +461,18 @@ URLs or transitive deps drift. Pin is a deliberate developer action,
 like `npm install` itself.
 
 **Do NOT modify the `.webjs/` lines in `.gitignore` / `.dockerignore`.**
-The scaffolded pattern is three lines (`.webjs/*` + `!.webjs/vendor/`
-+ `!.webjs/vendor/**`) and is structurally load-bearing. Collapsing it
-to a single `.webjs/` excludes the parent directory; once the parent
-is excluded, git cannot re-include `.webjs/vendor/` via a child
-negation (gitignore semantics: parent exclusion blocks child
-negations). The breakage is invisible: `webjs vendor pin` runs, writes
-files, and git silently ignores them. Production then has no
-importmap.json and the server falls back to calling api.jspm.io on
-every cold start. The `gitignore-vendor-not-ignored` lint rule
+The scaffolded `.gitignore` pattern is three lines (`**/.webjs/*` +
+`!**/.webjs/vendor/` + `!**/.webjs/vendor/**`) and is structurally
+load-bearing. Collapsing it to a single `.webjs/` excludes the parent
+directory; once the parent is excluded, git cannot re-include
+`.webjs/vendor/` via a child negation (gitignore semantics: parent
+exclusion blocks child negations). The breakage is invisible: `webjs
+vendor pin` runs, writes files, and git silently ignores them.
+Production then has no importmap.json and the server falls back to
+calling api.jspm.io on every cold start. The `**/` prefix matters too:
+it ignores `.webjs/` at any depth, so an app nested below its repo root
+(a monorepo package) does not leak its generated `.webjs/routes.d.ts`
+into `git status`. The `gitignore-vendor-not-ignored` lint rule
 (`webjs check`) verifies the pattern with `git check-ignore` and will
 fail CI if it regresses.
 

package/templates/CONVENTIONS.md

@@ -308,11 +308,28 @@ When the user asks the agent to build their actual app:
    need a theme picker.
 4. **Delete the example users module** (api/saas templates) if the app
    doesn't use it.
-5. **Keep:** the Prisma setup, the test config, the agent config files
+5. **Adapt `app/layout.ts` to the app, not just the page.** Set the real
+   brand, replace the example `Home` nav with the app's navigation, and
+   pick a content-width container that fits. The default
+   `<main class="max-w-[760px]">` is a reading column for prose, forms,
+   and marketing. Widen it or drop the cap for a full-bleed app,
+   dashboard, or board, or a wide layout overflows into an unnecessary
+   horizontal scrollbar. Keep the design tokens and theme setup, those
+   are infrastructure.
+6. **Keep:** the Prisma setup, the test config, the agent config files
    (`AGENTS.md`, `CONVENTIONS.md`, `CLAUDE.md`, `.cursorrules`, etc.),
    `lib/prisma.server.ts`, the directory conventions, the design tokens in
    `app/layout.ts`. These are the infrastructure, not the example app.
 
+This is enforced, not just advised. The example `app/page.ts` and
+`app/layout.ts` carry a `webjs-scaffold-placeholder` marker comment, and
+the `no-scaffold-placeholder` check fails while any marker remains, so a
+freshly scaffolded app fails `webjs check` until you address each
+placeholder. The marker is acknowledge-and-remove: replace the example
+content, or deliberately keep it, and in either case delete the marker
+line. So the delivered app contains only what the user asked for, never
+leftover scaffold code.
+
 The scaffold exists so the agent doesn't reinvent the directory layout,
 the Prisma wiring, the test runner config, or the convention files. It
 does NOT exist so the agent ships the example homepage.