@webjsdev/cli 0.10.37 → 0.10.39

package/bin/webjs.js

@@ -3,6 +3,8 @@ import { resolve, join, dirname } from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { resolveBin } from '../lib/resolve-bin.js';
+import { dbGenerateTtyHint } from '../lib/db-hints.js';
+import { DESIGN_REMINDER, hasUiLayout } from '../lib/design-bar.js';
 import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
 import { loadAppEnv, resolvePort } from '../lib/port.js';
 import { planDevSupervisor } from '../lib/dev-supervisor.js';
@@ -45,7 +47,7 @@ const USAGE = `webjs commands:
                                                   (--no-hot: run in-process, no hot-reload supervisor)
   webjs start [--port 8080]                       Start production server (serves source directly, no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
-  webjs check [--json]                            Run correctness checks on the app (--json emits structured violations)
+  webjs check [--json] [--clear-placeholders]     Run correctness checks (--json emits structured violations; --clear-placeholders strips scaffold markers)
   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, page/layout elision)
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
@@ -124,6 +126,21 @@ async function main() {
     const { assertNodeVersion } = await import('@webjsdev/server');
     assertNodeVersion({ onFail: 'exit' });
   }
+  // #954: `dev` / `start` need `@webjsdev/core` resolvable FROM the app dir. A
+  // fresh git worktree has no node_modules (git worktrees do not copy it), so
+  // the app's pages otherwise fail deep in SSR with a raw
+  // `ERR_MODULE_NOT_FOUND: Cannot find package '@webjsdev/core'`. Probe up front
+  // and surface the cause + remedy instead. No-op (a cheap resolve) when the
+  // framework resolves, so the happy-path boot is untouched.
+  if (cmd === 'dev' || cmd === 'start') {
+    const { checkFrameworkResolves } = await import('../lib/doctor.js');
+    const probe = checkFrameworkResolves(process.cwd());
+    if (probe.status !== 'pass') {
+      console.error(`[webjs] ${probe.message}`);
+      if (probe.fix) console.error(`[webjs] Fix: ${probe.fix}`);
+      process.exit(1);
+    }
+  }
   switch (cmd) {
     case 'dev': {
       // If we're already inside the reload child (node --watch or bun --hot),
@@ -240,8 +257,31 @@ async function main() {
         );
         process.exit(1);
       }
-      const child = spawn(process.execPath, [dkPath, ...kitArgs, ...args], { stdio: 'inherit', cwd: process.cwd() });
-      child.on('exit', (code) => process.exit(code ?? 0));
+      // For `generate` off a non-TTY, capture stderr (teed straight through) so
+      // the rename-prompt dead-end can be detected: drizzle-kit reports it on
+      // stderr but exits 0, so the exit code is useless. Every other case keeps
+      // plain inherit, and an interactive terminal still answers the prompt.
+      const captureStderr = sub === 'generate' && !process.stdin.isTTY;
+      const child = spawn(process.execPath, [dkPath, ...kitArgs, ...args], {
+        stdio: captureStderr ? ['inherit', 'inherit', 'pipe'] : 'inherit',
+        cwd: process.cwd(),
+      });
+      let errText = '';
+      if (captureStderr && child.stderr) {
+        child.stderr.on('data', (chunk) => { errText += chunk; process.stderr.write(chunk); });
+      }
+      // Read the captured stderr on `close`, NOT `exit`: `exit` can fire before
+      // the stderr pipe has drained its final chunk, which would miss the prompt
+      // signature (and tee the raw error AFTER the hint). `close` fires once all
+      // stdio has flushed, and still carries the exit code.
+      child.on('close', (code) => {
+        // Surface the escape hatch when `generate` dead-ends on a rename prompt
+        // with no TTY, instead of leaving the raw drizzle-kit error as the last
+        // word. Interactive and successful runs print nothing extra.
+        const hint = dbGenerateTtyHint(sub, process.stdin.isTTY, errText);
+        if (hint) console.error(hint);
+        process.exit(code ?? 0);
+      });
       break;
     }
     case 'ui': {
@@ -372,6 +412,29 @@ async function main() {
     case 'check': {
       const { checkConventions, RULES } = await import('@webjsdev/server/check');
 
+      // --clear-placeholders: acknowledge the whole scaffold gallery in one
+      // command (strip the marker comment lines, keep the demo code), instead of
+      // one hand-edit per file. The gate then reflects only real violations.
+      if (rest.includes('--clear-placeholders')) {
+        const { clearPlaceholders } = await import('../lib/clear-placeholders.js');
+        const report = clearPlaceholders(process.cwd());
+        const total = report.reduce((n, r) => n + r.markers, 0);
+        if (report.length === 0) {
+          console.log('webjs check: no scaffold-placeholder markers found (nothing to clear).');
+        } else {
+          console.log(`webjs check: cleared ${total} scaffold-placeholder marker(s) across ${report.length} file(s):`);
+          for (const r of report) console.log(`  ${r.file}`);
+          console.log('\nThe demo code is kept. Delete any gallery route/module you do not want, then re-run `webjs check`.');
+          // Re-surface the design bar the cleared markers carried. The
+          // layout/home marker was the just-in-time "adapt this chrome" reminder;
+          // stripping it silently is how an app ends up shipping the scaffold
+          // shell. Print the bar so clearing the markers cannot quietly drop it,
+          // but only for a UI app (the api template has no layout / no chrome).
+          if (hasUiLayout(process.cwd())) console.log(DESIGN_REMINDER);
+        }
+        break;
+      }
+
       if (rest.includes('--rules')) {
         console.log('webjs check, correctness rules:');
         console.log('  Every rule catches code that is wrong to ship: a crash, a');
@@ -406,12 +469,28 @@ async function main() {
         console.log('webjs check: all checks pass ✓');
       } else {
         console.log(`webjs check: ${violations.length} violation(s) found\n`);
+        // A fresh scaffold trips no-scaffold-placeholder on every unadapted demo
+        // file at once. Printing an identical block per file drowns the real
+        // feature violations, so collapse the sentinel to ONE grouped summary
+        // (with a one-command clear) and print every other rule per-violation.
+        // The returned violations and --json are unchanged; only this human
+        // printout groups, so agents/tools still see one entry per file.
+        const PLACEHOLDER = 'no-scaffold-placeholder';
+        const placeholders = violations.filter((v) => v.rule === PLACEHOLDER);
         for (const v of violations) {
+          if (v.rule === PLACEHOLDER) continue;
           console.log(`  ✗ [${v.rule}] ${v.file}`);
           console.log(`    ${v.message}`);
           if (v.fix) console.log(`    Fix: ${v.fix}`);
           console.log();
         }
+        if (placeholders.length > 0) {
+          console.log(`  ✗ [${PLACEHOLDER}] ${placeholders.length} file(s) still carry scaffold example content:`);
+          for (const v of placeholders) console.log(`      ${v.file}`);
+          console.log('    Fix: adapt or delete each file, then remove its marker comment line.');
+          console.log('         Keeping the gallery? Run `webjs check --clear-placeholders` to clear all markers at once.');
+          console.log();
+        }
         process.exit(1);
       }
       break;
@@ -582,6 +661,30 @@ Full docs: https://docs.webjs.dev`);
           (download ? ' (downloading bundles)' : '') + '...',
         );
         const result = await pinAll(appDir, { download, from: explicitFrom });
+        if (result.droppedUnresolvable && !result.pins?.length) {
+          // The scan FOUND bare specifiers but every one was dropped because
+          // it is not installed under node_modules, so no local version could
+          // be read. Name them and point at the remedy instead of the
+          // misleading "no bare imports found" message (#953).
+          const list = result.droppedUnresolvable;
+          // Root package name from a bare specifier: `@scope/pkg/sub` -> `@scope/pkg`,
+          // `pkg/sub` -> `pkg`. This is the thing the user must `npm install`.
+          const rootPkg = (s) => {
+            const parts = s.split('/');
+            return s.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+          };
+          console.error(
+            `Pin: found ${list.length} bare-specifier import${list.length === 1 ? '' : 's'} in ` +
+            `client code under ${appDir}, but could not resolve a version for ` +
+            `${list.length === 1 ? 'it' : 'them'} (not installed under node_modules):`,
+          );
+          for (const s of list) console.error(`  ${s}`);
+          console.error(
+            `Install the package first (e.g. \`npm install ${rootPkg(list[0])}\`), then rerun ` +
+            `\`webjs vendor pin\`. No pin file written.`,
+          );
+          process.exit(1);
+        }
         if (result.noBareImports) {
           // Scanner found zero bare-specifier imports in client-
           // reachable source. Without this branch pinAll would write
@@ -627,6 +730,16 @@ Full docs: https://docs.webjs.dev`);
           (downloaded ? ` + ${downloaded} bundle${downloaded === 1 ? '' : 's'}` : '') + '.';
         const pruneMsg = pruned.length ? ` Pruned ${pruned.length} orphan${pruned.length === 1 ? '' : 's'}.` : '';
         console.log(pinMsg + pruneMsg);
+        if (result.droppedUnresolvable?.length) {
+          // A partial pin: some specifiers resolved, others were dropped for a
+          // missing local version. Name the skipped ones so it is not silent.
+          console.warn(
+            `[webjs] Skipped ${result.droppedUnresolvable.length} import` +
+            `${result.droppedUnresolvable.length === 1 ? '' : 's'} with no installed version ` +
+            `(install then rerun to pin ${result.droppedUnresolvable.length === 1 ? 'it' : 'them'}):`,
+          );
+          for (const s of result.droppedUnresolvable) console.warn(`  ${s}`);
+        }
 
         // Make the pins committable. Vendoring is opt-in, so the pins the
         // user just wrote are meant for source control; a `.gitignore`

package/lib/clear-placeholders.js

@@ -0,0 +1,98 @@
+// `webjs check --clear-placeholders`: acknowledge the scaffold gallery in one
+// command instead of hand-editing every demo file. A fresh scaffold trips
+// `no-scaffold-placeholder` on every unadapted file at once, and the rule's
+// sanctioned "deliberately keep it, then delete the marker line" path otherwise
+// means one manual edit per file. This strips the marker comment lines so the
+// gate goes green while the demo CODE is kept verbatim (it does NOT prune the
+// gallery; deleting a demo you do not want stays a deliberate `rm`).
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Assembled so THIS source does not itself carry the contiguous literal (the
+// check scans raw source, and this file ships in the published CLI).
+export const MARKER = 'webjs-scaffold-' + 'placeholder';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.webjs', 'graphify-out', 'dist']);
+
+// Every scaffold marker's text ends with this closing clause (wrapped across
+// lines or not), so it precisely bounds the marker sentence. See create.js /
+// api-gallery.js where the markers are emitted.
+const TERMINATOR = 'the marker remains';
+
+// Strip comment punctuation and collapse whitespace so a marker wrapped across
+// several `//` or `<!-- -->` lines can be matched as one normalized sentence.
+const norm = (line) => line.replace(/<!--|-->|\/\//g, ' ').replace(/\s+/g, ' ').trim().toLowerCase();
+const isLineComment = (line) => /^\s*\/\//.test(line);
+
+/**
+ * Pure: drop exactly the marker COMMENT that carries the token, not just the
+ * token line and NOT the adjacent educational comment/code. The marker is not
+ * always one line (the layout footer is a multi-line `<!-- ... -->`, and the
+ * global-* markers wrap across `//` lines), and it is often immediately followed
+ * by a SEPARATE comment paragraph, so a greedy "remove the whole comment run"
+ * over-removes. The marker sentence always ends in TERMINATOR, so extend from
+ * the token line only to the line that completes that clause (or, if the clause
+ * is somehow absent, remove just the token line rather than over-reaching).
+ * @param {string} content
+ * @param {string} [marker]
+ * @returns {{ content: string, removed: number, markers: number }}
+ */
+export function stripPlaceholderMarkers(content, marker = MARKER) {
+  const lines = content.split('\n');
+  const kept = [];
+  let removed = 0;
+  let markers = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.includes(marker)) { kept.push(line); continue; }
+    markers += 1;
+    let acc = norm(line);
+    let end = i;
+    if (!acc.includes(TERMINATOR)) {
+      // Extend over the marker's own comment (contiguous `//`, or up to the HTML
+      // `-->`) until the closing clause completes. Stop at the comment boundary
+      // if the clause never appears, so an edited marker under-removes, never
+      // eats the following paragraph or code.
+      const html = line.includes('<!--');
+      for (let j = i + 1; j < lines.length; j++) {
+        if (!html && !isLineComment(lines[j])) break;
+        acc += ' ' + norm(lines[j]);
+        end = j;
+        if (acc.includes(TERMINATOR) || (html && lines[j].includes('-->'))) break;
+      }
+      if (!acc.includes(TERMINATOR) && !html) end = i; // clause absent: token line only
+    }
+    removed += end - i + 1;
+    i = end;
+  }
+  return { content: kept.join('\n'), removed, markers };
+}
+
+/**
+ * Walk an app root, strip the marker comments in place, and return a per-file
+ * report of how many markers were cleared (and how many lines that removed).
+ * Only `.ts`/`.js`/`.mts`/`.mjs` files that actually carry the marker are
+ * rewritten.
+ * @param {string} root
+ * @param {{ marker?: string, write?: (path: string, content: string) => void }} [opts]
+ * @returns {Array<{ file: string, markers: number, removed: number }>}
+ */
+export function clearPlaceholders(root, opts = {}) {
+  const marker = opts.marker ?? MARKER;
+  const write = opts.write ?? ((p, c) => writeFileSync(p, c));
+  const report = [];
+  (function walk(dir) {
+    for (const name of readdirSync(dir)) {
+      if (SKIP_DIRS.has(name)) continue;
+      const full = join(dir, name);
+      if (statSync(full).isDirectory()) { walk(full); continue; }
+      if (!/\.m?[jt]s$/.test(name)) continue;
+      const src = readFileSync(full, 'utf8');
+      if (!src.includes(marker)) continue;
+      const { content, removed, markers } = stripPlaceholderMarkers(src, marker);
+      write(full, content);
+      report.push({ file: full, markers, removed });
+    }
+  })(root);
+  return report;
+}