@webjsdev/cli 0.10.12 → 0.10.14

package/lib/prisma-preflight.js

@@ -0,0 +1,168 @@
+/**
+ * Prisma-client preflight for `webjs dev` (#452).
+ *
+ * The scaffold's `dev` npm script is `webjs dev`, and `npm run dev` runs the
+ * `predev` hook (`prisma generate`) FIRST. Invoking the `webjs dev` binary
+ * directly (easy to do, and tempting for an AI/CLI) skips `predev`, so the dev
+ * server boots against an ungenerated `@prisma/client` and crashes with a raw
+ * "did not initialize yet" error and no hint that the canonical command is
+ * `npm run dev`. This turns that crash into a one-line, actionable message.
+ *
+ * Scope is deliberately narrow: it only fires for an app that actually uses
+ * Prisma (a `prisma/schema.prisma` OR an `@prisma/client` dependency), and it
+ * only HINTS. It never auto-runs an arbitrary `predev` script and never shells
+ * out to `prisma generate` on its own, keeping the no-build promise intact.
+ *
+ * Detection (verified against a real Prisma 6 install): the GENERATED
+ * `.prisma/client` target is resolved through standard Node resolution from the
+ * app (so a hoisted monorepo, where the client lives at a PARENT `node_modules`,
+ * resolves correctly), then read. An ABSENT target, or a present-but-stub target
+ * (the ungenerated client whose `PrismaClient` constructor throws the init
+ * error), is "ungenerated". A real generated target older than the schema is
+ * "stale". We do NOT grep the static `@prisma/client` re-export shim: it is
+ * present in both states and never carries the init-error string itself.
+ */
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+
+/**
+ * Does this app use Prisma? True if a schema is checked in OR `@prisma/client`
+ * is a declared dependency. Either alone is enough; a non-Prisma app has
+ * neither and gets no warning.
+ *
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function usesPrisma(cwd) {
+  if (existsSync(join(cwd, 'prisma', 'schema.prisma'))) return true;
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return Boolean(deps && deps['@prisma/client']);
+  } catch {
+    return false;
+  }
+}
+
+// Marker the ungenerated `prisma-client-js` stub embeds in its generated target
+// (`node_modules/.prisma/client/index.js`). Verified against a real Prisma 6
+// install: after `npm i @prisma/client` but before `prisma generate`, the
+// generated `.prisma/client` entry IS present but its `PrismaClient` constructor
+// throws `@prisma/client did not initialize yet. Please run "prisma generate"`.
+// A real `prisma generate` replaces that stub with the generated client, which
+// does NOT contain this string. So the marker, read from the GENERATED target
+// (not the static `@prisma/client` shim), is the reliable ungenerated signal.
+const UNGENERATED_MARKER = 'did not initialize yet';
+
+/**
+ * Resolve the GENERATED Prisma client entry (`.prisma/client/index.js`) for an
+ * app, following standard Node resolution so a hoisted monorepo layout (the
+ * generated client at a PARENT `node_modules`, the app under `apps/<x>`) still
+ * resolves. Returns a discriminated result so the caller can tell the three
+ * cases apart:
+ *   - `{ kind: 'unresolved' }`        - `@prisma/client` itself is not resolvable.
+ *   - `{ kind: 'no-target' }`         - the package resolves but `.prisma/client`
+ *                                       does not (a custom `output`, ambiguous).
+ *   - `{ kind: 'target', path }`      - the generated target resolves.
+ *
+ * @param {string} cwd
+ * @returns {{ kind: 'unresolved' } | { kind: 'no-target' } | { kind: 'target', path: string }}
+ */
+function resolveGeneratedClient(cwd) {
+  let clientDir;
+  try {
+    // Resolve @prisma/client AS THE APP would (hoisting-aware), then locate its
+    // package dir. The shim itself loads `.prisma/client/default` relative to
+    // here, so resolving from this dir follows the same (possibly hoisted) path.
+    const appRequire = createRequire(join(cwd, 'noop.js'));
+    clientDir = dirname(appRequire.resolve('@prisma/client'));
+  } catch {
+    return { kind: 'unresolved' };
+  }
+  const shimRequire = createRequire(join(clientDir, 'noop.js'));
+  for (const entry of ['.prisma/client/index.js', '.prisma/client/default.js']) {
+    try {
+      return { kind: 'target', path: shimRequire.resolve(entry) };
+    } catch { /* try the next entry */ }
+  }
+  return { kind: 'no-target' };
+}
+
+/**
+ * Inspect the generated Prisma client state for a Prisma app.
+ *
+ * Returns one of:
+ *   - `{ status: 'ok' }`         - client generated and not older than the schema.
+ *   - `{ status: 'missing' }`    - schema/dep present but no generated client.
+ *   - `{ status: 'stale' }`      - client exists but the schema is newer than it.
+ *
+ * Detection resolves the GENERATED `.prisma/client` target through standard Node
+ * resolution (so hoisted monorepos are handled) and reads it: an absent target,
+ * or a present-but-stub target (the ungenerated `PrismaClient` that throws on
+ * construction), is `missing`. A real generated client that is older than the
+ * schema is `stale`. A custom-`output` generator whose target Node cannot
+ * resolve falls back to `ok` rather than nag a working app (false positives are
+ * worse than a missed hint here).
+ *
+ * @param {string} cwd
+ * @returns {{ status: 'ok' | 'missing' | 'stale' }}
+ */
+export function prismaClientState(cwd) {
+  const resolved = resolveGeneratedClient(cwd);
+
+  // @prisma/client not resolvable: the app declared the dep (usesPrisma gated
+  // us here) but it is not installed/generated. That is the boot-crash case.
+  if (resolved.kind === 'unresolved') return { status: 'missing' };
+
+  // The package resolves but the default `.prisma/client` target does not: a
+  // custom `output` whose location we cannot cheaply verify. Fall back to `ok`
+  // rather than nag a working app (false positives are worse than a missed hint).
+  if (resolved.kind === 'no-target') return { status: 'ok' };
+
+  const generatedIndex = resolved.path;
+
+  // The generated target exists. Is it still the ungenerated stub (its
+  // PrismaClient constructor throws the init error)?
+  try {
+    const body = readFileSync(generatedIndex, 'utf8');
+    if (body.includes(UNGENERATED_MARKER)) return { status: 'missing' };
+  } catch { /* unreadable: fall through to the stale check, then ok */ }
+
+  // Generated for real. Is it older than the schema (a stale client)?
+  const schema = join(cwd, 'prisma', 'schema.prisma');
+  try {
+    if (existsSync(schema)) {
+      const schemaMtime = statSync(schema).mtimeMs;
+      const clientMtime = statSync(generatedIndex).mtimeMs;
+      if (schemaMtime > clientMtime) return { status: 'stale' };
+    }
+  } catch { /* if we can't stat, treat as ok */ }
+
+  return { status: 'ok' };
+}
+
+/**
+ * Build the actionable hint for an ungenerated/stale client, or `null` when the
+ * app is fine or does not use Prisma. The caller prints it (a warning, not a
+ * hard exit) before booting the dev server.
+ *
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function prismaDevHint(cwd) {
+  if (!usesPrisma(cwd)) return null;
+  const { status } = prismaClientState(cwd);
+  if (status === 'ok') return null;
+
+  const reason =
+    status === 'stale'
+      ? 'Your Prisma client looks stale (the schema changed since it was generated).'
+      : 'Your Prisma client is not generated yet.';
+  return (
+    `webjs: ${reason}\n` +
+    `  The dev server will crash on an ungenerated client. Fix it with either:\n` +
+    `    npm run dev          # canonical: runs \`prisma generate\` (predev) first\n` +
+    `    webjs db generate    # just regenerate the client, then re-run\n`
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.12",
+  "version": "0.10.14",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {
@@ -10,10 +10,10 @@
     "bin",
     "lib",
     "templates",
-    "README.md",
-    "resources"
+    "README.md"
   ],
   "dependencies": {
+    "@webjsdev/mcp": "^0.1.0",
     "@webjsdev/server": "^0.8.0",
     "@webjsdev/ui": "^0.3.1"
   },
@@ -36,9 +36,5 @@
   ],
   "engines": {
     "node": ">=24.0.0"
-  },
-  "scripts": {
-    "prepack": "node scripts/copy-mcp-resources.js",
-    "postpack": "node scripts/clean-mcp-resources.js"
   }
 }

package/templates/.claude.json

@@ -8,7 +8,7 @@
     "webjs": {
       "type": "stdio",
       "command": "npx",
-      "args": ["@webjsdev/cli", "mcp"]
+      "args": ["@webjsdev/mcp"]
     }
   }
 }

package/templates/AGENTS.md

@@ -89,14 +89,60 @@ node_modules/@webjsdev/
     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 plugin: go-to-definition + diagnostic suppression
+  intellisense/    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
 doesn't X work?" with no documentation guesswork and no stale blog posts.
 
-## Editor TS plugin: `@webjsdev/ts-plugin`
+## Use the webjs MCP server (introspection + framework knowledge)
+
+This project ships a **read-only Model Context Protocol server** that gives
+you (the AI agent) live, version-accurate facts about THIS app and the
+framework. Prefer it over guessing or recalling webjs from training data,
+which drifts. It mutates nothing.
+
+**It is already available, no install needed:** the webjs CLI (a project
+dependency) has it built in as `webjs mcp`. It is an MCP STDIO server (JSON-RPC
+over stdout), so you do not run it in a terminal and read its output. Your MCP
+host (Claude Code, Cursor, etc.) launches it and surfaces its tools, then you
+invoke those tools through the MCP protocol.
+
+Claude Code is pre-wired (see `.claude.json`). For another host, register the
+server by pointing it at the CLI (or the equivalent standalone package):
+
+```jsonc
+// Cursor: .cursor/mcp.json   (or your host's MCP config)
+{ "mcpServers": { "webjs": {
+  "command": "npx", "args": ["@webjsdev/cli", "mcp"]   // the built-in CLI route
+  // equivalent: "command": "npx", "args": ["@webjsdev/mcp"]
+} } }
+```
+
+What it serves:
+
+- **Introspection of this app** (read-only, no module load, no DB side
+  effects): `list_routes` (the route table), `list_actions` (server actions
+  with their `/__webjs/action/<hash>/<fn>` RPC endpoints), `list_components`
+  (registered custom-element tags), `check` (the structured `webjs check`
+  violations). Use these to learn the real route/action/component surface
+  before editing, instead of grepping or assuming.
+- **Framework knowledge**: an `init` primer (the read-first mental model +
+  invariants), a `docs` tool (retrieve a topic or search the `agent-docs`
+  corpus), MCP `resources` (the docs corpus + this AGENTS.md), recipe
+  `prompts` (guided page/route/action/component workflows), and a `source`
+  tool that reads the framework's OWN no-build source from
+  `node_modules/@webjsdev/*/src` (what actually runs).
+
+You have TWO complementary ways to understand the framework, use whichever
+helps (or both): (1) **grep the full framework source** under
+`node_modules/@webjsdev/*/src`, which is the real no-build code that runs (no
+sourcemaps, no guessing), and (2) **the MCP** for live app introspection plus
+the curated `init` / `docs` / `source` knowledge tools. Reach for either before
+guessing from training data or asking the user.
+
+## Editor TS plugin: `@webjsdev/intellisense`
 
 This scaffold's `tsconfig.json` lists a single tsserver plugin. It is
 editor-only, not required for the framework to run.
@@ -104,22 +150,24 @@ editor-only, not required for the framework to run.
 ```jsonc
 // tsconfig.json (already wired by the scaffold)
 "plugins": [
-  { "name": "@webjsdev/ts-plugin" }
+  { "name": "@webjsdev/intellisense" }
 ]
 ```
 
-`@webjsdev/ts-plugin` bundles `ts-lit-plugin` internally (it's a runtime
-dependency of the plugin) and loads it programmatically, so users
-list one entry, not two. You get the full stack of template-literal
-intelligence (type-checking, diagnostics, go-to-def inside
-`` html`…` `` and `` css`…` `` templates) **plus** webjs-aware behaviour
-layered on top:
+`@webjsdev/intellisense` is **standalone** (no Lit dependency): one plugin
+entry, its own template parser. Inside `` html`…` `` templates you get:
+
+- Go-to-definition on custom-element tags, attribute / property / event
+  names, and CSS classes in `class="…"`.
+- Binding-aware completions: reachable tag names after `<`, and
+  prefix-keyed attributes (`.prop` property names, `?bool` / plain
+  hyphenated attribute names).
+- Diagnostics: value type-checks against `declare propName: T`, unquoted
+  `@`/`.`/`?` bindings, and expressionless `.prop` bindings.
+- Hover showing the component class / declared member type.
 
-- "Unknown tag/attribute" diagnostics are silenced for elements
-  registered via `Class.register('tag-name')`.
-- Attribute auto-complete sourced from each component's
-  `static properties`.
-- Attribute-value type-check against `declare propName: T` annotations.
+In VS Code / Cursor / Windsurf, the **`webjs` extension** bundles this
+automatically (no `tsconfig.json` edit, no separate Lit extension).
 
 See [docs.webjs.com → Editor setup](https://docs.webjs.com/docs/editor-setup)
 for the full walkthrough.
@@ -472,9 +520,10 @@ Production then has no importmap.json and the server falls back to
 calling api.jspm.io on every cold start. The `**/` prefix matters too:
 it ignores `.webjs/` at any depth, so an app nested below its repo root
 (a monorepo package) does not leak its generated `.webjs/routes.d.ts`
-into `git status`. The `gitignore-vendor-not-ignored` lint rule
-(`webjs check`) verifies the pattern with `git check-ignore` and will
-fail CI if it regresses.
+into `git status`. The `vendor-gitignore` check (`webjs doctor`)
+verifies the pattern with `git check-ignore` and warns if it regresses
+(it is a project-config / setup concern, not a source-code-correctness
+CI gate).
 
 ## Imports
 

package/templates/CONVENTIONS.md

@@ -66,7 +66,10 @@ even if the user doesn't explicitly ask.**
 Run `npm run doctor` (which runs `webjs doctor`) once after cloning to assert
 the project is set up correctly: the Node major (the strip-types floor), the
 tsconfig `erasableSyntaxOnly` flag, `.env` drift vs `.env.example`, vendor-pin
-freshness, `@webjsdev/*` version coherence, and the git pre-commit hook. It
+freshness, the `.gitignore` keeping `.webjs/vendor/` committable
+(`vendor-gitignore`), importmap-coherence (the resolved client deps agree on a
+shared transitive version), `@webjsdev/*` version coherence, and the git
+pre-commit hook. It
 prints `[pass]` / `[warn]` / `[fail]` per check with an actionable fix line and
 exits non-zero only on a hard fail (a broken toolchain), so a green run means
 `npm run dev` will boot. It is a local onboarding/setup-verify tool, not a CI
@@ -348,7 +351,7 @@ variables control infrastructure (no config files needed):
 | `AUTH_SECRET` | Required for auth JWT signing (32+ random chars) |
 | `AUTH_GOOGLE_ID` | Google OAuth client ID (optional) |
 | `AUTH_GITHUB_ID` | GitHub OAuth client ID (optional) |
-| `PORT` | Server port (default: 8080) |
+| `PORT` | Server port. Precedence: `--port` flag > `PORT` (a real exported env var or a `PORT` in `.env`) > 8080. |
 | `WEBJS_PUBLIC_*` | Any env var starting with this prefix is exposed to the browser as `process.env.WEBJS_PUBLIC_X`. Components can read it directly. No build step, no transform. Use for API base URLs, Stripe publishable keys, analytics IDs, anything that is intended to be visible client-side. |
 
 **Server-only by default.** Any env var without the `WEBJS_PUBLIC_` prefix never reaches the browser. Reading `process.env.DATABASE_URL` from a component returns `undefined`, the same as a typo. The prefix is fail-closed: secrets cannot accidentally leak.
@@ -654,11 +657,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 the `ts-lit-plugin` +
-`@webjsdev/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).
+editor. See the Editor Setup docs for the standalone `@webjsdev/intellisense`
+(no Lit dependency) that extends this to tag / attribute intelligence
+inside `html\`…\`` templates (go-to-definition, binding-aware completions,
+value/binding diagnostics, hover); in VS Code / Cursor / Windsurf the
+`webjs` extension bundles it automatically.
 
 **Rules:**
 - One component per file

package/lib/check-json.js

@@ -1,47 +0,0 @@
-/**
- * Shared JSON projector for `webjs check` violations (#262).
- *
- * `webjs check --json` and the `webjs mcp` server's `check` tool BOTH return
- * the identical shape, so the projection lives here once. The input is the raw
- * `Violation[]` from `checkConventions(appDir)` (each `{ rule, file, message,
- * fix }`); the output adds a `summary` count plus a per-rule breakdown so an
- * agent consuming the structured output never has to regex-scrape stdout.
- *
- * Pure and side-effect-free: it neither reads files nor prints. The caller owns
- * running `checkConventions` and (for the CLI) the non-zero exit when there are
- * violations.
- *
- * @module check-json
- */
-
-/**
- * @typedef {{ rule: string, file: string, message: string, fix: string }} Violation
- */
-
-/**
- * @typedef {{
- *   violations: Violation[],
- *   summary: { count: number, byRule: Record<string, number> },
- * }} CheckReport
- */
-
-/**
- * Project a raw `Violation[]` into the structured `{ violations, summary }`
- * report shared by `check --json` and the MCP `check` tool. `violations` is
- * passed through verbatim (the `{ rule, file, message, fix }` shape), and
- * `summary.byRule` tallies how many violations each rule produced.
- *
- * @param {Violation[]} violations
- * @returns {CheckReport}
- */
-export function projectCheck(violations) {
-  /** @type {Record<string, number>} */
-  const byRule = {};
-  for (const v of violations) {
-    byRule[v.rule] = (byRule[v.rule] || 0) + 1;
-  }
-  return {
-    violations,
-    summary: { count: violations.length, byRule },
-  };
-}