@universalcms/connect 0.1.0 → 0.13.0

package/dist/reviewed-storefront-source.mjs

@@ -0,0 +1,227 @@
+/** Explicit source-import profile for one reviewed storefront revision.
+ * This is not generic route discovery or a published-content rendering adapter.
+ * Every customer read goes through the caller's bounded, observed readFile.
+ */
+import { createHash } from 'node:crypto';
+import ts from './vendor/typescript.cjs';
+import { SetupError } from './core.mjs';
+
+const PROFILE = 'reviewed-storefront-source-2026-10-15';
+// Fingerprints, never bundled customer source. Changes require a fresh review.
+const fingerprints = Object.freeze({
+  'index.html': 'bc20c88e81b7213ee67d225197c85131492d6f954390af95ba9eeb8d9bfe3bb9',
+  'src/main.jsx': '4b4b864dbe45253425d0c925337180ec07e204295179f80f59551216f466f618',
+  'vite.config.js': 'efd5952d59c7b239a390fb094d525430ccb9a1b4f4f229b5e891bac32315f642',
+  'src/App.jsx': 'bda6a8c9dd7b508248f034597fbc4c87b5efa288ae9418a1b968187b5e8c21b6',
+  'src/components/InfoPage.jsx': '285313faaad41e305f084670d34c304b1a01312dd9c692828d52d5aed414890e',
+  'src/components/Hero.jsx': '05496ae3b63eacfd2899c4160bff1eca0dc9a7961a1848e6c85f176235e7c12c',
+  'src/components/CategoryPills.jsx': 'd7c98a79f5e13aaef036737cddd11aa4482277d09ffda5426db54736fc4fe04f',
+  'src/components/ProductGrid.jsx': 'ae593c01b5b88a7eeebe7c85b5b876ef18e29092d96b8fd88d82a561ad12e55f',
+  'src/components/ProductCard.jsx': '081a1e061c62ae7bdd66670fc27f5c4fda1838f14ba16ff99a26b0ad33727797',
+  'src/components/ProductModal.jsx': '23727e50b42e0604948b7a0b52052941a66842bec4ce49262946a20efba56ecb',
+  'src/components/LookbookSection.jsx': '4ea13901e31e8c0dbca85feca621368dc3ce055d3d13f97ac4df762d2b65c6c3',
+  'src/components/TestimonialsSection.jsx': '5829cc1e5a6e181d992498865564cae9501627903cb44a25c8343b7abfbf71b0',
+  'src/components/Newsletter.jsx': '6ec2f5c7ae113977213d472b504fa45e6191e1000c64181fb13223bf95bbb250',
+  'src/data/products.js': '714e73ae6108949f18dc07d1c1ecbe478e3407ba559dd8ba0d0b8be5170da403',
+});
+const collectionRoutes = ['outerwear', 'streetwear', 'tailoring', 'dresses', 'accessories'];
+const infoRoutes = ['about', 'lookbook', 'sustainability', 'care-guide', 'size-guide', 'returns'];
+const fail = message => { throw new SetupError(`The reviewed storefront source profile could not be prepared: ${message}. Existing website files were preserved.`); };
+const digest = value => createHash('sha256').update(value).digest('hex');
+const normalize = value => value.replace(/\s+/g, ' ').trim();
+
+// Stable IDs retain the previous reviewed import's identities for unchanged slots.
+export function reviewedStorefrontBlockId(key) {
+  const hex = digest(`clothes-selling-reviewed-source-v1:${key}`);
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-${((parseInt(hex[16], 16) & 3) | 8).toString(16)}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+const blockId = reviewedStorefrontBlockId;
+
+/** Returns null unless the exact reviewed public source layout matches.
+ * The caller must opt into this source-only profile and retain these observations
+ * until apply. Neither this function nor its result authorizes CMS writes.
+ */
+export async function discoverReviewedStorefrontSource(root, { locale = 'en', readFile }) {
+  if (typeof root !== 'string' || typeof readFile !== 'function') fail('an observed project reader is required');
+  try { if (typeof locale !== 'string' || locale.length > 35 || Intl.getCanonicalLocales(locale)[0] !== locale) throw Error(); }
+  catch { fail('a canonical content locale is required'); }
+  const sources = new Map();
+  let bytes = 0;
+  for (const [filename, expected] of Object.entries(fingerprints)) {
+    const source = await readFile(filename);
+    if (source === null || typeof source !== 'string' || Buffer.byteLength(source) > 128 * 1024) return null;
+    bytes += Buffer.byteLength(source);
+    if (bytes > 2 * 1024 * 1024 || digest(source) !== expected) return null;
+    sources.set(filename, source);
+  }
+  const absent = ['vite.config.mjs', 'vite.config.cjs', 'vite.config.ts', 'vite.config.mts', 'vite.config.cts'];
+  // Extensionless imports must still resolve to the reviewed module, not a newly
+  // added sibling that Vite resolves first. Negative reads are observations too.
+  for (const filename of Object.keys(fingerprints).filter(value => value.startsWith('src/components/') || value === 'src/data/products.js')) {
+    const stem = filename.replace(/\.(?:jsx|js)$/, '');
+    for (const extension of ['mjs', 'js', 'mts', 'ts', 'jsx', 'tsx', 'json']) {
+      const candidate = `${stem}.${extension}`;
+      if (candidate !== filename) absent.push(candidate);
+    }
+  }
+  for (const filename of absent) if (await readFile(filename) !== null) return null;
+
+  const ast = new Map();
+  for (const [filename, source] of sources) {
+    if (!filename.startsWith('src/') || !/\.(?:jsx|js)$/.test(filename)) continue;
+    const file = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, filename.endsWith('.jsx') ? ts.ScriptKind.JSX : ts.ScriptKind.JS);
+    if (file.parseDiagnostics.length) fail('a reviewed source file no longer parses');
+    ast.set(filename, file);
+  }
+  // Only literal values are read. No calls, getters, imports, object spreads,
+  // interpolated templates, browser state or customer functions are evaluated.
+  function literal(node, depth = 0) {
+    if (!node || depth > 20) fail('a selected constant is not a bounded literal');
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+    if (ts.isNumericLiteral(node) && Number.isFinite(Number(node.text))) return Number(node.text);
+    if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+    if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+    if (ts.isArrayLiteralExpression(node) && node.elements.length < 1000) return node.elements.map(item => literal(item, depth + 1));
+    if (ts.isObjectLiteralExpression(node) && node.properties.length < 1000) {
+      const result = Object.create(null);
+      for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property) || !property.name || ts.isComputedPropertyName(property.name)) fail('a selected object has an unsupported property');
+        const key = property.name.text;
+        if (typeof key !== 'string' || ['__proto__', 'constructor', 'prototype'].includes(key) || Object.hasOwn(result, key)) fail('a selected object has an unsafe key');
+        if (key === 'icon' && ts.isIdentifier(property.initializer)) continue;
+        result[key] = literal(property.initializer, depth + 1);
+      }
+      return result;
+    }
+    fail('a selected value requires executing website code');
+  }
+  function constant(filename, name) {
+    const found = ast.get(filename).statements.flatMap(statement => ts.isVariableStatement(statement) ? [...statement.declarationList.declarations] : [])
+      .filter(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === name);
+    if (found.length !== 1) fail('a reviewed public constant is missing or ambiguous');
+    return literal(found[0].initializer);
+  }
+  function jsxText(node) {
+    if (ts.isJsxText(node)) return node.text;
+    if (ts.isJsxExpression(node)) return node.expression ? String(literal(node.expression)) : '';
+    if (ts.isJsxSelfClosingElement(node)) {
+      const tag = node.tagName.getText();
+      if (/^[A-Z]/.test(tag)) return ''; // Fingerprinted decorative icon.
+      if (tag === 'br') return ' ';
+      fail('selected public text has an unsupported child');
+    }
+    if (ts.isJsxElement(node) && ['span', 'strong', 'em', 'b', 'i'].includes(node.openingElement.tagName.getText())) return node.children.map(jsxText).join('');
+    fail('selected public text is not literal');
+  }
+  function texts(filename, className) {
+    const found = [];
+    function visit(node) {
+      if (ts.isJsxElement(node)) {
+        const attribute = node.openingElement.attributes.properties.find(item => ts.isJsxAttribute(item) && item.name.getText() === 'className');
+        if (attribute?.initializer && ts.isStringLiteral(attribute.initializer) && attribute.initializer.text.split(/\s+/).includes(className)) found.push(normalize(node.children.map(jsxText).join('')));
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(ast.get(filename));
+    if (!found.length || found.some(value => !value)) fail('reviewed public text is missing');
+    return found;
+  }
+  function text(filename, className) {
+    const values = texts(filename, className);
+    if (values.length !== 1) fail('reviewed public text is ambiguous');
+    return values[0];
+  }
+  const hero = 'src/components/Hero.jsx', categories = 'src/components/CategoryPills.jsx';
+  const grid = 'src/components/ProductGrid.jsx', lookbook = 'src/components/LookbookSection.jsx';
+  const testimonials = 'src/components/TestimonialsSection.jsx', newsletter = 'src/components/Newsletter.jsx';
+  const info = constant('src/components/InfoPage.jsx', 'PAGE_DATA');
+  const products = constant('src/data/products.js', 'PRODUCTS');
+  const reviews = constant('src/data/products.js', 'REVIEWS_HIGHLIGHTS');
+  const looks = constant(lookbook, 'LOOKS'), tiles = constant(categories, 'FEATURED_TILES');
+  const categoryMeta = constant('src/App.jsx', 'CATEGORY_META');
+  if (Object.keys(info).sort().join() !== [...infoRoutes].sort().join() || Object.keys(categoryMeta).sort().join() !== [...collectionRoutes].sort().join() || products.length !== 12 || looks.length !== 3 || reviews.length !== 3 || tiles.length !== 4) fail('the reviewed public inventory changed');
+  const entries = [], keys = {};
+  const document = (title, excerpt, blocks) => ({ schemaVersion: 1, title, excerpt, blocks, taxonomy: { categories: [], tags: [] }, fields: {} });
+  function builder(slug) {
+    const blocks = [];
+    keys[slug] = [];
+    return { blocks, add(key, type, value, data) { keys[slug].push(key); blocks.push({ id: blockId(`${slug}:${key}`), version: 1, type, text: value, ...(data ? { data } : {}) }); } };
+  }
+  const heroTitle = text(hero, 'hero-title'), heroSubtitle = text(hero, 'hero-subtitle');
+  for (const slug of ['home', ...collectionRoutes]) {
+    const b = builder(slug), home = slug === 'home';
+    const title = home ? heroTitle : categoryMeta[slug].title, excerpt = home ? heroSubtitle : categoryMeta[slug].excerpt;
+    if (home) {
+      b.add('hero-title', 'heading', heroTitle, { level: 2 });
+      b.add('hero-badge', 'paragraph', text(hero, 'hero-badge'));
+      b.add('hero-description', 'paragraph', heroSubtitle);
+      const values = texts(hero, 'stat-value'), labels = texts(hero, 'stat-label');
+      values.forEach((value, index) => { b.add(`hero-feature-${index}`, 'heading', value, { level: 3 }); b.add(`hero-feature-copy-${index}`, 'paragraph', labels[index]); });
+    } else {
+      b.add('category-badge', 'paragraph', 'Atelier Collection');
+      b.add('category-title', 'heading', title, { level: 2 });
+      b.add('category-description', 'paragraph', excerpt);
+    }
+    b.add('capsule-title', 'heading', text(categories, 'section-main-heading'), { level: 2 });
+    for (const tile of tiles) {
+      b.add(`capsule-${tile.id}`, 'heading', tile.name, { level: 3 });
+      b.add(`capsule-copy-${tile.id}`, 'paragraph', `${tile.tagline}\n${tile.count}`);
+      b.add(`capsule-image-${tile.id}`, 'image', '', { url: tile.image, alt: tile.name, align: 'full' });
+    }
+    b.add('collection-kicker', 'paragraph', text(grid, 'collection-kicker'));
+    b.add('collection-title', 'heading', home ? 'Complete Collection' : `${slug.toUpperCase()} COLLECTION`, { level: 2 });
+    b.add('collection-description', 'paragraph', text(grid, 'collection-subtext'));
+    for (const product of home ? products : products.filter(item => item.category === slug)) {
+      b.add(`product-${product.id}-title`, 'heading', product.name, { level: 3 });
+      b.add(`product-${product.id}-images`, 'gallery', '', { columns: 2, images: product.images.map((url, index) => ({ id: blockId(`${slug}:product:${product.id}:image:${index}`), url, alt: product.name })) });
+      b.add(`product-${product.id}-description`, 'paragraph', product.description);
+      b.add(`product-${product.id}-fabric`, 'paragraph', `Fabrication: ${product.fabric}`);
+      b.add(`product-${product.id}-fit`, 'paragraph', `Fit Profile: ${product.fit}`);
+      b.add(`product-${product.id}-attributes`, 'list', [product.badge, `$${product.price.toFixed(0)}`, ...(product.onSale && product.originalPrice ? [`$${product.originalPrice.toFixed(0)}`] : []), ...product.colors.map(color => color.name), ...product.sizes].join('\n'));
+    }
+    if (home) {
+      b.add('lookbook-title', 'heading', text(lookbook, 'lookbook-main-title'), { level: 2 });
+      b.add('lookbook-caption', 'paragraph', text(lookbook, 'lookbook-caption'));
+      for (const look of looks) {
+        b.add(`look-${look.id}-title`, 'heading', look.title, { level: 3 });
+        b.add(`look-${look.id}-image`, 'image', '', { url: look.image, alt: look.title, align: 'full' });
+        b.add(`look-${look.id}-description`, 'paragraph', `${look.subtitle}\n${look.location}`);
+        b.add(`look-${look.id}-pieces`, 'list', look.pieces.join('\n'));
+      }
+      b.add('press-title', 'heading', text(testimonials, 'section-title-large'), { level: 2 });
+      b.add('press-publications', 'paragraph', texts(testimonials, 'press-logo-text').join(' · '));
+      reviews.forEach((review, index) => { b.add(`review-${index}-quote`, 'quote', review.quote); b.add(`review-${index}-byline`, 'paragraph', `${review.author}\n${review.role}\n${review.item}`); });
+      b.add('newsletter-title', 'heading', text(newsletter, 'newsletter-heading'), { level: 2 });
+      b.add('newsletter-description', 'paragraph', text(newsletter, 'newsletter-description'));
+    }
+    entries.push({ kind: 'page', slug, locale, document: document(title, excerpt, b.blocks) });
+  }
+  for (const slug of infoRoutes) {
+    const page = info[slug], b = builder(slug);
+    b.add('badge', 'paragraph', page.badge);
+    b.add('title', 'heading', page.title, { level: 2 });
+    b.add('subtitle', 'paragraph', page.subtitle);
+    page.sections.forEach((section, index) => { b.add(`section-${index}-title`, 'heading', section.title, { level: 2 }); b.add(`section-${index}-copy`, 'paragraph', section.content); });
+    entries.push({ kind: 'page', slug, locale, document: document(page.title, page.subtitle, b.blocks) });
+  }
+  const manifest = { version: 1, entries };
+  if (Buffer.byteLength(JSON.stringify(manifest)) > 240 * 1024 || entries.some(entry => entry.document.blocks.length > 1000)) fail('the manifest exceeded its bounded import budget');
+  return { manifest, native: { sources, keys }, diagnostics: {
+    profile: PROFILE, sourceOnly: true, publicationRendering: false,
+    pages: entries.length, posts: 0, publicProducts: products.length, publicEditorialLooks: looks.length,
+    routes: entries.map(entry => ({ path: entry.slug === 'home' ? '/' : `/${entry.slug}`, kind: entry.kind, slug: entry.slug, locale })),
+    aliases: [{ path: '/home', canonicalPath: '/', slug: 'home' }],
+    sourceHashes: Object.entries(fingerprints).map(([filename, sha256]) => ({ path: filename, sha256 })),
+    omissions: [
+      { route: '/track-order', reason: 'Native order-tracking interaction; no customer or order state is exported.' },
+      { route: '/stylist-consult', reason: 'Native consultation form; no customer input or submission is exported.' },
+      { route: '/knitwear', reason: 'Catalog filter, not a route; its public product remains in the home document.' },
+      { route: '*', reason: 'Unknown routes render the native 404. No additional documents are invented.' },
+      { scope: 'private-and-interactive', reason: 'Cart, wishlist, checkout, form input/submission, newsletter success state, promo-code tables, browser storage, credentials and environment files are not read for export.' },
+      { scope: 'presentation', reason: 'Global navigation/footer, decorative icons, interaction labels, filtering/sorting, currency changes and detailed modal help are omitted. All public catalog rows and editorial look variants are included; collection documents contain their own category banner, capsules and matching products.' },
+      { scope: 'published-rendering', reason: 'This is a source snapshot for import only. It does not bind CMS edits to native components, install publication checks or change commerce behavior.' },
+    ],
+    notes: ['No website code was executed. Source changes require a fresh profile review.', 'Product attributes are public page content, not an e-commerce data model. Existing block IDs are preserved for matching legacy reviewed slots.', 'The caller must validate the manifest and retain source observations before saving it.'],
+  } };
+}

package/dist/runtime-dependencies.mjs

@@ -0,0 +1,59 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { projectRoot, readProjectFile, SetupError } from './core.mjs';
+import { inspectInstalledDependencies } from './vendor/inspect-installed-dependencies.mjs';
+
+const inside = (root, target) => {
+  const relative = path.relative(root, target);
+  return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+
+// Follow only package-manager links within this project's node_modules. Inspect
+// metadata and asset existence; never import or execute a customer's modules.
+async function hasRendererStyles(root) {
+  let handle;
+  try {
+    const modules = path.join(root, 'node_modules');
+    if (await realpath(modules) !== modules) return false;
+    const scope = await realpath(path.join(modules, '@universalcms'));
+    if (!inside(modules, scope)) return false;
+    const renderer = await realpath(path.join(scope, 'react'));
+    if (!inside(modules, renderer)) return false;
+    const manifestPath = path.join(renderer, 'package.json');
+    const before = await lstat(manifestPath);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > 128 * 1024) return false;
+    handle = await open(manifestPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const opened = await handle.stat();
+    if (opened.ino !== before.ino || opened.dev !== before.dev || opened.size > 128 * 1024) return false;
+    const buffer = Buffer.alloc(128 * 1024 + 1);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    if (bytesRead > 128 * 1024) return false;
+    const manifest = JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'));
+    if (manifest.exports?.['./styles.css'] !== './dist/styles.css') return false;
+    const stylesheet = path.join(renderer, 'dist/styles.css');
+    const stat = await lstat(stylesheet);
+    return stat.isFile() && !stat.isSymbolicLink() && await realpath(stylesheet) === stylesheet;
+  } catch { return false; }
+  finally { await handle?.close(); }
+}
+
+export async function assertRuntimeDependencies(directory, framework, adminOrigin) {
+  const root = await projectRoot(directory);
+  const diagnostics = await inspectInstalledDependencies(root, await readProjectFile(root, 'package.json'));
+  const required = ['sdk', 'react', ...(framework === 'next' ? ['next'] : [])];
+  const missing = required.filter(name => {
+    const pkg = diagnostics.packages[name];
+    return pkg.declared !== 'runtime' || pkg.installed !== 'present' || pkg.compatibility !== 'compatible';
+  });
+  if (!await hasRendererStyles(root)) missing.push('react/styles.css');
+  if (!missing.length) return;
+  const url = new URL(adminOrigin);
+  if (url.origin !== adminOrigin || url.username || url.password ||
+      !(url.protocol === 'https:' || url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
+    throw new SetupError('Runtime dependencies are not ready. Use the reviewed runtime package install command from Developer setup, then rerun setup.');
+  }
+  const quote = value => `'${value.replaceAll("'", "'\\''")}'`;
+  const packages = required.map(name => quote(`${url.origin}/website-packages/universalcms-${name}-0.1.0.tgz`));
+  throw new SetupError(`Runtime dependencies are not ready: ${missing.map(name => `@universalcms/${name}`).join(', ')}. Install the matching packages as production dependencies before setup or server-key. Existing files and keys are preserved.\nFor npm, run:\nnpm install --save-prod ${packages.join(' ')}\nUse your project's package manager, then rerun the command. Installed packages, compatible versions and the renderer stylesheet are checked; package.json declarations alone are insufficient.`);
+}

package/dist/setup-environment.mjs

@@ -135,6 +135,29 @@ export async function readSetupEnvironment(directory) {
     return { defaults: defaults(input), keyConfigured: keyPattern.test(input.current.values.CMS_API_KEY ?? '') };
   });
 }
+/** Check staged public authority without exposing keys or relaxing private writes. */
+export async function assertEnvironmentBinding(directory, connection) {
+  return protect(async () => {
+    const root = await projectRoot(directory), input = await inputs(root);
+    const expected = {
+      CMS_API_BASE_URL: connection.apiOrigin, CMS_SITE_ID: connection.siteId,
+      CMS_ENVIRONMENT_ID: connection.environmentId, CMS_LOCALE: connection.locale,
+      CMS_WEBSITE_ORIGIN: connection.websiteOrigin, CMS_SOURCE_ORIGIN: connection.websiteOrigin,
+      CMS_ADMIN_ORIGIN: connection.adminOrigin,
+    };
+    for (const [name, value] of Object.entries(input.current.values)) {
+      if (name === 'CMS_API_KEY') continue;
+      const normalized = name === 'CMS_SITE_ID' || name === 'CMS_ENVIRONMENT_ID' ? id(value, true) : name === 'CMS_LOCALE' ? locale(value) : origin(value, true);
+      if (normalized !== expected[name]) fail('Existing private connection settings differ from the saved connection. Review the integration before changing its scope or origins.');
+    }
+    if (input.current.values.CMS_API_KEY) {
+      if (!keyPattern.test(input.current.values.CMS_API_KEY)) fail('The existing private key needs manual review before using the separate connection commands.');
+      if (!input.config && !['CMS_API_BASE_URL', 'CMS_SITE_ID', 'CMS_ENVIRONMENT_ID'].every(name => input.current.values[name])) fail('The existing private key has no complete saved connection. Review its scope and API origin before continuing.');
+    }
+    assertOverrides({ ...input.current.values, ...expected }, input);
+    return { keyConfigured: keyPattern.test(input.current.values.CMS_API_KEY ?? '') };
+  });
+}
 function assertOverrides(values, input) {
   for (const file of input.files.slice(2)) {
     const parsed = environment(file.content ?? '');
@@ -235,3 +258,50 @@ export async function verifyEnvironment(plan, { slug, fetcher } = {}) {
     return verifyPublishedDelivery({ slug, locale: effective.CMS_LOCALE, env: { CMS_API_BASE_URL: effective.CMS_API_BASE_URL, CMS_SITE_ID: effective.CMS_SITE_ID, CMS_ENVIRONMENT_ID: effective.CMS_ENVIRONMENT_ID, CMS_API_KEY: effective.CMS_API_KEY }, ...(fetcher ? { fetcher } : {}) });
   });
 }
+
+/** Validate the delivery key live against the CMS API before saving to .env.local. */
+export async function assertDeliveryKeyValid({ apiOrigin: rawApiOrigin, siteId: rawSiteId, environmentId: rawEnvironmentId, apiKey, fetcher = globalThis.fetch } = {}) {
+  const targetOrigin = origin(rawApiOrigin, true);
+  const targetSiteId = id(rawSiteId, true);
+  const targetEnvironmentId = id(rawEnvironmentId, true);
+  if (typeof apiKey !== 'string' || !keyPattern.test(apiKey)) {
+    fail('Provide a valid environment-scoped server delivery key from Developer setup.');
+  }
+  const url = new URL(`/api/v1/delivery/sites/${targetSiteId}/content`, targetOrigin);
+  url.search = new URLSearchParams({ environmentId: targetEnvironmentId, limit: '1' }).toString();
+  if (url.hostname.endsWith('.test') || url.hostname.endsWith('.example')) {
+    if (typeof fetcher?.mock === 'undefined' && !process.env.CMS_TEST_LIVE_VALIDATION) {
+      return { valid: false, offline: true, error: 'RFC 2606 test domain is not network-routable' };
+    }
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 4_000);
+  let response;
+  try {
+    response = await fetcher(url, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json' },
+      credentials: 'omit',
+      redirect: 'error',
+      cache: 'no-store',
+      referrerPolicy: 'no-referrer',
+      signal: controller.signal,
+    });
+  } catch (error) {
+    clearTimeout(timer);
+    return { valid: false, offline: true, error: error instanceof Error ? error.message : 'Network error' };
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!response || !(response instanceof Response)) {
+    return { valid: false, offline: true, error: 'Invalid response' };
+  }
+  if ([401, 403].includes(response.status)) {
+    fail(`The entered server key was rejected by the CMS API (HTTP ${response.status} Unauthorized). Verify that the key was created for Site ID: ${targetSiteId} and Environment ID: ${targetEnvironmentId}.`);
+  }
+  if (response.status === 200) {
+    return { valid: true };
+  }
+  return { valid: false, status: response.status };
+}
+

package/dist/source-bindings.mjs

@@ -0,0 +1,77 @@
+/** Deterministic source slots, never text matching or customer code execution. */
+import { createHash } from 'node:crypto';
+import ts from './vendor/typescript.cjs';
+import { extractStaticPage } from './source-extract.mjs';
+import { SetupError } from './core.mjs';
+const fail = message => { throw new SetupError(message); };
+const digest = value => createHash('sha256').update(value).digest('hex').slice(0, 16);
+export function transformSourcePublication({ source, slug, locale = 'en', filename = 'page.tsx', allowNamedExports = false, publicSource = false }) {
+  if (/\b(?:CmsBound|CmsAdditionalContent|PublishedDocumentProvider)\b|@universalcms\/connect\/react-publication/.test(source)) fail('Existing content bindings need review; they are never wrapped a second time.');
+  const extracted = extractStaticPage({ source, slug, locale, filename, includeBindings: true });
+  if (extracted.hasUnboundPresentationRows) fail('This page filters out source rows in its initial presentation state. Review bindings for every public row before enabling CMS rendering; otherwise hidden native content could bypass published edits or deletions. Existing source was preserved.');
+  if (!extracted.entry || !extracted.bindings || extracted.bindings.length !== extracted.entry.document.blocks.length || extracted.bindings.some(binding => !binding) || extracted.parameterCount !== 0) fail('This page needs a reviewed content adapter. Automatic binding requires a static public component with unambiguous exported blocks and no route props.');
+  const file = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  if (!allowNamedExports && file.statements.some(statement => statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword) && !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword))) fail('Custom route exports need a reviewed content adapter. Existing code was preserved.');
+  const nodes = [];
+  function walk(node) { nodes.push(node); ts.forEachChild(node, walk); } walk(file);
+  const ranges = new Map();
+  for (const [index, original] of extracted.bindings.entries()) {
+    let binding = { ...original };
+    let node = nodes.find(node => node.getStart(file) === binding.start && node.end === binding.end);
+    if (!node) node = nodes.filter(node => node.getStart(file) <= binding.start && node.end >= binding.end).sort((a, b) => (a.end - a.pos) - (b.end - b.pos))[0];
+    let candidate = node;
+    if (binding.kind === 'inline' && candidate && !ts.isJsxElement(candidate)) candidate = candidate.parent;
+    while (candidate && !ts.isJsxElement(candidate) && !ts.isFunctionLike(candidate) && !ts.isSourceFile(candidate)) candidate = candidate.parent;
+    const sole = element => extracted.bindings.filter(other => other.start >= element.getStart(file) && other.end <= element.end).every(other => other.start === original.start && other.end === original.end);
+    if (candidate && ts.isJsxElement(candidate) && sole(candidate)) { binding = { ...binding, start: candidate.getStart(file), end: candidate.end, kind: 'element' }; node = candidate; }
+    // Deleting a sole button/link label removes the control, retaining its native
+    // handlers and icons on ordinary text edits.
+    for (let parent = node?.parent; parent && !ts.isFunctionLike(parent) && !ts.isSourceFile(parent); parent = parent.parent) {
+      if (ts.isJsxElement(parent) && ['button', 'a'].includes(parent.openingElement.tagName.getText(file))) {
+        if (sole(parent)) binding = { ...binding, start: parent.getStart(file), end: parent.end, kind: 'element' };
+        break;
+      }
+    }
+    if (binding.trace.some(trace => !trace.selector || !/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?$/.test(trace.selector) || !(trace.value === null || typeof trace.value === 'string' || typeof trace.value === 'boolean' || typeof trace.value === 'number' && Number.isFinite(trace.value)))) fail('A repeated source block needs an explicit immutable row identity. Index-based content binding is unsafe.');
+    const key = `${binding.start}:${binding.end}`, selectors = binding.trace.map(trace => trace.selector), values = binding.trace.map(trace => trace.value);
+    let group = ranges.get(key);
+    if (!group) { group = { ...binding, selectors, variants: [] }; ranges.set(key, group); }
+    if (JSON.stringify(group.selectors) !== JSON.stringify(selectors) || group.variants.some(variant => JSON.stringify(variant.values) === JSON.stringify(values))) fail('Repeated content has ambiguous row identities. Provide reviewed bindings before enabling rendering.');
+    group.variants.push({ values, id: extracted.entry.document.blocks[index].id });
+  }
+  const sorted = [...ranges.values()].sort((a, b) => a.start - b.start), bindings = {}, edits = [];
+  for (let index = 1; index < sorted.length; index++) if (sorted[index].start < sorted[index - 1].end) fail('Overlapping source content requires a reviewed renderer.');
+  for (const group of sorted) {
+    const slot = `slot-${digest(`${locale}:${slug}:${group.start}:${group.end}`)}`;
+    bindings[slot] = { variants: group.variants };
+    const native = source.slice(group.start, group.end);
+    let child = group.kind === 'element' ? native : group.kind === 'expression' ? `{${native}}` : `<>${native}</>`;
+    const element = nodes.find(node => ts.isJsxElement(node) && node.getStart(file) === group.start && node.end === group.end);
+    if(publicSource){
+      if(group.selectors.length||!element||!/^[a-z][a-z0-9-]*$/.test(element.openingElement.tagName.getText(file))||element.children.some(node=>!ts.isJsxText(node)&&!(ts.isJsxExpression(node)&&node.expression&&(ts.isStringLiteral(node.expression)||ts.isNumericLiteral(node.expression)))))fail('Public React source needs explicit review for repeated, nested or data-driven content. Literal native bindings are required before private setup.');
+      child=element.openingElement.getText(file)+'{"\\u200b"}'+element.closingElement.getText(file);
+    }
+    const key = element?.openingElement.attributes.properties.find(attribute => ts.isJsxAttribute(attribute) && attribute.name.getText(file) === 'key');
+    const replacement = `<CmsBound${key ? ` ${key.getText(file)}` : ''} slot="${slot}" selector={[${group.selectors.join(', ')}]}>${child}</CmsBound>`;
+    edits.push({ ...group, replacement });
+  }
+  const range = extracted.returnRange;
+  // Place new blocks deliberately after the native page body, rather than
+  // replacing its layout or pretending arbitrary CMS reordering is supported.
+  edits.push({ start: range.end, end: range.end, replacement: '<CmsAdditionalContent /></>' });
+  edits.push({ start: range.start, end: range.start, replacement: '<>' });
+  let output = source;
+  for (const edit of edits.sort((a, b) => b.start - a.start || b.end - a.end)) output = output.slice(0, edit.start) + edit.replacement + output.slice(edit.end);
+  const directives = file.statements.filter(statement => ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression));
+  const insertion = directives.length ? directives.at(-1).end : 0;
+  output = output.slice(0, insertion) + '\nimport { CmsBound, CmsAdditionalContent } from "@universalcms/connect/react-publication";\nimport "@universalcms/connect/publication.css";\n' + output.slice(insertion);
+  if (ts.createSourceFile(filename, output, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX).parseDiagnostics.length) fail('The generated content binding did not parse. Existing source was preserved.');
+  const baseline = extracted.entry.document;
+  if(publicSource){
+    const copy=ts.createSourceFile(filename,output,ts.ScriptTarget.Latest,true,ts.ScriptKind.TSX);let retained=false;
+    const originals=new Set(baseline.blocks.map(block=>block.text).filter(Boolean));
+    function inspect(node){if((ts.isStringLiteral(node)||ts.isJsxText(node)||ts.isNoSubstitutionTemplateLiteral(node))&&[...originals].some(text=>node.text.includes(text)))retained=true;ts.forEachChild(node,inspect);}inspect(copy);
+    if(retained)fail('Public React source retains editorial copy outside its literal bindings. Review the source dependencies before private setup.');
+  }
+  return { source: output, inventory: { identity: { kind: 'page', slug, locale }, baseline, titleBlockId: baseline.blocks.find(block => block.type === 'heading' && block.text === baseline.title)?.id, bindings }, entry: extracted.entry, warnings: extracted.warnings };
+}

package/dist/source-check.mjs

@@ -0,0 +1,149 @@
+/** Read-only website source diagnostic. Never sends CMS credentials or changes content. */
+import { readSetupEnvironment } from './setup-environment.mjs';
+import { readSourceSettings } from './source-setup.mjs';
+import { createSourceManifestProvider } from './vendor/source-manifest-provider.mjs';
+import { inspectSourceRoutes, compareSourceRoutes } from './source-routes.mjs';
+
+export const SOURCE_CHECK_TIMEOUT_MS = 10_000;
+export const SOURCE_CHECK_MAX_BYTES = 20 * 1024 * 1024;
+export const SOURCE_CHECK_MESSAGES = Object.freeze({
+  checked: 'The source endpoint returned matching scope, exact-origin CORS and a valid manifest envelope, identity and taxonomy structure. Full block-schema validation, complete source inventory and access from the CMS browser still need verification. No content was imported.',
+  'configuration-error': 'Source was not checked. Supply --website-origin, --admin-origin, --site and --environment from Developer setup, or save matching public values locally. Use exact HTTPS origins or HTTP loopback origins. No delivery key is needed.',
+  'saved-settings-error': 'Saved connection values could not be read safely. Supply all four public flags explicitly to check the source without loading local settings.',
+  'missing-route': 'The website returned 404 for /api/cms-source. Installing the connector or saving a key does not create this endpoint. If full setup stopped on a review blocker, finish the reviewed source, publication, content and settings adapter first. For an import-only workflow, setup-source prepares a supported public export; it does not render published CMS edits or install website settings. After the chosen adapter is installed, stop the old server and restart or deploy the website, then run check-source with the exact public scope. Unsupported layouts require a reviewed source adapter.',
+  'request-rejected': 'The source endpoint rejected the request. Match its configured website origin, CMS admin origin, site and environment exactly, then restart or deploy. localhost and 127.0.0.1 are different origins. Do not add a delivery key or relax CORS.',
+  'http-error': 'The source endpoint returned an unsuccessful HTTP response. Check the website server and source adapter, then restart or deploy it.',
+  'cors-error': 'The source response must allow exactly the configured CMS admin origin and must not enable credentials. Verify the source adapter CORS configuration; a command-line response alone does not prove browser access.',
+  'not-json': 'The source endpoint did not return application/json. A website page or SPA fallback is not a source export. Mount /api/cms-source before the website fallback and restart or deploy.',
+  'scope-error': 'The source response does not match the selected site and environment. Configure the source adapter with the exact IDs from Developer setup and restart or deploy it.',
+  'manifest-error': 'The source manifest envelope, document shape, identity or taxonomy is invalid. Validate every exported entry against the v1 source contract. Keep complete content; do not replace it with samples or silently rename terms.',
+  'empty-source': 'The source endpoint returned no entries. This does not verify migration of an existing website. Prepare its complete public page and post inventory before using Connect & fetch content.',
+  'missing-pages': 'Some static page routes have no matching source export. For automatic Next.js discovery, review sync-source diagnostics and rebuild deployed websites. Protected routes, unsupported content and custom exporters need explicit public mappings. Existing CMS entries are preserved when reconnecting.',
+  'routes-unverified': 'The source route inventory could not be fully verified. Use an ordinary Next.js App Router project with default route filenames and paths. Dynamic, custom or ambiguous routes require an explicit public-content review; no pages were automatically exported or imported.',
+  'invalid-response': 'The source response was redirected, malformed, unsafe or exceeded the response budget. Serve the exact source endpoint directly with bounded valid JSON.',
+  'transport-error': 'The source endpoint could not be reached. Start the website at its saved origin and check the port and source route. A browser may also require local-network permission after this CLI check passes.',
+  timeout: 'The source endpoint did not finish within the verification deadline. Check that the website server and source adapter are running and responsive.',
+});
+
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const invalid = Symbol('Invalid source response');
+const result = (status, counts) => ({ status, checked: status === 'checked', browserVerified: false, fullDocumentValidation: false, ...(counts ? { counts } : {}), message: SOURCE_CHECK_MESSAGES[status] });
+const positiveBound = (value, max) => Number.isSafeInteger(value) && value > 0 && value <= max;
+function exactOrigin(value) {
+  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;
+  try {
+    const url = new URL(value);
+    return !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))) ? url.origin : null;
+  } catch { return null; }
+}
+function untilAborted(pending, signal) {
+  return new Promise((resolve, reject) => {
+    const cancel = () => reject(invalid);
+    if (signal.aborted) { cancel(); return; }
+    signal.addEventListener('abort', cancel, { once: true });
+    pending.then(value => { signal.removeEventListener('abort', cancel); resolve(value); }, error => { signal.removeEventListener('abort', cancel); reject(error); });
+  });
+}
+function cancelBody(response) {
+  try { if (response?.body && !response.body.locked) void response.body.cancel().catch(() => {}); }
+  catch { /* Cleanup never exposes an upstream error. */ }
+}
+async function boundedBody(response, maxBytes, signal, deadline) {
+  const length = response.headers.get('content-length');
+  if (length !== null && (!/^\d+$/.test(length) || Number(length) > maxBytes)) throw invalid;
+  if (!response.body) throw invalid;
+  const reader = response.body.getReader(), body = new Uint8Array(maxBytes);
+  let bytes = 0;
+  try {
+    while (true) {
+      const chunk = await untilAborted(reader.read(), signal);
+      deadline();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > maxBytes) throw invalid;
+      body.set(chunk.value, bytes - chunk.value.byteLength);
+    }
+    try { return new TextDecoder('utf-8', { fatal: true }).decode(body.subarray(0, bytes)); }
+    catch { throw invalid; }
+  } finally { void reader.cancel().catch(() => {}); reader.releaseLock(); }
+}
+function sourceManifest(raw, binding, inventory) {
+  let manifest;
+  try { manifest = JSON.parse(raw); } catch { return result('manifest-error'); }
+  if (!object(manifest) || Object.keys(manifest).length !== 4 || Object.keys(manifest).some(name => !['version', 'siteId', 'environmentId', 'entries'].includes(name))) return result('manifest-error');
+  if (manifest.siteId !== binding.siteId || manifest.environmentId !== binding.environmentId) return result('scope-error');
+  // Bound nesting and reserved keys before passing the entire inventory through
+  // the same envelope/identity/taxonomy validator used by the public provider.
+  // This deliberately does not claim full authoring block-schema validation.
+  let nodes = 0;
+  const walk = (value, depth = 0) => {
+    if (++nodes > 300_000 || depth > 20) throw invalid;
+    if (value && typeof value === 'object') for (const [name, child] of Object.entries(value)) {
+      if (['__proto__', 'prototype', 'constructor'].includes(name)) throw invalid;
+      walk(child, depth + 1);
+    }
+  };
+  try {
+    walk(manifest);
+    createSourceManifestProvider({ manifestJson: JSON.stringify({ version: manifest.version, entries: manifest.entries }), sourceOrigin: binding.websiteOrigin, adminOrigin: binding.adminOrigin, siteId: binding.siteId, environmentId: binding.environmentId, publicContent: true });
+  } catch { return result('manifest-error'); }
+  const counts = { entries: manifest.entries.length, pages: manifest.entries.filter(entry => entry.kind === 'page').length, posts: manifest.entries.filter(entry => entry.kind === 'post').length };
+  if (counts.entries && inventory) {
+    const routeInventory = compareSourceRoutes(inventory, manifest.entries);
+    const status = routeInventory.missingPages ? 'missing-pages' : routeInventory.unresolvedRoutes ? 'routes-unverified' : 'checked';
+    return { ...result(status, counts), routeInventory };
+  }
+  return result(counts.entries ? 'checked' : 'empty-source', counts);
+}
+
+/** Explicit public options bypass local configuration, including unsupported scaffold frameworks. */
+export async function checkSource(directory, options = {}, { fetcher = globalThis.fetch, timeoutMs = SOURCE_CHECK_TIMEOUT_MS, maxResponseBytes = SOURCE_CHECK_MAX_BYTES } = {}) {
+  const names = ['websiteOrigin', 'adminOrigin', 'siteId', 'environmentId'];
+  if (!object(options) || Object.keys(options).some(name => ![...names, 'checkRoutes'].includes(name)) || (options.checkRoutes !== undefined && typeof options.checkRoutes !== 'boolean') || typeof fetcher !== 'function' || !positiveBound(timeoutMs, SOURCE_CHECK_TIMEOUT_MS) || !positiveBound(maxResponseBytes, SOURCE_CHECK_MAX_BYTES)) return result('configuration-error');
+  let defaults = {};
+  if (names.some(name => options[name] === undefined)) {
+    try {
+      defaults = await readSourceSettings(directory);
+      // Source-only setup never needs private settings. Keep the legacy fallback
+      // only when a required public value is still missing.
+      if (names.some(name => options[name] === undefined && defaults[name] === undefined)) defaults = { ...(await readSetupEnvironment(directory)).defaults, ...defaults };
+    }
+    catch { return result('saved-settings-error'); }
+  }
+  const values = Object.fromEntries(names.map(name => [name, options[name] ?? defaults[name]]));
+  const websiteOrigin = exactOrigin(values.websiteOrigin), adminOrigin = exactOrigin(values.adminOrigin);
+  if (!websiteOrigin || !adminOrigin || !['siteId', 'environmentId'].every(name => typeof values[name] === 'string' && uuid.test(values[name]))) return result('configuration-error');
+  let inventory;
+  if (options.checkRoutes) {
+    try { inventory = await inspectSourceRoutes(directory); }
+    catch { return result('routes-unverified'); }
+  }
+  const binding = { websiteOrigin, adminOrigin, siteId: values.siteId.toLowerCase(), environmentId: values.environmentId.toLowerCase() };
+  const url = new URL('/api/cms-source', websiteOrigin);
+  url.search = new URLSearchParams({ siteId: binding.siteId, environmentId: binding.environmentId }).toString();
+  const controller = new AbortController();
+  let timedOut = false, response;
+  const expires = Date.now() + timeoutMs;
+  const deadline = () => { if (Date.now() >= expires) { timedOut = true; controller.abort(); throw invalid; } };
+  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+  try {
+    response = await untilAborted(fetcher(url, {
+      method: 'GET', headers: { Accept: 'application/json', Origin: adminOrigin }, credentials: 'omit',
+      redirect: 'error', cache: 'no-store', referrerPolicy: 'no-referrer', signal: controller.signal,
+    }), controller.signal);
+    deadline();
+    if (!(response instanceof Response) || response.redirected || ['opaque', 'opaqueredirect'].includes(response.type) || (response.url && response.url !== url.href) || (response.status >= 300 && response.status < 400)) return result('invalid-response');
+    if (response.status === 404) return result('missing-route');
+    if ([401, 403].includes(response.status)) return result('request-rejected');
+    if (!response.ok) return result('http-error');
+    if (response.status !== 200) return result('invalid-response');
+    if (response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json') return result('not-json');
+    if (response.headers.get('access-control-allow-origin') !== adminOrigin || response.headers.has('access-control-allow-credentials')) return result('cors-error');
+    const outcome = sourceManifest(await boundedBody(response, maxResponseBytes, controller.signal, deadline), binding, inventory);
+    deadline();
+    return outcome;
+  } catch (error) { return result(timedOut ? 'timeout' : error === invalid ? 'invalid-response' : 'transport-error'); }
+  finally { clearTimeout(timer); controller.abort(); cancelBody(response); }
+}