@webjsdev/cli 0.10.70 → 0.10.72

package/bin/webjs.js

@@ -99,6 +99,8 @@ const USAGE = `webjs commands:
   webjs elision [--json] [--verify]               Report which component modules are elided and why each shipped one ships;
                                                   --verify diffs SSR output with elision on vs off (exits non-zero on a divergence)
   webjs mcp                                       Start the read-only MCP server (routes / actions / components / elision / check)
+  webjs source <Export> [--pkg <name>]            Print the signature plus doc comment of one export from the installed @webjsdev/*
+                                                  packages (typed declarations first, the authored JSDoc as the fallback); exit 1 on a miss
   webjs doctor [--json] [--strict]                Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision, component elision, un-versioned stylesheet links).
                                                   --json emits the structured results (with stable codes). --strict additionally fails on every remaining warning.
                                                   Per-check severity is CONFIG: map a code to off/warn/error under "webjs": { "doctor": { "gate": {...} } }
@@ -326,6 +328,19 @@ const HELP = {
     summary: 'Start the read-only MCP server (routes / actions / components / elision / check + a docs/source knowledge layer).',
     examples: ['webjs mcp'],
   },
+  source: {
+    usage: 'webjs source <Export> [--pkg <name>]',
+    summary: 'Print one framework export\'s signature plus the doc comment above it, read from the installed @webjsdev/* packages (the typed declarations first, the authored JSDoc when none carries a doc; every overload). The cheap way to check a contract before opening the source file.',
+    options: [
+      { flag: '--pkg <name>', description: 'Search one package only: core, server, cli, ui or intellisense.' },
+    ],
+    notesTitle: 'Exit status',
+    notes: [
+      '0 when at least one declaration printed; 1 on a miss (the message names the packages that were searched).',
+      'The read-only MCP `source` tool returns the same text for { export: "<Export>" }.',
+    ],
+    examples: ['webjs source createAuth', 'webjs source optimistic --pkg core', 'webjs source getFileStore'],
+  },
   version: {
     usage: 'webjs version',
     summary: 'Print the installed @webjsdev/cli version. Also available as webjs --version / -v.',
@@ -1968,6 +1983,29 @@ Full docs: https://webjs.dev/docs`);
         `  --from PROVIDER     CDN to resolve through. One of: ${[...SUPPORTED_PROVIDERS].join(', ')}. Default: jspm.`);
       process.exit(1);
     }
+    case 'source': {
+      // One export's signature plus its doc comment from the installed
+      // @webjsdev/* packages (#1623): the same lookup the MCP `source` tool
+      // runs for its `export` arg, so a Bash-only agent (no MCP) checks a
+      // contract for the price of the declaration instead of the whole file.
+      // Read-only: it reads the resolved package roots and loads no module.
+      const name = rest.find((a) => !a.startsWith('--'));
+      const pkgAt = rest.indexOf('--pkg');
+      const pkg = pkgAt >= 0 ? rest[pkgAt + 1] : undefined;
+      if (!name) {
+        console.error('usage: webjs source <Export> [--pkg core|server|cli|ui|intellisense]');
+        process.exit(1);
+      }
+      const { lookupExport, resolveFrameworkRoots } = await import('@webjsdev/mcp');
+      const { existsSync, readdirSync } = await import('node:fs');
+      const { readFile } = await import('node:fs/promises');
+      const roots = resolveFrameworkRoots(process.cwd(), { exists: existsSync });
+      const readdir = (d) => readdirSync(d, { withFileTypes: true }).map((e) => ({ name: e.name, isDir: e.isDirectory() }));
+      const out = await lookupExport({ roots, readFile, readdir }, name, pkg);
+      console.log(out);
+      if (!/^@webjsdev\//m.test(out)) process.exit(1);
+      break;
+    }
     case 'mcp': {
       // Read-only MCP server (#262, #415) over stdio. STDOUT is the JSON-RPC
       // channel, so nothing here may write to stdout: the data functions are

package/lib/app-icon.js

@@ -43,13 +43,3 @@ export function appManifest(name) {
     icons: [{ src: '/icon.svg', sizes: 'any', type: 'image/svg+xml' }],
   }, null, 2) + '\n';
 }
-
-/**
- * Whether an SVG is the WebJs brand mark earlier scaffolds shipped as
- * `public/favicon.svg` (a rounded square with the gallery's grey gradient).
- * Apps made before the placeholder still serve it as their favicon.
- * @param {string} svg
- */
-export function isLegacyBrandFavicon(svg) {
-  return /aria-label="WebJs"/.test(svg) && /<linearGradient id="wj"/.test(svg);
-}

package/lib/doctor/probes/app-icon.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { PLACEHOLDER_MARKER, isLegacyBrandFavicon } from '../../app-icon.js';
+import { PLACEHOLDER_MARKER } from '../../app-icon.js';
 
 /**
  * @typedef {import('../codes.js').DoctorResult} DoctorResult
@@ -12,11 +12,9 @@ function read(file) {
 }
 
 /**
- * Warn when the app's favicon is still the one `webjs create` shipped: the
- * neutral `app/icon.svg` placeholder, or the WebJs brand mark earlier
- * scaffolds put at `public/favicon.svg`. Either way every app made from the
- * scaffold shows the same tab icon, which reads as a demo rather than a
- * product. An app with no `app/` directory (a library, the api template with
+ * Warn when the app's favicon is still the neutral `app/icon.svg` placeholder
+ * `webjs create` shipped: every app made from the scaffold would show the same
+ * tab icon, which reads as a demo rather than a product. An app with no `app/` directory (a library, the api template with
  * no pages) passes.
  *
  * @param {string} appDir
@@ -25,12 +23,9 @@ function read(file) {
 export function checkAppIcon(appDir) {
   const name = 'app-icon';
   if (!existsSync(join(appDir, 'app'))) return { name, status: 'pass', message: 'no app/ directory to analyse' };
-  const fix = 'Replace app/icon.svg with an icon for this app (a simple symbol for what it is, in its own colours, legible at 16px), and delete public/favicon.svg plus any metadata.icons that still points at it.';
+  const fix = 'Replace app/icon.svg with an icon for this app (a simple symbol for what it is, in its own colours, legible at 16px).';
   if (read(join(appDir, 'app', 'icon.svg')).includes(PLACEHOLDER_MARKER)) {
     return { name, status: 'warn', message: 'app/icon.svg is still the scaffold placeholder icon', fix };
   }
-  if (isLegacyBrandFavicon(read(join(appDir, 'public', 'favicon.svg')))) {
-    return { name, status: 'warn', message: 'public/favicon.svg is still the WebJs mark an earlier scaffold shipped', fix };
-  }
   return { name, status: 'pass', message: 'the app has its own icon (or declares none)' };
 }

package/lib/runtime-rewrite.js

@@ -23,11 +23,9 @@
  *   - the `dev` / `start` scripts force `bun --bun` (the server is Bun),
  *   - every other command stays `bun run` / `webjs ...` (runs on Node via the
  *     `webjs` bin's `#!/usr/bin/env node` shebang),
- *   - the Dockerfile is a pure `oven/bun:1-slim` base (#595, #1606). This is safe as of
- *     `@webjsdev/cli@0.10.20` (#570): `webjs db migrate` resolves drizzle-kit
- *     and runs it under Bun (no `npx`), so a Node-less image works. (Before
- *     #570 shipped as `latest`, this stayed on `node:24-alpine` + a copied Bun
- *     binary, since the installed CLI could still shell `npx`.)
+ *   - the Dockerfile is a pure `oven/bun:1-slim` base (#595, #1606): `webjs db
+ *     migrate` resolves drizzle-kit and runs it under Bun (no `npx`, #570), so
+ *     a Node-less image works.
  */
 
 /**
@@ -97,15 +95,11 @@ export function bunifyProse(s) {
  * Rewrite the scaffolded Dockerfile for Bun.
  *
  * Base decision (acceptance criterion): a pure `oven/bun:1-slim` image (no Node).
- * Safe as of `@webjsdev/cli@0.10.20` (#570): `webjs db` / `webjs test` resolve
- * their tools (drizzle-kit, wtr) and spawn them with the current runtime instead
- * of `npx`, so the boot-time `webjs db migrate` runs under Bun with no Node
- * toolchain. (Before #570 was the published `latest`, this stayed on a
- * `node:24-alpine` base with a copied Bun binary, since the installed CLI could
- * still shell `npx`, which a pure Bun image lacks. #595 flipped it once the
- * npx-free CLI shipped.) `oven/bun:1` is Debian-based: `ca-certificates` ship in
- * the image, and SQLite uses the built-in bun:sqlite (no native module), so no
- * build toolchain is needed.
+ * `webjs db` / `webjs test` resolve their tools (drizzle-kit, wtr) and spawn
+ * them with the current runtime instead of `npx` (#570), so the boot-time
+ * `webjs db migrate` runs under Bun with no Node toolchain. `oven/bun:1` is
+ * Debian-based: `ca-certificates` ship in the image, and SQLite uses the
+ * built-in bun:sqlite (no native module), so no build toolchain is needed.
  *
  * @param {string} s
  * @returns {string}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.70",
+  "version": "0.10.72",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
@@ -17,8 +17,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/mcp": "^0.1.0",
-    "@webjsdev/server": "^0.8.88",
+    "@webjsdev/mcp": "^0.1.16",
+    "@webjsdev/server": "^0.8.89",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

package/templates/.agents/skills/webjs/SKILL.md

@@ -9,7 +9,7 @@ Use this skill for end-to-end WebJs app work. It helps you choose the right laye
 
 ## Full Documentation
 
-This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). The complete hosted docs live at https://webjs.dev/docs.
+This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). To check ONE export's contract, run `npx webjs source <Export>` (for example `npx webjs source createAuth`, or `--pkg core` to narrow): it prints that export's signature and the doc comment above it from the installed package, so you read the declaration instead of the file. The MCP `source` tool does the same with `export`. Open the source file when the question is about behaviour the signature does not state. The complete hosted docs live at https://webjs.dev/docs.
 
 ## What WebJs Is
 
@@ -155,7 +155,7 @@ Find the right export fast. Load the linked reference for full examples.
 
 ### `@webjsdev/core` (browser + isomorphic)
 
-- `html` / `css` tagged templates. `WebComponent({ ... })` base-class factory; `prop(type?, opts?)` declares one reactive property. `register(tag, C)` / `Class.register('tag')`.
+- `html` / `css` tagged templates. `WebComponent({ ... })` base-class factory; `prop(type?, opts?)` declares one reactive property. `Class.register('tag')` binds the tag.
 - `signal` / `computed` reactive state, `effect(fn)` client-only reaction (returns a disposer), `batch(fn)` coalesced writes; `render(v, el)` client render.
 - `notFound()` / `redirect(url[, status])` control-flow throws (page/layout/action only, NOT `route.ts`). `forbidden()` / `unauthorized()` render the nearest boundary.
 - `Suspense({fallback, children})` page-level streaming; `<webjs-suspense>` component-level streaming.

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -296,7 +296,7 @@ Three levels, the same scale ESLint uses: `error` fails the exit, `warn` reports
 
 Two guarantees worth knowing. A result that could not check (a network or toolchain outage) is capped at `warn` and can never be escalated, so a jspm or npm outage cannot red your CI. And a malformed gate exits 1 naming the offender rather than being ignored, so a typo cannot silently un-gate the build. That covers an unknown code, a bad severity, a wrong shape (a non-object `doctor` or `gate`), and a misspelled sibling of `gate` such as `gates`, since every one of those would otherwise leave the build un-gated while the `package.json` looks gated. Under `--json` the offenders come back as a `configErrors` array alongside an empty `results`, each entry a `{ kind }` of `malformed` / `unknown-key` / `unknown-code` / `bad-severity`. Wire it up with one workflow step, `npm run doctor`, and change what is fatal in `package.json` rather than in the workflow.
 
-`APP_ICON` warns while the favicon is still the scaffold's: the placeholder `app/icon.svg` (marked `data-webjs-placeholder`) or the WebJs mark older scaffolds shipped at `public/favicon.svg`. Replace it with the app's own icon (`references/routing-and-pages.md`, "App icon and manifest").
+`APP_ICON` warns while the favicon is still the scaffold's placeholder `app/icon.svg` (marked `data-webjs-placeholder`). Replace it with the app's own icon (`references/routing-and-pages.md`, "App icon and manifest").
 
 ### Dependency audit allowlist
 

package/templates/AGENTS.md

@@ -22,10 +22,13 @@ This is what separates a working app from a broken one.
    rules (git, tests, review) are in `.agents/rules/workflow.md`; follow them
    too.
 3. **Read the framework source for exact contracts.** WebJs is 100% buildless
-   native ES modules, so the source you run IS the source you read. When you
-   need a precise API signature or behavior, open the package source under
-   `node_modules/@webjsdev/*` directly (each package ships its own `AGENTS.md`).
-   The full hosted docs are at https://webjs.dev/docs.
+   native ES modules, so the source you run IS the source you read. For one
+   export's signature and doc comment run `npx webjs source <Export>` (for
+   example `npx webjs source createAuth`); it reads the installed package and
+   prints the declaration, not the file. When you need the behaviour behind a
+   signature, open the package source under `node_modules/@webjsdev/*` directly
+   (each package ships its own `AGENTS.md`). The full hosted docs are at
+   https://webjs.dev/docs.
 
 {{PLAYBOOK}}