@universalcms/connect 0.0.0-stage → 0.13.0

package/dist/source-routes.mjs

@@ -0,0 +1,65 @@
+import { lstat, opendir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { projectRoot, readProjectFile } from './project-files.mjs';
+
+/** An opt-in inventory of filenames only. Never import, render or crawl a page. */
+export async function inspectSourceRoutes(directory) {
+  const root = await projectRoot(directory);
+  const pkg = JSON.parse(await readProjectFile(root, 'package.json'));
+  if (!pkg || !pkg.dependencies?.next && !pkg.devDependencies?.next || pkg.workspaces) throw Error('Unsupported route inventory');
+  for (const extension of ['js', 'mjs', 'cjs', 'ts']) {
+    const config = await readProjectFile(root, `next.config.${extension}`);
+    if (config && /\b(?:pageExtensions|basePath|rewrites|redirects|i18n)\b/.test(config)) throw Error('Custom route inventory');
+  }
+  async function ordinaryDirectory(relative) {
+    const parts = relative.split('/');
+    let current = root;
+    for (const part of parts) {
+      current = path.join(current, part);
+      let stat;
+      try { stat = await lstat(current); } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+      if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(current) !== current) throw Error('Unsafe directory');
+    }
+    return true;
+  }
+  const candidates = [];
+  for (const relative of ['app', 'src/app']) if (await ordinaryDirectory(relative)) candidates.push(relative);
+  if (candidates.length !== 1) throw Error('Ambiguous App Router');
+  for (const relative of ['pages', 'src/pages']) if (await ordinaryDirectory(relative)) throw Error('Mixed routing');
+  const routes = new Set(), files = {}, unresolvedPaths = [];
+  let entries = 0, directories = 0;
+  async function walk(relative, segments, depth) {
+    if (depth > 12 || ++directories > 256 || !await ordinaryDirectory(relative)) throw Error('Directory budget');
+    const directoryHandle = await opendir(path.join(root, relative));
+    for await (const entry of directoryHandle) {
+      if (++entries > 4000) throw Error('Entry budget');
+      if (entry.isSymbolicLink()) throw Error('Symbolic route');
+      if (entry.isDirectory()) {
+        // Parallel slots can contain routable descendants; they need review.
+        if (entry.name.startsWith('_')) continue;
+        if (/^[@.]/.test(entry.name)) { unresolvedPaths.push(`${relative}/${entry.name}`); continue; }
+        if (/^\[[^/]+\]$/.test(entry.name) || /^\(\.{1,3}\)/.test(entry.name)) { unresolvedPaths.push(`${relative}/${entry.name}`); continue; }
+        const group = /^\([a-zA-Z0-9_-]+\)$/.test(entry.name);
+        if (!group && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(entry.name)) { unresolvedPaths.push(`${relative}/${entry.name}`); continue; }
+        await walk(`${relative}/${entry.name}`, group ? segments : [...segments, entry.name], depth + 1);
+      } else if (entry.isFile() && /^page\.(?:js|jsx|ts|tsx)$/.test(entry.name)) {
+        const route = segments.join('/');
+        if (routes.has(route)) throw Error('Duplicate route');
+        routes.add(route);
+        files[route || 'home'] = `${relative}/${entry.name}`;
+        if (routes.size > 1000) throw Error('Route budget');
+      } else if (/^page\.(?:md|mdx)$/.test(entry.name)) unresolvedPaths.push(`${relative}/${entry.name}`);
+    }
+  }
+  await walk(candidates[0], [], 0);
+  if (!routes.size) throw Error('No known pages');
+  return { routes: [...routes], unresolved: unresolvedPaths.length, unresolvedPaths, files };
+}
+
+export function compareSourceRoutes(inventory, entries) {
+  const exported = new Set(entries.filter(entry => entry.kind === 'page').map(entry => entry.slug));
+  const missing = inventory.routes.filter(route => !exported.has(route || 'home')).length;
+  // /home and / cannot both be represented by the same identity.
+  const ambiguousHome = inventory.routes.includes('') && inventory.routes.includes('home');
+  return { staticPages: inventory.routes.length, missingPages: missing, unresolvedRoutes: inventory.unresolved + Number(ambiguousHome) };
+}

package/dist/source-setup.mjs

@@ -0,0 +1,490 @@
+/** Additive public-source setup. Never reads credentials or executes website code. */
+import { constants } from 'node:fs';
+import { lstat, realpath, open, mkdir, readdir, rename, unlink } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { projectRoot, SetupError } from './core.mjs';
+import { collectSource } from './source-collect.mjs';
+import { createSourceManifestProvider } from './vendor/source-manifest-provider.mjs';
+import { discoverViteSource } from './vite-source-discovery.mjs';
+import { discoverReviewedStorefrontSource } from './reviewed-storefront-source.mjs';
+import { planAstroIntegration } from './astro-setup.mjs';
+import { inspectAstroSource } from './astro-source.mjs';
+import { contentDigest } from './content-registry.mjs';
+import { inspectSetupFramework } from './framework.mjs';
+import { nativeFramework, inspectNativeSource, planNativeIntegration } from './native-adapters.mjs';
+
+export const SOURCE_CONFIG_FILE = '.universalcms/source.config.json';
+export const SOURCE_SNAPSHOT_FILE = '.universalcms/source.generated.json';
+export const VITE_SOURCE_ENTRIES_FILE = '.universalcms/source.entries.json';
+const VITE_SOURCE_WRAPPER = '.universalcms/source.vite.config.mjs';
+const VITE_CONTENT_ROUTES_FILE = '.universalcms/content.routes.json';
+const plans = new WeakMap();
+const MAX_BYTES = 20 * 1024 * 1024;
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = message => { throw new SetupError(message); };
+const json = value => `${JSON.stringify(value, null, 2)}\n`;
+const stamp = stat => [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs, stat.nlink, stat.mode].join(':');
+
+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)) throw Error();
+    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)))) throw Error();
+    return url.origin;
+  } catch { fail('Use exact website and CMS admin HTTPS origins without credentials, paths or queries (HTTP loopback is allowed for development).'); }
+}
+
+export function validateSourceConfig(input) {
+  const keys = ['version', 'siteId', 'environmentId', 'websiteOrigin', 'adminOrigin', 'locale', 'skipSlugs', 'excludedRoutes', 'publicStaticPages', 'exportClosed'];
+  if (!plain(input) || Object.keys(input).some(key => !keys.includes(key)) || (input.exportClosed !== undefined && input.exportClosed !== true) || input.version !== 1 || input.publicStaticPages !== true || !['siteId', 'environmentId'].every(key => typeof input[key] === 'string' && uuid.test(input[key]))) fail('Use valid public source configuration and website/environment UUIDs. Credentials are not source configuration.');
+  let locale;
+  try { if (typeof input.locale !== 'string' || input.locale.length > 35) throw Error(); locale = Intl.getCanonicalLocales(input.locale)[0]; if (!locale) throw Error(); }
+  catch { fail('Use a valid source content locale, such as en.'); }
+  if (!Array.isArray(input.skipSlugs) || input.skipSlugs.length > 1000 || input.skipSlugs.some(slug => typeof slug !== 'string' || slug.length > 160 || !/^[a-z0-9]+(?:[-/][a-z0-9]+)*$/.test(slug)) || new Set(input.skipSlugs).size !== input.skipSlugs.length) fail('Source exclusions must be unique ordinary page slugs.');
+  const excludedRoutes = input.excludedRoutes ?? [];
+  if (!Array.isArray(excludedRoutes) || excludedRoutes.length > 1000 || excludedRoutes.some(route => typeof route !== 'string' || route.length > 161 || !/^\/(?:[a-z0-9]+(?:[-/][a-z0-9]+)*)?$/.test(route)) || new Set(excludedRoutes).size !== excludedRoutes.length) fail('Excluded routes must be unique ordinary website paths, such as /account.');
+  return { version: 1, siteId: input.siteId.toLowerCase(), environmentId: input.environmentId.toLowerCase(), websiteOrigin: origin(input.websiteOrigin), adminOrigin: origin(input.adminOrigin), locale, skipSlugs: [...input.skipSlugs], excludedRoutes: [...excludedRoutes], publicStaticPages: true, ...(input.exportClosed ? { exportClosed: true } : {}) };
+}
+
+async function inspect(root, relative, directory = false) {
+  if (!relative || relative.includes('\\') || path.isAbsolute(relative) || relative.split('/').some(part => !part || part === '.' || part === '..')) fail('Unsafe source setup path.');
+  let target = root;
+  const parts = relative.split('/');
+  for (let index = 0; index < parts.length; index++) {
+    target = path.join(target, parts[index]);
+    let stat;
+    try { stat = await lstat(target); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    if (stat.isSymbolicLink() || await realpath(target) !== target) fail('Source setup paths cannot be symbolic links.');
+    if (index < parts.length - 1 || directory) { if (!stat.isDirectory()) fail('A source setup directory has an incompatible file type.'); }
+    else if (!stat.isFile() || stat.nlink !== 1) fail('Source setup files must be ordinary files without hard links.');
+    if (index === parts.length - 1) return { target, stat };
+  }
+}
+
+async function read(root, relative) {
+  const found = await inspect(root, relative);
+  if (!found) return { content: null, stamp: null };
+  const limit = [SOURCE_SNAPSHOT_FILE, VITE_SOURCE_ENTRIES_FILE].includes(relative) ? MAX_BYTES : 128 * 1024;
+  if (found.stat.size > limit) fail('A source setup file exceeds its read budget.');
+  const handle = await open(found.target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (stamp(stat) !== stamp(found.stat)) fail('A source setup file changed during inspection. Retry setup.');
+    const buffer = Buffer.alloc(limit + 1); let bytes = 0;
+    while (bytes < buffer.length) { const chunk = await handle.read(buffer, bytes, buffer.length - bytes, bytes); if (!chunk.bytesRead) break; bytes += chunk.bytesRead; }
+    if (bytes > limit || stamp(await handle.stat()) !== stamp(stat)) fail('A source setup file changed or exceeded its read budget.');
+    return { content: new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, bytes)), stamp: stamp(stat) };
+  } finally { await handle.close(); }
+}
+
+export function sourceRouteTemplate(appDirectory) {
+  const prefix = appDirectory === 'src/app' ? '../../../../' : '../../../';
+  return `// Generated by @universalcms/connect. Public content only; no delivery credentials.\nimport { createNextSourceHandler } from '@universalcms/connect/next-source';\nimport configuration from '${prefix}.universalcms/source.config.json';\nimport snapshot from '${prefix}.universalcms/source.generated.json';\n\nconst handle = createNextSourceHandler({ sourceRoot: process.cwd(), configuration, snapshot });\nexport const GET = handle;\nexport const HEAD = handle;\nexport const OPTIONS = handle;\n`;
+}
+
+function validateSnapshot(value) {
+  if (!plain(value) || Object.keys(value).sort().join() !== 'diagnostics,entries,version' || value.version !== 1 || !Array.isArray(value.entries) || value.entries.length > 1000 || !plain(value.diagnostics)) fail('The generated source snapshot needs manual review. Preserve your edits before regenerating it.');
+  return value;
+}
+
+function buildHook(manifest) {
+  if (manifest.scripts !== undefined && !plain(manifest.scripts)) fail('The website scripts need manual review before source setup.');
+  const scripts = { ...manifest.scripts }, hook = 'universalcms-connect sync-source';
+  if (typeof scripts.build !== 'string' || !/\bnext\s+build\b/.test(scripts.build)) fail('Source setup requires a Next.js build script so deployed source snapshots are refreshed.');
+  if (scripts.prebuild !== undefined && (typeof scripts.prebuild !== 'string' || scripts.prebuild.length > 8192 || /[\r\n\0]/.test(scripts.prebuild))) fail('The existing prebuild script needs manual review.');
+  if (scripts.prebuild?.startsWith(`${hook} && `)) {
+    // An earlier connector preview placed sync first. Preserve the customer
+    // preparation step but capture any pages it generates before Next builds.
+    scripts.prebuild = `${scripts.prebuild.slice(`${hook} && `.length)} && ${hook}`;
+  } else if (scripts.prebuild !== hook && !scripts.prebuild?.endsWith(` && ${hook}`)) {
+    if (scripts.prebuild?.includes('universalcms-connect')) fail('A custom connector prebuild script needs manual review before setup.');
+    scripts.prebuild = scripts.prebuild ? `${scripts.prebuild} && ${hook}` : hook;
+  }
+  return { ...manifest, scripts };
+}
+
+async function appRoot(root, manifest) {
+  const next = manifest.dependencies?.next ?? manifest.devDependencies?.next;
+  if (manifest.workspaces || typeof next !== 'string' || !/^(?:\^|~)?16\.\d+\.\d+$/.test(next)) fail('Automatic source setup supports a single Next.js 16 App Router website.');
+  const roots = [];
+  for (const candidate of ['app', 'src/app']) if (await inspect(root, candidate, true)) roots.push(candidate);
+  if (roots.length !== 1) fail('Automatic source setup requires exactly one App Router directory.');
+  for (const candidate of ['pages', 'src/pages']) if (await inspect(root, candidate, true)) fail('Mixed or Pages Router source setup requires a manual adapter.');
+  for (const extension of ['js', 'mjs', 'cjs', 'ts']) {
+    const config = (await read(root, `next.config.${extension}`)).content;
+    if (config && /\b(?:pageExtensions|basePath|rewrites|redirects|i18n)\b|\boutput\s*:\s*['"]export['"]|\bruntime\s*:\s*['"]edge['"]/.test(config)) fail('Custom routes or static/Edge deployment require a manual source adapter. Cache Components is supported.');
+  }
+  let layout = false;
+  for (const extension of ['js', 'jsx', 'ts', 'tsx']) {
+    const source = (await read(root, `${roots[0]}/layout.${extension}`)).content;
+    if (source) { layout = true; if (/\bruntime\s*=\s*['"]edge['"]/.test(source)) fail('Automatic source discovery requires the Node runtime, not Edge.'); }
+  }
+  if (!layout) fail('The App Router requires an existing root layout.');
+  return roots[0];
+}
+
+async function checkGroupedEndpoint(root, appDirectory, expectedRoute) {
+  let visited = 0;
+  async function walk(relative, segments, depth) {
+    if (++visited > 256 || depth > 12) fail('The source endpoint route tree exceeds its inspection budget.');
+    await inspect(root, relative, true);
+    const children = await readdir(path.join(root, relative), { withFileTypes: true });
+    for (const child of children) {
+      if (child.isSymbolicLink()) fail('Source endpoint route paths cannot be symbolic links.');
+      if (child.isFile() && /^route\.(?:js|jsx|ts|tsx)$/.test(child.name) && segments.join('/') === 'api/cms-source' && `${relative}/${child.name}` !== expectedRoute) fail('Another route already owns /api/cms-source through a route group. Review the existing source adapter manually.');
+      if (!child.isDirectory()) continue;
+      const group = /^\([a-zA-Z0-9_-]+\)$/.test(child.name);
+      if (group) await walk(`${relative}/${child.name}`, segments, depth + 1);
+      else if (child.name === ['api', 'cms-source'][segments.length]) await walk(`${relative}/${child.name}`, [...segments, child.name], depth + 1);
+    }
+  }
+  await walk(appDirectory, [], 0);
+}
+
+function legacyViteSourceWrapper() {
+  return `// Generated by @universalcms/connect. Keep your original Vite configuration.\nimport { defineConfig, loadConfigFromFile } from 'vite';\nimport { universalCmsSource } from '@universalcms/connect/vite-source';\nimport configuration from './source.config.json' with { type: 'json' };\n\nexport default defineConfig(async env => {\n  const existing = (await loadConfigFromFile(env, undefined, process.cwd()))?.config ?? {};\n  if (existing.root || existing.base && existing.base !== '/' || existing.appType === 'custom') throw new Error('Custom Vite roots, base paths and servers need a reviewed source integration.');\n  return { ...existing, plugins: [universalCmsSource({ configuration }), ...(existing.plugins ?? [])] };\n});\n`;
+}
+
+function legacyPublicationViteSourceWrapper() {
+  return legacyViteSourceWrapper()
+    .replace("import { universalCmsSource }", "import { universalCmsPublication } from '@universalcms/connect/vite-publication';\nimport publication from './publication.config.json' with { type: 'json' };\nimport contentBindings from './content.bindings.json' with { type: 'json' };\nimport { universalCmsSource }")
+    .replace('[universalCmsSource({ configuration }),', '[universalCmsPublication({ configuration: publication, sourceConfiguration: configuration, contentBindings }), universalCmsSource({ configuration }),');
+}
+
+export function viteSourceWrapper(publication = false, previous = false) {
+  if (publication && previous) return viteSourceWrapper(true).replace("import contentBindings from './content.bindings.json' with { type: 'json' };\n", '').replace('configuration: publication, sourceConfiguration: configuration, contentBindings', 'configuration: publication');
+  if (publication) return legacyViteSourceWrapper()
+    .replace("import { universalCmsSource }", "import { universalCmsWebsite } from '@universalcms/connect/website-node';\nimport { universalCmsPublication } from '@universalcms/connect/vite-publication';\nimport publication from './publication.config.json' with { type: 'json' };\nimport contentBindings from './content.bindings.json' with { type: 'json' };\nimport { universalCmsSource }")
+    .replace('return { ...existing, plugins:', `return { ...existing, ...(typeof contentBindings !== 'undefined' && !contentBindings.profile ? { server: { ...existing.server, fs: { ...existing.server?.fs, strict: true, deny: ['.env', '.env.*', '*.{crt,pem}', '**/.git/**', ...(existing.server?.fs?.deny ?? []), '**/.universalcms/**'] } } } : {}), plugins:`)
+    .replace('[universalCmsSource({ configuration }),', '[universalCmsWebsite({ configuration: publication, sourceConfiguration: configuration, contentBindings }), universalCmsPublication({ configuration: publication, sourceConfiguration: configuration, contentBindings }), universalCmsSource({ configuration }),');
+  return legacyViteSourceWrapper();
+}
+
+function viteScripts(manifest, publication = false) {
+  if (!plain(manifest.scripts)) fail('Vite source setup requires the website dev script. Custom servers need a reviewed source integration.');
+  const scripts = { ...manifest.scripts };
+  const option = ` --config ${VITE_SOURCE_WRAPPER}`;
+  for (const name of ['dev', 'preview']) {
+    if (name === 'preview' && scripts[name] === undefined) continue;
+    const command = scripts[name], expected = name === 'dev' ? 'vite' : 'vite preview';
+    if (typeof command !== 'string') fail('Vite source setup requires ordinary vite dev/preview scripts. Existing scripts were preserved.');
+    const original = command.endsWith(option) ? command.slice(0, -option.length) : command;
+    // Preserve only understood CLI flags; never rewrite a shell pipeline or a
+    // custom config/server command. The original Vite config is loaded above.
+    if (!original.startsWith(expected) || !/^(?:\s+--(?:host(?:\s+(?:localhost|127\.0\.0\.1|0\.0\.0\.0|::1))?|port\s+\d{1,5}|strictPort|open|https))*$/.test(original.slice(expected.length))) fail('Vite source setup cannot safely update this dev/preview command. Add universalCmsSource to your existing server configuration; existing scripts were preserved.');
+    scripts[name] = original + option;
+  }
+  if (publication) {
+    const build = scripts.build;
+    const original = typeof build === 'string' && build.endsWith(option) ? build.slice(0, -option.length) : build;
+    if (typeof original !== 'string' || !/^(?:(?:tsc(?: -b)?|tsc --noEmit) && )?vite build$/.test(original)) fail('Publication setup requires an ordinary vite build command. Preserve the custom build and integrate the publication plugin manually.');
+    scripts.build = original + option;
+    const start = 'node .universalcms/serve.mjs';
+    if (scripts.start !== undefined && scripts.start !== start) fail('Publication setup cannot replace a custom production server. Integrate the publication handler in that server before declaring setup complete.');
+    scripts.start = start;
+  }
+  return { ...manifest, scripts };
+}
+
+async function discoverViteFallback(root, locale, { readFile }) {
+  const indexHtml = await readFile('index.html');
+  if (!indexHtml) return null;
+  let title = 'Home';
+  const match = /<title[^>]*>([^<]+)<\/title>/i.exec(indexHtml);
+  if (match?.[1]?.trim()) title = match[1].trim();
+  let candidate = null;
+  for (const name of ['src/App.jsx', 'src/App.tsx', 'src/App.js', 'src/App.ts', 'src/main.jsx', 'src/main.tsx']) {
+    if ((await readFile(name)) !== null) { candidate = name; break; }
+  }
+  if (!candidate) return null;
+  const headingId = 'block-home-heading';
+  const manifest = {
+    version: 1,
+    entries: [
+      {
+        kind: 'page',
+        slug: 'home',
+        locale: locale || 'en',
+        document: {
+          schemaVersion: 1,
+          title,
+          excerpt: '',
+          blocks: [
+            {
+              id: headingId,
+              type: 'heading',
+              text: title,
+              data: { level: 1 }
+            }
+          ]
+        }
+      }
+    ]
+  };
+  const mappings = [{ path: '/', sourceFile: candidate }];
+  return { manifest, mappings, diagnostics: { automaticPages: 1, discovery: 'fallback' } };
+}
+
+async function setupViteSource(root, manifest, packageFile, options) {
+  const vite = manifest.dependencies?.vite ?? manifest.devDependencies?.vite;
+  const react = manifest.dependencies?.react ?? manifest.devDependencies?.react;
+  if (manifest.workspaces || typeof vite !== 'string' || !/^(?:\^|~)?[678]\.\d+\.\d+$/.test(vite) || typeof react !== 'string' || !/^(?:\^|~)?19\.(?:[2-9]|\d{2,})\.\d+$/.test(react)) fail('Vite source setup supports a single React 19.2+ / Vite 6–8 website.');
+  for (const extension of ['js', 'mjs', 'cjs', 'ts', 'mts', 'cts']) {
+    const existing = (await read(root, `vite.config.${extension}`)).content;
+    if (existing && /\b(?:root|base|appType|configureServer|configurePreviewServer|universalCmsSource)\b|cms-source/.test(existing)) fail('Custom Vite roots, base paths or server middleware need a reviewed source integration. Existing configuration and scripts were preserved.');
+  }
+  const configFile = await read(root, SOURCE_CONFIG_FILE), entriesFile = await read(root, VITE_SOURCE_ENTRIES_FILE), wrapperFile = await read(root, VITE_SOURCE_WRAPPER);
+  let previous;
+  if (configFile.content !== null) {
+    try { previous = validateSourceConfig(JSON.parse(configFile.content)); } catch { fail('The existing source configuration needs manual review. Existing files were preserved.'); }
+    if (json(previous) !== configFile.content) fail('The source configuration was edited. Review it manually before setup.');
+  }
+  const config = validateSourceConfig({ version: 1, siteId: options.siteId ?? previous?.siteId, environmentId: options.environmentId ?? previous?.environmentId, websiteOrigin: options.websiteOrigin ?? previous?.websiteOrigin, adminOrigin: options.adminOrigin ?? previous?.adminOrigin, locale: options.locale ?? previous?.locale ?? 'en', skipSlugs: [], excludedRoutes: [], publicStaticPages: true, ...(previous?.exportClosed ? { exportClosed: true } : {}) });
+  if (previous && (previous.skipSlugs.length || previous.excludedRoutes.length)) fail('Vite exports require exclusions to be applied to the reviewed public manifest. Existing source settings were preserved.');
+  const publication = options.publication === true || [viteSourceWrapper(true), viteSourceWrapper(true, true), legacyPublicationViteSourceWrapper()].includes(wrapperFile.content);
+  const publicationFile = await read(root, '.universalcms/publication.config.json');
+  const observations = new Map([['.universalcms/publication.config.json', publicationFile]]);
+  let discovery, entriesContent = entriesFile.content, mappingFile, mappingContent;
+  if (entriesContent === null) {
+    const discoveryOptions = { locale: config.locale, readFile: async filename => {
+      if (!observations.has(filename)) observations.set(filename, await read(root, filename));
+      return observations.get(filename).content;
+    } };
+    // The exact reviewed profile supplies the same stable import identities for
+    // source-only and full setup. Full setup still has to build and validate its
+    // separate native content plan; this discovery is never completion evidence.
+    discovery = publicationFile.content === null && (!publication || options.publication === true) ? await discoverReviewedStorefrontSource(root, discoveryOptions) : null;
+    try {
+      discovery ??= await discoverViteSource(root, discoveryOptions);
+    } catch (discoveryError) {
+      // Publication setup cannot turn a known access or routing refusal into
+      // an empty home mapping. Those boundaries need explicit ownership.
+      if (discoveryError.code === 'VITE_SOURCE_OWNERSHIP_REVIEW') throw discoveryError;
+      discovery = await discoverViteFallback(root, config.locale, discoveryOptions);
+      if (!discovery) throw discoveryError;
+    }
+    entriesContent = json(discovery.manifest);
+    if (discovery.mappings) {
+      mappingFile = await read(root, VITE_CONTENT_ROUTES_FILE);
+      mappingContent = json(discovery.mappings);
+      if (mappingFile.content !== null) {
+        let matches = false;
+        try { matches = JSON.stringify(JSON.parse(mappingFile.content)) === JSON.stringify(discovery.mappings); } catch { /* Preserve an unrecognized mapping. */ }
+        if (!matches) fail('The existing Vite content route mapping differs from the discovered public pages. Review it manually; existing mappings were preserved.');
+        mappingContent = mappingFile.content;
+      }
+    }
+  }
+  let entries;
+  try {
+    createSourceManifestProvider({ manifestJson: entriesContent, sourceOrigin: config.websiteOrigin, adminOrigin: config.adminOrigin, siteId: config.siteId, environmentId: config.environmentId, publicContent: true });
+    entries = JSON.parse(entriesContent).entries;
+    if (!entries.length || entries.some(entry => Intl.getCanonicalLocales(entry.locale)[0] !== config.locale)) throw Error();
+  } catch { fail('The Vite public source manifest must contain valid nonempty pages/posts for the configured locale. Review .universalcms/source.entries.json; no customer code was executed.'); }
+  const wrapper = viteSourceWrapper(publication);
+  if (wrapperFile.content !== null && (!previous || ![viteSourceWrapper(), viteSourceWrapper(true), viteSourceWrapper(true, true), legacyViteSourceWrapper(), legacyPublicationViteSourceWrapper()].includes(wrapperFile.content))) fail('The Vite source wrapper was customized. Existing files were preserved; integrate the source plugin manually.');
+  const nextPackage = viteScripts(manifest, publication), packageContent = JSON.stringify(nextPackage) === JSON.stringify(manifest) ? packageFile.content : json(nextPackage);
+  const desired = [[SOURCE_CONFIG_FILE, json(config), configFile], [VITE_SOURCE_ENTRIES_FILE, entriesContent, entriesFile], ...(discovery?.mappings ? [[VITE_CONTENT_ROUTES_FILE, mappingContent, mappingFile]] : []), [VITE_SOURCE_WRAPPER, wrapper, wrapperFile], ['package.json', packageContent, packageFile]];
+  const files = desired.map(([file, content, prior]) => Object.freeze({ path: file, state: prior.content === content ? 'unchanged' : prior.content === null ? 'create' : 'update' }));
+  const identities = Object.freeze(entries.map(({ kind, slug, locale }) => Object.freeze({ kind, slug, locale })));
+  const plan = Object.freeze({ root, config: Object.freeze(config), framework: 'vite', identities, diagnostics: { mappedPages: entries.filter(entry => entry.kind === 'page').length, mappedPosts: entries.filter(entry => entry.kind === 'post').length, ...discovery?.diagnostics }, retainedAdapter: false, files: Object.freeze(files) });
+  plans.set(plan, { root, desired, observations: [...observations], applied: false });
+  if (options.apply) return { plan, ...await applySourcePlan(plan) };
+  return plan;
+}
+
+async function setupAstroSource(root, options, framework = 'astro') {
+  const configFile = await read(root, SOURCE_CONFIG_FILE), snapshotFile = await read(root, SOURCE_SNAPSHOT_FILE);
+  let previous;
+  if (configFile.content !== null) {
+    try { previous = validateSourceConfig(JSON.parse(configFile.content)); } catch { fail('The saved native source configuration needs review.'); }
+    if (json(previous) !== configFile.content || previous.skipSlugs.length || previous.excludedRoutes.length) fail('Custom native source exclusions need an explicit reviewed adapter.');
+  }
+  const config = validateSourceConfig({ version: 1, siteId: options.siteId ?? previous?.siteId, environmentId: options.environmentId ?? previous?.environmentId, websiteOrigin: options.websiteOrigin ?? previous?.websiteOrigin, adminOrigin: options.adminOrigin ?? previous?.adminOrigin, locale: options.locale ?? previous?.locale ?? 'en', skipSlugs: [], excludedRoutes: [], publicStaticPages: true, ...(previous?.exportClosed ? { exportClosed: true } : {}) });
+  const sourceOptions = { locale: config.locale, websiteOrigin: config.websiteOrigin };
+  const inspection = framework === 'astro' ? await inspectAstroSource(root, sourceOptions) : await inspectNativeSource(root, framework, sourceOptions);
+  const snapshotContent = json(inspection.snapshot);
+  if (Buffer.byteLength(snapshotContent) > 128 * 1024) fail('The native source snapshot exceeds its bounded integration budget. Split it into a reviewed adapter.');
+  if (snapshotFile.content !== null && (!previous || snapshotFile.content !== snapshotContent)) fail('The frozen native source inventory changed. Review the source adapter before replacing its baseline.');
+  const integrationOptions = { publication: options.publication === true, sourceConfiguration: config };
+  const integration = framework === 'astro' ? await planAstroIntegration(root, integrationOptions) : await planNativeIntegration(root, framework, integrationOptions);
+  const desired = [[SOURCE_CONFIG_FILE, json(config), configFile], [SOURCE_SNAPSHOT_FILE, snapshotContent, snapshotFile]];
+  for (const file of integration.files) desired.push([file.path, file.content, await read(root, file.path)]);
+  const observations = [];
+  for (const file of inspection.sourceFiles) {
+    const observed = await read(root, file.path);
+    if (observed.content === null || contentDigest(observed.content) !== file.sha256) fail('A native source module changed during planning.');
+    if (!desired.some(([name]) => name === file.path)) observations.push([file.path, observed]);
+  }
+  const files = desired.map(([name, content, before]) => Object.freeze({ path: name, state: content === before.content ? 'unchanged' : before.content === null ? 'create' : 'update' }));
+  const plan = Object.freeze({ root, config: Object.freeze(config), framework, routes: inspection.routes, identities: inspection.entries.map(({kind,slug,locale}) => ({kind,slug,locale})), diagnostics: inspection.diagnostics, retainedAdapter: false, files: Object.freeze(files) });
+  plans.set(plan, { root, desired, observations, applied: false });
+  if (options.apply) return { plan, ...await applySourcePlan(plan) };
+  return plan;
+}
+
+/** Returns a reviewable plan by default. apply:true applies precisely that plan. */
+export async function setupSource(directory, options = {}) {
+  if (!plain(options) || Object.keys(options).some(key => !['siteId', 'environmentId', 'websiteOrigin', 'adminOrigin', 'locale', 'apply', 'publication'].includes(key)) || (options.apply !== undefined && typeof options.apply !== 'boolean') || (options.publication !== undefined && typeof options.publication !== 'boolean')) fail('Source setup accepts only public scope, origins, locale and an apply choice.');
+  const root = await projectRoot(directory);
+  const packageFile = await read(root, 'package.json');
+  let manifest;
+  try { manifest = JSON.parse(packageFile.content); if (!plain(manifest)) throw Error(); }
+  catch { fail('A valid website package.json is required for source setup.'); }
+  if (nativeFramework(manifest)) {
+    await inspectSetupFramework(root);
+    return setupAstroSource(root, options, nativeFramework(manifest));
+  }
+  if (manifest.dependencies?.astro || manifest.devDependencies?.astro) {
+    await inspectSetupFramework(root);
+    return setupAstroSource(root, options);
+  }
+  if (!manifest.dependencies?.next && !manifest.devDependencies?.next && (manifest.dependencies?.vite || manifest.devDependencies?.vite)) {
+    await inspectSetupFramework(root);
+    return setupViteSource(root, manifest, packageFile, options);
+  }
+  const appDirectory = await appRoot(root, manifest);
+  const configFile = await read(root, SOURCE_CONFIG_FILE), snapshotFile = await read(root, SOURCE_SNAPSHOT_FILE);
+  let previous;
+  if (configFile.content !== null) {
+    try { previous = validateSourceConfig(JSON.parse(configFile.content)); }
+    catch { fail('The existing source configuration needs manual review. Existing files were preserved.'); }
+    if (json(previous) !== configFile.content) fail('The source configuration was edited. Review it manually before setup.');
+  }
+  if (snapshotFile.content !== null) {
+    let value;
+    try { value = validateSnapshot(JSON.parse(snapshotFile.content)); } catch { fail('The existing source snapshot needs manual review. Existing files were preserved.'); }
+    if (!previous || json(value) !== snapshotFile.content) fail('The source snapshot was edited or is not owned by this setup. Existing files were preserved.');
+  }
+  const config = validateSourceConfig({ version: 1, siteId: options.siteId ?? previous?.siteId, environmentId: options.environmentId ?? previous?.environmentId, websiteOrigin: options.websiteOrigin ?? previous?.websiteOrigin, adminOrigin: options.adminOrigin ?? previous?.adminOrigin, locale: options.locale ?? previous?.locale ?? 'en', skipSlugs: previous?.skipSlugs ?? [], excludedRoutes: previous?.excludedRoutes ?? [], publicStaticPages: true, ...(previous?.exportClosed ? { exportClosed: true } : {}) });
+  const route = `${appDirectory}/api/cms-source/route.ts`;
+  if (await inspect(root, `${appDirectory}/api/cms-source`, true)) {
+    const children = await readdir(path.join(root, appDirectory, 'api/cms-source'));
+    if (children.some(name => name !== 'route.ts')) fail('An existing /api/cms-source adapter was preserved. Integrate createNextSourceHandler with its reviewed base manifest manually; source setup never replaces custom routes.');
+  }
+  await checkGroupedEndpoint(root, appDirectory, route);
+  const routeFile = await read(root, route);
+  let routeContent = sourceRouteTemplate(appDirectory), retainedAdapter = false;
+  if (routeFile.content !== null && (routeFile.content !== routeContent || !previous)) {
+    // A reviewed bridge may keep complete pre-existing public document mappings
+    // while the connector discovers new pages. Only refresh its owned snapshot;
+    // never infer a new scope for custom code or replace that code.
+    if (!previous || previous.skipSlugs.length === 0 || snapshotFile.content === null || configFile.content !== json(config)) fail('An existing /api/cms-source adapter was preserved. Integrate createNextSourceHandler with its reviewed base manifest manually; source setup never replaces custom routes. Changing a custom adapter connection requires manual review.');
+    routeContent = routeFile.content; retainedAdapter = true;
+  }
+  const snapshot = validateSnapshot(await collectSource({ root, locale: config.locale, skipSlugs: config.skipSlugs, excludedRoutes: config.excludedRoutes }));
+  const snapshotContent = json(snapshot);
+  if (Buffer.byteLength(snapshotContent) > MAX_BYTES) fail('The generated source snapshot exceeds the response budget.');
+  const nextPackage = buildHook(manifest), packageContent = JSON.stringify(nextPackage) === JSON.stringify(manifest) ? packageFile.content : json(nextPackage);
+  const desired = [[SOURCE_CONFIG_FILE, json(config), configFile], [SOURCE_SNAPSHOT_FILE, snapshotContent, snapshotFile], [route, routeContent, routeFile], ['package.json', packageContent, packageFile]];
+  const files = desired.map(([file, content, prior]) => Object.freeze({ path: file, state: prior.content === content ? 'unchanged' : prior.content === null ? 'create' : 'update' }));
+  const identities = Object.freeze(snapshot.entries.map(({ kind, slug, locale }) => Object.freeze({ kind, slug, locale })));
+  const plan = Object.freeze({ root, config: Object.freeze(config), identities, diagnostics: snapshot.diagnostics, retainedAdapter, files: Object.freeze(files) });
+  plans.set(plan, { root, desired, applied: false });
+  if (options.apply) return { plan, ...await applySourcePlan(plan) };
+  return plan;
+}
+
+async function recheck(state) {
+  if (state.applied) fail('This source setup plan was already applied. Make a fresh plan.');
+  if (await projectRoot(state.root) !== state.root) fail('The website directory changed after planning.');
+  for (const [file, , before] of state.desired) {
+    const current = await read(state.root, file);
+    if (current.content !== before.content || current.stamp !== before.stamp) fail('A source setup file changed after planning. Existing edits were preserved; rerun setup.');
+  }
+  for (const [file, before] of state.observations ?? []) {
+    const current = await read(state.root, file);
+    if (current.content !== before.content || current.stamp !== before.stamp) fail('A discovered source file changed after planning. Existing edits were preserved; rerun setup.');
+  }
+}
+
+/** Read a prospective source artifact without writing it before user review. */
+export function readPlannedSourceFile(plan, filename) {
+  if (!plan) return undefined;
+  const state = plans.get(plan);
+  if (!state) fail('Use the original source setup plan returned by setup.');
+  return state.desired.find(([file]) => file === filename)?.[1];
+}
+
+export async function validateSourcePlan(plan) {
+  const state = plans.get(plan); if (!state) fail('Use the original source setup plan returned by setup.');
+  await recheck(state); return true;
+}
+
+/** Read only public source defaults; never opens a private environment file. */
+export async function readSourceSettings(directory) {
+  const root = await projectRoot(directory), source = await read(root, SOURCE_CONFIG_FILE);
+  if (source.content === null) return {};
+  let value;
+  try { value = validateSourceConfig(JSON.parse(source.content)); }
+  catch { fail('The saved public source configuration needs manual review.'); }
+  if (json(value) !== source.content) fail('The saved public source configuration was edited. Review it before setup.');
+  return value;
+}
+
+/** Refresh the owned build snapshot without touching an existing source route. */
+export async function syncSource(directory) {
+  const root = await projectRoot(directory), configFile = await read(root, SOURCE_CONFIG_FILE);
+  const manifest = JSON.parse((await read(root, 'package.json')).content);
+  if (manifest.dependencies?.astro || manifest.devDependencies?.astro || nativeFramework(manifest)) {
+    const plan = await setupSource(root);
+    return { ...await applySourcePlan(plan), diagnostics: plan.diagnostics };
+  }
+  if (configFile.content === null) fail('Run setup-source first to configure the public source export.');
+  const config = await readSourceSettings(root), before = await read(root, SOURCE_SNAPSHOT_FILE);
+  if (before.content !== null) {
+    let value;
+    try { value = validateSnapshot(JSON.parse(before.content)); } catch { fail('The source snapshot needs manual review before regeneration.'); }
+    if (json(value) !== before.content) fail('The source snapshot was edited. Review it before regeneration.');
+  }
+  const snapshot = validateSnapshot(await collectSource({ root, locale: config.locale, skipSlugs: config.skipSlugs, excludedRoutes: config.excludedRoutes }));
+  const content = json(snapshot);
+  if (Buffer.byteLength(content) > MAX_BYTES) fail('The generated source snapshot exceeds the response budget.');
+  const plan = Object.freeze({ root, files: Object.freeze([{ path: SOURCE_CONFIG_FILE, state: 'unchanged' }, { path: SOURCE_SNAPSHOT_FILE, state: before.content === content ? 'unchanged' : before.content === null ? 'create' : 'update' }]) });
+  plans.set(plan, { root, desired: [[SOURCE_CONFIG_FILE, configFile.content, configFile], [SOURCE_SNAPSHOT_FILE, content, before]], applied: false });
+  const result = await applySourcePlan(plan);
+  return { ...result, diagnostics: snapshot.diagnostics };
+}
+
+export async function applySourcePlan(plan, { beforeWrite } = {}) {
+  if (beforeWrite !== undefined && typeof beforeWrite !== 'function') fail('Source setup needs a valid final binding check.');
+  const state = plans.get(plan); if (!state) fail('Use the original source setup plan returned by setup.');
+  await recheck(state);
+  const lockPath = path.join(state.root, '.universalcms-source-setup.lock');
+  let lock, lockStat;
+  const temporaryFiles = [];
+  try {
+    try { lock = await open(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+    catch (error) { if (error.code === 'EEXIST') fail('Another source setup is active. Finish it before retrying.'); throw error; }
+    lockStat = await lock.stat(); await recheck(state);
+    // Explicit key-first setup rechecks its separate private binding here, after
+    // the final source scan and under the source lock. Ordinary public-source
+    // setup supplies no guard and never opens private settings.
+    if (beforeWrite) await beforeWrite();
+    const created = [], updated = [];
+    for (const [file, content, before] of state.desired) {
+      if (content === before.content) continue;
+      const segments = file.split('/');
+      for (let index = 1; index < segments.length; index++) {
+        const relative = segments.slice(0, index).join('/');
+        if (!await inspect(state.root, relative, true)) { try { await mkdir(path.join(state.root, relative), { mode: 0o755 }); } catch (error) { if (error.code !== 'EEXIST') throw error; } await inspect(state.root, relative, true); }
+      }
+      const temporary = path.join(state.root, path.dirname(file), `.cms-source-${randomUUID()}.tmp`);
+      const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+      temporaryFiles.push(temporary);
+      try { await handle.writeFile(content, 'utf8'); await handle.sync(); } finally { await handle.close(); }
+      const current = await read(state.root, file);
+      if (current.content !== before.content || current.stamp !== before.stamp) fail('A source setup file changed while saving. Existing edits were preserved.');
+      await rename(temporary, path.join(state.root, file));
+      (before.content === null ? created : updated).push(file);
+    }
+    state.applied = true;
+    return { created, updated, unchanged: state.desired.length - created.length - updated.length };
+  } finally {
+    await lock?.close().catch(() => {});
+    for (const temporary of temporaryFiles) await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; });
+    if (lockStat) { try { const current = await lstat(lockPath); if (current.dev === lockStat.dev && current.ino === lockStat.ino) await unlink(lockPath); } catch { /* Do not remove another operation's lock. */ } }
+  }
+}