@webjsdev/cli 0.10.69 → 0.10.71

package/templates/AGENTS.md

@@ -1,52 +1,50 @@
 # AGENTS.md for {{APP_NAME}}
 
-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.
+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. For one
+   export's signature and doc comment run `npx webjs source <Export>` (for
+   example `npx webjs source createAuth`); it reads the installed package and
+   prints the declaration, not the file. When you need the behaviour behind a
+   signature, 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.
 
 {{PLAYBOOK}}
 
-## 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.
+## Type everything (all templates)
+
+Derive the type at every boundary from its source. Never reach for `any`, and
+never `unknown` where a real type exists. The rule is step 8 of the skill's "Default
+Workflow"; the full ladder, with an end-to-end example, is
+`.agents/skills/webjs/references/typescript.md`.
+
+Keep server-only code (database drivers, secrets, `node:*` builtins) in
+`.server.ts` modules. The two kinds (with and without `'use server'`) are the
+skill's "Core WebJs Rules" 1 and 2.
+
+## 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.

package/templates/CLAUDE.md

@@ -3,19 +3,16 @@
 # 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 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.
+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.
 
-- 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`).
-
-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.
+The full git contract (branches, commit messages, attribution) is
+`.agents/rules/workflow.md` "Git rules"; the
+`.claude/hooks/guard-branch-context.sh` hook refuses a commit on `main`. 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.

package/templates/CONVENTIONS.md

@@ -1,35 +1,18 @@
 # Conventions for {{APP_NAME}}
 
-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 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
+only says where each rule lives, so no rule is stated twice.
 
-## The essentials
-
-- **`app/` is routing only.** Only routing files live there (page, layout, route,
-  middleware, metadata routes). Feature logic goes in `modules/<feature>/`
-  (`actions/`, `queries/`, `components/`, `utils/`); shared UI primitives go in
-  top-level `components/`; browser-safe helpers in `lib/utils/`.
-- **Server-only code goes behind `.server.ts`.** Reach it from a page or component
-  through a `'use server'` action, never by importing a server-only utility
-  directly into browser-bound code.
-- **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 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.
-- **Progressive enhancement is the default.** Pages render as HTML, `<a>`
-  navigates, a `<form action=${importedAction}>` submits, all with JavaScript off; opt into
-  interactivity per behaviour inside a component.
-- **Commit per logical unit** as soon as it is complete, and never push to `main`.
-
-Everything else (the module architecture, the `ActionResult` envelope, styling,
-testing, the client router, optimistic UI) is in the skill's references.
+- **Build order** (study the showcase: a full-stack app's gallery under
+  `app/features/` and `app/examples/todo`, the api template's
+  `app/api/features/`; then `npm run gallery:clear`, data, UI, verify):
+  the playbook in `AGENTS.md`.
+- **Data** (the wired-up Drizzle database, never a JSON file, an in-memory
+  array or Map, or localStorage): `AGENTS.md`, "Data".
+- **Layout** (`app/` is routing only, logic in `modules/<feature>/`): the
+  skill's "Project Layout".
+- **Server boundary, progressive enhancement, typing**: the skill's "What WebJs
+  Is", "Core WebJs Rules", and "Default Workflow".
+- **Git, tests, and `npm run ci`**: `.agents/rules/workflow.md`.

package/templates/Dockerfile

@@ -30,8 +30,14 @@ WORKDIR /app
 # Install deps first so this layer is cached unless the manifests change.
 # package-lock.json is optional (it's absent when the app was scaffolded with
 # --no-install); the glob keeps the COPY working with or without it.
+# Production dependencies only: the image never runs the type checker, the
+# test runner or the browser tests, and leaving them out keeps it a fraction
+# of the size. What the boot itself runs (drizzle-kit for `webjs db migrate`,
+# the Tailwind CLI for the CSS compile) is a production dependency for that
+# reason. The npm cache is emptied in the same layer: it is a second copy of
+# every package fetched and would otherwise ship in the image.
 COPY package.json package-lock.json* ./
-RUN npm install --no-audit --no-fund
+RUN npm install --omit=dev --no-audit --no-fund && npm cache clean --force
 
 # App source. node_modules and local state are excluded via .dockerignore.
 COPY . .

package/templates/partials/agents-playbook-api.md

@@ -44,20 +44,12 @@ cross-origin access use the `cors()` middleware from `@webjsdev/server`; with
 
 ### 5. Verify before you call it done
 
-Run `npm run ci` and fix what it reports. It is one command for every gate,
-the step list declared in `package.json` under `webjs.ci`, with a result line
-per step:
-
-- `webjs check` (correctness: no browser-import or boundary violation).
-- `webjs doctor` (project health). It fails on whatever `package.json`
-  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
-  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
-- `webjs typecheck` (zero type errors).
-- A dependency audit.
-- The test layers for the endpoints and modules you built.
-
-The GitHub workflow runs the same list, so a green local run predicts CI.
-While iterating, `npm run ci -- --only Tests` runs one layer.
+Run `npm run ci` and fix what it reports. It runs every gate declared under
+`webjs.ci` in `package.json` (`webjs check`, `webjs doctor`, `webjs typecheck`,
+a dependency audit, then the test layers for the endpoints and modules you
+built), and the GitHub workflow runs the
+same list; `.agents/rules/workflow.md` has what each gate checks. While
+iterating, `npm run ci -- --only Tests` runs one layer.
 
 Then boot `npm run dev` and probe each endpoint for the expected status and JSON
 shape.