@webjsdev/cli 0.10.22 → 0.10.23

package/bin/webjs.js

@@ -47,7 +47,7 @@ const USAGE = `webjs commands:
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check [--json]                            Run correctness checks on the app (--json emits structured violations)
   webjs mcp                                       Start the read-only MCP server (routes / actions / components / check)
-  webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook)
+  webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision)
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs typecheck [tsc args...]                   Type-check the app with the project's tsc --noEmit (non-zero on errors)
   webjs create <name> [--template full-stack|api|saas] [--db sqlite|postgres] [--runtime node|bun] [--no-install]  Scaffold a new webjs app

package/lib/doctor.js

@@ -36,7 +36,7 @@
 
 import { existsSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { checkNodeInline } from './node-preflight.js';
 
 /**
@@ -795,6 +795,53 @@ function checkGitHook(appDir) {
  *     instead of a real live resolve / node_modules read.
  * @returns {Promise<DoctorResult[]>}
  */
+/**
+ * Advisory (#646): name why a page/layout SHIPS its module to the browser
+ * instead of being elided. A page/layout that is a pure carrier (import-only
+ * #605 / inert #179) stays out of the browser; one that ships whole is pinned
+ * by a specific client-effecting NON-component in its closure (a util touching
+ * a client global, a module-scope side effect, a bare side-effect import) or by
+ * its own client work. This turns that invisible #605/#179 regression into a
+ * named line. WARN only: a page legitimately MAY ship, and the analyser is
+ * biased toward shipping by design (server AGENTS invariant 7), so this is a
+ * "you may not have intended this" hint, never a hard fail.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkElisionCarriers(appDir) {
+  const name = 'Page/layout elision (carrier hygiene)';
+  let report;
+  try {
+    const { analyzeAppElision } = await import('@webjsdev/server');
+    report = await analyzeAppElision(appDir);
+  } catch {
+    // Analysis unavailable (no app, malformed, server import failed): no advice.
+    return { name, status: 'pass', message: 'not analysed (no routable app or analysis unavailable)' };
+  }
+  if (!report.analysed) {
+    return { name, status: 'pass', message: 'not analysed (no routable app, or elision is disabled)' };
+  }
+  if (report.shipped.length === 0) {
+    return { name, status: 'pass', message: 'every page/layout is elided (a pure import-only or inert carrier)' };
+  }
+  const rel = (f) => relative(appDir, f) || f;
+  // Name the FIRST client-effecting blocker (there may be more than one; the
+  // module stays shipped until every such blocker is moved out).
+  const lines = report.shipped.map(({ file, blocker, reason }) =>
+    blocker
+      ? `${rel(file)} ships whole. Its first client-effecting blocker is ${rel(blocker)}, which ${reason} and is not a component`
+      : `${rel(file)} ships whole because it ${reason}`,
+  );
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${report.shipped.length} page/layout module(s) ship to the browser instead of being elided:\n` +
+      lines.map((l) => `    ${l}`).join('\n'),
+    fix: 'Move the client work out of the page/layout closure (into a component, or a .server module reached through an action) so the carrier can be elided, or accept that it ships. See agent-docs/components.md.',
+  };
+}
+
 export async function runDoctorChecks(appDir, opts = {}) {
   const cliDir = opts.cliDir || new URL('.', import.meta.url).pathname;
   const results = await Promise.all([
@@ -806,6 +853,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkWebjsVersions(appDir),
     checkImportmapCoherence(appDir, opts),
     Promise.resolve(checkGitHook(appDir)),
+    checkElisionCarriers(appDir),
   ]);
   return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.22",
+  "version": "0.10.23",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/CONVENTIONS.md

@@ -506,7 +506,7 @@ SSR, page actions, server-action RPC, auth + CSRF), drive
 
 ```ts
 import { createRequestHandler } from '@webjsdev/server';
-import { testRequest, getCsrf, invokeActionForTest, loginAndGetCookies, withSessionCookie }
+import { testRequest, invokeActionForTest, loginAndGetCookies, withSessionCookie }
   from '@webjsdev/server/testing';
 
 const app = await createRequestHandler({ appDir: process.cwd(), dev: true });
@@ -524,8 +524,9 @@ const out = await invokeActionForTest(app, 'modules/posts/actions/create.server.
 
 Prefer `invokeActionForTest` over a direct import of the action when you want
 to verify the production contract: it exercises the wire serializer (a `Date` /
-`Map` arg survives), CSRF, and prod error sanitization, which a direct call
-bypasses. The saas template's `test/auth/auth.test.ts` is a worked example.
+`Map` arg survives), the Origin / Sec-Fetch-Site CSRF check (it models a
+same-origin POST), and prod error sanitization, which a direct call bypasses.
+The saas template's `test/auth/auth.test.ts` is a worked example.
 
 This is also why the auth test lives at `test/auth/auth.test.ts` (the
 feature-folder convention), NOT `test/unit/auth.test.ts`. Test KIND is a