@universalcms/connect 0.1.0 → 0.13.1

package/dist/staged-setup.mjs

@@ -0,0 +1,287 @@
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { applyPlan, CONFIG_FILE, planSetup, projectRoot, readProjectFile, SetupError, validateConfig, validatePlan } from './core.mjs';
+import { applyEnvironment, assertDeliveryKeyValid, assertEnvironmentBinding, planEnvironment, readSetupEnvironment, validateEnvironmentPlan } from './setup-environment.mjs';
+import { readSourceSettings } from './source-setup.mjs';
+import { planInstalledPublication, readPublicationConfiguration } from './publication-setup.mjs';
+import { assertRuntimeDependencies } from './runtime-dependencies.mjs';
+import { assertConnectorRuntime } from './connector-runtime.mjs';
+import { inspectSetupFramework } from './framework.mjs';
+
+export const CONNECTION_FILE = '.universalcms/connection.json';
+const fields = ['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'];
+const authority = ['apiOrigin', 'siteId', 'environmentId', 'locale'];
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const key = /^cms_server\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.[A-Za-z0-9_-]{43}$/;
+const json = value => `${JSON.stringify(value, null, 2)}\n`;
+const fail = message => { throw new SetupError(message); };
+function origin(value) {
+  try {
+    if (typeof value !== 'string' || value.length > 2048 || /[\s\\]|cms_server\.|sk-[A-Za-z0-9_-]{12,}|AIza[A-Za-z0-9_-]{20,}/i.test(value)) return null;
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/' || !(url.protocol === 'https:' || url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) return null;
+    return url.origin;
+  } catch { return null; }
+}
+function locale(value) { try { return typeof value === 'string' && value.length <= 35 ? Intl.getCanonicalLocales(value)[0] : null; } catch { return null; } }
+const validators = {
+  apiOrigin: origin, siteId: value => typeof value === 'string' && uuid.test(value) && value.toLowerCase(),
+  environmentId: value => typeof value === 'string' && uuid.test(value) && value.toLowerCase(),
+  locale, websiteOrigin: origin, adminOrigin: origin,
+};
+function connectionMismatch(root, savedFile, saved, requested, names = fields) {
+  const labels = { apiOrigin: 'CMS API origin', siteId: 'Website ID', environmentId: 'Environment ID', locale: 'Content locale', websiteOrigin: 'Website origin', adminOrigin: 'CMS admin origin' };
+  // Only independently validated public values reach the diagnostic. Never
+  // include raw config, private environment values, credentials or URLs with
+  // userinfo/query strings, even when a malformed file caused the mismatch.
+  const values = names.map(name => [name, validators[name](saved[name]), validators[name](requested[name])]);
+  if (values.some(([, before, after]) => !before || !after)) fail('This website folder has a different saved connection. Open the matching website project and use its Developer setup commands. Existing settings were preserved.');
+  const describe = index => values.map(value => `  ${labels[value[0]]}: ${value[index]}`).join('\n');
+  fail(`Website connection mismatch. These commands do not match this folder's saved website.\nProject folder: ${JSON.stringify(root)}\nSaved public settings (${savedFile}):\n${describe(1)}\nRequested command:\n${describe(2)}\nOpen the project folder for the requested website and run its setup commands there. If you intended to set up this existing website, copy the commands from its matching website and environment in UniversalWeb.\nThis check preserved existing settings. Changing a key or restarting this folder cannot resolve a website or port mismatch.`);
+}
+export function validateConnection(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || input.version !== 1 || Object.keys(input).some(name => !['version', ...fields].includes(name))) fail('The saved connection must contain only supported public configuration. Credentials are never accepted here.');
+  const result = { version: 1 };
+  for (const name of fields) {
+    const value = validators[name](input[name]);
+    if (!value) fail('Use valid public connection origins, website/environment UUIDs and content locale from Developer setup.');
+    result[name] = value;
+  }
+  return result;
+}
+export async function readConnection(directory) {
+  const root = await projectRoot(directory), content = await readProjectFile(root, CONNECTION_FILE);
+  if (content === null) return null;
+  if ((await lstat(path.join(root, CONNECTION_FILE))).nlink !== 1) fail('The saved connection must be an ordinary file without hard links.');
+  let value;
+  try { value = validateConnection(JSON.parse(content)); }
+  catch { fail('The saved public connection is invalid. Review .universalcms/connection.json before continuing.'); }
+  if (json(value) !== content) fail('The saved public connection was edited. Review .universalcms/connection.json before continuing.');
+  return value;
+}
+export async function assertConnectionMatches(directory, connection) {
+  const root = await projectRoot(directory), value = validateConnection(connection);
+  const configText = await readProjectFile(root, CONFIG_FILE);
+  let config = null;
+  if (configText !== null) {
+    try { config = validateConfig(JSON.parse(configText)); }
+    catch { fail('The generated delivery configuration needs manual review before continuing.'); }
+    if (authority.some(name => config[name] !== value[name])) connectionMismatch(root, CONFIG_FILE, config, value, authority);
+  }
+  const source = await readSourceSettings(root);
+  if (Object.keys(source).length && fields.filter(name => name !== 'apiOrigin').some(name => source[name] !== value[name])) connectionMismatch(root, '.universalcms/source.config.json', source, value, fields.filter(name => name !== 'apiOrigin'));
+  const saved = await assertEnvironmentBinding(root, value);
+  const publication = await readPublicationConfiguration(root);
+  if (publication && (['apiOrigin', 'siteId', 'environmentId', 'websiteOrigin'].some(name => publication[name] !== value[name]) || publication.routes.some(route => route.locale !== value.locale))) fail('Original-route publication configuration differs from this connection. Review it before changing scope or origins.');
+  return { config, configText, source, publication, keyConfigured: saved.keyConfigured };
+}
+export async function assertSavedConnection(directory, connection) {
+  const current = await readConnection(directory);
+  if (!current || json(current) !== json(connection)) fail('The saved connection changed during setup. Review it and run the command again.');
+  return assertConnectionMatches(directory, connection);
+}
+async function validateSavedRuntime(plan) {
+  await validatePlan(plan);
+  // The additive writer permits a missing unchanged file so it can recreate it.
+  // Saving a key does not apply that writer: every reviewed runtime file must
+  // still exist exactly as prepared, including during the confirmation window.
+  for (const file of plan.files) {
+    if (await readProjectFile(plan.root, file.path) !== file.content) fail('The generated delivery integration changed or is incomplete. Run setup or review the files before saving a server key.');
+    if ((await lstat(path.join(plan.root, file.path))).nlink !== 1) fail('The generated delivery integration contains a linked file. Review it before saving a server key.');
+  }
+}
+export async function runConnect(directory, options, io) {
+  const root = await projectRoot(directory);
+  if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).some(name => !fields.includes(name))) fail('Connect accepts public connection fields only. Secrets are not accepted as options.');
+  let manifest;
+  try { manifest = JSON.parse(await readProjectFile(root, 'package.json')); } catch { /* A fixed diagnostic follows. */ }
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) fail('Run connect in the website folder containing a valid package.json.');
+  const previous = await readConnection(root), saved = await readSetupEnvironment(root);
+  const defaults = { ...saved.defaults, ...(previous ?? {}) };
+  const labels = { apiOrigin: 'CMS API origin', siteId: 'Website ID', environmentId: 'Environment ID', locale: 'Content locale', websiteOrigin: 'Website origin', adminOrigin: 'CMS admin origin' };
+  const entered = { version: 1 };
+  for (const name of fields) {
+    const fallback = defaults[name] ?? (name === 'locale' ? 'en' : undefined);
+    if (options[name] !== undefined) {
+      const value = validators[name](options[name]);
+      if (!value) fail('Use valid public connection origins, website/environment UUIDs and content locale from Developer setup.');
+      entered[name] = value;
+      continue;
+    }
+    while (true) {
+      const answer = (await io.ask(`${labels[name]}${fallback ? ` [${fallback}]` : ''}: `)).trim();
+      const value = validators[name](answer || fallback || '');
+      if (value) { entered[name] = value; break; }
+      io.write('Enter the valid public value from Developer setup. Do not enter a credential.\n');
+    }
+  }
+  const connection = validateConnection(entered);
+  if (previous && json(previous) !== json(connection)) connectionMismatch(root, CONNECTION_FILE, previous, connection);
+  await assertConnectionMatches(root, connection);
+  const plan = { root, files: [{ path: CONNECTION_FILE, content: json(connection), state: previous ? 'unchanged' : 'create' }] };
+  io.write(`Website: ${connection.siteId}\nEnvironment: ${connection.environmentId}\nAPI: ${connection.apiOrigin}\nWebsite origin: ${connection.websiteOrigin}\nCMS admin: ${connection.adminOrigin}\nLocale: ${connection.locale}\n`);
+  io.write('Save these public values for the setup command. No server key is requested and no connection has been verified.\n');
+  const answer = (await io.ask('Save this connection? [Y/n] ')).trim().toLowerCase();
+  if (answer && !['y', 'yes'].includes(answer)) { io.write('Connection cancelled. No files changed.\n'); return { saved: false }; }
+  if (previous) await assertSavedConnection(root, previous);
+  else {
+    const current = await readConnection(root);
+    if (current && json(current) !== json(connection)) fail('The saved connection changed while reviewing. No existing file was overwritten.');
+    await assertConnectionMatches(root, connection);
+  }
+  await applyPlan(plan);
+  io.write('Public connection saved. Next run: npx --no-install universalcms-connect setup\n');
+  return { saved: true };
+}
+export async function runServerKey(directory, io, { validateKey = false } = {}) {
+  const root = await projectRoot(directory), connection = await readConnection(root);
+  if (!connection) fail('Run connect, then setup before saving a server key.');
+  const context = await assertConnectionMatches(root, connection);
+  const publicationPlan = await planInstalledPublication(root);
+  if (!context.config && !publicationPlan) fail('No generated delivery configuration is available. Run setup first. Source export alone does not require a delivery key.');
+  const runtimePlan = context.config ? await planSetup(root, { apiOrigin: connection.apiOrigin, siteId: connection.siteId, environmentId: connection.environmentId, locale: connection.locale, framework: context.config.framework, mount: context.config.mount }) : publicationPlan;
+  if (runtimePlan.files.some(file => file.state !== 'unchanged')) fail('The generated delivery integration is incomplete. Run setup before saving a server key, or review custom integration files manually.');
+  await validateSavedRuntime(runtimePlan);
+  if (publicationPlan && publicationPlan !== runtimePlan) await validateSavedRuntime(publicationPlan);
+  const assertPublicationRuntime = async () => {
+    if (!publicationPlan) return;
+    const detected = await inspectSetupFramework(root);
+    await assertConnectorRuntime(root, detected.framework);
+  };
+  await assertPublicationRuntime();
+  if (context.config) await assertRuntimeDependencies(root, context.config.framework, connection.adminOrigin);
+  let apiKey;
+  while (true) {
+    const answer = await io.hidden(context.keyConfigured ? 'Server delivery key (hidden; Enter keeps the saved key): ' : 'Server delivery key (hidden): ');
+    if (!answer && context.keyConfigured) break;
+    if (typeof answer === 'string' && key.test(answer)) { apiKey = answer; break; }
+    io.write('Enter a valid server delivery key from Developer setup. It is not an AI provider key.\n');
+  }
+  if (apiKey && validateKey) {
+    const check = await assertDeliveryKeyValid({
+      apiOrigin: connection.apiOrigin,
+      siteId: connection.siteId,
+      environmentId: connection.environmentId,
+      apiKey,
+      fetcher: io.fetcher,
+    });
+    if (check.valid) {
+      io.write('Server key verified with CMS API.\n');
+    } else if (check.offline) {
+      io.write(`Notice: CMS API is unreachable (${check.error}). Key format is valid, but online authorization could not be confirmed.\n`);
+    }
+  }
+  const options = Object.fromEntries(fields.map(name => [name, connection[name]]));
+  const environment = await planEnvironment(root, { ...options, ...(apiKey ? { apiKey } : {}) });
+  apiKey = undefined;
+  for (const file of environment.files) io.write(`  ${file.action}: ${file.path}\n`);
+  io.write('The server key will be saved only in Git-ignored .env.local with owner-only access. Published delivery remains unverified.\n');
+  const answer = (await io.ask('Save this server key? [Y/n] ')).trim().toLowerCase();
+  if (answer && !['y', 'yes'].includes(answer)) { io.write('Server key cancelled. No files changed.\n'); return { saved: false }; }
+  const current = await assertSavedConnection(root, connection);
+  if (current.configText !== context.configText || json(current.source) !== json(context.source) || json(current.publication) !== json(context.publication)) fail('The delivery or source configuration changed while entering the key. Review it and rerun server-key.');
+  await validateSavedRuntime(runtimePlan);
+  if (publicationPlan && publicationPlan !== runtimePlan) await validateSavedRuntime(publicationPlan);
+  await validateEnvironmentPlan(environment);
+  await assertPublicationRuntime();
+  if (context.config) await assertRuntimeDependencies(root, context.config.framework, connection.adminOrigin);
+  await applyEnvironment(environment);
+  io.write('Server key saved privately. Restart your website, then verify a published page with check and selected configuration access with check-settings. Existing header/footer integration was preserved. Saving a key does not verify delivery or publish content.\n');
+  return { saved: true };
+}
+
+// Explicit key preparation is independent of installing a renderer. It still
+// binds every saved public/private setting before receiving a secret. Keep the
+// normal server-key runtime checks above for the already-installed flow.
+const preparationFiles = ['package.json', CONNECTION_FILE, CONFIG_FILE,
+  '.universalcms/source.config.json', '.universalcms/publication.config.json',
+  '.env.local', '.gitignore', '.env.development', '.env.development.local', '.env.production', '.env.production.local'];
+async function preparationSnapshot(root) {
+  const result = [];
+  for (const filename of preparationFiles) {
+    let before;
+    try { before = await lstat(path.join(root, filename)); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const content = await readProjectFile(root, filename);
+    if (!before) {
+      if (content !== null) fail('Connection settings changed during key preparation. Review them and retry.');
+      result.push([filename, null]);
+      continue;
+    }
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1) fail('Key preparation requires ordinary configuration files without symbolic links or hard links.');
+    const after = await lstat(path.join(root, filename));
+    const metadata = stat => [stat.dev, stat.ino, stat.mode, stat.nlink, stat.size, stat.mtimeMs, stat.ctimeMs];
+    if (JSON.stringify(metadata(before)) !== JSON.stringify(metadata(after))) fail('Connection settings changed during key preparation. Review them and retry.');
+    result.push([filename, content, metadata(after)]);
+  }
+  return JSON.stringify(result);
+}
+
+/** Explicit key-first source flow. Ordinary public source setup never calls this. */
+export async function prepareSourceKeyCheck(directory, options) {
+  const root = await projectRoot(directory), initial = await preparationSnapshot(root);
+  const connection = validateConnection({ version: 1, ...options });
+  const check = async () => {
+    if (await projectRoot(directory) !== root || await preparationSnapshot(root) !== initial) fail('Connection settings changed during source preparation. No source files were saved; review them and retry.');
+    const saved = await readConnection(root);
+    if (saved && json(saved) !== json(connection)) connectionMismatch(root, CONNECTION_FILE, saved, connection);
+    const context = await assertConnectionMatches(root, connection);
+    if (!context.keyConfigured) fail('Save a server delivery key first with server-key --prepare-only and the matching public connection flags, then rerun source setup.');
+  };
+  await check();
+  return check;
+}
+
+export async function runPrepareServerKey(directory, options, io) {
+  const allowed = [...fields, 'validateKey'];
+  if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).some(name => !allowed.includes(name))) fail('Key preparation accepts public connection fields only. Secrets are not accepted as options.');
+  const root = await projectRoot(directory), initial = await preparationSnapshot(root);
+  let manifest;
+  try { manifest = JSON.parse(await readProjectFile(root, 'package.json')); } catch { /* Fixed diagnostic below. */ }
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) fail('Run key preparation in the website folder containing a valid package.json.');
+  const previous = await readConnection(root), saved = await readSetupEnvironment(root), source = await readSourceSettings(root);
+  const explicit = Object.fromEntries(Object.entries(options).filter(([name, value]) => value !== undefined && fields.includes(name)));
+  const connection = validateConnection({ version: 1, locale: 'en', ...saved.defaults, ...Object.fromEntries(fields.filter(name => source[name] !== undefined).map(name => [name, source[name]])), ...(previous ?? {}), ...explicit });
+  if (previous && json(previous) !== json(connection)) connectionMismatch(root, CONNECTION_FILE, previous, connection);
+  const context = await assertConnectionMatches(root, connection);
+  const recheck = async () => {
+    if (await projectRoot(directory) !== root || await preparationSnapshot(root) !== initial) fail('Connection settings changed during key preparation. No server key was saved; review them and retry.');
+    await assertConnectionMatches(root, connection);
+  };
+  await recheck();
+  io.write(`Website: ${connection.siteId}\nEnvironment: ${connection.environmentId}\nAPI: ${connection.apiOrigin}\nWebsite origin: ${connection.websiteOrigin}\nCMS admin: ${connection.adminOrigin}\nLocale: ${connection.locale}\n`);
+  io.write('PREPARE KEY ONLY: Save private delivery settings before website integration. This does not install a renderer, verify the key, import content or publish anything. The public source endpoint never receives this key.\n');
+  let apiKey;
+  while (true) {
+    const answer = await io.hidden(context.keyConfigured ? 'Server delivery key (hidden; Enter keeps the saved key): ' : 'Server delivery key (hidden): ');
+    if (!answer && context.keyConfigured) break;
+    if (typeof answer === 'string' && key.test(answer)) { apiKey = answer; break; }
+    io.write('Enter a valid server delivery key from Developer setup. It is not an AI provider key.\n');
+  }
+  if (apiKey && options.validateKey) {
+    const check = await assertDeliveryKeyValid({
+      apiOrigin: connection.apiOrigin,
+      siteId: connection.siteId,
+      environmentId: connection.environmentId,
+      apiKey,
+      fetcher: io.fetcher,
+    });
+    if (check.valid) {
+      io.write('Server key verified with CMS API.\n');
+    } else if (check.offline) {
+      io.write(`Notice: CMS API is unreachable (${check.error}). Key format is valid, but online authorization could not be confirmed.\n`);
+    }
+  }
+  await recheck();
+  const environment = await planEnvironment(root, { ...Object.fromEntries(fields.map(name => [name, connection[name]])), ...(apiKey ? { apiKey } : {}) });
+  apiKey = undefined;
+  for (const file of environment.files) io.write(`  ${file.action}: ${file.path}\n`);
+  io.write('The server key will be saved only in Git-ignored .env.local with owner-only access. Key authorization and published rendering remain unverified.\n');
+  const answer = (await io.ask('Save this server key? [Y/n] ')).trim().toLowerCase();
+  if (answer && !['y', 'yes'].includes(answer)) { io.write('Server key cancelled. No files changed.\n'); return { saved: false }; }
+  await recheck();
+  await validateEnvironmentPlan(environment);
+  await applyEnvironment(environment);
+  io.write('Server key saved privately. Existing website integration files were preserved. Saving a key does not install missing endpoints, content bindings or header/footer integration. If integration is incomplete, resolve the scoped preflight blockers first. For a custom adapter, follow its reviewed installation and validation steps; do not rerun generic setup over custom files. After the complete adapter is installed, restart or deploy the website to load the adapter and key. Then run npx --no-install universalcms-connect check-publication and npx --no-install universalcms-connect check-settings with the matching public scope from Developer setup, and verify the actual pages. Key authorization and published rendering remain unverified; no content was published.\n');
+  return { saved: true };
+}

package/dist/static-runtime.mjs

@@ -0,0 +1,67 @@
+import { createServer } from 'node:http';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createAstroRuntime, astroBound } from './astro-runtime.mjs';
+import { renderNativeWebsite } from './native-website-server.mjs';
+const escape=value=>String(value??'').replace(/[&<>"']/g,char=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[char]));
+export function renderStaticPage(context,snapshot){
+  const payload={pathname:context.pathname,scope:context.scope,initialResult:context.result,initialSettings:context.settings,...(context.publicInventory?{inventory:context.publicInventory}:{})};
+  const template=snapshot.templates?.[context.pathname];
+  if(!template)return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head><body>${renderNativeWebsite(payload)}<script type="module" src="/.well-known/universalcms-native.mjs"></script></body></html>`;
+  let html=template.body;
+  for(const slot of template.slots){
+    const block=astroBound(context,slot.id,slot.type);let value='';
+    if(block){
+      if(slot.type==='image')value=slot.opening.replace(/\s*\/?>$/,` src="${escape(block.url)}" alt="${escape(block.alt)}">`);
+      else value=slot.opening+(slot.type==='list'?block.text.split('\n').map(text=>slot.itemOpening+escape(text)+'</li>').join(''):escape(block.text))+slot.closing;
+    }
+    html=html.replace(`<!--universalcms:block:${slot.id}-->`,()=>value);
+  }
+  return template.prefix+renderNativeWebsite(payload,html)+'<script type="module" src="/.well-known/universalcms-native.mjs"></script>'+template.suffix;
+}
+const types={'.css':'text/css','.png':'image/png','.jpg':'image/jpeg','.jpeg':'image/jpeg','.gif':'image/gif','.webp':'image/webp','.svg':'image/svg+xml','.ico':'image/x-icon','.woff':'font/woff','.woff2':'font/woff2','.ttf':'font/ttf','.otf':'font/otf','.pdf':'application/pdf'};
+export async function startStaticWebsite({root}){
+  root=await realpath(root);const load=async name=>JSON.parse(await readFile(path.join(root,'.universalcms',name),'utf8'));
+  const optional=async name=>{try{return await load(name);}catch(error){if(error.code==='ENOENT')return undefined;throw error;}};
+  const sourceConfiguration=await load('source.config.json'),snapshot=await load('source.generated.json');
+  const configuration=await optional('publication.config.json'),contentBindings=await optional('content.bindings.json'),originalPages=new Map();
+  if((configuration===undefined)!==(contentBindings===undefined))throw Error('Static publication configuration or content bindings are missing. Repair the installed integration before starting.');
+  if(configuration===undefined){
+    if(await optional('website.integration.json')!==undefined)throw Error('Static publication configuration is missing. Repair the installed integration before starting.');
+    // Only standalone source export retains the original public website. Once
+    // publication owns these routes, missing delivery must never restore it.
+    const {inspectStaticSource}=await import('./static-setup.mjs');
+    const source=await inspectStaticSource(root,{locale:sourceConfiguration.locale,websiteOrigin:sourceConfiguration.websiteOrigin});
+    if(source.prepared.some(item=>item.installed)||JSON.stringify(source.snapshot)!==JSON.stringify(snapshot))throw Error('Static source changed. Run sync-source before starting.');
+    for(const item of source.prepared)originalPages.set(item.path,item.original);
+  }
+  const runtime=createAstroRuntime({configuration,contentBindings,sourceConfiguration,snapshot,sourceRoot:root}),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.');
+  const bridge=await readFile(fileURLToPath(new URL('./native-website.mjs',import.meta.url)));
+  const server=createServer({requestTimeout:15000,headersTimeout:10000,maxHeaderSize:8192},async(req,res)=>{
+    try{
+      if(!req.url?.startsWith('/')||req.url.startsWith('//')||/[\\\s#]|%(?:2e|2f|5c|25|3f|23)/i.test(req.url.split('?')[0])||req.url.split('?')[0].split('/').some(part=>part==='.'||part==='..')||req.headers.host!==origin.host){res.writeHead(400);res.end();return;}
+      const url=new URL(req.url,origin),request=new Request(url,{method:req.method,headers:new Headers(Object.entries(req.headers).flatMap(([key,value])=>value===undefined?[]:[[key,Array.isArray(value)?value.join(', '):value]]))});
+      let response;
+      if(['GET','HEAD'].includes(req.method)&&!url.search&&url.pathname==='/.well-known/universalcms-native.mjs')response=new Response(bridge,{headers:{'Content-Type':'text/javascript','Cache-Control':'no-cache'}});
+      else {
+        const context={request,locals:{}};
+        response=await runtime.onRequest(context,async()=>{
+          if(context.locals.universalcms)return new Response(renderStaticPage(context.locals.universalcms,snapshot),{headers:{'Content-Type':'text/html; charset=utf-8'}});
+          const original=originalPages.get(url.pathname==='/'?'/':url.pathname.replace(/\/$/,''));
+          if(['GET','HEAD'].includes(req.method)&&!url.search&&original!==undefined)return new Response(original,{headers:{'Content-Type':'text/html; charset=utf-8','Cache-Control':'no-store'}});
+          const asset=url.pathname.slice(1);
+          if(['GET','HEAD'].includes(req.method)&&!url.search&&snapshot.assets?.includes(asset)){
+            let filename=root;for(const part of asset.split('/')){filename=path.join(filename,part);const info=await lstat(filename);if(info.isSymbolicLink()||await realpath(filename)!==filename)throw Error('Invalid asset');}
+            const info=await lstat(filename);if(!info.isFile()||info.nlink!==1||info.size>16*1024*1024||!types[path.extname(filename)])throw Error('Invalid asset');
+            return new Response(await readFile(filename),{headers:{'Content-Type':types[path.extname(filename)],'Cache-Control':'no-cache'}});
+          }
+          return new Response('Not found',{status:404});
+        });
+      }
+      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'});res.end('Website temporarily unavailable.');}
+  });
+  server.listen(port,'0.0.0.0');return server;
+}

package/dist/static-setup.mjs

@@ -0,0 +1,136 @@
+/** Bounded literal HTML adapter with a private Node host. */
+import path from 'node:path';
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import { parse } from './vendor/astro-compiler/node/index.js';
+import { projectRoot, readProjectFile, SetupError } from './core.mjs';
+import { extractAstroPage } from './astro-source.mjs';
+import { CONTENT_BINDINGS_FILE, contentDigest, readContentRegistry, readFrozenContent, validateContentRegistry } from './content-registry.mjs';
+import { WEBSITE_SECTIONS } from './website-http.mjs';
+import { isExcludedPublicationPath } from './publication.mjs';
+import {readNativeChromeReview,reviewedNativeChrome,nativeChromeObservation} from './native-chrome-review.mjs';
+const json = value => JSON.stringify(value,null,2)+'\n';
+const fail = reason => { throw new SetupError('Static HTML setup needs review: '+reason+'. Existing files were preserved.'); };
+const extensions = new Set(['.css','.png','.jpg','.jpeg','.webp','.gif','.svg','.ico','.woff','.woff2','.ttf','.otf','.pdf']);
+const ignored = new Set(['node_modules','.git','.universalcms']);
+async function read(root,name) {
+  const value=await readProjectFile(root,name);
+  if(value!==null){const info=await lstat(path.join(root,name));if(info.nlink!==1||info.size>128*1024)fail('linked or oversized source');}
+  return value;
+}
+async function inventory(root) {
+  const pages=[],assets=[];let nodes=0;
+  async function walk(directory,depth=0){
+    if(depth>12)fail('directory depth exceeds limit');
+    for(const item of await readdir(path.join(root,directory),{withFileTypes:true})){
+      if(++nodes>5000)fail('file count exceeds limit');
+      if(depth===0&&(ignored.has(item.name)||item.name.startsWith('.')))continue;
+      const name=directory?directory+'/'+item.name:item.name;
+      if(item.isSymbolicLink()||item.name.startsWith('.')||/[\\%?#:\u0000-\u0020]/.test(item.name)||await realpath(path.join(root,name))!==path.join(root,name))fail('linked or unsafe public paths');
+      const stem=(item.isDirectory()?item.name:path.basename(item.name,path.extname(item.name))).toLowerCase();
+      if(/^(?:private|internal)(?:-|$)/.test(stem)||!['assets','static'].includes(stem)&&/^[a-z0-9_.@-]+$/.test(stem)&&isExcludedPublicationPath('/'+stem))fail('private or reserved public paths');
+      if(item.isDirectory()){await walk(name,depth+1);continue;}
+      const stat=await lstat(path.join(root,name));if(!stat.isFile()||stat.nlink!==1)fail('linked public files');
+      if(item.name==='index.html'&&(depth===0||directory.split('/').every(part=>/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(part)))){
+        const pathname=directory?'/'+directory:'/';if(isExcludedPublicationPath(pathname))fail('private or reserved page routes');
+        pages.push({path:pathname,kind:'page',slug:directory||'home',sourceFile:name});
+      }
+      else if(extensions.has(path.extname(item.name))){if(stat.size>16*1024*1024)fail('asset size limit');assets.push(name);}
+      else if(depth===0&&['package.json','package-lock.json','pnpm-lock.yaml','yarn.lock','README.md','AGENTS.md'].includes(item.name))continue;
+      else fail('automatic HTML hosting accepts directory index.html pages and ordinary assets; scripts, other routes and application files need a native adapter');
+    }
+  }
+  await walk('');
+  if(!pages.some(row=>row.path==='/')||pages.length>1000)fail('a root index.html and bounded page inventory are required');
+  return {pages:pages.sort((a,b)=>a.path.localeCompare(b.path)),assets:assets.sort()};
+}
+export async function inspectStaticProject(directory){
+  const root=await projectRoot(directory),packageText=await read(root,'package.json');let manifest;
+  try{manifest=JSON.parse(packageText);}catch{fail('valid package.json required');}
+  if(manifest.workspaces||manifest.type&&manifest.type!=='module'||Object.keys({...manifest.devDependencies,...manifest.dependencies}).some(name=>name!=='@universalcms/connect'))fail('this folder is not a literal HTML project');
+  const scripts={...manifest.scripts};
+  for(const name of ['dev','start','preview']){
+    const command='node .universalcms/static.serve.mjs';if(scripts[name]!==undefined&&scripts[name]!==command)fail('custom startup command');scripts[name]=command;
+  }
+  const build='universalcms-connect sync-source';if(scripts.build!==undefined&&scripts.build!==build)fail('custom build command');scripts.build=build;
+  for(const name of ['dev','start','preview']){const hook='pre'+name;if(scripts[hook]!==undefined&&scripts[hook]!==build)fail('custom lifecycle hook');scripts[hook]=build;}
+  return {root,manifest,packageText,nextPackage:{...manifest,type:'module',scripts},...await inventory(root)};
+}
+async function template(source,slug,locale,websiteOrigin,allowNativeChrome=false){
+  if(/\{|\}|---|universalcms:block|<(?:script|template|slot)\b/i.test(source.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi,'')))fail('dynamic HTML or reserved markers');
+  const extracted=await extractAstroPage({source,slug,locale,websiteOrigin,allowNativeChrome});
+  if(extracted.imports.length||!/<html\b/.test(source)||!/<head\b/.test(source)||!/<body\b/.test(source))fail('complete literal HTML document required');
+  const {ast}=await parse(source,{position:true}),offsets=new Map([[0,0]]);let bytes=0,chars=0,cursor=0,bodyStart,bodyEnd;const slots=[],edits=[];
+  for(const character of source){bytes+=Buffer.byteLength(character);chars+=character.length;offsets.set(bytes,chars);}
+  const startOf=node=>{let start=offsets.get(node.position?.start?.offset);if(source[start]!=='<'&&source[start-1]==='<')start--;if(!Number.isInteger(start)||!source.startsWith('<'+node.name,start))fail('ambiguous source position');return start;};
+  const openEndOf=start=>{let quote=null;for(let i=start+1;i<source.length;i++){const c=source[i];if(quote){if(c===quote)quote=null;}else if(c==='"'||c==="'")quote=c;else if(c==='>')return i+1;}fail('incomplete opening tag');};
+  const visit=node=>{
+    if(node.type!=='element'){for(const child of node.children??[])visit(child);return;}
+    if(['head','style'].includes(node.name)||extracted.inventory.nativeChrome&&['header','footer'].includes(node.name))return;
+    if(node.name==='body'){if(bodyStart!==undefined)fail('ambiguous body');bodyStart=openEndOf(startOf(node));bodyEnd=offsets.get(node.position?.end?.offset)-7;if(!source.startsWith('</body>',bodyEnd))fail('incomplete body');}
+    if(!/^(?:h[1-6]|p|ul|ol|img)$/.test(node.name)){for(const child of node.children??[])visit(child);return;}
+    const from=startOf(node),openEnd=openEndOf(from);
+    const to=node.name==='img'?openEnd:offsets.get(node.position?.end?.offset),block=extracted.entry.document.blocks[cursor++];
+    if(!block||!Number.isInteger(to)||to<=from)fail('ambiguous editorial range');
+    let opening=source.slice(from,openEnd),closing=node.name==='img'?'':`</${node.name}>`;
+    if(block.type==='image'){
+      const ranges=node.attributes.filter(attr=>['src','alt'].includes(attr.name)).map(attr=>{
+        const at=offsets.get(attr.position?.start?.offset),prefix=new RegExp(`^${attr.name}\\s*=\\s*`).exec(source.slice(at));
+        if(!Number.isInteger(at)||!prefix||attr.kind!=='quoted'||!['"',"'"].includes(attr.raw?.[0])||source.slice(at+prefix[0].length,at+prefix[0].length+attr.raw.length)!==attr.raw)fail('ambiguous image attribute');
+        return {start:at-from,end:at-from+prefix[0].length+attr.raw.length};
+      });
+      for(const range of ranges.sort((a,b)=>b.start-a.start))opening=opening.slice(0,range.start)+opening.slice(range.end);
+    }
+    else if(block.type!=='list'&&node.children.some(child=>!['text','comment'].includes(child.type)))fail('formatted text needs explicit native bindings');
+    let itemOpening='<li>';
+    if(block.type==='list') {const item=node.children.find(child=>child.type==='element'),start=startOf(item);itemOpening=source.slice(start,openEndOf(start));}
+    slots.push({id:block.id,type:block.type,opening,closing,...(block.type==='list'?{itemOpening}:{})});
+    edits.push({from,to,text:`<!--universalcms:block:${block.id}-->`});
+  };
+  visit(ast);if(cursor!==extracted.entry.document.blocks.length||!Number.isInteger(bodyStart)||!Number.isInteger(bodyEnd))fail('incomplete native bindings');
+  let body=source.slice(bodyStart,bodyEnd);for(const edit of edits.sort((a,b)=>b.from-a.from)){if(edit.from<bodyStart||edit.to>bodyEnd)fail('editorial range outside body');body=body.slice(0,edit.from-bodyStart)+edit.text+body.slice(edit.to-bodyStart);}
+  const prefix=source.slice(0,bodyStart),suffix=source.slice(bodyEnd),native=prefix+body+suffix;
+  return {entry:extracted.entry,inventory:extracted.inventory,native,prefix,body,suffix,slots};
+}
+export async function inspectStaticSource(directory,{locale='en',websiteOrigin}={}){
+  const project=await inspectStaticProject(directory),registry=await readContentRegistry(project.root),entries=[],inventories={},templates={},prepared=[],sourceFiles=[];
+  const chromeReview=await readNativeChromeReview(project.root,'static');
+  const routes=project.pages.map(row=>({...row,locale}));
+  for(const row of routes){
+    const installed=registry?.routes.find(item=>item.path===row.path),current=await read(project.root,row.sourceFile),frozen=installed?await readFrozenContent(project.root,installed):null;
+    const original=frozen?frozen.texts.original:current,extracted=await template(original,row.slug,locale,websiteOrigin,reviewedNativeChrome(chromeReview,row.sourceFile,original));
+    if(installed&&(current!==extracted.native||json(extracted.inventory)!==frozen.texts.inventory))fail('bound source changed');
+    entries.push(extracted.entry);inventories[row.path]=extracted.inventory;templates[row.path]={prefix:extracted.prefix,body:extracted.body,suffix:extracted.suffix,slots:extracted.slots};prepared.push({...row,installed,current,original,extracted});sourceFiles.push({path:row.sourceFile,sha256:contentDigest(current)});
+  }
+  if(registry&&registry.routes.length!==routes.length)fail('previously managed route removed');
+  if(chromeReview)sourceFiles.push({path:chromeReview.path,sha256:chromeReview.sha256});
+  return {root:project.root,framework:'static',chromeReview,entries,routes:routes.map(({sourceFile,...row})=>row),snapshot:{version:1,entries,inventories,templates,assets:project.assets},sourceFiles,diagnostics:{mappedPages:entries.length,mappedPosts:0},prepared};
+}
+const serve=`import { fileURLToPath } from 'node:url';\nimport { startStaticWebsite } from '@universalcms/connect/static-runtime';\nawait startStaticWebsite({root:fileURLToPath(new URL('../',import.meta.url))});\n`;
+export async function planStaticIntegration(root,{publication=false}={}){
+  const project=await inspectStaticProject(root),name='.universalcms/static.serve.mjs',before=await read(root,name);
+  if(before!==null&&before!==serve)fail('custom static host');
+  const pkg=json(project.nextPackage);
+  return {root:project.root,framework:'static',files:[{path:name,content:serve,state:before===null?'create':'unchanged'},{path:'package.json',content:pkg,state:pkg===project.packageText?'unchanged':'update',...(pkg===project.packageText?{}:{previous:project.packageText})}]};
+}
+export async function planStaticContent(root,config){
+  const source=await inspectStaticSource(root,{locale:config.routes[0]?.locale,websiteOrigin:config.websiteOrigin});if(json(source.routes)!==json(config.routes))fail('route mappings differ');
+  const files=await nativeChromeObservation(root,source.chromeReview),rows=[];
+  for(const item of source.prepared){
+    if(item.installed){const frozen=await readFrozenContent(root,item.installed);for(const [prefix,content]of Object.entries(frozen.texts))files.push({path:item.installed[prefix+'File'],content,state:'unchanged'});rows.push(item.installed);continue;}
+    const token=contentDigest(item.path).slice(0,24),nativeFile=`.universalcms/content/${token}.native.txt`,originalFile=`.universalcms/content/${token}.original.txt`,inventoryFile=`.universalcms/content/${token}.json`,inventoryText=json(item.extracted.inventory);
+    for(const name of [nativeFile,originalFile,inventoryFile])if(await read(root,name)!==null)fail('unowned frozen content file');
+    const row={path:item.path,kind:item.kind,slug:item.slug,locale:item.locale,sourceFile:item.sourceFile,nativeFile,originalFile,inventoryFile,sourceHash:contentDigest(item.extracted.native),nativeHash:contentDigest(item.extracted.native),originalHash:contentDigest(item.original),inventoryHash:contentDigest(inventoryText)};
+    files.push({path:nativeFile,content:item.extracted.native,state:'create'},{path:originalFile,content:item.original,state:'create'},{path:inventoryFile,content:inventoryText,state:'create'},{path:item.sourceFile,content:item.extracted.native,state:'update',previous:item.current});rows.push(row);
+  }
+  const content=json(validateContentRegistry({version:1,routes:rows})),before=await read(root,CONTENT_BINDINGS_FILE);if(before!==null&&before!==content)fail('content registry changed');
+  files.push({path:CONTENT_BINDINGS_FILE,content,state:before===null?'create':'unchanged'});return {root,framework:'static',files};
+}
+export async function validateInstalledStatic(root,config){
+  const plan=await planStaticIntegration(root,{publication:true}),source=await inspectStaticSource(root,{locale:config.routes[0]?.locale,websiteOrigin:config.websiteOrigin});
+  if(plan.files.some(file=>file.state!=='unchanged')||json(source.routes)!==json(config.routes)||await read(root,'.universalcms/source.generated.json')!==json(source.snapshot))fail('runtime or source inventory is incomplete');
+  const content=await planStaticContent(root,config);if(content.files.some(file=>file.state!=='unchanged'))fail('native content bindings incomplete');return {...plan,config,files:[...plan.files,...content.files]};
+}
+export async function planStaticSettings(root,{config,source}){
+  const plan=await validateInstalledStatic(root,config),name='.universalcms/website.integration.json',content=json({version:1,framework:'static',siteId:config.siteId,environmentId:config.environmentId,apiOrigin:config.apiOrigin,websiteOrigin:config.websiteOrigin,adminOrigin:source.adminOrigin,sections:WEBSITE_SECTIONS,files:plan.files.filter(file=>file.path!=='package.json').map(file=>({path:file.path,sha256:contentDigest(file.content)}))}),before=await read(root,name);
+  if(before!==null&&before!==content)fail('settings ownership changed');plan.files.push({path:name,content,state:before===null?'create':'unchanged'});return {...plan,sections:[...WEBSITE_SECTIONS]};
+}

package/dist/svelte-runtime.d.mts

@@ -0,0 +1,27 @@
+import type { WebsiteResult, WebsiteSnapshot } from './website-runtime.mjs';
+export type NativePublicContext = {
+  pathname: string;
+  scope: string;
+  result: WebsiteResult;
+  settings: WebsiteSnapshot;
+  publicInventory?: unknown;
+  bindings: Record<string, { text?: string; url?: string; alt?: string }>;
+};
+export type NativeRuntimeOptions = {
+  configuration?: unknown;
+  sourceConfiguration: unknown;
+  contentBindings?: unknown;
+  snapshot: unknown;
+  sourceRoot: string;
+  renderWebsite(value: unknown, childrenHtml?: string): string;
+  env?: Record<string, string | undefined> | (() => Record<string, string | undefined> | Promise<Record<string, string | undefined>>);
+  fetcher?: typeof fetch;
+};
+export function nativePublicContext(value: unknown): NativePublicContext | null;
+export function renderNativeResponse(response: Response, context: NativePublicContext | null, renderWebsite: NativeRuntimeOptions['renderWebsite']): Promise<Response>;
+export function createSvelteRuntime(options: NativeRuntimeOptions): {
+  handle<Event extends { request: Request; isDataRequest?: boolean; locals: object }>(input: {
+    event: Event;
+    resolve(event: Event): Promise<Response>;
+  }): Promise<Response>;
+};

package/dist/svelte-runtime.mjs

@@ -0,0 +1,40 @@
+/** SvelteKit/Angular bridge to the reviewed request-local private runtime. */
+import { createAstroRuntime, astroBound } from './astro-runtime.mjs';
+const publicContext = cms => {
+  if(!cms)return null;
+  const bindings={};
+  for(const block of cms.inventory?.baseline.blocks??[]){const value=astroBound(cms,block.id,block.type);if(value)bindings[block.id]=value;}
+  return {pathname:cms.pathname,scope:cms.scope,result:cms.result,settings:cms.settings,publicInventory:cms.publicInventory,bindings};
+};
+export function createSvelteRuntime(options) {
+  const runtime=createAstroRuntime(options);
+  return {async handle({event,resolve}) {
+    // Supported native navigation performs a full document request. Svelte's
+    // alternate data transport must never return frozen source or bypass checks.
+    if(event.isDataRequest||/\/(?:\.universalcms|\.env(?:[./]|$))/.test(new URL(event.request.url).pathname))return new Response('Not found',{status:404,headers:{'Cache-Control':'no-store'}});
+    const context={request:event.request,locals:{}};
+    return runtime.onRequest(context,async()=>{
+      event.locals.universalcms=publicContext(context.locals.universalcms);
+      const response=await resolve(event);
+      return renderNativeResponse(response,event.locals.universalcms,options.renderWebsite);
+    });
+  }};
+}
+export async function renderNativeResponse(response,cms,renderWebsite) {
+  if(!cms||response.status!==200||!response.headers.get('content-type')?.includes('text/html'))return response;
+  if(typeof renderWebsite!=='function'||!response.body)throw Error('Native website renderer unavailable');
+  const reader=response.body.getReader(),chunks=[];let size=0,timer;
+  const deadline=new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error('Native response timed out')),10000);});
+  try {for(;;){const item=await Promise.race([reader.read(),deadline]);if(item.done)break;if((size+=item.value.byteLength)>8*1024*1024)throw Error('Native response exceeded budget');chunks.push(item.value);}}
+  finally{clearTimeout(timer);void reader.cancel().catch(()=>{});reader.releaseLock();}
+  const html=new TextDecoder('utf-8',{fatal:true}).decode(Buffer.concat(chunks));
+  const markers=[...html.matchAll(/<universalcms-website\b[^>]*>([\s\S]*?)<\/universalcms-website>/g)];
+  if(markers.length!==1)throw Error('Native website host unavailable');
+  const payload={pathname:cms.pathname,scope:cms.scope,initialResult:cms.result,initialSettings:cms.settings,...(cms.publicInventory?{inventory:cms.publicInventory}:{})};
+  // Framework load/TransferState owns the public payload. Extra light-DOM nodes
+  // would confuse native hydration; the consumed declarative shadow root does not.
+  const host=renderWebsite(payload,cms.publicInventory?markers[0][1]:'').replace(/^<universalcms-website>/,markers[0][0].slice(0,markers[0][0].indexOf('>')+1)).replace(/<script type="application\/json" data-universalcms-payload>[\s\S]*?<\/script>/,'');
+  const headers=new Headers(response.headers);headers.delete('Content-Length');headers.delete('ETag');
+  return new Response(html.slice(0,markers[0].index)+host+html.slice(markers[0].index+markers[0][0].length),{status:200,headers});
+}
+export { publicContext as nativePublicContext };