@webjsdev/server 0.8.67 → 0.8.69

package/src/dev-source-locations.js

@@ -0,0 +1,453 @@
+/**
+ * Dev-only source locations on rendered elements (#1499).
+ *
+ * Under `webjs dev` with `WEBJS_SOURCE_LOCATIONS=1`, every element opening tag
+ * written in an `html` tagged template inside the app carries
+ * `data-webjs-src="<app-relative-file>:<line>"`, in SSR output AND in client
+ * renders, so a tool hosting the app (an inspector, click-to-edit in an
+ * embedding builder) can map a clicked DOM element back to the line that wrote
+ * it.
+ *
+ * Mechanism: a SOURCE transform, applied to the same module bytes on both
+ * sides. The dev server runs it over app modules it serves to the browser
+ * (`dev/serve.js`), and a load hook runs it over app modules the server imports
+ * for SSR (`module.registerHooks` on Node, `Bun.plugin` on Bun). Because both
+ * sides see one transform of one file, the SSR markup and the client render
+ * carry identical attributes.
+ *
+ * Why a source transform and not a runtime one inside `html`: the runtime knows
+ * a template's CALL SITE (from a stack) but not where each element sits inside
+ * it, because the static strings it receives drop the text of every `${...}`
+ * expression, so any multi-line hole would skew every line after it. Lexing the
+ * source keeps every line exact, needs no change to `@webjsdev/core`, and the
+ * inserted text never contains a newline, so every later line keeps its number
+ * (stack traces included; only columns on an annotated line shift).
+ *
+ * What is annotated: element opening tags in the STATIC text of an `html`
+ * template. The attribute goes right after the tag name, before any other
+ * attribute, so attribute, property (`.x=`), event (`@x=`) and boolean (`?x=`)
+ * holes keep their positions and their names. What is not: closing tags,
+ * comments, `<!doctype>`, the inside of a tag or an attribute value, the body of
+ * a raw-text element (`script`, `style`, `textarea`, `title`), descendants of
+ * `svg` / `math` (the root element itself is annotated), document-shell and
+ * head-only elements (`html`, `head`, `body`, `meta`, `link`, `base`, `title`,
+ * `script`, `style`, `noscript`, `template`, `slot`), `css` / `svg` tagged
+ * templates, and any untagged template literal.
+ *
+ * The lexer understands line and block comments, single and double quoted
+ * strings, template literals with nested `${}` (including nested templates),
+ * and regex literals (told apart from division by the previous token). It is a
+ * dev aid, so it fails OPEN: anything it cannot make sense of is returned
+ * unchanged rather than throwing.
+ */
+import { isAbsolute, relative, sep } from 'node:path';
+
+/** Elements never annotated, even at the top level of a template. */
+const SKIP_TAGS = new Set([
+  'html', 'head', 'body', 'meta', 'link', 'base', 'title',
+  'script', 'style', 'noscript', 'template', 'slot',
+]);
+
+/** Raw-text elements: their body is text up to the matching close tag. */
+const RAW_TAGS = new Set(['script', 'style', 'textarea', 'title']);
+
+/** Foreign-content roots: annotate the root, never its descendants. */
+const FOREIGN_TAGS = new Set(['svg', 'math']);
+
+/** Keywords after which a `/` starts a regex rather than a division. */
+const REGEX_AFTER_KEYWORDS = new Set([
+  'return', 'typeof', 'case', 'do', 'else', 'in', 'of', 'new', 'delete',
+  'void', 'throw', 'instanceof', 'yield', 'await',
+]);
+
+/** The env var that turns the feature on (dev only). */
+export const SOURCE_LOCATIONS_ENV = 'WEBJS_SOURCE_LOCATIONS';
+
+/**
+ * Whether source locations are on (#1499, #1504). The app's
+ * `webjs.dev.sourceLocations` sets the default; the env var, when set, wins
+ * either way (`1` / `true` on, `0` / `false` off), so one run can flip it
+ * without editing package.json. Read by the dev handler once, at construction;
+ * the caller also requires `dev`, so production never consults it.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @param {unknown} [configured] the app's `webjs.dev.sourceLocations`
+ * @returns {boolean}
+ */
+export function sourceLocationsRequested(env = process.env, configured = false) {
+  const v = String(env[SOURCE_LOCATIONS_ENV] || '').trim().toLowerCase();
+  if (v === '1' || v === 'true') return true;
+  if (v === '0' || v === 'false') return false;
+  return configured === true;
+}
+
+/**
+ * Whether `abs` is an app module the transform should touch: inside `appDir`,
+ * not under `node_modules`, not a `*.server.*` module (server actions and
+ * server-only utilities never render to the page through a component, and the
+ * `'use server'` load hook owns them), and a JS / TS module.
+ *
+ * @param {string} abs absolute file path (no query)
+ * @param {string} appDir absolute app root
+ * @returns {boolean}
+ */
+export function isSourceLocationCandidate(abs, appDir) {
+  if (!abs || !appDir) return false;
+  const rel = relative(appDir, abs);
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) return false;
+  if (rel.split(/[\\/]/).includes('node_modules')) return false;
+  if (!/\.m?[jt]s$/.test(abs)) return false;
+  if (/\.server\.m?[jt]s$/.test(abs)) return false;
+  return true;
+}
+
+/**
+ * The attribute value for a file: the app-relative path with forward slashes.
+ * Characters that could end the attribute, the template literal, or start a
+ * hole are percent-encoded, so the inserted text is always inert.
+ *
+ * @param {string} abs
+ * @param {string} appDir
+ * @returns {string}
+ */
+export function sourceLocationFile(abs, appDir) {
+  return relative(appDir, abs).split(sep).join('/')
+    .replace(/["'<>&`$\\\s]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0'));
+}
+
+/**
+ * Annotate every element opening tag in the `html` templates of `source`.
+ * Returns the source unchanged when it has no `html` template (or on any
+ * lexing surprise). Never adds or removes a newline.
+ *
+ * @param {string} source module source, JavaScript or erasable TypeScript
+ * @param {string} file the attribute's file part (app-relative, see `sourceLocationFile`)
+ * @returns {string}
+ */
+export function annotateSourceLocations(source, file) {
+  if (typeof source !== 'string' || !source.includes('html')) return source;
+  try {
+    const inserts = collectInserts(source, file);
+    if (!inserts.length) return source;
+    let out = '';
+    let last = 0;
+    for (const [at, text] of inserts) {
+      out += source.slice(last, at) + text;
+      last = at;
+    }
+    return out + source.slice(last);
+  } catch {
+    return source;
+  }
+}
+
+/**
+ * Lex `src` and return `[offset, text]` insertions, in ascending order.
+ *
+ * @param {string} src
+ * @param {string} file
+ * @returns {Array<[number, string]>}
+ */
+function collectInserts(src, file) {
+  /** @type {Array<[number, string]>} */
+  const inserts = [];
+  const n = src.length;
+  let i = 0;
+  // 1-based line of `src[i]`, maintained by `advance`-style bookkeeping: every
+  // place that skips characters counts the newlines it passes.
+  let line = 1;
+  // The previous significant token, for regex-vs-division: 'id' (with its
+  // text in prevWord), 'num', 'str', 'close' (`)` / `]` / `}` ending an
+  // expression), or 'punct'.
+  let prev = 'punct';
+  let prevWord = '';
+  let prevWordStart = -1;
+  // Stack of brace contexts. A '{' frame is an ordinary block; a 'tpl' frame
+  // is a `${` inside a template, and its matching `}` resumes that template.
+  /** @type {Array<{ kind: 'brace' } | { kind: 'tpl', html: HtmlState | null }>} */
+  const stack = [];
+
+  /** @param {number} from @param {number} to */
+  const countLines = (from, to) => {
+    for (let k = from; k < to; k++) if (src.charCodeAt(k) === 10) line++;
+  };
+
+  /**
+   * Scan template literal text starting at `i` (just after a backtick or a
+   * hole's closing brace). Stops after the closing backtick (returns 'end') or
+   * after a `${` (returns 'hole'). Feeds static text to the html machine.
+   * @param {HtmlState | null} html
+   * @returns {'end' | 'hole'}
+   */
+  const scanTemplateText = (html) => {
+    while (i < n) {
+      const c = src[i];
+      if (c === '\\') {
+        // An escape is static text the html machine sees as an opaque char.
+        if (html) html.feed(src, i, line);
+        if (src[i + 1] === '\n') line++;
+        i += 2;
+        continue;
+      }
+      if (c === '`') { i++; return 'end'; }
+      if (c === '$' && src[i + 1] === '{') { i += 2; return 'hole'; }
+      if (html) {
+        const ins = html.feed(src, i, line);
+        if (ins !== -1) inserts.push([ins, ` data-webjs-src="${file}:${line}"`]);
+      }
+      if (c === '\n') line++;
+      i++;
+    }
+    throw new Error('unterminated template');
+  };
+
+  /**
+   * Enter a template literal whose backtick is at `i`.
+   * @param {boolean} isHtml
+   */
+  const enterTemplate = (isHtml) => {
+    i++; // the backtick
+    const html = isHtml ? new HtmlState() : null;
+    const r = scanTemplateText(html);
+    if (r === 'hole') { stack.push({ kind: 'tpl', html }); prev = 'punct'; }
+    else prev = 'str';
+  };
+
+  while (i < n) {
+    const c = src[i];
+    const cc = src.charCodeAt(i);
+    // Whitespace.
+    if (c === '\n') { line++; i++; continue; }
+    if (c === ' ' || c === '\t' || c === '\r' || cc === 0xfeff || cc === 0xa0 || cc === 0x2028 || cc === 0x2029) { i++; continue; }
+    // Comments.
+    if (c === '/' && src[i + 1] === '/') {
+      const end = src.indexOf('\n', i);
+      i = end === -1 ? n : end;
+      continue;
+    }
+    if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      if (end === -1) throw new Error('unterminated comment');
+      countLines(i, end);
+      i = end + 2;
+      continue;
+    }
+    // Strings.
+    if (c === '"' || c === "'") {
+      let k = i + 1;
+      while (k < n && src[k] !== c) {
+        if (src[k] === '\\') k++;
+        else if (src[k] === '\n') throw new Error('unterminated string');
+        k++;
+      }
+      countLines(i, k);
+      i = k + 1;
+      prev = 'str';
+      continue;
+    }
+    // Template literals: tagged with `html` (and not a property access like
+    // `foo.html`) means annotate.
+    if (c === '`') {
+      const isHtml = prev === 'id' && prevWord === 'html' && !isPropertyAccess(src, prevWordStart);
+      enterTemplate(isHtml);
+      continue;
+    }
+    // Identifiers and keywords.
+    if (isIdStart(cc)) {
+      const start = i;
+      while (i < n && isIdPart(src.charCodeAt(i))) i++;
+      prevWord = src.slice(start, i);
+      prevWordStart = start;
+      prev = 'id';
+      continue;
+    }
+    // Numbers.
+    if (cc >= 48 && cc <= 57) {
+      while (i < n && /[0-9a-zA-Z_.]/.test(src[i])) i++;
+      prev = 'num';
+      continue;
+    }
+    // Regex literal vs division.
+    if (c === '/') {
+      const regexAllowed = prev === 'punct' || (prev === 'id' && REGEX_AFTER_KEYWORDS.has(prevWord));
+      if (regexAllowed) {
+        let k = i + 1;
+        let inClass = false;
+        while (k < n) {
+          const d = src[k];
+          if (d === '\\') { k += 2; continue; }
+          if (d === '\n') throw new Error('unterminated regex');
+          if (inClass) { if (d === ']') inClass = false; }
+          else if (d === '[') inClass = true;
+          else if (d === '/') break;
+          k++;
+        }
+        i = k + 1;
+        while (i < n && isIdPart(src.charCodeAt(i))) i++; // flags
+        prev = 'str';
+        continue;
+      }
+      i++;
+      prev = 'punct';
+      continue;
+    }
+    // Braces drive the template-hole stack.
+    if (c === '{') { stack.push({ kind: 'brace' }); i++; prev = 'punct'; continue; }
+    if (c === '}') {
+      const top = stack.pop();
+      i++;
+      if (top && top.kind === 'tpl') {
+        // Back inside the template the hole interrupted.
+        const r = scanTemplateText(top.html);
+        if (r === 'hole') { stack.push(top); prev = 'punct'; }
+        else prev = 'str';
+        continue;
+      }
+      prev = 'close';
+      continue;
+    }
+    if (c === ')' || c === ']') { i++; prev = 'close'; continue; }
+    // Any other punctuation.
+    i++;
+    prev = 'punct';
+  }
+  return inserts;
+}
+
+/**
+ * The HTML tokenizer state for one `html` template, carried across holes so an
+ * attribute value or a raw-text body that a hole interrupts stays recognised.
+ */
+class HtmlState {
+  constructor() {
+    /** @type {'text' | 'tag' | 'dq' | 'sq' | 'comment' | 'raw'} */
+    this.mode = 'text';
+    /** Tag name of the tag being read (lowercased), '' for a close / bang tag. */
+    this.tag = '';
+    /** True while reading a closing tag. */
+    this.closing = false;
+    /** Raw-text element whose body we are in. */
+    this.rawTag = '';
+    /** Depth inside svg / math. */
+    this.foreign = 0;
+    /** The previous char in `tag` mode, to spot a self-closing `/>`. */
+    this.lastTagChar = '';
+  }
+
+  /**
+   * Feed the static char at `src[i]`. Returns the offset to insert the
+   * attribute at (just past an annotatable tag name), else -1.
+   * @param {string} src
+   * @param {number} i
+   * @param {number} _line
+   * @returns {number}
+   */
+  feed(src, i, _line) {
+    const c = src[i];
+    switch (this.mode) {
+      case 'text': {
+        if (c !== '<') return -1;
+        if (src.startsWith('<!--', i)) { this.mode = 'comment'; return -1; }
+        const next = src[i + 1];
+        if (next === '/') {
+          const name = readTagName(src, i + 2);
+          this.mode = 'tag';
+          this.closing = true;
+          this.tag = name.toLowerCase();
+          this.lastTagChar = '';
+          if (FOREIGN_TAGS.has(this.tag) && this.foreign > 0) this.foreign--;
+          return -1;
+        }
+        if (next === '!' || next === '?') {
+          this.mode = 'tag';
+          this.closing = true; // treated like a close tag: never annotated
+          this.tag = '';
+          this.lastTagChar = '';
+          return -1;
+        }
+        const name = readTagName(src, i + 1);
+        if (!name || !/^[A-Za-z]/.test(name)) return -1; // a bare `<` in text
+        this.mode = 'tag';
+        this.closing = false;
+        this.tag = name.toLowerCase();
+        this.lastTagChar = '';
+        if (this.foreign > 0 || SKIP_TAGS.has(this.tag)) return -1;
+        return i + 1 + name.length;
+      }
+      case 'comment': {
+        if (c === '>' && src[i - 1] === '-' && src[i - 2] === '-') this.mode = 'text';
+        return -1;
+      }
+      case 'dq': {
+        if (c === '"') this.mode = 'tag';
+        return -1;
+      }
+      case 'sq': {
+        if (c === "'") this.mode = 'tag';
+        return -1;
+      }
+      case 'raw': {
+        if (c === '<' && src[i + 1] === '/' &&
+          readTagName(src, i + 2).toLowerCase() === this.rawTag) {
+          this.mode = 'tag';
+          this.closing = true;
+          this.tag = this.rawTag;
+          this.rawTag = '';
+          this.lastTagChar = '';
+        }
+        return -1;
+      }
+      case 'tag': {
+        if (c === '"') { this.mode = 'dq'; return -1; }
+        if (c === "'") { this.mode = 'sq'; return -1; }
+        if (c === '>') {
+          const selfClosing = this.lastTagChar === '/';
+          this.mode = 'text';
+          if (!this.closing && !selfClosing) {
+            if (RAW_TAGS.has(this.tag)) { this.mode = 'raw'; this.rawTag = this.tag; }
+            else if (FOREIGN_TAGS.has(this.tag)) this.foreign++;
+          }
+          return -1;
+        }
+        if (c !== ' ' && c !== '\t' && c !== '\n' && c !== '\r') this.lastTagChar = c;
+        return -1;
+      }
+    }
+    return -1;
+  }
+}
+
+/**
+ * Read an HTML tag name starting at `at` (letters, digits, `-`, `:`, `_`, `.`).
+ * @param {string} src
+ * @param {number} at
+ * @returns {string}
+ */
+function readTagName(src, at) {
+  let k = at;
+  while (k < src.length && /[A-Za-z0-9\-:_.]/.test(src[k])) k++;
+  return src.slice(at, k);
+}
+
+/**
+ * Whether the identifier starting at `start` is a member access (`x.html`,
+ * `x?.html`), skipping whitespace back to the previous character.
+ * @param {string} src
+ * @param {number} start
+ * @returns {boolean}
+ */
+function isPropertyAccess(src, start) {
+  let k = start - 1;
+  while (k >= 0 && /\s/.test(src[k])) k--;
+  return k >= 0 && src[k] === '.';
+}
+
+/** @param {number} cc */
+function isIdStart(cc) {
+  return (cc >= 65 && cc <= 90) || (cc >= 97 && cc <= 122) || cc === 36 || cc === 95 || cc > 127;
+}
+
+/** @param {number} cc */
+function isIdPart(cc) {
+  return isIdStart(cc) || (cc >= 48 && cc <= 57);
+}

package/src/ssr/head.js

@@ -6,6 +6,7 @@ import { jsonForScriptTag } from '../script-tag-json.js';
 import { vendorIntegrityFor } from '../importmap.js';
 import { publicEnvShim } from './env-shim.js';
 import { clientRouterEnabled } from './client-router-flag.js';
+import { embedScriptTag } from '../dev-embed.js';
 
 // Which icon metadata ROUTES the app has (`app/icon.*`, `app/apple-icon.*`).
 // Set at boot and on each route rebuild from the route table, the same shape
@@ -845,7 +846,7 @@ export function wrapHead(opts) {
 ${opts.nonce ? `<meta name="csp-nonce" content="${escapeAttr(opts.nonce)}">` : ''}
 ${metaTags.join('\n')}
 <title>${escapeHtml(title)}</title>
-${publicEnvShim({ dev: opts.dev, nonce: opts.nonce })}${clientRouterEnabled() ? '' : `\n<script${n}>window.__WEBJS_CLIENT_ROUTER__=false;</script>`}
+${publicEnvShim({ dev: opts.dev, nonce: opts.nonce })}${embedScriptTag({ dev: opts.dev, nonce: opts.nonce })}${clientRouterEnabled() ? '' : `\n<script${n}>window.__WEBJS_CLIENT_ROUTER__=false;</script>`}
 ${importMapTag({ nonce: opts.nonce })}
 ${linkTags.join('\n')}
 ${scriptTags.length ? scriptTags.join('\n') + '\n' : ''}${boot}

package/src/webjs-config-validate.js

@@ -41,9 +41,9 @@ import { fileURLToPath } from 'node:url';
  * `integer` leaf types.
  *
  * So a value is type-checked only when its schema declares `type: "boolean"` or
- * `type: "integer"`, or an `enum`. Today that is 9 of the 19 top-level keys; the
- * other 10 (`headers`, `redirects`, `allowedOrigins`, `basePath`, `csp`, `dev`,
- * `start`, `db`, `doctor`, `ci`) pass whatever they hold, `csp` because its schema is a
+ * `type: "integer"`, or an `enum`. Today that is 9 of the 20 top-level keys; the
+ * other 11 (`headers`, `redirects`, `allowedOrigins`, `basePath`, `csp`, `dev`,
+ * `start`, `db`, `doctor`, `ci`, `audit`) pass whatever they hold, `csp` because its schema is a
  * `oneOf` with no `type` at all and the rest because theirs is `array`,
  * `string`, or `object`. That is enough for the case this exists to close, a
  * typo'd top-level key silently dropped, plus the leaf kinds a schema can decide

package/webjs-config.schema.json

@@ -202,6 +202,15 @@
           "description": "Extra directories the dev live-reload watcher follows in addition to the appDir (#894), for content the app reads from outside its own tree (e.g. blog markdown in a repo-root blog/ dir). Each entry is resolved relative to the app root and may escape it (../blog). Read by the server (readDevWatchPathsFromApp).",
           "type": "array",
           "items": { "type": "string" }
+        },
+        "embedOrigins": {
+          "description": "Dev embed bridge (#1498, #1504), DEV-ONLY and off by default. Parent origins (e.g. https://builder.example) allowed to frame the dev server: X-Frame-Options is dropped and frame-ancestors widened for them, and every document carries a nonce-signed script that posts { source: 'webjs-embed', type } messages to such a parent and takes { source: 'webjs-embed-host', type } commands from it. A set WEBJS_EMBED_ORIGINS env var replaces this list. Read by the server (readDevToolingFromApp). Ignored by webjs start.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "sourceLocations": {
+          "description": "Dev source locations (#1499, #1504), DEV-ONLY and off by default. When true, element opening tags in the app's html templates carry data-webjs-src=\"<app-relative-file>:<line>\" in SSR output and client renders. WEBJS_SOURCE_LOCATIONS=1 or 0 overrides it for one run. Read by the server (readDevToolingFromApp). Ignored by webjs start.",
+          "type": "boolean"
         }
       }
     },
@@ -238,6 +247,31 @@
         }
       }
     },
+    "audit": {
+      "description": "`webjs audit` (#1492): the dependency audit's failing level and its allowlist, in one place. `webjs audit` runs `npm audit` or `bun audit` (by the nearest lockfile) and fails on any advisory at or above `level` that `ignore` does not list. Read by the CLI (readAuditConfig in packages/cli/lib/audit.js), NOT the server. A malformed block (an unknown key, a bad level, an entry without an id or a reason) exits 1, so an allowlist cannot silently stop applying.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "level": {
+          "description": "The lowest severity that fails the audit. Default high.",
+          "type": "string",
+          "enum": ["low", "moderate", "high", "critical"]
+        },
+        "ignore": {
+          "description": "Advisories the app accepts, each with the reason it is safe. Only for an advisory with no patched release that the app's users cannot reach; an id the audit no longer reports is printed as stale.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "reason"],
+            "properties": {
+              "id": { "description": "The advisory id, GHSA-xxxx-xxxx-xxxx or CVE-YYYY-NNNN.", "type": "string", "pattern": "^(GHSA(-[0-9a-zA-Z]{4}){3}|CVE-[0-9]{4}-[0-9]+)$" },
+              "reason": { "description": "Why accepting it is safe (which dependency chain reaches it, and why that chain cannot reach users).", "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
     "ci": {
       "description": "Local CI (#1471): the step list `webjs ci` runs on a developer machine, and the same list a cloud pipeline runs by calling `npm run ci`, so the two cannot drift. Read by the CLI (readCiConfig in packages/cli/lib/ci-config.js), NOT the server. A step is a string (shorthand for a command whose title is the command), a { title, run, env? } command, or a { title, steps, parallel? } group. `parallel` is a slot count (default 1, sequential); a group nested inside a parallel group takes ONE slot and runs its steps in order, so it cannot declare `parallel` itself.",
       "type": "object",