@webjskit/cli 0.3.0 → 0.4.0

package/bin/webjs.js

@@ -6,6 +6,11 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
 
+// Exactly three scaffolds exist — keep this list as the single source of
+// truth. AI-agent docs in README.md / AGENTS.md / .cursorrules /
+// .windsurfrules / .github/copilot-instructions.md mirror it.
+const TEMPLATES = ['full-stack', 'api', 'saas'];
+
 const USAGE = `webjs — commands:
   webjs dev   [--port 3000]                       Start dev server with live reload
   webjs start [--port 3000]                       Start production server (serves source directly; no build required)
@@ -14,6 +19,7 @@ const USAGE = `webjs — commands:
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check                                     Validate app against conventions
   webjs create <name> [--template full-stack|api|saas]  Scaffold a new webjs app
+                                                  (only 3 templates exist; default: full-stack with Prisma+SQLite)
   webjs db generate                               Run \`prisma generate\`
   webjs db migrate [name]                         Run \`prisma migrate dev\`
   webjs db studio                                 Run \`prisma studio\`
@@ -201,11 +207,36 @@ async function main() {
     }
     case 'create': {
       const name = rest[0];
-      if (!name) {
-        console.error('Usage: webjs create <app-name> [--template full-stack|api]');
+      if (!name || name.startsWith('-')) {
+        console.error('Usage: webjs create <app-name> [--template full-stack|api|saas]');
         process.exit(1);
       }
       const template = flag(rest, '--template', 'full-stack');
+      if (!TEMPLATES.includes(template)) {
+        // AI agents sometimes hallucinate template names ("blog", "todo",
+        // "ecommerce"). Reject early with the canonical list + guidance
+        // on which scaffold to pick for which kind of app.
+        console.error(`Error: unknown template '${template}'.
+
+Only three scaffolds exist:
+  full-stack   (default) — pages + components + API + Prisma/SQLite.
+                Pick this for any app the user describes in product terms
+                (todo app, blog, dashboard, marketplace, social feed, …).
+  api          — backend-only: route handlers + modules, no pages/SSR.
+                Pick this only if the user explicitly asks for an HTTP/JSON
+                API with no UI.
+  saas         — auth + login/signup + protected dashboard + Prisma User
+                model. Pick this only if the user explicitly asks for auth
+                or a SaaS-shaped product.
+
+The scaffold is a starting point — replace the example layout/page/
+components/schema with the actual app the user requested. Use Prisma +
+SQLite for persistence (already wired up); never store app data in JSON
+files.
+
+Full docs: https://docs.webjs.com`);
+        process.exit(1);
+      }
       const { scaffoldApp } = await import('../lib/create.js');
       await scaffoldApp(name, process.cwd(), { template });
       break;

package/lib/create.js

@@ -25,6 +25,14 @@ const TEMPLATES = resolve(__dirname, '..', 'templates');
  */
 export async function scaffoldApp(name, cwd, opts = {}) {
   const template = opts.template || 'full-stack';
+  // Defence in depth — the CLI already validates this, but library
+  // callers (tests, programmatic use) might pass anything.
+  const VALID_TEMPLATES = ['full-stack', 'api', 'saas'];
+  if (!VALID_TEMPLATES.includes(template)) {
+    throw new Error(
+      `Unknown template '${template}'. Only ${VALID_TEMPLATES.join(' / ')} exist.`,
+    );
+  }
   const isApi = template === 'api';
   const isSaas = template === 'saas';
   const appDir = join(cwd, name);
@@ -79,6 +87,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       '@web/test-runner': '^0.20.0',
       '@web/test-runner-playwright': '^0.11.0',
       'playwright': '^1.59.0',
+      // tsserver plugins for editor intelligence inside html`` templates.
+      // Order in tsconfig matters — see below.
+      'ts-lit-plugin': '^2.0.0',
+      '@webjskit/ts-plugin': 'latest',
     },
   }, null, 2) + '\n');
 
@@ -92,10 +104,16 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       noEmit: true,
       allowImportingTsExtensions: true,
       skipLibCheck: true,
-      // ts-lit-plugin gives tag/attribute intelligence inside html`` templates
-      // (autocomplete, type-check, go-to-definition for <my-element>).
-      // Install: `npm i -D ts-lit-plugin`. Remove this plugin entry if you don't want it.
-      plugins: [{ name: 'ts-lit-plugin', strict: true }],
+      // ts-lit-plugin: type-check + diagnostics inside html`` templates.
+      // @webjskit/ts-plugin: webjs-aware go-to-definition, "Unknown tag/attr"
+      // suppression for elements registered via Class.register('tag'), and
+      // attribute auto-complete sourced from `static properties`.
+      // Order matters — list ts-lit-plugin first; @webjskit/ts-plugin wraps
+      // it. Remove either entry if you don't want that capability.
+      plugins: [
+        { name: 'ts-lit-plugin', strict: true },
+        { name: '@webjskit/ts-plugin' },
+      ],
     },
   }, null, 2) + '\n');
 
@@ -579,5 +597,22 @@ AI-driven development (enforced for all AI agents):
   ✓ Commits are automatic, small, and meaningful
   ✓ No AI attribution in commit messages
   ✓ Convention validation via \`webjs check\`
+
+For AI agents — read this before editing scaffolded files:
+  • The example layout / page / components / schema are REFERENCE ONLY.
+    Replace them with the app the user actually asked for. Don't ship
+    the scaffold's example User model or "Hello from …" page as the
+    final product.
+  • Use Prisma + SQLite for app data — it's already wired up. Define
+    real models in prisma/schema.prisma and run \`webjs db migrate\`.
+    NEVER store app data in JSON files, in-memory arrays, or
+    localStorage as a substitute for the database.
+  • Only three scaffolds exist: full-stack (default), api, saas. Don't
+    invent template names. If you need a different kind of app, pick
+    the closest scaffold and adapt it.
+  • Read AGENTS.md + CONVENTIONS.md in the new project before writing
+    any code. They are the contract.
+  • Need more detail? Full hosted docs are at https://docs.webjs.com
+    (every API, directive, recipe, and deployment guide).
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjskit/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "webjs CLI — dev, start, create, db",
   "bin": {
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjskit/server": "0.3.0"
+    "@webjskit/server": "0.4.0"
   },
   "publishConfig": {
     "access": "public"

package/templates/.cursorrules

@@ -2,7 +2,28 @@
 
 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.
+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.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
 

package/templates/.github/copilot-instructions.md

@@ -2,7 +2,28 @@
 
 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.
+project-specific conventions. 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.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
 

package/templates/.windsurfrules

@@ -2,7 +2,28 @@
 
 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.
+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.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
 

package/templates/AGENTS.md

@@ -2,8 +2,57 @@
 
 Read this before editing any file. This is a webjs app: AI-first, web-
 components-first, no build step. The framework's own full API reference
-lives at https://github.com/vivek7405/webjs/blob/main/AGENTS.md — treat
-this file as the app-scoped companion.
+lives at https://github.com/vivek7405/webjs/blob/main/AGENTS.md and the
+full hosted documentation (every API, recipe, and example) lives at
+**https://docs.webjs.com** — treat this file as the app-scoped
+companion and reach for docs.webjs.com whenever you need more detail.
+
+## If you just scaffolded this app (AI agents — read first)
+
+This project was created with `webjs create`. The files you see right
+now — `app/page.ts` ("Hello from {{APP_NAME}}"), the example `User`
+model in `prisma/schema.prisma`, the `theme-toggle` component, the
+example users module (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.
+
+**Non-negotiables for every webjs app:**
+
+1. **Use Prisma + SQLite for persistence.** It's already wired up
+   (`prisma/schema.prisma`, `lib/prisma.ts`, `npm run db:migrate`,
+   `predev` hook running `prisma generate`). For any data the app
+   stores — todos, posts, messages, products, comments, anything —
+   define a Prisma model and persist there.
+   - **NEVER** store app data in JSON files (`data/todos.json`,
+     `db.json`, …). The convention check `no-json-data-files` flags
+     this and the user's prompt explicitly forbids it.
+   - **NEVER** use in-memory arrays or `Map`s as a substitute for the
+     database — they vanish on every dev-server reload and aren't
+     shared across processes.
+   - **NEVER** use `localStorage` to persist app data — it's per-browser
+     and doesn't reach the server.
+2. **One of three scaffolds only.** The CLI exposes exactly three:
+   `full-stack` (default), `--template api`, `--template saas`. Don't
+   reach for a `--template blog` / `--template todo` / `--template
+   ecommerce` — they don't exist and the CLI will reject them.
+3. **First step after scaffolding:** edit `prisma/schema.prisma` to the
+   app's real domain models (delete the example `User` model unless the
+   app actually needs users), run `webjs db migrate <name>`, then build
+   pages / actions / queries against those models.
+
+**Picking the right scaffold from the user's prompt** (you do this BEFORE
+running `webjs create`; if you're reading this you've already scaffolded —
+verify the choice was correct, otherwise re-scaffold in a fresh dir):
+
+| User asks for… | Scaffold |
+|---|---|
+| Todo app, blog, notes, dashboard, marketplace, social feed, e-commerce, any product with a UI | `webjs create <name>` (default full-stack) |
+| HTTP/JSON API only, no UI | `webjs create <name> --template api` |
+| Anything with login / signup / accounts / protected pages / SaaS | `webjs create <name> --template saas` |
+
+When in doubt, **full-stack is the default**. Pick `api` only if the user
+is explicit about wanting a backend-only API. Pick `saas` only if the user
+is explicit about auth / accounts / SaaS.
 
 ## Framework source is in `node_modules/`
 
@@ -28,7 +77,8 @@ node_modules/@webjskit/
     src/actions.js            ← .server.ts scanner, RPC, expose()
     src/auth.js, session.js, cache.js, rate-limit.js, csrf.js
   cli/             webjs CLI (dev / start / build / test / check / create / db)
-  ts-plugin/       tsserver go-to-definition for custom-element tag names
+  ts-plugin/       tsserver plugin: go-to-definition + diagnostic suppression
+                   + attribute auto-complete for Class.register('tag') elements
 ```
 
 Reaching straight for the source is the fastest way to resolve "why

package/templates/CLAUDE.md

@@ -1,70 +1,2 @@
-# CLAUDE.md — {{APP_NAME}}
-
-This file instructs AI coding agents on how to work in this project.
-**Do not duplicate content here** — reference the authoritative sources below.
-
-## Required reading (in this order)
-
-1. **[AGENTS.md](./AGENTS.md)** — Full webjs API reference, file conventions,
-   invariants, recipes, directives, lifecycle, controllers, context, task.
-2. **[CONVENTIONS.md](./CONVENTIONS.md)** — Project-specific conventions for
-   module architecture, testing rules, component patterns, code style.
-   Users may override sections.
-
-## AI-driven development workflow
-
-**CRITICAL: Every code change MUST include the following — automatically,
-without the user having to ask:**
-
-### 1. Commit and push often (mandatory, never skip)
-
-**Commit AND push after each logical unit of work** — a completed
-feature, a passing test, a doc update. Don't accumulate uncommitted
-or unpushed changes. Small focused commits with meaningful messages.
-No AI attribution trailers. Always `git push` after committing.
-This is automatic — the user should never have to ask.
-
-### 2. Tests (mandatory, never skip)
-
-- **New server action or query** → add unit test in `test/unit/<module>.test.ts`
-- **New or modified component** → add unit test (SSR rendering via `renderToString`)
-- **New or modified page/route** → add E2E test in `test/browser/<feature>.test.ts`
-- **Bug fix** → add regression test proving the fix
-- **Refactor** → run existing tests, ensure they pass
-
-After writing code, ALWAYS run `webjs test`. If E2E-relevant,
-also run `webjs test --browser`. Never report a task as done with
-failing tests.
-
-### 3. Documentation (mandatory, never skip)
-
-When adding or modifying features, update:
-
-- **AGENTS.md** — API surface table, directive reference, recipes, or
-  relevant sections. This is the source of truth for the framework.
-- **CONVENTIONS.md** — Only if the change introduces or modifies a convention.
-
-If this project has a **docs/** directory, also:
-- Add or update the relevant documentation page under `docs/`.
-
-If this project has a **website/** directory, also:
-- Update the website landing page if the feature is user-facing/marketable.
-
-### 4. Convention validation
-
-After making changes, run `webjs check` and fix any violations before
-reporting the task as done.
-
-## Quick reference
-
-```sh
-webjs dev              # dev server with live reload
-webjs test             # run unit tests
-webjs test --browser       # run unit + E2E tests
-webjs check            # validate conventions
-webjs build            # (optional) production bundle
-webjs start            # production server
-```
-
-All API details, recipes, and feature documentation → see **[AGENTS.md](./AGENTS.md)**.
-All project conventions and overrides → see **[CONVENTIONS.md](./CONVENTIONS.md)**.
+@AGENTS.md
+@CONVENTIONS.md

package/templates/CONVENTIONS.md

@@ -74,6 +74,70 @@ docs" — that is the agent's default behavior in a webjs project.
 
 ---
 
+## Data persistence — Prisma + SQLite, never JSON files
+
+<!-- OVERRIDE -->
+
+Every webjs app uses **Prisma + SQLite** for persistence by default. The
+scaffold ships `prisma/schema.prisma`, `lib/prisma.ts` (singleton), the
+`predev` / `prestart` hooks that run `prisma generate` / `prisma migrate
+deploy`, and `npm run db:migrate` / `db:generate` / `db:studio` scripts.
+
+**AI agents — these rules are absolute:**
+
+1. For ANY data the app stores (todos, posts, messages, products,
+   comments, users…), define a Prisma model in `prisma/schema.prisma`
+   and persist there.
+2. **NEVER** create JSON files under `data/`, `db.json`, `posts.json`,
+   `todos.json`, etc. as a fake database. The `no-json-data-files`
+   convention check flags this and `webjs check` will fail.
+3. **NEVER** use module-scope arrays or `Map`s as a "store" — they
+   reset on every dev-server reload and can't scale beyond one process.
+4. **NEVER** use `localStorage` / `sessionStorage` to persist app data —
+   it's per-browser and never reaches the server. Use it only for UI
+   preferences (theme, sidebar collapsed, etc.).
+5. To add a model: edit `prisma/schema.prisma`, then `npm run db:migrate
+   -- --name <description>`. Access via `import { prisma } from
+   '../../../lib/prisma.ts'` — never `new PrismaClient()`.
+
+To switch to Postgres or MySQL: change `provider` in
+`prisma/schema.prisma` and the `DATABASE_URL` in `.env`. Do this only
+if the user explicitly asks for it — SQLite is the right default for
+dev and small production workloads.
+
+---
+
+## The scaffold is reference, not the final product
+
+<!-- OVERRIDE -->
+
+This project was created with `webjs create`. Every file you see right
+now — `app/page.ts` ("Hello from …"), the example `User` model, the
+`theme-toggle` component, the example users module (api / saas
+templates) — is a **starting point**.
+
+When the user asks the agent to build their actual app:
+
+1. **Replace the example `User` model** in `prisma/schema.prisma` with
+   the real domain models the app needs (e.g. `Todo`, `Post`, `Message`)
+   — unless the app actually has users.
+2. **Replace `app/page.ts`** with the app's real homepage. Don't ship
+   "Hello from …" as the deliverable.
+3. **Delete or replace `components/theme-toggle.ts`** if the app doesn't
+   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
+   (`AGENTS.md`, `CONVENTIONS.md`, `CLAUDE.md`, `.cursorrules`, etc.),
+   `lib/prisma.ts`, the directory conventions, the design tokens in
+   `app/layout.ts`. These are the infrastructure, not the example app.
+
+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.
+
+---
+
 ## Sensible defaults
 
 <!-- OVERRIDE -->
@@ -225,6 +289,14 @@ export class MyWidget extends WebComponent {
   declare count: number;
   // Light DOM is the default; Tailwind utility classes apply directly.
 
+  constructor() {
+    super();
+    // Defaults go here — never as class-field initializers
+    // (`label = ''` would clobber the framework's reactive accessor).
+    this.label = '';
+    this.count = 0;
+  }
+
   render() {
     return html`
       <div class="p-4 border border-border rounded-lg">
@@ -241,9 +313,11 @@ attribute coercion, reflection). `declare` types the field for
 TypeScript without emitting a class-field initializer that would
 clobber the reactive accessor at construction time. The two
 declarations together give you full intelligence in any tsserver-backed
-editor — see the Editor Setup docs for `ts-lit-plugin` setup that
-extends this to tag / attribute intelligence inside `html\`…\``
-templates.
+editor — see the Editor Setup docs for the `ts-lit-plugin` +
+`@webjskit/ts-plugin` setup that extends this to tag / attribute
+intelligence inside `html\`…\`` templates (go-to-definition, attribute
+auto-complete from `static properties`, no "Unknown tag" red-squiggle on
+registered webjs elements).
 
 **Rules:**
 - One component per file
@@ -254,6 +328,7 @@ templates.
   - `my-widget .body`, `my-widget .title` (descendant selector)
 - Tag name must contain a hyphen (HTML spec)
 - Always call `Class.register('tag')` — the standard DOM API
+- **Reactive props use `declare propName: Type` (no value) plus a default in `constructor()` after `super()`.** Never write `propName = value` or `propName: Type = value` as a class-field initializer — it compiles to `Object.defineProperty(this, …)` after `super()` and clobbers the framework's reactive accessor, silently breaking re-renders. `webjs check` flags this via the `reactive-props-use-declare` rule.
 - Use `setState()` for state changes, never mutate `this.state` directly
 - Use lifecycle hooks (`firstUpdated`, `updated`) only when needed