@webjsdev/cli 0.8.1

package/templates/.windsurfrules

@@ -0,0 +1,91 @@
+# 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