@webjsdev/cli 0.10.67 → 0.10.69

package/templates/AGENTS.md

@@ -1,82 +1,52 @@
 # AGENTS.md for {{APP_NAME}}
 
-This is a WebJs app: AI-first, web-components-first, buildless, and
-progressively enhanced. Read this whole file before you edit anything, then
-follow it. The steps here are required, not optional.
-
-## Gather context BEFORE you build (required)
-
-WebJs is its own framework. It is not React, Next, or Lit, so writing code from
-that muscle memory produces broken WebJs code. Before you write or change
-anything, gather context from these sources. Do not skip a step to save time.
-This is what separates a working app from a broken one.
-
-1. **Read the skill.** Start with `.agents/skills/webjs/SKILL.md`, then load the
-   `references/*.md` files it routes to for the surface you are touching. The
-   skill is the guide to building a WebJs app: it helps you choose the right
-   layer, reach for the right export, and avoid the mistakes Next.js or Lit
-   habits cause. Reading it is never wasted work: it survives the
-   gallery-clearing step in the playbook below.
-2. **Study the shipped examples, then build on a clean slate.** The template
-   playbook below says what ships and the exact order to follow. The workflow
-   rules (git, tests, review) are in `.agents/rules/workflow.md`; follow them
-   too.
-3. **Read the framework source for exact contracts.** WebJs is 100% buildless
-   native ES modules, so the source you run IS the source you read. When you
-   need a precise API signature or behavior, open the package source under
-   `node_modules/@webjsdev/*` directly (each package ships its own `AGENTS.md`).
-   The full hosted docs are at https://webjs.dev/docs.
+This is a WebJs app: server-rendered pages, web components for interactivity,
+server actions, Drizzle, and no build step. WebJs is its own framework, not
+React, Next.js or Lit, so write it from the patterns in this file rather than
+from that memory. Read this whole file before you edit anything.
 
 {{PLAYBOOK}}
 
-## Type everything (all templates)
-
-Full-stack type safety is what the `.server.ts` boundary buys you: a client
-component importing a server action resolves to that action's real signature at
-type-check time, with no build step and no code generation in between. So
-DERIVE the type at every boundary instead of widening it:
-
-- A database row: `export type Todo = typeof todos.$inferSelect` in
-  `db/schema.server.ts` (`$inferInsert` for a write), carried into a
-  browser-shipped component with `import type` (erased before it reaches the
-  browser, so it does not trip the server-import boundary).
-- An action's input: a named `interface`. Its result: `ActionResult<T>`.
-  Narrow with `if (result.success && result.data)`.
-- Routing files: `PageProps<'/blog/[slug]'>`, `LayoutProps`,
-  `RouteHandlerContext`, all from `@webjsdev/core`. Run `npx webjsdev types`
-  for the typed `Route` union and per-route `params`.
-- A reactive property: `prop<Student>(Object)`, `prop<Tag[]>(Array)`.
-
-Never reach for `any` or a loose `as any` cast, and do not reach for `unknown`
-either just because it looks safer. `unknown` is right for a payload nothing
-has vouched for yet, narrowed on the very next line (a `route.ts` `await
-req.json()`, an action's `export const validate` or a validator it delegates
-to, a `catch` binding), and for a parameter of YOUR OWN helper that forwards
-into an `html` template hole (a hole renders a string, a number, a
-`TemplateResult`, or an array of those, so `TemplateResult` alone is too
-narrow). That second case is about a value you accept, never one the framework
-already types. Everywhere else it is a missing type, not a safe one: `unknown`
-that survives into a return type, a component prop, a layout's `children`, or
-an action signature is the shape to fix.
-Nothing enforces this (both are valid TypeScript, so `webjs check` and `tsc`
-pass either way), which is exactly why it is written down. The full ladder,
-with an end-to-end example, is in
-`.agents/skills/webjs/references/typescript.md`.
-
-Keep server-only code (database drivers, secrets, `node:*` builtins) in
-`.server.ts` modules. There are exactly two kinds:
-
-- A `.server.ts` file WITH `'use server';` as its first line is a server
-  action: WebJs exposes its exported async functions to browser code as RPC
-  calls, so browser modules may import it directly.
-- A `.server.ts` file WITHOUT `'use server'` is a server-only utility:
-  importing it from a page, layout, or component CRASHES in the browser at
-  module load. Reach it only from `'use server'` actions, `route.ts` handlers,
-  or middleware. Never add `'use server'` to a file only other server code
-  imports (the DB connection, the schema).
-
-## Data (all templates)
-
-Use the wired-up database (Drizzle) for every piece of data the app stores;
-the playbook above has the modeling step. Never store app data in a JSON file,
-an in-memory array, or localStorage.
+## Rules that hold everywhere
+
+- **Type every boundary from its source.** A row is
+  `typeof posts.$inferSelect` (exported from `db/schema.server.ts`, carried
+  into browser code with `import type`), an action's input is a named
+  `interface`, a routing file uses `PageProps<'/posts/[id]'>` / `LayoutProps` /
+  `RouteHandlerContext` from `@webjsdev/core`, and a component prop that holds
+  an object is `prop<Post>(Object)`. Never reach for `any` or `as any`, and
+  keep `unknown` for an untrusted payload you narrow on the next line.
+- **Server-only code stays behind `.server.ts`.** A file WITH `'use server'`
+  exposes its exported async functions as actions; a file WITHOUT it is a
+  server-only utility that only other server code may import. Never add
+  `'use server'` to a file only server code imports (the DB connection, the
+  schema).
+- **Store data with Drizzle** in the wired-up database (`db/`), never in a
+  JSON file, an in-memory array or Map, or localStorage. Every schema change is
+  `npm run db:generate` then `npm run db:migrate`, and the generated
+  migrations are committed.
+- **TypeScript is erasable:** no `enum`, no `namespace`, no constructor
+  parameter properties, no decorators. Never put a backtick inside an
+  `html` template body, even in a comment.
+- **Errors tell you the fix.** `npm run check` and `npm run typecheck` name
+  the file, the rule and the fix; do what they say rather than searching.
+
+## Git
+
+Commit per logical unit (CLAUDE.md has the rule). When you build a whole app
+from a spec in one session, the build is one unit: work on a feature branch
+(commits to `main` are refused), and commit once at the end after the checks
+pass (`git add -A && git commit -m "<imperative subject>"`). Team workflow
+(pull requests, CI, worktrees) is in `.agents/rules/workflow.md`.
+
+## When you need more
+
+The reference set is `.agents/skills/webjs/` (`SKILL.md` routes to
+`references/*.md`). Open one only for a surface this file does not show:
+streaming and Suspense (`client-router-and-streaming.md`), optimistic UI
+(`optimistic-ui.md`), caching, rate limits, file uploads, env vars
+(`built-ins.md`), OAuth providers and sessions (`auth-and-sessions.md`),
+browser and e2e tests (`testing.md`), deeper component topics such as slots,
+shadow DOM, context and directives (`components.md`). The exact framework
+source is under `node_modules/@webjsdev/*`, and the hosted docs are at
+https://webjs.dev/docs.

package/templates/CLAUDE.md

@@ -3,21 +3,19 @@
 # Committing per logical unit (this OVERRIDES Claude Code's default)
 
 Claude Code's built-in default is to NEVER commit unless the user explicitly
-asks. **For this project that default does NOT apply.** Commit and push per
-logical unit (one feature, one fix, one rename, one doc rewrite) as soon as it
-is complete, WITHOUT being asked. Do not save all the work for one commit at the
-end. A finished implementation with zero commits is a mistake here, because git
-history is the user's revert and cherry-pick safety net.
+asks. **For this project that default does NOT apply.** Commit per logical
+unit (one feature, one fix, one rename, one doc rewrite) as soon as it is
+complete and its checks pass, WITHOUT being asked, then push when there is a
+remote. Git history is the user's revert and cherry-pick safety net.
 
-- After each completed unit whose tests pass, `git add` the related files and
-  `git commit` with an imperative subject under 72 chars, then push. If 5+ files
-  span more than one concern, you already waited too long.
-- Never commit to `main`. Work on a feature branch (the
-  `.claude/hooks/guard-branch-context.sh` hook enforces this).
-- No AI-attribution trailers (`Co-Authored-By`, `Generated by`).
+- Building a whole app from a spec in one session is ONE unit: build it,
+  verify it, then commit once. Later changes are one commit each.
+- Never commit to `main`. Work on a feature branch (the pre-commit hook
+  refuses `main`).
+- Imperative subject under 72 characters. No AI-attribution trailers
+  (`Co-Authored-By`, `Generated by`).
 
-See AGENTS.md "Git workflow" for the full contract. Two hooks back this up: the
-`.claude/hooks/nudge-uncommitted.sh` PostToolUse hook reminds you while
-uncommitted changes pile up during work, and the
-`.claude/hooks/commit-before-stop.sh` Stop hook stops you from ending a turn
-with a pile of uncommitted work still on a feature branch.
+Two hooks back this up: `.claude/hooks/nudge-uncommitted.sh` reminds you while
+uncommitted changes pile up on a branch that already has commits, and
+`.claude/hooks/commit-before-stop.sh` stops you from ending a turn with
+uncommitted work on a feature branch.

package/templates/CONVENTIONS.md

@@ -1,9 +1,9 @@
 # Conventions for {{APP_NAME}}
 
-The conventions for building a WebJs app live in the agent skill. **Read
-`AGENTS.md` first, then `.agents/skills/webjs/SKILL.md`** (it routes to focused
-references under `.agents/skills/webjs/references/`, loaded on demand). This file
-is the short version.
+The conventions for building a WebJs app live in **`AGENTS.md`**, which shows
+every common pattern as a worked example. The deeper reference set is
+`.agents/skills/webjs/` (`SKILL.md` routes to `references/*.md`), for the rarer
+surfaces. This file is the short version.
 
 ## The essentials
 
@@ -17,13 +17,12 @@ is the short version.
 - **Use the wired-up database (Drizzle).** Define real models in
   `db/schema.server.ts`, then `npm run db:generate` and `npm run db:migrate`.
   Never persist to a JSON file, an in-memory array or Map, or localStorage.
-- **The scaffold ships a showcase to learn from.** A full-stack app ships a UI
-  feature gallery (`app/features/`, `app/examples/todo`); the api template ships
-  a backend-features showcase (`app/api/features/`), with logic in `modules/`.
-  When you build a real app, study the parts that match your task (the skill
-  teaches the same and survives the clear), run `npm run gallery:clear` to shed
-  the showcase, then grow the app in place. `AGENTS.md` has the full
-  template-specific playbook.
+- **The scaffold ships a demo showcase.** A full-stack app ships a UI feature
+  gallery (`app/features/`, `app/examples/todo`); the api template ships a
+  backend-features showcase (`app/api/features/`), with logic in `modules/`.
+  When you build a real app, run `npm run gallery:clear` first to shed the
+  showcase, then grow the app in place. `AGENTS.md` has the template-specific
+  build steps.
 - **Derive types at every boundary.** Rows from `$inferSelect`, action inputs
   from an `interface`, routing files from `PageProps` / `LayoutProps`. Never
   `any`, and never `unknown` where a real type exists.

package/templates/gallery/app/icon.ts

@@ -3,12 +3,14 @@
 // content type, so an inline SVG needs no asset file. Generate it dynamically
 // (per-theme, per-tenant) when the mark must be computed at request time.
 //
-// This is the DEMO of that surface, not the gallery's own favicon. A metadata
-// route is not auto-linked: the framework emits `<link rel="icon">` only from
-// metadata.icons, so the gallery declares the static WebJs brand mark from
-// public/ there (see app/layout.ts) and this route stays browsable at /icon.
-// For a favicon that never changes, that static path is the one to copy; drop
-// this route when your app has no request-time mark to compute.
+// This is the DEMO of that surface, not the gallery's own favicon. With no
+// metadata.icons declared, the framework auto-links an app-root icon: a STATIC
+// file (app/icon.svg, app/icon.png) wins that link over this route, and a
+// declared metadata.icons wins over both. The gallery declares its WebJs brand
+// mark in app/layout.ts, so this route stays browsable at /icon without being
+// the tab icon. For an icon that never changes, write app/icon.svg instead
+// (what `webjs create` ships); keep a route like this only when the mark must
+// be computed at request time (per theme, per tenant).
 export default function Icon() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
     <rect width="32" height="32" rx="7" fill="#1e2226"/>

package/templates/gallery/app/manifest.ts

@@ -3,6 +3,9 @@
 // icons to your app; pair it with the opt-in service worker for an installable
 // PWA. See agent-docs/service-worker.md. (Gallery files are copied verbatim, so
 // set the real app name here by hand rather than expecting substitution.)
+// The framework links an app-root manifest into <head> by itself. A static
+// app/manifest.webmanifest (what `webjs create` ships) wins that link over this
+// route; write a route like this only when a value must be computed.
 export default function Manifest() {
   return {
     name: 'webjs app',
@@ -12,7 +15,7 @@ export default function Manifest() {
     background_color: '#ffffff',
     theme_color: '#1e2226',
     icons: [
-      { src: '/favicon.svg', sizes: 'any', type: 'image/svg+xml' },
+      { src: '/icon', sizes: 'any', type: 'image/svg+xml' },
     ],
   };
 }