domma-cms 0.22.1 → 0.22.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "0.22.1",
+  "version": "0.22.2",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

package/public/js/menu-decor.mjs

@@ -0,0 +1 @@
+export const PRESET_COLOUR_VARS={primary:"--dm-primary",success:"--dm-success",danger:"--dm-danger",warning:"--dm-warning",info:"--dm-info",neutral:"--dm-text-muted"};const o=/^#[0-9a-fA-F]{6}$/;export function colourToCss(t){return typeof t!="string"?"":PRESET_COLOUR_VARS[t]?`var(${PRESET_COLOUR_VARS[t]})`:o.test(t)?t:""}export function makeBadgeEl(t){if(!t||t.text==null||t.text==="")return null;const n=document.createElement("span");n.className="dm-menu-badge",n.textContent=String(t.text);const r=t.variant?colourToCss(t.variant):"";return r&&(n.style.background=r,n.style.color="#fff"),n}export function applyColour(t,n){const r=colourToCss(n);r&&(t.style.color=r)}export function applyPill(t,n){if(!n)return;t.classList.add("dm-nav-pill");const r=n.variant?colourToCss(n.variant):"";n.style==="outline"?(t.classList.add("dm-nav-pill--outline"),r&&(t.style.borderColor=r,t.style.color=r)):r&&(t.style.background=r,t.style.color="#fff")}

package/scripts/build.js

@@ -1,246 +1,263 @@
-/**
- * Build script — creates a publishable staging copy in _publish/
- * Browser-facing JS/CSS is minified; server-side code is copied as-is.
- * Run: node scripts/build.js
- */
-
-import {cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync} from 'fs';
-import {readdir} from 'fs/promises';
-import {createHash} from 'crypto';
-import {dirname, join, relative} from 'path';
-import * as esbuild from 'esbuild';
-
-const ROOT = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
-const OUT = join(ROOT, '_publish');
-
-// Files/dirs copied verbatim (server-side, config, docs)
-const COPY_AS_IS = [
-  'server',
-  'bin',
-  'config',
-  'scripts',
-  'package.json',
-  'public/js/package.json',
-  'README.md',
-  'CLAUDE.md',
-  'LICENSE',
-  '.npmignore',
-];
-
-// Glob patterns for browser-facing assets to minify
-const MINIFY_PATTERNS = [
-  'admin/js/**/*.js',
-  'admin/css/**/*.css',
-  'public/js/**/*.js',
-  'public/css/**/*.css',
-  'plugins/*/public/**/*.js',
-  'plugins/*/public/**/*.css',
-];
-
-// Files within plugins that are copied as-is (server-side plugin code)
-const PLUGIN_AS_IS_PATTERNS = [
-  'plugins/**/plugin.js',
-  'plugins/**/config.js',
-  'plugins/**/routes/**/*.js',
-  'plugins/**/services/**/*.js',
-  'plugins/**/views/**/*.js',
-  'plugins/**/*.json',
-  'plugins/**/*.html',
-];
-
-// HTML templates in admin (copied as-is)
-const ADMIN_HTML_PATTERNS = [
-  'admin/**/*.html',
-];
-
-/**
- * Recursively list all files under a directory, returning paths relative to ROOT.
- * @param {string} dir - Absolute path to the directory to scan.
- * @returns {Promise<string[]>}
- */
-async function listFilesRecursive(dir) {
-  const entries = await readdir(dir, {recursive: true, withFileTypes: true});
-  return entries
-    .filter(e => e.isFile())
-    .map(e => relative(ROOT, join(e.parentPath ?? e.path, e.name)));
-}
-
-/**
- * Match files relative to ROOT against a simple glob pattern.
- * Supports `**` (any path segment), `*` (any non-separator chars), and `{a,b}` alternation.
- * @param {string} pattern
- * @returns {Promise<string[]>}
- */
-async function collectFiles(pattern) {
-  // Expand top-level {a,b,...} alternation into individual patterns
-  const braceMatch = pattern.match(/^\{([^}]+)\}\/(.+)$/);
-  if (braceMatch) {
-    const alts = braceMatch[1].split(',');
-    const rest = braceMatch[2];
-    const results = await Promise.all(alts.map(a => collectFiles(a + '/' + rest)));
-    return [...new Set(results.flat())];
-  }
-
-  // Determine the top-level directory from the pattern (part before first wildcard)
-  const parts = pattern.split('/');
-  let baseDir = ROOT;
-  for (const part of parts) {
-    if (part.includes('*') || part.includes('{')) break;
-    baseDir = join(baseDir, part);
-  }
-
-  if (!existsSync(baseDir)) return [];
-
-  const allFiles = await listFilesRecursive(baseDir);
-
-  // Convert glob pattern to a RegExp
-  const reStr = pattern
-    .replace(/[.+^${}()|[\]\\]/g, (c) => (c === '{' || c === '}' ? c : '\\' + c))
-    .replace(/\{([^}]+)\}/g, (_, alts) => '(?:' + alts.split(',').join('|') + ')')
-    .replace(/\*\*\//g, '(?:[^/]+/){0,}')   // **/ → zero-or-more path segments
-    .replace(/\*\*/g, '(.+)')
-    .replace(/(?<!\()\*/g, '([^/]+)');
-  const re = new RegExp('^' + reStr + '$');
-
-  return allFiles.filter(f => re.test(f.replace(/\\/g, '/')));
-}
-
-async function minifyFile(relPath, loader) {
-  const src = readFileSync(join(ROOT, relPath), 'utf8');
-  const result = await esbuild.transform(src, {
-    loader,
-    minify: true,
-    target: 'es2020',
-  });
-  const outPath = join(OUT, relPath);
-  mkdirSync(dirname(outPath), {recursive: true});
-  writeFileSync(outPath, result.code);
-}
-
-/**
- * Compute a short content hash for a file, used for cache-busting view entries.
- * Returns the first 8 hex chars of SHA-256, or null if the file can't be read.
- *
- * @param {string} filePath - Absolute path to the file
- * @returns {string|null}
- */
-function contentHash(filePath) {
-    try {
-        const content = readFileSync(filePath);
-        return createHash('sha256').update(content).digest('hex').slice(0, 8);
-    } catch {
-        return null;
-    }
-}
-
-/**
- * Rewrite admin.views entry paths in every plugin.json under _publish/plugins/
- * with a content-hash version (?v=<hash>), eliminating the need for manual ?v=N bumps.
- */
-async function stampPluginVersions() {
-    const pluginJsonFiles = await collectFiles('plugins/*/plugin.json');
-    for (const rel of pluginJsonFiles) {
-        const outPath = join(OUT, rel);
-        if (!existsSync(outPath)) continue;
-
-        let manifest;
-        try { manifest = JSON.parse(readFileSync(outPath, 'utf8')); } catch { continue; }
-        if (!manifest.admin?.views) continue;
-
-        let changed = false;
-        for (const [viewName, viewDef] of Object.entries(manifest.admin.views)) {
-            const entryBase = viewDef.entry.split('?')[0];
-            const entryFilePath = join(OUT, 'plugins', entryBase);
-            const hash = contentHash(entryFilePath);
-            if (hash) {
-                manifest.admin.views[viewName] = { ...viewDef, entry: `${entryBase}?v=${hash}` };
-                changed = true;
-            }
-        }
-
-        if (changed) writeFileSync(outPath, JSON.stringify(manifest, null, 2) + '\n');
-    }
-}
-
-async function build() {
-  // Clean and recreate _publish/
-  if (existsSync(OUT)) rmSync(OUT, {recursive: true, force: true});
-  mkdirSync(OUT, {recursive: true});
-
-  // Copy server-side dirs/files verbatim
-  for (const item of COPY_AS_IS) {
-    const src = join(ROOT, item);
-    if (existsSync(src)) {
-      const dest = join(OUT, item);
-      mkdirSync(dirname(dest), {recursive: true});
-      cpSync(src, dest, {recursive: true});
-    }
-  }
-
-  // Strip prepublishOnly from _publish/package.json — the guard is for the
-  // source tree only; running npm publish inside _publish/ must succeed.
-  const pkgPath = join(OUT, 'package.json');
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-  delete pkg.scripts?.prepublishOnly;
-  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
-
-  // Copy plugin server-side code verbatim
-  const pluginAsIs = await collectFiles('{' + PLUGIN_AS_IS_PATTERNS.join(',') + '}');
-  for (const rel of pluginAsIs) {
-    const outPath = join(OUT, rel);
-    mkdirSync(dirname(outPath), {recursive: true});
-    cpSync(join(ROOT, rel), outPath);
-  }
-
-  // Copy admin HTML templates verbatim
-  const adminHtml = await collectFiles(ADMIN_HTML_PATTERNS[0]);
-  for (const rel of adminHtml) {
-    const outPath = join(OUT, rel);
-    mkdirSync(dirname(outPath), {recursive: true});
-    cpSync(join(ROOT, rel), outPath);
-  }
-
-  // Copy Domma tools assets (gitignored but tracked for distribution)
-  const dommaTools = [
-    'admin/dist/domma/domma-tools.css',
-    'admin/dist/domma/domma-tools.min.js',
-  ];
-  for (const rel of dommaTools) {
-    const src = join(ROOT, rel);
-    if (existsSync(src)) {
-      const outPath = join(OUT, rel);
-      mkdirSync(dirname(outPath), {recursive: true});
-      cpSync(src, outPath);
-    }
-  }
-
-  // Minify browser-facing JS and CSS
-  let jsCount = 0;
-  let cssCount = 0;
-
-  // Collect all minify targets, deduplicate against plugin as-is
-  const pluginAsIsSet = new Set(pluginAsIs);
-
-  for (const pattern of MINIFY_PATTERNS) {
-    const files = await collectFiles(pattern);
-    for (const rel of files) {
-      if (pluginAsIsSet.has(rel)) continue; // skip plugin server-side JS
-      const loader = rel.endsWith('.css') ? 'css' : 'js';
-      await minifyFile(rel, loader);
-      if (loader === 'js') jsCount++;
-      else cssCount++;
-    }
-  }
-
-  const totalCopied = COPY_AS_IS.filter(i => existsSync(join(ROOT, i))).length
-    + pluginAsIs.length + adminHtml.length;
-
-  await stampPluginVersions();
-
-  console.log(`Built into _publish/ — JS: ${jsCount} minified, CSS: ${cssCount} minified, ${totalCopied} entries copied`);
-}
-
-build().catch(err => {
-  console.error('Build failed:', err.message);
-  process.exit(1);
-});
+/**
+ * Build script — creates a publishable staging copy in _publish/
+ * Browser-facing JS/CSS is minified; server-side code is copied as-is.
+ * Run: node scripts/build.js
+ */
+
+import {cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync} from 'fs';
+import {readdir} from 'fs/promises';
+import {createHash} from 'crypto';
+import {dirname, join, relative} from 'path';
+import * as esbuild from 'esbuild';
+import {verifyAssetImports, formatReport} from './verify-assets.mjs';
+
+const ROOT = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+const OUT = join(ROOT, '_publish');
+
+// Files/dirs copied verbatim (server-side, config, docs)
+const COPY_AS_IS = [
+  'server',
+  'bin',
+  'config',
+  'scripts',
+  'package.json',
+  'public/js/package.json',
+  'README.md',
+  'CLAUDE.md',
+  'LICENSE',
+  '.npmignore',
+];
+
+// Glob patterns for browser-facing assets to minify. NOTE: both .js AND .mjs
+// must be listed — the browser ESM modules served raw (e.g. public/js/*.mjs)
+// use the .mjs extension, and omitting it silently drops those files from the
+// published package (this is the bug that shipped 0.22.1 without menu-decor.mjs).
+const MINIFY_PATTERNS = [
+  'admin/js/**/*.js',
+  'admin/js/**/*.mjs',
+  'admin/css/**/*.css',
+  'public/js/**/*.js',
+  'public/js/**/*.mjs',
+  'public/css/**/*.css',
+  'plugins/*/public/**/*.js',
+  'plugins/*/public/**/*.mjs',
+  'plugins/*/public/**/*.css',
+];
+
+// Files within plugins that are copied as-is (server-side plugin code)
+const PLUGIN_AS_IS_PATTERNS = [
+  'plugins/**/plugin.js',
+  'plugins/**/config.js',
+  'plugins/**/routes/**/*.js',
+  'plugins/**/services/**/*.js',
+  'plugins/**/views/**/*.js',
+  'plugins/**/*.json',
+  'plugins/**/*.html',
+];
+
+// HTML templates in admin (copied as-is)
+const ADMIN_HTML_PATTERNS = [
+  'admin/**/*.html',
+];
+
+/**
+ * Recursively list all files under a directory, returning paths relative to ROOT.
+ * @param {string} dir - Absolute path to the directory to scan.
+ * @returns {Promise<string[]>}
+ */
+async function listFilesRecursive(dir) {
+  const entries = await readdir(dir, {recursive: true, withFileTypes: true});
+  return entries
+    .filter(e => e.isFile())
+    .map(e => relative(ROOT, join(e.parentPath ?? e.path, e.name)));
+}
+
+/**
+ * Match files relative to ROOT against a simple glob pattern.
+ * Supports `**` (any path segment), `*` (any non-separator chars), and `{a,b}` alternation.
+ * @param {string} pattern
+ * @returns {Promise<string[]>}
+ */
+async function collectFiles(pattern) {
+  // Expand top-level {a,b,...} alternation into individual patterns
+  const braceMatch = pattern.match(/^\{([^}]+)\}\/(.+)$/);
+  if (braceMatch) {
+    const alts = braceMatch[1].split(',');
+    const rest = braceMatch[2];
+    const results = await Promise.all(alts.map(a => collectFiles(a + '/' + rest)));
+    return [...new Set(results.flat())];
+  }
+
+  // Determine the top-level directory from the pattern (part before first wildcard)
+  const parts = pattern.split('/');
+  let baseDir = ROOT;
+  for (const part of parts) {
+    if (part.includes('*') || part.includes('{')) break;
+    baseDir = join(baseDir, part);
+  }
+
+  if (!existsSync(baseDir)) return [];
+
+  const allFiles = await listFilesRecursive(baseDir);
+
+  // Convert glob pattern to a RegExp
+  const reStr = pattern
+    .replace(/[.+^${}()|[\]\\]/g, (c) => (c === '{' || c === '}' ? c : '\\' + c))
+    .replace(/\{([^}]+)\}/g, (_, alts) => '(?:' + alts.split(',').join('|') + ')')
+    .replace(/\*\*\//g, '(?:[^/]+/){0,}')   // **/ → zero-or-more path segments
+    .replace(/\*\*/g, '(.+)')
+    .replace(/(?<!\()\*/g, '([^/]+)');
+  const re = new RegExp('^' + reStr + '$');
+
+  return allFiles.filter(f => re.test(f.replace(/\\/g, '/')));
+}
+
+async function minifyFile(relPath, loader) {
+  const src = readFileSync(join(ROOT, relPath), 'utf8');
+  const result = await esbuild.transform(src, {
+    loader,
+    minify: true,
+    target: 'es2020',
+  });
+  const outPath = join(OUT, relPath);
+  mkdirSync(dirname(outPath), {recursive: true});
+  writeFileSync(outPath, result.code);
+}
+
+/**
+ * Compute a short content hash for a file, used for cache-busting view entries.
+ * Returns the first 8 hex chars of SHA-256, or null if the file can't be read.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {string|null}
+ */
+function contentHash(filePath) {
+    try {
+        const content = readFileSync(filePath);
+        return createHash('sha256').update(content).digest('hex').slice(0, 8);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Rewrite admin.views entry paths in every plugin.json under _publish/plugins/
+ * with a content-hash version (?v=<hash>), eliminating the need for manual ?v=N bumps.
+ */
+async function stampPluginVersions() {
+    const pluginJsonFiles = await collectFiles('plugins/*/plugin.json');
+    for (const rel of pluginJsonFiles) {
+        const outPath = join(OUT, rel);
+        if (!existsSync(outPath)) continue;
+
+        let manifest;
+        try { manifest = JSON.parse(readFileSync(outPath, 'utf8')); } catch { continue; }
+        if (!manifest.admin?.views) continue;
+
+        let changed = false;
+        for (const [viewName, viewDef] of Object.entries(manifest.admin.views)) {
+            const entryBase = viewDef.entry.split('?')[0];
+            const entryFilePath = join(OUT, 'plugins', entryBase);
+            const hash = contentHash(entryFilePath);
+            if (hash) {
+                manifest.admin.views[viewName] = { ...viewDef, entry: `${entryBase}?v=${hash}` };
+                changed = true;
+            }
+        }
+
+        if (changed) writeFileSync(outPath, JSON.stringify(manifest, null, 2) + '\n');
+    }
+}
+
+async function build() {
+  // Clean and recreate _publish/
+  if (existsSync(OUT)) rmSync(OUT, {recursive: true, force: true});
+  mkdirSync(OUT, {recursive: true});
+
+  // Copy server-side dirs/files verbatim
+  for (const item of COPY_AS_IS) {
+    const src = join(ROOT, item);
+    if (existsSync(src)) {
+      const dest = join(OUT, item);
+      mkdirSync(dirname(dest), {recursive: true});
+      cpSync(src, dest, {recursive: true});
+    }
+  }
+
+  // Strip prepublishOnly from _publish/package.json — the guard is for the
+  // source tree only; running npm publish inside _publish/ must succeed.
+  const pkgPath = join(OUT, 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  delete pkg.scripts?.prepublishOnly;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+
+  // Copy plugin server-side code verbatim
+  const pluginAsIs = await collectFiles('{' + PLUGIN_AS_IS_PATTERNS.join(',') + '}');
+  for (const rel of pluginAsIs) {
+    const outPath = join(OUT, rel);
+    mkdirSync(dirname(outPath), {recursive: true});
+    cpSync(join(ROOT, rel), outPath);
+  }
+
+  // Copy admin HTML templates verbatim
+  const adminHtml = await collectFiles(ADMIN_HTML_PATTERNS[0]);
+  for (const rel of adminHtml) {
+    const outPath = join(OUT, rel);
+    mkdirSync(dirname(outPath), {recursive: true});
+    cpSync(join(ROOT, rel), outPath);
+  }
+
+  // Copy Domma tools assets (gitignored but tracked for distribution)
+  const dommaTools = [
+    'admin/dist/domma/domma-tools.css',
+    'admin/dist/domma/domma-tools.min.js',
+  ];
+  for (const rel of dommaTools) {
+    const src = join(ROOT, rel);
+    if (existsSync(src)) {
+      const outPath = join(OUT, rel);
+      mkdirSync(dirname(outPath), {recursive: true});
+      cpSync(src, outPath);
+    }
+  }
+
+  // Minify browser-facing JS and CSS
+  let jsCount = 0;
+  let cssCount = 0;
+
+  // Collect all minify targets, deduplicate against plugin as-is
+  const pluginAsIsSet = new Set(pluginAsIs);
+
+  for (const pattern of MINIFY_PATTERNS) {
+    const files = await collectFiles(pattern);
+    for (const rel of files) {
+      if (pluginAsIsSet.has(rel)) continue; // skip plugin server-side JS
+      const loader = rel.endsWith('.css') ? 'css' : 'js';
+      await minifyFile(rel, loader);
+      if (loader === 'js') jsCount++;
+      else cssCount++;
+    }
+  }
+
+  const totalCopied = COPY_AS_IS.filter(i => existsSync(join(ROOT, i))).length
+    + pluginAsIs.length + adminHtml.length;
+
+  await stampPluginVersions();
+
+  console.log(`Built into _publish/ — JS: ${jsCount} minified, CSS: ${cssCount} minified, ${totalCopied} entries copied`);
+
+  // Integrity gate — fail the build (and therefore `make pack` / `make
+  // release-npm`) if the staged set ships any ESM import pointing at a file
+  // that isn't there. This is what stops a "shipped code that imports a missing
+  // file" release (the 0.22.1 menu-decor.mjs incident) from ever publishing.
+  const integrity = await verifyAssetImports({projectRoot: OUT});
+  console.log(formatReport(integrity, '_publish/'));
+  if (!integrity.ok) {
+    throw new Error(`asset integrity check failed — ${integrity.missing.length} dangling import(s); refusing to package a broken release`);
+  }
+}
+
+build().catch(err => {
+  console.error('Build failed:', err.message);
+  process.exit(1);
+});

package/scripts/verify-assets.mjs

@@ -0,0 +1,190 @@
+/**
+ * Asset Import Verifier — build/publish gate
+ *
+ * Statically resolves every local ESM import under the browser-facing code
+ * (admin/ + public/) against the files that actually exist, and fails if any
+ * specifier points at a missing file ("dangling import").
+ *
+ * Why this exists
+ * ---------------
+ * The admin SPA and public site ship UNMINIFIED-then-minified ESM that browsers
+ * import natively (no bundler). If a release ships consumer code that imports a
+ * new module but forgets to include the module file (as 0.22.1 did with
+ * /public/js/menu-decor.mjs), every page 404s on the import and the whole site
+ * breaks — with no signal but a browser console error, and it cascades to every
+ * downstream project that copies these dirs on update. A bundler would catch
+ * this at build time; because we don't bundle, this gate stands in for that.
+ *
+ * Usage
+ * -----
+ *   node scripts/verify-assets.mjs [root]      # default root: repo root
+ * Exits 1 (with a report) on any dangling import, 0 otherwise. Wired into
+ * scripts/build.js so `make pack` / `make release-npm` cannot ship a broken set.
+ *
+ * Scope (deliberately conservative — zero false positives is the whole point):
+ * only STATIC, LOCAL specifiers with an explicit extension are checked — the
+ * only kind this codebase emits. Bare (npm) specifiers, URLs, dynamic/template
+ * specifiers, commented-out imports, and extension-less paths are all ignored.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+const SCAN_EXTS = new Set(['.js', '.mjs']);
+const CHECK_EXTS = new Set(['.js', '.mjs', '.css']);
+
+const FROM_RE = /\bfrom\s*(['"])([^'"]+)\1/g;
+const SIDE_EFFECT_RE = /(?:^|[;{}\s])import\s*(['"])([^'"]+)\1/g;
+const DYNAMIC_RE = /\bimport\s*\(\s*(['"])([^'"]+)\1\s*\)/g;
+
+function isCheckableSpecifier(spec) {
+    if (typeof spec !== 'string' || !spec) return false;
+    if (!(spec.startsWith('/') || spec.startsWith('./') || spec.startsWith('../'))) return false;
+    const clean = spec.replace(/[?#].*$/, '');
+    return CHECK_EXTS.has(path.extname(clean).toLowerCase());
+}
+
+function resolveSpecifier(spec, importer, projectRoot) {
+    const clean = spec.replace(/[?#].*$/, '');
+    if (clean.startsWith('/')) return path.join(projectRoot, clean); // served /public/... → root/public/...
+    return path.resolve(path.dirname(importer), clean);
+}
+
+/**
+ * Strip // and /* *\/ comments while preserving string-literal bodies, so a
+ * commented-out import isn't flagged and a "https://…" URL isn't mistaken for a
+ * comment. Both are false positives, fatal for a publish gate.
+ */
+function stripComments(source) {
+    let out = '';
+    let state = 'code';
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i];
+        const n = source[i + 1];
+        switch (state) {
+            case 'code':
+                if (c === '/' && n === '/') { state = 'line'; i++; }
+                else if (c === '/' && n === '*') { state = 'block'; i++; }
+                else if (c === "'") { state = 'single'; out += c; }
+                else if (c === '"') { state = 'double'; out += c; }
+                else if (c === '`') { state = 'template'; out += c; }
+                else out += c;
+                break;
+            case 'line':
+                if (c === '\n') { state = 'code'; out += c; }
+                break;
+            case 'block':
+                if (c === '*' && n === '/') { state = 'code'; i++; }
+                break;
+            case 'single':
+            case 'double':
+            case 'template': {
+                out += c;
+                const quote = state === 'single' ? "'" : state === 'double' ? '"' : '`';
+                if (c === '\\') { out += source[i + 1] ?? ''; i++; }
+                else if (c === quote) state = 'code';
+                break;
+            }
+        }
+    }
+    return out;
+}
+
+function extractSpecifiers(rawSource) {
+    const source = stripComments(rawSource);
+    const out = new Set();
+    for (const re of [FROM_RE, SIDE_EFFECT_RE, DYNAMIC_RE]) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            if (isCheckableSpecifier(m[2])) out.add(m[2]);
+        }
+    }
+    return out;
+}
+
+async function listScannable(dir) {
+    const result = [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+        return result;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        let isDir = entry.isDirectory();
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            try {
+                const st = await fs.stat(full);
+                isDir = st.isDirectory();
+                isFile = st.isFile();
+            } catch { continue; }
+        }
+        if (isDir) {
+            if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+            result.push(...await listScannable(full));
+        } else if (isFile && SCAN_EXTS.has(path.extname(entry.name).toLowerCase())) {
+            result.push(full);
+        }
+    }
+    return result;
+}
+
+export async function verifyAssetImports({ projectRoot, roots = ['admin', 'public'] }) {
+    const missing = [];
+    let scanned = 0;
+    for (const rel of roots) {
+        const rootAbs = path.join(projectRoot, rel);
+        if (!existsSync(rootAbs)) continue;
+        for (const file of await listScannable(rootAbs)) {
+            scanned++;
+            let source;
+            try { source = await fs.readFile(file, 'utf8'); } catch { continue; }
+            for (const spec of extractSpecifiers(source)) {
+                const resolved = resolveSpecifier(spec, file, projectRoot);
+                if (!existsSync(resolved)) {
+                    missing.push({
+                        importer: path.relative(projectRoot, file),
+                        specifier: spec,
+                        resolved: path.relative(projectRoot, resolved),
+                    });
+                }
+            }
+        }
+    }
+    return { ok: missing.length === 0, scanned, missing };
+}
+
+export function formatReport(result, label) {
+    if (result.ok) {
+        return `[verify-assets] OK — ${result.scanned} files scanned, all local imports resolve (${label}).`;
+    }
+    const lines = [
+        '',
+        '  ╔════════════════════════════════════════════════════════════════╗',
+        '  ║  ASSET INTEGRITY FAILURE — dangling front-end imports detected  ║',
+        '  ╚════════════════════════════════════════════════════════════════╝',
+        `  Context: ${label}`,
+        `  ${result.missing.length} import(s) reference files that do not exist:`,
+        '',
+    ];
+    for (const m of result.missing) {
+        lines.push(`    ✗ ${m.importer}`);
+        lines.push(`        imports "${m.specifier}"  →  missing ${m.resolved}`);
+    }
+    lines.push('');
+    lines.push('  A page that loads one of these modules will 404 and fail to render.');
+    lines.push('  Add the missing file (or remove the import) before building/publishing.');
+    lines.push('');
+    return lines.join('\n');
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const projectRoot = path.resolve(process.argv[2] || process.cwd());
+    const result = await verifyAssetImports({ projectRoot });
+    console.log(formatReport(result, projectRoot));
+    process.exit(result.ok ? 0 : 1);
+}