@webjsdev/cli 0.9.1 → 0.10.1

package/templates/CONVENTIONS.md

@@ -95,16 +95,135 @@ even if the user doesn't explicitly ask.**
    Run `webjs test` after every change. Never mark work as done with
    failing tests.
 
-3. **Documentation updates.** When adding or modifying features:
-   - Update `AGENTS.md` if the change affects the framework API surface.
-   - Update `CONVENTIONS.md` only if the change introduces a new convention.
-   - If a `docs/` directory exists, add or update the relevant doc page.
-   - If a `website/` directory exists, update the landing page for
-     user-facing features.
-
-3. **Convention check.** Run `webjs check` after changes and fix
+3. **Documentation updates.** See the **Definition of done** section
+   below for the per-surface checklist. The short version: docs land on
+   the same PR as the code, never as a follow-up. Drift is how a
+   codebase rots; the user should never have to ask "did you update the
+   docs?"
+
+4. **Convention check.** Run `webjs check` after changes and fix
    any violations before reporting the task as done.
 
+### Definition of done (MUST be addressed BEFORE opening the PR)
+
+This is the per-PR contract. Before running `gh pr create`, walk through
+every surface below and either update it OR write `N/A because <reason>`
+in the PR body so the omission is visible. The
+[`.github/pull_request_template.md`](./.github/pull_request_template.md)
+checklist mirrors this list.
+
+**Surfaces to consider on EVERY PR:**
+
+1. **Tests.** Unit coverage for new logic. Real-browser coverage for
+   user-facing behaviour. `webjs test` must pass; `webjs test --browser`
+   for any DOM-touching change. See the "Testing" section below for the
+   per-change matrix.
+2. **Every markdown file in the project.** Walk the whole tree, not a
+   closed list. Run `git ls-files '*.md'` (or `git ls-files '*.md'
+   '*.mdx'` if the project ships MDX) and for each path ask: does this
+   file describe behaviour, surface, or invariants that this PR changed?
+   If yes, update it on this PR. Common surfaces (non-exhaustive):
+   - `AGENTS.md` (root and every nested one) for API surface, invariants,
+     file-routing rules, project-wide agent workflow.
+   - `CONVENTIONS.md` (this file) for architectural conventions. Do NOT
+     enumerate lint rules in prose; those live in `package.json` under
+     `"webjs": { "conventions": { … } }`.
+   - `README.md` (root and any nested ones) for install / use / public
+     surface descriptions.
+   - `CHANGELOG.md` for any user-visible change, including the SHA / PR
+     reference. Keep it in chronological order; don't backdate.
+   - `docs/` (if the project has one). Every user-visible change. Add a
+     new page if the surface is new and there's no obvious home.
+   - Any `*.md` under `agent-docs/`, `docs-internal/`, `decisions/`, or
+     similar reference trees.
+   - `.github/*.md` (issue templates, PR templates, contributing) when
+     a workflow rule shifts.
+3. **`website/`** (if the project has one). Marketing copy on the
+   landing page or pricing page when the change touches a claim made
+   there.
+4. **Scaffold or codegen scripts** (if the project has any). Update
+   when the change affects what new instances generate.
+5. **PR body.** Summary, test plan checklist, and a per-row answer to
+   the Definition-of-done checklist (`Updated <path>` or `N/A because
+   <reason>`).
+
+**How to use the checklist.** For each surface above, explicitly answer
+one of:
+
+- **Updated**, with the file path in the commit and PR body.
+- **N/A because**, with a one-sentence reason.
+
+The "every markdown file" rule is generative, not enumerative. New
+markdown files appear over a project's lifetime, and this checklist
+must not silently exclude them. The git query above is the source of
+truth; the named files are just common cases.
+
+If you find yourself writing `N/A` for every surface except tests, that
+is a smell. Most user-visible code changes touch at least one markdown
+file and either `AGENTS.md` or `CONVENTIONS.md`.
+
+**Worked examples:**
+
+- Add a new server action `modules/posts/actions/create-post.server.ts`.
+  Updated: test (`test/posts/posts.test.ts`), `AGENTS.md` (action listed
+  in the module map if the project keeps one), `CHANGELOG.md` (one-line
+  entry), `docs/` (the page listing shipped actions if one exists). N/A
+  on website / scaffold scripts.
+- Rename a directory convention (e.g. `modules/` to `features/`).
+  Updated: existing tests still pass after renames, every markdown file
+  that mentions the old name (run `git grep -l 'modules/' '*.md'`),
+  scaffold scripts, `CHANGELOG.md`. N/A on website unless the layout
+  appears in a landing-page screenshot.
+- Fix a bug in `rateLimit()` that doesn't change the surface. Updated:
+  test (regression), `CHANGELOG.md` (one-line entry under fixes). N/A
+  on every other markdown file because the public contract did not
+  change.
+
+### Pre-merge self-review loop (MUST run before signaling the PR is ready)
+
+Saying "ready for merge" before a self-review loop converges is a recurring source of low-quality PRs. The pattern to avoid: agent claims ready-for-merge, user requests a code review, agent finds issues, fixes them, claims ready-for-merge again, repeat 4-5 cycles before a review comes back clean. The cure is to run that loop internally before the first "ready" signal, so the user only hears "ready to merge" after the loop has converged on a clean round.
+
+**How the loop works:**
+
+1. After committing the work and (if remote pushes are in use) pushing the branch, do NOT report "ready for merge" yet. Trigger a **fresh-context review pass**: an AI review with NO prior knowledge of the decisions you made during the implementation. Each AI tool exposes its own primitive for this:
+
+   - **Cursor**: open a new composer tab.
+   - **Claude Code**: spawn a `general-purpose` subagent via the Agent tool.
+   - **GitHub Copilot**: open a new chat (reset the side panel).
+   - **Antigravity** (Google, formerly Windsurf): open a new Cascade thread or a fresh side-panel session.
+   - **Aider**: invoke a separately-started `aider` session (do NOT use `/ask` inside the same session; `/ask` only flips the mode for the next message and still sees the existing context).
+   - **Gemini CLI**: invoke a separately-started `gemini` session.
+   - **OpenCode**: open a new agent session (the `tool.execute.after` hook is a different surface and not a fresh-context primitive).
+
+   The shared property is that the reviewer does not see your decision log. That independence is what makes the review catch blind spots. If your tool does not expose a true fresh-context primitive, the canonical fallback is a separately-invoked CLI process; what matters is the reviewer starts with an empty context, not the specific UI affordance.
+
+2. Prompt the review for problems only. A working prompt template:
+
+   > Review the changes on this branch against the project's `AGENTS.md` and `CONVENTIONS.md`. Look for bugs, regressions, security issues, missed edge cases, broken invariants, doc drift, test gaps, and style violations. Read every file the diff touches in its current state, not just the diff hunks. Specifically check: \<focus rotates per round\>. Report findings as a numbered list with file:line references. Problems only, no suggestions. If you find nothing genuinely wrong, reply exactly `CLEAN` on its own line and stop.
+
+3. For each finding the review reports, either:
+
+   - Fix it on the branch (commit + push), OR
+   - Reject it explicitly with a one-sentence reason. False positives are real, but rejection has to be defensible (e.g. "the reviewer flagged X as a security issue but X runs server-side only and never reaches user input"). Hand-waving doesn't count.
+
+4. If the round found any findings, run another round. The new round picks a slightly different focus: if round 1 was broad, round 2 zooms in on the file you most edited; if round 2 zoomed in, round 3 zooms out to cross-file consistency. Rotate focus to avoid the reviewer rediscovering the same surface twice.
+
+5. If the round reports `CLEAN`, the loop is done.
+
+The minimum is TWO rounds. A clean first round is rare and usually means the review was too shallow; if round 1 is clean, run a second one with a sharper focus before believing the result.
+
+**When to skip the loop:**
+
+Skip only for changes that touch a single line of trivially-correct content (a doc typo, a renamed local variable, a one-token config bump). Anything that touches logic, public surface, build, security, or multiple files goes through the loop without exception. A bias toward running the loop is correct; a bias toward skipping it is the exact failure mode this rule exists to prevent.
+
+**Reporting after the loop:**
+
+When the user is notified the PR is ready, the message should carry:
+
+> Ready for merge. Self-review loop ran \<K\> rounds; last round clean. Issues found and fixed during the loop: \<one-line list, or "none" if rounds 2+ kept finding nothing\>.
+
+If you cannot honestly say "last round clean", you cannot say "ready for merge". If a finding was rejected as a false positive, mention it so the user can second-guess the rejection.
+
 ### Autonomous mode (sandbox / bypass permissions)
 
 When running without interactive approval, agents must NOT ask questions.
@@ -332,6 +451,15 @@ test/
 - `webjs test --browser` (or `npx wtr`) runs the browser tests.
 - `WEBJS_E2E=1 webjs test` adds the e2e tests.
 
+**Every change ships with a test, enforced at commit time.** A commit
+that stages app code (`app/`, `modules/`, `components/`, `lib/`) without
+staging a test is blocked by `.claude/hooks/require-tests-with-src.sh`
+(Claude Code) and the universal `.hooks/pre-commit` (any agent or human).
+A unit test alone is not enough for interactive or component code: add
+the browser test that asserts the rendered/hydrated behaviour. Bypass a
+genuine non-code commit with `WEBJS_NO_TEST_GATE=1`, or `--no-verify` in
+an emergency.
+
 ### Choosing a feature folder
 
 Use the same name as the matching module folder when one exists:
@@ -653,7 +781,15 @@ Use `rateLimit()` as per-segment middleware to protect routes:
 ```ts
 // app/api/auth/middleware.ts: protect auth endpoints
 import { rateLimit } from '@webjsdev/server';
+
+// Direct deploy (default). Keys on the socket-stamped IP, ignoring
+// forwarded-IP headers.
 export default rateLimit({ window: '10s', max: 5 });
+
+// Behind a reverse proxy or CDN (Cloudflare, Railway, Fly, Vercel,
+// nginx, Caddy). Set trustProxy to honour X-Forwarded-For. The proxy
+// MUST strip inbound X-Forwarded-For before adding its own.
+export default rateLimit({ window: '10s', max: 5, trustProxy: true });
 ```
 
 Place `middleware.ts` at any route level. It applies to that subtree only.
@@ -681,9 +817,11 @@ SSR content is visible immediately. Only the JS download is deferred.
 ## expose(): REST endpoints from server actions
 
 <!-- OVERRIDE -->
-Tag a server action to also be reachable over HTTP:
+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`.
 
 ```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 }) => {
   return prisma.post.create({ data: { title, body } });
@@ -823,7 +961,7 @@ export async function createPost(input: {
     constructor(x: number) { this.x = x; }
   }
   ```
-  If you turn `erasableSyntaxOnly` off and use non-erasable syntax, the dev server falls back to esbuild and ships inline sourcemaps for those files (~3x wire bytes per request and stack traces lose strict accuracy). The `erasable-typescript-only` convention check warns when the flag is off.
+  If you turn `erasableSyntaxOnly` off and use non-erasable syntax, 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. The `erasable-typescript-only` convention check warns when the flag is off.
 - No semicolons (or with semicolons, pick one and stay consistent)
 - `const` by default, `let` when needed, never `var`
 - Prefer `async/await` over `.then()` chains
@@ -837,7 +975,7 @@ export async function createPost(input: {
 <!-- OVERRIDE -->
 
 This project enforces a git workflow via agent-specific config files
-(`.claude/settings.json`, `.cursorrules`, `.windsurfrules`,
+(`.claude/settings.json`, `.cursorrules`, `.agents/rules/workflow.md`,
 `.github/copilot-instructions.md`). These rules apply to ALL AI agents:
 
 **Commit rules:**
@@ -862,7 +1000,7 @@ This project enforces a git workflow via agent-specific config files
   Delete or keep `<branch>` after?" Wait for approval AND the preference.
 - **Claude Code hook** (`.claude/hooks/guard-main-merge.sh`) enforces
   merge/push-to-main approval programmatically for Claude agents.
-  Other agents enforce this via `.cursorrules`, `.windsurfrules`,
+  Other agents enforce this via `.cursorrules`, `.agents/rules/workflow.md`,
   `.github/copilot-instructions.md`.
 
 **Pre-commit checks:**

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

@@ -6,7 +6,8 @@
  */
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { html, renderToString } from '@webjsdev/core';
+import { html } from '@webjsdev/core';
+import { renderToString } from '@webjsdev/core/server';
 
 test('html template renders correctly', async () => {
   const result = await renderToString(html`<p>Hello, ${'world'}!</p>`);

package/templates/.windsurfrules

@@ -1,91 +0,0 @@
-# Windsurf Rules - webjs app
-
-You are working on a webjs app - an AI-first, no-build, web-components-first
-framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
-project-specific conventions before writing any code. When AGENTS.md doesn't
-cover what you need, the full hosted docs are at **https://docs.webjs.com**.
-
-## Persistence + scaffold rules (non-negotiable)
-
-- **Use Prisma + SQLite for data, never JSON files.** It's already wired up
-  (`prisma/schema.prisma`, `lib/prisma.server.ts`, `npm run db:migrate`). For ANY
-  data the app stores (todos, posts, messages, products, comments…),
-  define a Prisma model. NEVER create `data/*.json`, `db.json`, or any
-  JSON file as a fake database. NEVER use module-scope arrays / Maps as
-  a substitute. NEVER use localStorage for app data. `webjs check`'s
-  `no-json-data-files` rule will fail the build if you do.
-- **The scaffold is reference, not the final product.** Replace
-  `app/page.ts`, the example `User` model, the example users module, etc.
-  with the app the user actually asked for. Don't ship "Hello from
-  <app-name>" as the deliverable.
-- **Only three templates exist:** `webjs create <name>` (default
-  full-stack), `--template api`, `--template saas`. The CLI rejects any
-  other `--template` value. Pick:
-  - Any product UI (todo, blog, dashboard, marketplace, social…) → default
-  - HTTP/JSON API only, no UI → `--template api`
-  - Auth / login / signup / SaaS → `--template saas`
-
-## Before starting ANY work
-
-FIRST, before writing any code:
-1. Check `git branch --show-current`.
-   - If on main/master: create a feature branch before editing.
-   - If on a feature branch: verify it matches the current task.
-2. Sync: `git fetch origin && git rebase origin/main` if behind.
-
-## Autonomous mode (sandbox / no-prompt)
-
-If running without interactive approval, auto-decide:
-- On main? Auto-create feature/<task-slug> branch
-- Parent behind? Auto-rebase. Merge? Auto-merge + delete feature branches.
-- Auto-generate commit messages. Fix failing tests and violations.
-Quality bar stays the same - no blocking on questions.
-
-## Mandatory workflow (never skip)
-
-Every code change must include:
-1. Server tests in test/<feature>/*.test.ts (node:test)
-2. Browser tests in test/<feature>/browser/*.test.js (WTR + Playwright, real Chromium)
-3. Documentation updates (AGENTS.md, docs/, website/ if they exist)
-4. Convention check: `webjs check` must pass
-
-The user should never have to ask for tests or documentation.
-
-## Git rules
-
-- COMMIT AND PUSH PER LOGICAL UNIT, NOT AT THE END. One feature, one fix,
-  one rename, one doc rewrite per commit. Always `git push` after
-  committing. This is automatic.
-- HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
-  commit before continuing. The Claude Code hook at
-  `.claude/hooks/nudge-uncommitted.sh` fires at threshold 4. Windsurf
-  users should self-enforce the same rule. Batching multiple logical units
-  into one commit is the failure mode this rule exists to prevent.
-- Meaningful commit messages: what changed and why
-- NEVER add Co-Authored-By or AI attribution trailers to commits
-- NEVER use em-dashes (U+2014), a hyphen-as-pause (` - `), or a
-  semicolon-as-pause (` ; `) in commit messages or anywhere else.
-  Rewrite the sentence so no pause-punctuation crutch is needed.
-  Use a period, comma, colon, parentheses, or a restructured phrasing.
-  Plain hyphens stay fine in compound words, CLI flags, filenames,
-  and ranges. Semicolons stay fine inside code
-- Work on feature branches, never push directly to main
-- Create pull requests for review
-- NEVER merge any branch without explicit user permission. Always ask:
-  "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
-  Wait for approval AND the delete/keep preference. Applies to ALL merges.
-- Run `webjs test` before every commit
-
-## Framework specifics
-
-- No build step: ES modules served directly
-- **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 falls back to esbuild + inline sourcemap for those files (~3x wire bytes per request).
-- Web components render into light DOM by default (so Tailwind / global CSS apply directly). Opt in to shadow DOM per component with `static shadow = true` when you need scoped styles (via `static styles = css\`...\``) or third-party-embed isolation. `<slot>` projection works identically in both modes (named slots, fallback content, `assignedNodes` / `slotchange`, first-wins resolution).
-- Custom-element tag names are passed to `.register('tag-name')` - they are NOT a static field on the class.
-- One function per server action file (*.server.ts)
-- 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.
-- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Use plain template-literal expressions (`class=${active ? 'btn active' : 'btn'}`, `style=${'color:' + color}`, `${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
-- **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()`, not `connectedCallback` - the server doesn't call lifecycle hooks). Initial data for components comes from the page function (server-side fetch + pass as attribute/property), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` + server action over `fetch` + 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. Layouts persist across navigation - put shared chrome (sidenav, header) in `layout.ts`, 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.
-- Full API reference in AGENTS.md