@universalcms/connect 0.1.0 → 0.13.0

package/dist/vite-source-discovery.mjs

@@ -0,0 +1,315 @@
+/** Conservative Vite route discovery. Parses source; never loads website code. */
+import path from 'node:path';
+import ts from './vendor/typescript.cjs';
+import { SetupError } from './core.mjs';
+import { extractStaticPage } from './source-extract.mjs';
+import { transformSourcePublication } from './source-bindings.mjs';
+
+const privateSegment = /^(?:admin|account|dashboard|profile|auth|login|register|checkout|orders|settings|billing|portal|patient|patients|vault|records)(?:[-.]|$)|(?:^|-)vault$|^(?:medical|health)-records(?:-|$)/i;
+const accessLogic = /\b(?:cookies|headers|useSession|getServerSession|useAuth|useUser|useContext|auth|requireAuth|currentUser|redirect)\s*\(/;
+const customRouter = /\b(?:window|document)\s*\.\s*(?:location|history)\b|\b(?:history|location)\s*\.\s*(?:pathname|pushState|replaceState)\b|\b(?:useRoutes|createBrowserRouter|createHashRouter|RouterProvider|HashRouter)\b/;
+const fail = (reason, ownershipReview = false) => { const error = new SetupError(`Vite source export is missing. Automatic source mapping could not safely determine the public page components: ${reason}. Follow the manual developer mapping guide for this React/Vite website to create .universalcms/source.entries.json and .universalcms/content.routes.json, then rerun setup. No AI is required. No project code was executed and no source mapping was saved.`); if (ownershipReview) error.code = 'VITE_SOURCE_OWNERSHIP_REVIEW'; throw error; };
+const unbox = node => { while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node))) node = node.expression; return node; };
+const open = node => node && ts.isJsxElement(node) ? node.openingElement : node && ts.isJsxSelfClosingElement(node) ? node : null;
+const noAttributes = node => open(node)?.attributes.properties.length === 0;
+const children = node => node && (ts.isJsxElement(node) || ts.isJsxFragment(node)) ? node.children.filter(child => !(ts.isJsxText(child) && !child.text.trim()) && !(ts.isJsxExpression(child) && !child.expression)) : [];
+const plainModule = value => /^src\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+\.(?:jsx|tsx)$/.test(value) && !value.split('/').some(segment => privateSegment.test(segment));
+
+function parse(source, filename) {
+  if (typeof source !== 'string' || Buffer.byteLength(source) > 128 * 1024) fail('a source module is missing or exceeds its inspection budget');
+  const file = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  if (file.parseDiagnostics.length) fail('a source module does not parse');
+  let count = 0;
+  const walk = (node, depth = 0) => { if (++count > 30_000 || depth > 100) fail('the source tree exceeds its inspection budget'); ts.forEachChild(node, child => walk(child, depth + 1)); };
+  walk(file); return file;
+}
+
+function entryModule(html) {
+  // This deliberately accepts ordinary Vite entry documents, not the whole HTML
+  // language. Quoted > characters and ordinary comments cannot invent entries.
+  const allowed = new Set(['html', 'head', 'title', 'meta', 'link', 'body', 'div', 'script']);
+  const scripts = [];
+  let cursor = 0;
+  while (cursor < html.length) {
+    const start = html.indexOf('<', cursor);
+    if (start < 0) break;
+    if (html.startsWith('<!--', start)) {
+      const end = html.indexOf('-->', start + 4);
+      if (end < 0 || html.slice(start + 4, end).includes('--')) fail('index.html has an ambiguous comment');
+      cursor = end + 3; continue;
+    }
+    if (/^<!doctype\s+html\s*>/i.test(html.slice(start))) {
+      cursor = start + /^<!doctype\s+html\s*>/i.exec(html.slice(start))[0].length; continue;
+    }
+    let end = start + 1, quote;
+    for (; end < html.length; end++) {
+      const character = html[end];
+      if (quote) { if (character === quote) quote = undefined; }
+      else if (character === '"' || character === "'") quote = character;
+      else if (character === '>') break;
+      else if (character === '<') fail('index.html has ambiguous markup');
+    }
+    if (end === html.length || quote) fail('index.html has incomplete markup');
+    const token = html.slice(start, end + 1), tag = /^<(\/?)([A-Za-z][A-Za-z0-9-]*)([\s\S]*?)>$/.exec(token);
+    if (!tag || !allowed.has(tag[2].toLowerCase())) fail('index.html uses a custom loader or unsupported inert/foreign markup');
+    const name = tag[2].toLowerCase();
+    if (tag[1]) { if (tag[3].trim()) fail('index.html has an invalid closing tag'); cursor = end + 1; continue; }
+    const attributes = new Map();
+    let remaining = tag[3].replace(/\/\s*$/, '');
+    while (remaining.trim()) {
+      const attribute = /^\s+([A-Za-z_:][A-Za-z0-9_.:-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s'"=<>`]+)))?/.exec(remaining);
+      if (!attribute) fail('index.html has unsupported attributes');
+      const key = attribute[1].toLowerCase(), value = attribute[2] ?? attribute[3] ?? attribute[4] ?? '';
+      // Font URLs commonly contain raw query separators. These passive values
+      // do not choose the executable entry; script attributes stay literal and
+      // entity-like encodings still require a full HTML-parser review.
+      const passiveValue = name === 'link' && ['href', 'title'].includes(key) || name === 'meta' && key === 'content';
+      if (attributes.has(key) || /^on/.test(key) || key === 'xmlns' || key.includes(':') || value.includes('\0') || value.includes('&') && (!passiveValue || /&#|&[A-Za-z][A-Za-z0-9]*;/.test(value))) fail('index.html has executable or ambiguous attributes');
+      attributes.set(key, value); remaining = remaining.slice(attribute[0].length);
+    }
+    cursor = end + 1;
+    if (attributes.has('http-equiv')) fail('index.html has a redirect or custom response policy');
+    if (name === 'title') {
+      const closing = /<\/title\s*>/gi; closing.lastIndex = cursor;
+      const close = closing.exec(html); if (!close) fail('index.html has an incomplete title');
+      cursor = close.index + close[0].length; continue;
+    }
+    if (name !== 'script') continue;
+    const close = /<\/script\s*>/gi; close.lastIndex = cursor;
+    const closing = close.exec(html);
+    if (!closing || html.slice(cursor, closing.index).trim()) fail('index.html has an inline executable loader');
+    if (attributes.get('type') !== 'module' || !/^\/src\/(?:main|index)\.(?:jsx|tsx)$/.test(attributes.get('src') ?? '') || [...attributes.keys()].some(key => !['type', 'src', 'crossorigin'].includes(key))) fail('index.html has an unsupported script loader');
+    scripts.push(attributes.get('src').slice(1)); cursor = closing.index + closing[0].length;
+  }
+  if (scripts.length !== 1) fail('index.html must have one active ordinary module entry');
+  return scripts[0];
+}
+
+function checkModuleStatements(file, mode, mountedImport) {
+  const known = new Set();
+  const inert = expression => {
+    const node = unbox(expression);
+    if (!node) return false;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isNumericLiteral(node) || [ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.NullKeyword].includes(node.kind) || ts.isArrowFunction(node) || ts.isFunctionExpression(node)) return true;
+    if (ts.isIdentifier(node)) return known.has(node.text);
+    if (ts.isPrefixUnaryExpression(node) && [ts.SyntaxKind.MinusToken, ts.SyntaxKind.PlusToken].includes(node.operator)) return ts.isNumericLiteral(node.operand);
+    if (ts.isArrayLiteralExpression(node)) return node.elements.every(inert);
+    if (ts.isObjectLiteralExpression(node)) return node.properties.every(item => ts.isPropertyAssignment(item) && (ts.isIdentifier(item.name) || ts.isStringLiteral(item.name) || ts.isNumericLiteral(item.name)) && inert(item.initializer));
+    return false;
+  };
+  for (const statement of file.statements) {
+    if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+      const specifier = statement.moduleSpecifier.text, clause = statement.importClause;
+      if (clause?.isTypeOnly) continue;
+      if (!clause) {
+        if (/^\.\.?\/(?:[A-Za-z0-9_./-]+)\.css$/.test(specifier)) continue;
+        fail('a source module has an unknown side-effect import');
+      }
+      const builtin = ['react', 'react-dom/client', 'lucide-react', ...(mode === 'page' ? [] : ['react-router-dom', 'react-router'])].includes(specifier);
+      const localPage = (mode === 'router' || mode === 'main' && clause.name?.text === mountedImport) && specifier.startsWith('.') && clause.name && !clause.namedBindings;
+      if (!builtin && !localPage) fail('a source module imports runtime code that needs access review');
+      continue;
+    }
+    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEmptyStatement(statement)) continue;
+    if (ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)) continue;
+    if (mode === 'main' && ts.isExpressionStatement(statement)) continue; // The caller requires precisely one recognized mount.
+    if (ts.isFunctionDeclaration(statement) && mode !== 'main') { if (statement.name) known.add(statement.name.text); continue; }
+    if (ts.isVariableStatement(statement) && statement.declarationList.flags & ts.NodeFlags.Const && mode !== 'main') {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || !inert(declaration.initializer)) fail('a source module executes unresolved initialization code');
+        known.add(declaration.name.text);
+      }
+      continue;
+    }
+    if (ts.isExportAssignment(statement) && mode !== 'main' && inert(statement.expression)) continue;
+    fail('a source module executes guards or other top-level control flow');
+  }
+  if (mode !== 'page') return;
+  const component = defaultComponent(file);
+  if (!component || component.parameters?.length !== 0) fail('automatic pages need a default component without props or parameter initializers');
+  if (!component?.body || !ts.isBlock(component.body)) return;
+  const stateHooks = new Set();
+  for (const statement of file.statements) if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === 'react') {
+    if (statement.importClause?.name) stateHooks.add(`${statement.importClause.name.text}.useState`);
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) for (const item of bindings.elements) if ((item.propertyName?.text ?? item.name.text) === 'useState') stateHooks.add(item.name.text);
+  }
+  for (const statement of component.body.statements) {
+    if (ts.isReturnStatement(statement) || ts.isFunctionDeclaration(statement) || ts.isEmptyStatement(statement)) continue;
+    if (ts.isVariableStatement(statement) && statement.declarationList.flags & ts.NodeFlags.Const) {
+      for (const declaration of statement.declarationList.declarations) {
+        const initializer = unbox(declaration.initializer);
+        const state = initializer && ts.isCallExpression(initializer) && stateHooks.has(initializer.expression.getText(file)) && initializer.arguments.length === 1 && inert(initializer.arguments[0]) && !ts.isIdentifier(unbox(initializer.arguments[0])) && !ts.isArrowFunction(unbox(initializer.arguments[0])) && !ts.isFunctionExpression(unbox(initializer.arguments[0]));
+        if (state ? !ts.isArrayBindingPattern(declaration.name) || declaration.name.elements.some(item => !ts.isBindingElement(item) || !ts.isIdentifier(item.name) || item.initializer || item.dotDotDotToken) : !ts.isIdentifier(declaration.name) || !inert(initializer)) fail('a page executes unresolved initialization or access code');
+        if (ts.isIdentifier(declaration.name)) known.add(declaration.name.text);
+      }
+      continue;
+    }
+    fail('a page executes unresolved runtime control flow');
+  }
+}
+
+function checkViteConfiguration(source, filename) {
+  const file = parse(source, filename), definitions = new Set(), reactPlugins = new Set();
+  let exported;
+  for (const statement of file.statements) {
+    if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+      const specifier = statement.moduleSpecifier.text, clause = statement.importClause;
+      if (clause?.isTypeOnly) continue;
+      if (specifier === 'vite' && clause?.namedBindings && ts.isNamedImports(clause.namedBindings) && clause.namedBindings.elements.every(item => (item.propertyName?.text ?? item.name.text) === 'defineConfig')) {
+        for (const item of clause.namedBindings.elements) definitions.add(item.name.text);
+      } else if (['@vitejs/plugin-react', '@vitejs/plugin-react-swc'].includes(specifier) && clause?.name && !clause.namedBindings) reactPlugins.add(clause.name.text);
+      else fail('automatic discovery cannot review a custom Vite plugin or config import');
+    } else if (ts.isExportAssignment(statement) && !exported) exported = unbox(statement.expression);
+    else fail('automatic discovery cannot review executable Vite configuration');
+  }
+  if (exported && ts.isCallExpression(exported) && ts.isIdentifier(exported.expression) && definitions.has(exported.expression.text) && exported.arguments.length === 1) exported = unbox(exported.arguments[0]);
+  if (!exported || !ts.isObjectLiteralExpression(exported)) fail('automatic discovery requires a literal Vite configuration');
+  for (const property of exported.properties) {
+    if (!ts.isPropertyAssignment(property) || !(ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))) fail('automatic discovery cannot review computed Vite configuration');
+    const key = property.name.text, value = unbox(property.initializer);
+    if (key === 'plugins') {
+      if (!ts.isArrayLiteralExpression(value) || value.elements.some(element => !ts.isCallExpression(element) || !ts.isIdentifier(element.expression) || !reactPlugins.has(element.expression.text) || element.arguments.length !== 0)) fail('automatic discovery needs ordinary official React plugins; custom Vite middleware requires a reviewed mapping');
+    } else if (['server', 'preview'].includes(key)) {
+      if (!ts.isObjectLiteralExpression(value) || value.properties.some(item => !ts.isPropertyAssignment(item) || !['host', 'port', 'strictPort', 'open'].includes(item.name?.text) || ![ts.SyntaxKind.StringLiteral, ts.SyntaxKind.NumericLiteral, ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(item.initializer.kind))) fail('automatic discovery cannot review custom Vite server behavior');
+    } else fail('automatic discovery cannot review custom Vite configuration fields');
+  }
+}
+
+function imports(file) {
+  const defaults = new Map(), routers = new Map(), strict = new Set(), roots = new Set();
+  for (const statement of file.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.importClause?.isTypeOnly) continue;
+    const specifier = statement.moduleSpecifier.text, clause = statement.importClause;
+    if (clause?.name) {
+      if (specifier.startsWith('.')) defaults.set(clause.name.text, specifier);
+      if (specifier === 'react') strict.add(`${clause.name.text}.StrictMode`);
+      if (specifier === 'react-dom/client') roots.add(`${clause.name.text}.createRoot`);
+    }
+    if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings)) for (const item of clause.namedBindings.elements) {
+      if (item.isTypeOnly) continue;
+      const imported = item.propertyName?.text ?? item.name.text;
+      if (['react-router-dom', 'react-router'].includes(specifier) && ['BrowserRouter', 'Routes', 'Route'].includes(imported)) routers.set(item.name.text, imported);
+      if (specifier === 'react' && imported === 'StrictMode') strict.add(item.name.text);
+      if (specifier === 'react-dom/client' && imported === 'createRoot') roots.add(item.name.text);
+    }
+  }
+  return { defaults, routers, strict, roots };
+}
+
+function defaultComponent(file) {
+  let component;
+  for (const statement of file.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) component = statement;
+    if (ts.isExportAssignment(statement)) {
+      const value = unbox(statement.expression);
+      if (ts.isArrowFunction(value) || ts.isFunctionExpression(value)) component = value;
+      else if (ts.isIdentifier(value)) {
+        component = file.statements.find(item => ts.isFunctionDeclaration(item) && item.name?.text === value.text);
+        for (const item of file.statements) if (ts.isVariableStatement(item)) for (const declaration of item.declarationList.declarations) {
+          if (ts.isIdentifier(declaration.name) && declaration.name.text === value.text) component = unbox(declaration.initializer);
+        }
+      }
+    }
+  }
+  return component;
+}
+
+function returnedDefault(file) {
+  const component = defaultComponent(file);
+  if (!component || !(ts.isFunctionDeclaration(component) || ts.isArrowFunction(component) || ts.isFunctionExpression(component)) || component.parameters.length || !component.body) fail('the router needs a default component without route props');
+  if (!ts.isBlock(component.body)) return unbox(component.body);
+  if (component.body.statements.length !== 1 || !ts.isReturnStatement(component.body.statements[0])) fail('the router contains runtime control flow');
+  return unbox(component.body.statements[0].expression);
+}
+
+/** readFile is the source planner's bounded, symlink-safe read callback. */
+export async function discoverViteSource(root, { locale = 'en', readFile }) {
+  let bytes = 0;
+  const read = async filename => {
+    const source = await readFile(filename);
+    if (source !== null && (bytes += Buffer.byteLength(source)) > 8 * 1024 * 1024) fail('the source inventory exceeds its inspection budget');
+    return source;
+  };
+  const resolveModule = async (from, specifier) => {
+    if (typeof specifier !== 'string' || !specifier.startsWith('.') || specifier.includes('\\') || /[?#]/.test(specifier)) fail('a page uses a nonlocal or dynamic module');
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(from), specifier));
+    const candidates = /\.(?:jsx|tsx)$/.test(base) ? [base] : path.posix.extname(base) ? [] : [`${base}.jsx`, `${base}.tsx`, `${base}/index.jsx`, `${base}/index.tsx`];
+    if (!candidates.length || candidates.some(filename => !plainModule(filename))) fail('a page module is outside the ordinary public src directory');
+    const found = [];
+    for (const filename of candidates) { const source = await read(filename); if (source !== null) found.push({ filename, source }); }
+    if (found.length !== 1) fail('a page import is missing or ambiguous');
+    return found[0];
+  };
+
+  for (const extension of ['js', 'mjs', 'cjs', 'ts', 'mts', 'cts']) {
+    const filename = `vite.config.${extension}`, source = await read(filename);
+    if (source !== null) checkViteConfiguration(source, filename);
+  }
+
+  // Verify the mounted entry. Merely finding an unused App.jsx is not evidence
+  // that it owns /, or that an authentication wrapper is absent.
+  const index = await read('index.html');
+  if (index === null) fail('the conventional index.html entry is missing');
+  const mainFile = entryModule(index), mainSource = await read(mainFile), main = parse(mainSource, mainFile), mainImports = imports(main);
+  if (accessLogic.test(mainSource) || customRouter.test(mainSource)) fail('the entry requires access or custom-router review', true);
+  const renders = main.statements.filter(ts.isExpressionStatement).map(statement => unbox(statement.expression)).filter(node => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'render');
+  if (renders.length !== 1 || renders[0].arguments.length !== 1) fail('the entry must mount one static React root');
+  if (main.statements.filter(statement => ts.isExpressionStatement(statement) && !ts.isStringLiteral(statement.expression)).length !== 1) fail('the entry executes runtime code outside its React mount');
+  const render = renders[0], create = unbox(render.expression.expression);
+  if (!ts.isCallExpression(create) || !mainImports.roots.has(create.expression.getText(main))) fail('the React root is not a direct createRoot mount');
+  const target = unbox(create.arguments[0]);
+  if (create.arguments.length !== 1 || !target || !ts.isCallExpression(target) || target.expression.getText(main) !== 'document.getElementById' || target.arguments.length !== 1 || !ts.isStringLiteral(target.arguments[0])) fail('the React root uses a custom mount expression');
+  let mounted = unbox(render.arguments[0]);
+  while (open(mounted) && (mainImports.strict.has(open(mounted).tagName.getText(main)) || mainImports.routers.get(open(mounted).tagName.getText(main)) === 'BrowserRouter')) {
+    const nested = children(mounted); if (!noAttributes(mounted) || nested.length !== 1) fail('the React root has an unsupported wrapper'); mounted = nested[0];
+  }
+  if (!open(mounted) || !noAttributes(mounted) || children(mounted).length || !mainImports.defaults.has(open(mounted).tagName.getText(main))) fail('the mounted app is guarded, parameterized or ambiguous');
+  checkModuleStatements(main, 'main', open(mounted).tagName.getText(main));
+  const app = await resolveModule(mainFile, mainImports.defaults.get(open(mounted).tagName.getText(main)));
+  if (accessLogic.test(app.source) || customRouter.test(app.source)) fail('the app uses access controls or a custom history/location router', true);
+  const appAst = parse(app.source, app.filename), appImports = imports(appAst);
+  const usesRouter = [...appImports.routers.values()].some(value => value === 'Routes' || value === 'Route');
+  checkModuleStatements(appAst, usesRouter ? 'router' : 'page');
+  const mappings = [], entries = [];
+  const addPage = (pathname, page) => {
+    if (!/^\/(?:[a-z0-9]+(?:[-/][a-z0-9]+)*)?$/.test(pathname) || pathname === '/home') fail('a public URL is dynamic, ambiguous or unsupported');
+    if (mappings.some(row => row.path === pathname || row.sourceFile === page.filename)) fail('public URLs must have distinct page modules and identities');
+    if (accessLogic.test(page.source) || customRouter.test(page.source)) fail('a page requires access or custom-router review', true);
+    checkModuleStatements(parse(page.source, page.filename), 'page');
+    const slug = pathname.slice(1) || 'home';
+    const extracted = extractStaticPage({ source: page.source, slug, locale, filename: page.filename });
+    if (!extracted.entry || !extracted.complete) fail('a page contains unresolved components, data or conditional content');
+    // Export only pages that can also be bound to publications without guessing
+    // props, row identities or partial native content.
+    try { transformSourcePublication({ source: page.source, slug, locale, filename: page.filename, allowNamedExports: true }); }
+    catch { fail('a public page needs an explicit content binding'); }
+    mappings.push({ path: pathname, sourceFile: page.filename }); entries.push(extracted.entry);
+    if (mappings.length > 1000) fail('the public route inventory exceeds its inspection budget');
+  };
+  if (!usesRouter) addPage('/', app);
+  else {
+    const routes = [];
+    let returned = returnedDefault(appAst);
+    if (!returned) fail('the router has no returned route tree');
+    while (ts.isJsxFragment(returned) || open(returned) && appImports.routers.get(open(returned).tagName.getText(appAst)) === 'BrowserRouter') {
+      const nested = children(returned); if (open(returned) && !noAttributes(returned) || nested.length !== 1) fail('the router has an unsupported layout or wrapper'); returned = nested[0];
+    }
+    if (!open(returned) || appImports.routers.get(open(returned).tagName.getText(appAst)) !== 'Routes' || !noAttributes(returned)) fail('only a flat static Routes tree can be mapped automatically');
+    for (const route of children(returned)) {
+      if (!open(route) || appImports.routers.get(open(route).tagName.getText(appAst)) !== 'Route' || children(route).length) fail('nested, conditional or guarded routes need an explicit mapping');
+      const attributes = open(route).attributes.properties;
+      if (attributes.some(attribute => !ts.isJsxAttribute(attribute) || !['path', 'element'].includes(attribute.name.getText(appAst))) || attributes.length !== 2) fail('routes need literal path and direct element attributes');
+      const pathname = attributes.find(attribute => attribute.name.getText(appAst) === 'path')?.initializer;
+      if (!pathname || !ts.isStringLiteral(pathname)) fail('route paths must be literal strings');
+      if (pathname.text === '*' || pathname.text.split('/').some(segment => privateSegment.test(segment))) continue;
+      const element = attributes.find(attribute => attribute.name.getText(appAst) === 'element')?.initializer;
+      const pageNode = element && ts.isJsxExpression(element) ? unbox(element.expression) : null;
+      if (!pageNode || !open(pageNode) || !noAttributes(pageNode) || children(pageNode).length || !appImports.defaults.has(open(pageNode).tagName.getText(appAst))) fail('route elements must be local default-imported pages without props or guards');
+      routes.push({ pathname: pathname.text, specifier: appImports.defaults.get(open(pageNode).tagName.getText(appAst)) });
+    }
+    if (!routes.length || routes.length > 1000) fail('there are no bounded public page routes');
+    for (const route of routes) addPage(route.pathname, await resolveModule(app.filename, route.specifier));
+  }
+  return { manifest: { version: 1, entries }, mappings, diagnostics: { automaticPages: entries.length, discovery: usesRouter ? 'react-router' : 'single-page' } };
+}

package/dist/vite-source.d.mts

@@ -0,0 +1,30 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+export type PublicSourceConfiguration = {
+  version: 1;
+  siteId: string;
+  environmentId: string;
+  websiteOrigin: string;
+  adminOrigin: string;
+  locale?: string;
+  publicStaticPages: true;
+  /** Close the initial public source export after migration. */
+  exportClosed?: true;
+  /** Must be empty: apply exclusions directly to the reviewed manifest. */
+  skipSlugs?: string[];
+  /** Must be empty: apply exclusions directly to the reviewed manifest. */
+  excludedRoutes?: string[];
+};
+export const VITE_SOURCE_MANIFEST_FILE: '.universalcms/source.entries.json';
+/** Uses only the fixed, reviewed JSON manifest; never executes website source. */
+export function createViteSourceHandler(options: { sourceRoot: string; configuration: PublicSourceConfiguration }): (request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
+type Middleware = (request: IncomingMessage, response: ServerResponse, next: () => void) => void;
+type ViteSourceServerOptions = { port?: number; strictPort?: boolean };
+/** Development/preview middleware; static production hosts need a server adapter. */
+export function universalCmsSource(options: { configuration: PublicSourceConfiguration }): {
+  name: string;
+  config(config: { server?: ViteSourceServerOptions; preview?: ViteSourceServerOptions }, environment: { command: 'build' | 'serve' }): { server: ViteSourceServerOptions & { port: number; strictPort: true }; preview: ViteSourceServerOptions & { port: number; strictPort: true } } | undefined;
+  configResolved(config: { root: string; command?: 'build' | 'serve'; server?: ViteSourceServerOptions; preview?: ViteSourceServerOptions }): void;
+  configureServer(server: { middlewares: { use(handler: Middleware): unknown } }): void;
+  configurePreviewServer(server: { middlewares: { use(handler: Middleware): unknown } }): void;
+};

package/dist/vite-source.mjs

@@ -0,0 +1,141 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { createSourceManifestProvider } from './vendor/source-manifest-provider.mjs';
+import { validateSourceConfiguration } from './source-config.mjs';
+
+export const VITE_SOURCE_MANIFEST_FILE = '.universalcms/source.entries.json';
+const MAX_BYTES = 20 * 1024 * 1024;
+const stamp = stat => [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs, stat.nlink, stat.mode].join(':');
+
+/** Read one explicitly reviewed public JSON file, never executable website code. */
+async function readManifest(sourceRoot, locale) {
+  const requested = path.resolve(sourceRoot), rootStat = await lstat(requested);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw Error('Invalid source root');
+  const root = await realpath(requested);
+  let target = root;
+  const parts = VITE_SOURCE_MANIFEST_FILE.split('/');
+  let found;
+  for (const [index, part] of parts.entries()) {
+    target = path.join(target, part);
+    const stat = await lstat(target);
+    if (stat.isSymbolicLink() || await realpath(target) !== target || (index === parts.length - 1 ? !stat.isFile() || stat.nlink !== 1 : !stat.isDirectory())) throw Error('Invalid source file');
+    found = stat;
+  }
+  if (found.size > MAX_BYTES) throw Error('Source budget');
+  const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const before = await file.stat();
+    if (stamp(before) !== stamp(found)) throw Error('Source changed');
+    const buffer = Buffer.alloc(MAX_BYTES + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const result = await file.read(buffer, size, buffer.length - size, size);
+      if (!result.bytesRead) break;
+      size += result.bytesRead;
+    }
+    if (size > MAX_BYTES || stamp(await file.stat()) !== stamp(before) || stamp(await lstat(target)) !== stamp(before)) throw Error('Source changed or exceeded budget');
+    const json = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size));
+    const manifest = JSON.parse(json);
+    if (!manifest || !Array.isArray(manifest.entries) || manifest.entries.length === 0) throw Error('No reviewed public content');
+    if (manifest.entries.some(entry => typeof entry?.locale !== 'string' || entry.locale.length > 35 || Intl.getCanonicalLocales(entry.locale)[0] !== locale)) throw Error('Source locale does not match reviewed configuration');
+    return json;
+  } finally { await file.close(); }
+}
+
+function validateViteConfiguration(value) {
+  const config = validateSourceConfiguration(value);
+  if (config.skipSlugs.length || config.excludedRoutes.length) throw Error('Apply source exclusions in the reviewed Vite manifest before enabling its export');
+  return config;
+}
+
+function capture(provider, request) {
+  const result = { handled: false, status: 404, headers: {}, body: undefined };
+  result.handled = provider(request, {
+    writeHead(status, headers) { result.status = status; result.headers = headers; },
+    end(body) { result.body = body; },
+  });
+  return result;
+}
+
+/**
+ * Node middleware for a reviewed source manifest. Returns false for other URLs.
+ * Deploy this handler with the reviewed file when serving outside Vite; a static
+ * hosting/CDN deployment cannot provide the required scoped server endpoint.
+ */
+export function createViteSourceHandler({ sourceRoot, configuration }) {
+  const config = validateViteConfiguration(configuration);
+  const binding = { siteId: config.siteId, environmentId: config.environmentId, sourceOrigin: config.websiteOrigin, adminOrigin: config.adminOrigin, publicContent: true };
+  const probe = createSourceManifestProvider({ ...binding, manifestJson: '{"version":1,"entries":[]}' });
+  let pending;
+  return async function handle(request, response) {
+    // The provider's origin, host, credential and scope checks run before disk I/O.
+    const gate = capture(probe, request);
+    if (!gate.handled) return false;
+    const send = result => {
+      if (response.destroyed || response.writableEnded) return;
+      response.writeHead(result.status, result.headers);
+      response.end(result.body);
+    };
+    if (gate.status !== 200 || !['GET', 'HEAD'].includes(request.method)) { send(gate); return true; }
+    if (config.exportClosed) {
+      const body = JSON.stringify({ version: 1, siteId: config.siteId, environmentId: config.environmentId, sourceExport: 'closed' });
+      send({ status: 410, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', 'Access-Control-Allow-Origin': config.adminOrigin, Vary: 'Origin', 'X-Content-Type-Options': 'nosniff' }, body: request.method === 'HEAD' ? undefined : body });
+      return true;
+    }
+    try {
+      // Coalesce in-flight reads only; a completed check never caches old content.
+      pending ??= readManifest(sourceRoot, config.locale).then(manifestJson => createSourceManifestProvider({ ...binding, manifestJson })).finally(() => { pending = undefined; });
+      const provider = await pending;
+      send(capture(provider, request));
+    } catch {
+      const body = JSON.stringify({ error: 'Website source setup is incomplete. Add a non-empty reviewed public source manifest at .universalcms/source.entries.json, then check again.' });
+      send({ status: 503, headers: {
+        'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store',
+        'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer',
+        'Access-Control-Allow-Origin': config.adminOrigin, Vary: 'Origin', 'Content-Length': Buffer.byteLength(body),
+      }, body: request.method === 'HEAD' ? undefined : body });
+    }
+    return true;
+  };
+}
+
+/** Install before Vite's SPA fallback during normal development and local preview. */
+export function universalCmsSource({ configuration }) {
+  const config = validateViteConfiguration(configuration);
+  const origin = new URL(config.websiteOrigin);
+  const localPort = origin.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(origin.hostname) ? Number(origin.port || 80) : null;
+  const portError = () => { throw Error(`Universal CMS source export requires the registered website port ${localPort} with strictPort enabled. Remove conflicting Vite port overrides or update the reviewed website origin.`); };
+  let sourceRoot;
+  function install(server) {
+    if (!sourceRoot) throw Error('Universal CMS source plugin requires the resolved website root');
+    const handle = createViteSourceHandler({ sourceRoot, configuration: config });
+    server.middlewares.use((request, response, next) => {
+      void handle(request, response).then(handled => { if (!handled) next(); }, () => {
+        if (!response.destroyed && !response.writableEnded) {
+          response.writeHead(503, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+          response.end(JSON.stringify({ error: 'Website source setup is incomplete.' }));
+        }
+      });
+    });
+  }
+  return {
+    name: 'universalcms-public-source',
+    config(value, environment) {
+      if (localPort === null) return;
+      // Source reads bind the exact registered Host. Do not silently switch to
+      // another development port or Vite preview's separate default port.
+      if (environment.command === 'serve' && [value.server?.port, value.preview?.port].some(port => port !== undefined && port !== localPort)) portError();
+      return {
+        server: { ...value.server, port: localPort, strictPort: true },
+        preview: { ...value.preview, port: localPort, strictPort: true },
+      };
+    },
+    configResolved(resolved) {
+      if (localPort !== null && resolved.command === 'serve' && [resolved.server, resolved.preview].some(server => server?.port !== localPort || server?.strictPort !== true)) portError();
+      sourceRoot = resolved.root;
+    },
+    configureServer: install,
+    configurePreviewServer: install,
+  };
+}

package/dist/vue-runtime.d.mts

@@ -0,0 +1,10 @@
+import type { PublicationConfiguration } from './publication.mjs';
+import type { NativeWebsitePayload } from './native-website-model.mjs';
+export type VuePublicPayload = NativeWebsitePayload & { bindings: Record<string, { id: string; version: number; type: string; text: string; data?: Record<string, unknown>; url?: string; alt?: string }> };
+export type VueRuntimeOptions = { configuration?: PublicationConfiguration; sourceConfiguration: unknown; contentBindings?: unknown; snapshot: unknown; sourceRoot: string; env?: Record<string,string|undefined> | (()=>Record<string,string|undefined>|Promise<Record<string,string|undefined>>); fetcher?: typeof fetch };
+export type VuePrepared = { pass: true; payload: VuePublicPayload | null; context: unknown; headers: Record<string,string> } | { pass: false; response: Response };
+export function vuePublicPayload(context: unknown): VuePublicPayload | null;
+export function serializeVuePayload(payload: unknown): string;
+export function createVueRuntime(options: VueRuntimeOptions): { handle(request: Request,render: (payload: VuePublicPayload | null)=>Promise<Response>): Promise<Response>; prepare(request: Request): Promise<VuePrepared> };
+export function renderVueWebsite(payload: VuePublicPayload | null,nativeHtml?: string): string;
+export function finishNuxtHtml(html: string,prepared: VuePrepared): string;

package/dist/vue-runtime.mjs

@@ -0,0 +1,50 @@
+/** Native Vue/Nuxt server boundary. No delivery credentials enter hydration. */
+import { createAstroRuntime, astroBound } from './astro-runtime.mjs';
+import { renderNativeWebsite } from './native-website-server.mjs';
+import { websiteHtml } from './website-http.mjs';
+import { PUBLICATION_SCRIPT_PATH } from './publication-browser.mjs';
+
+export function vuePublicPayload(context) {
+  if (!context) return null;
+  const bindings = {};
+  for (const block of context.inventory?.baseline.blocks ?? []) {
+    const current = astroBound(context, block.id, block.type);
+    if (current) bindings[block.id] = current;
+  }
+  return { pathname: context.pathname, scope: context.scope, initialResult: context.result, initialSettings: context.settings, ...(context.publicInventory ? { inventory: context.publicInventory } : {}), bindings };
+}
+export function serializeVuePayload(payload) { return JSON.stringify(payload).replace(/[<>&\u2028\u2029]/g,char=>'\\u'+char.charCodeAt(0).toString(16).padStart(4,'0')); }
+
+export function createVueRuntime(options) {
+  const runtime=createAstroRuntime(options);
+  return {
+    async handle(request, render) {
+      const context={request,locals:{}};
+      return runtime.onRequest(context, async()=>render(vuePublicPayload(context.locals.universalcms)));
+    },
+    /** Nitro middleware cannot await the framework renderer; resolve the same
+     * gate first, retaining private metadata only on this server request. */
+    async prepare(request) {
+      const context={request,locals:{}};let passed=false;
+      const response=await runtime.onRequest(context,async()=>{passed=true;return new Response('<html><head></head><body></body></html>',{headers:{'Content-Type':'text/html; charset=utf-8'}});});
+      return passed&&response.status===200?{pass:true,payload:vuePublicPayload(context.locals.universalcms),context:context.locals.universalcms,headers:Object.fromEntries(response.headers)}:{pass:false,response};
+    },
+  };
+}
+export function renderVueWebsite(payload, nativeHtml='') {
+  if(!payload)return `<div id="app">${nativeHtml}</div>`;
+  return renderNativeWebsite(payload,payload.inventory?`<div id="universalcms-native">${nativeHtml}</div>`:'');
+}
+export function finishNuxtHtml(html, prepared) {
+  if(!prepared?.payload)return html;
+  if(typeof html!=='string'||Buffer.byteLength(html)>8*1024*1024)throw Error('Nuxt rendering unavailable.');
+  const open='<universalcms-website data-universalcms-native>',close='</universalcms-website>';
+  const start=html.indexOf(open),end=html.indexOf(close,start);
+  if(start<0||end<start||html.indexOf(open,start+open.length)!==-1||html.indexOf(close,end+close.length)!==-1)throw Error('Nuxt native boundary missing.');
+  const native=html.slice(start+open.length,end);
+  // Nuxt owns its light DOM and hydration markers; do not add a native wrapper.
+  html=html.slice(0,start)+renderNativeWebsite(prepared.payload,prepared.payload.inventory?native:'')+html.slice(end+close.length);
+  const {settings,metadata,inventory}=prepared.context,seo=settings.sections.seo.state==='ready';
+  html=websiteHtml(html,seo||!inventory?metadata:null,{seo,branding:settings.sections.branding.state==='ready'?settings.sections.branding.data:undefined});
+  return html.replace(/<head\b[^>]*>/i,head=>head+`<script src="${PUBLICATION_SCRIPT_PATH}"></script>`);
+}

package/dist/vue-server.d.mts

@@ -0,0 +1,2 @@
+import type { Server } from 'node:http';
+export function startVueWebsite(options: {root: string; production?: boolean; vite?: {version?: string; createServer(options: unknown): Promise<unknown>}}): Promise<Server>;

package/dist/vue-server.mjs

@@ -0,0 +1,58 @@
+/** Official Vue/Vite SSR host. Generated application imports remain website-owned. */
+import { createServer } from 'node:http';
+import { readFile, lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createVueRuntime, renderVueWebsite, serializeVuePayload } from './vue-runtime.mjs';
+const types={'.js':'text/javascript','.css':'text/css','.svg':'image/svg+xml','.png':'image/png','.jpg':'image/jpeg','.webp':'image/webp','.ico':'image/x-icon','.woff2':'font/woff2','.json':'application/json','.txt':'text/plain','.xml':'application/xml','.pdf':'application/pdf'};
+async function asset(root,pathname){
+  if(!pathname.startsWith('/')||/[\\%?#\u0000-\u0020]/.test(pathname)||pathname.split('/').slice(1).some(p=>!p||p==='.'||p==='..'||p.startsWith('.')))return null;
+  const type=types[path.extname(pathname)];if(!type)return null;
+  let target=root;
+  try{for(const part of pathname.slice(1).split('/')){target=path.join(target,part);const stat=await lstat(target);if(stat.isSymbolicLink()||await realpath(target)!==target)return null;}
+    const stat=await lstat(target);if(!stat.isFile()||stat.nlink!==1||stat.size>16*1024*1024)return null;
+    return new Response(await readFile(target),{headers:{'Content-Type':type,'Cache-Control':'no-cache'}});
+  }catch(error){if(['ENOENT','ENOTDIR'].includes(error.code))return null;throw error;}
+}
+export async function startVueWebsite({root,production=false,vite}){
+  root=await realpath(root);
+  const read=async name=>JSON.parse(await readFile(path.join(root,'.universalcms',name),'utf8'));
+  const sourceConfiguration=await read('source.config.json'),snapshot=await read('source.generated.json');
+  let configuration,contentBindings;try{configuration=await read('publication.config.json');contentBindings=await read('content.bindings.json');}catch(error){if(error.code!=='ENOENT')throw error;}
+  const runtime=createVueRuntime({configuration,contentBindings,sourceConfiguration,snapshot,sourceRoot:root});
+  const origin=new URL(sourceConfiguration.websiteOrigin),port=Number(process.env.PORT??(origin.port||(origin.protocol==='https:'?443:80)));
+  if(!Number.isInteger(port)||port<1||port>65535)throw Error('Invalid website port.');
+  let dev=null;
+  const built=production?await import(pathToFileURL(path.join(root,'.universalcms/dist/server/vue.entry-server.mjs')).href):null;
+  const server=createServer({requestTimeout:15000,headersTimeout:10000,maxHeaderSize:8192},async(req,res)=>{
+    try{
+      if(!req.url?.startsWith('/')||req.url.startsWith('//')||/[\\\s#]/.test(req.url)||req.headers.host!==origin.host||req.url.split('?')[0].split('/').some(part=>part==='.'||part==='..')||/%(?:2e|2f|5c|25)/i.test(req.url.split('?')[0])){res.writeHead(403,{'Cache-Control':'no-store'});res.end();return;}
+      const pathname=req.url.split('?')[0];
+      if(pathname.includes('/.universalcms/')&&!['/.universalcms/vue.app.mjs','/.universalcms/vue.client.mjs'].includes(pathname)){res.writeHead(404,{'Cache-Control':'no-store'});res.end();return;}
+      const request=new Request(new URL(req.url,origin),{method:req.method,headers:new Headers(Object.entries(req.headers).flatMap(([k,v])=>v===undefined?[]:[[k,Array.isArray(v)?v.join(', '):v]]))});
+      let delegated=false;
+      const response=await runtime.handle(request,async payload=>{
+        if(!payload&&new URL(request.url).pathname!=='/'){
+          if(dev){delegated=true;dev.middlewares(req,res,()=>{if(!res.writableEnded){res.writeHead(404);res.end();}});return new Response(null,{status:204});}
+          return await asset(path.join(root,'.universalcms/dist/client'),new URL(request.url).pathname)??new Response(null,{status:404});
+        }
+        let template=await readFile(path.join(root,production?'.universalcms/dist/client/.universalcms/vue.index.html':'.universalcms/vue.index.html'),'utf8');
+        if(dev)template=await dev.transformIndexHtml(request.url,template);
+        const render=dev?(await dev.ssrLoadModule('/.universalcms/vue.entry-server.mjs')).render:built.render;
+        const native=payload&&!payload.inventory?'':await render(payload);
+        const markup=renderVueWebsite(payload,native);
+        const body=template.replace('<!--universalcms-app-->',markup).replace('<!--universalcms-state-->',`<script type="application/json" id="universalcms-vue-state">${serializeVuePayload(payload)}</script>`);
+        return new Response(body,{headers:{'Content-Type':'text/html; charset=utf-8'}});
+      });
+      if(delegated)return;
+      res.writeHead(response.status,Object.fromEntries(response.headers));res.end(req.method==='HEAD'?undefined:Buffer.from(await response.arrayBuffer()));
+    }catch{if(!res.headersSent)res.writeHead(503,{'Cache-Control':'no-store','Content-Type':'text/plain'});res.end('Website temporarily unavailable.');}
+  });
+  // Attach Vite's websocket to this website's port; the default standalone HMR
+  // port collides when several connected websites are developed together.
+  if(!production){
+    const websocket=Number(vite.version?.split('.')[0])>=8?{ws:{server}}:{hmr:{server}};
+    dev=await vite.createServer({root,configFile:path.join(root,'.universalcms/vue.config.mjs'),server:{middlewareMode:true,...websocket},appType:'custom'});
+  }
+  server.on('close',()=>{void dev?.close();});server.listen(port,'0.0.0.0');return server;
+}