@universalcms/connect 0.0.0-stage → 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

@@ -0,0 +1,307 @@
+import { constants } from 'node:fs';
+import { lstat, open, rename, unlink } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify, parseEnv } from 'node:util';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { projectRoot, readProjectFile, validateConfig, CONFIG_FILE, SetupError } from './core.mjs';
+import { verifyPublishedDelivery } from './vendor/check-delivery.mjs';
+
+const run = promisify(execFile);
+const plans = new WeakMap();
+const maxFileBytes = 128 * 1024;
+const names = ['CMS_API_BASE_URL', 'CMS_SITE_ID', 'CMS_ENVIRONMENT_ID', 'CMS_LOCALE', 'CMS_API_KEY', 'CMS_WEBSITE_ORIGIN', 'CMS_SOURCE_ORIGIN', 'CMS_ADMIN_ORIGIN'];
+const managed = new Set(names);
+const modes = ['.env.development', '.env.development.local', '.env.production', '.env.production.local'];
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// Tokens encode organization/key IDs. Only an authenticated delivery read can
+// establish whether a credential authorizes the selected site/environment.
+const keyPattern = /^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 fail = message => { throw new SetupError(message); };
+async function protect(action) {
+  try { return await action(); }
+  catch (error) { if (error instanceof SetupError) throw error; fail('Private setup settings could not be inspected or saved. Check ordinary files and permissions; no credential details are displayed.'); }
+}
+function origin(value, required = false) {
+  if ((value === undefined || value === '') && !required) return undefined;
+  try {
+    if (typeof value !== 'string' || /[\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 an HTTPS origin without credentials, path or query (HTTP loopback is allowed for local development).'); }
+}
+function id(value, required = false) {
+  if ((value === undefined || value === '') && !required) return undefined;
+  if (typeof value !== 'string' || !uuid.test(value)) fail('Use valid website and environment UUIDs from Developer setup.');
+  return value.toLowerCase();
+}
+function locale(value) {
+  if (value === undefined || value === '') return undefined;
+  try {
+    if (typeof value !== 'string' || value.length > 35 || /[\s\\]/.test(value)) throw Error();
+    const result = Intl.getCanonicalLocales(value)[0]; if (!result) throw Error(); return result;
+  } catch { fail('Use a valid content locale.'); }
+}
+function metadata(stat) { return [stat.dev, stat.ino, stat.mode, stat.nlink, stat.size, stat.mtimeMs, stat.ctimeMs]; }
+async function snapshot(root, file) {
+  let before;
+  try { before = await lstat(path.join(root, file)); } catch (error) { if (error.code === 'ENOENT') return { file, content: null, metadata: null, mode: null }; throw error; }
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1) fail('Private setup files must be ordinary files with no symbolic links or hard links.');
+  const content = await readProjectFile(root, file), after = await lstat(path.join(root, file));
+  if (JSON.stringify(metadata(before)) !== JSON.stringify(metadata(after))) fail('A setup file changed during inspection. Retry setup.');
+  return { file, content, metadata: metadata(after), mode: after.mode & 0o777 };
+}
+function environment(source = '') {
+  if (source.includes('\0')) fail('The environment file contains ambiguous data. Review it manually before setup.');
+  const parsed = parseEnv(source), assignments = new Map();
+  const lines = source.match(/[^\r\n]*(?:\r\n|\n|\r|$)/g).filter(Boolean);
+  for (let index = 0; index < lines.length; index++) {
+    const raw = lines[index], ending = /(?:\r\n|\n|\r)$/.exec(raw)?.[0] ?? '', line = raw.slice(0, raw.length - ending.length);
+    const candidate = /^\s*(?:export\s+)?(CMS_[A-Z_]+)\b/.exec(line);
+    if (!candidate || !managed.has(candidate[1])) continue;
+    const match = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(\s*=\s*)(.*)$/.exec(line);
+    if (!match || assignments.has(match[2])) fail('Duplicate or ambiguous managed CMS assignments require manual review before setup.');
+    const value = match[4]; let tail = '', literal;
+    if (value.startsWith('"') || value.startsWith("'")) {
+      const quote = value[0], end = value.indexOf(quote, 1);
+      if (end < 0 || value.slice(1, end).includes('\\')) fail('Multiline or escaped managed CMS values require manual review before setup.');
+      literal = value.slice(0, end + 1); tail = value.slice(end + 1);
+      if (!/^\s*(?:#.*)?$/.test(tail)) fail('An ambiguous managed CMS value requires manual review before setup.');
+    } else {
+      if (value.includes('`') || value.includes('\\')) fail('An ambiguous managed CMS value requires manual review before setup.');
+      const comment = value.indexOf('#'), body = comment < 0 ? value : value.slice(0, comment);
+      literal = body.trimEnd(); tail = body.slice(literal.length) + (comment < 0 ? '' : value.slice(comment));
+    }
+    const isolated = parseEnv(`${match[2]}=${literal}`)[match[2]];
+    if (typeof isolated !== 'string' || parsed[match[2]] !== isolated) fail('An ambiguous managed CMS assignment requires manual review before setup.');
+    assignments.set(match[2], { index, prefix: match[1], equals: match[3], tail, ending });
+  }
+  for (const name of names) if (Object.hasOwn(parsed, name) && !assignments.has(name)) fail('Managed CMS values could not be read unambiguously. Review the environment file manually.');
+  return { values: Object.fromEntries(names.filter(name => Object.hasOwn(parsed, name)).map(name => [name, parsed[name]])), allValues: parsed, assignments, lines };
+}
+function renderEnvironment(source, parsed, values) {
+  const lines = [...parsed.lines], ending = source.includes('\r\n') ? '\r\n' : '\n';
+  const appended = [];
+  for (const [name, value] of Object.entries(values)) {
+    // All values were validated into a quote/control-free ASCII form.
+    const assignment = parsed.assignments.get(name), quoted = `"${value}"`;
+    if (assignment) lines[assignment.index] = `${assignment.prefix}${name}${assignment.equals}${quoted}${assignment.tail}${assignment.ending}`;
+    else appended.push(`${name}=${quoted}${ending}`);
+  }
+  const existing = lines.join('');
+  return existing + (appended.length && existing && !/[\r\n]$/.test(existing) ? ending : '') + appended.join('');
+}
+async function assertUntracked(root) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')));
+  Object.assign(env, { LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0', GIT_CONFIG_NOSYSTEM: '1' });
+  try {
+    await run('git', ['-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', '-c', 'core.hooksPath=/dev/null', '-C', root, 'ls-files', '--error-unmatch', '--', '.env.local'], { env, timeout: 5000, maxBuffer: 16 * 1024 });
+  } catch (error) {
+    if (error.code === 1 || (error.code === 128 && /not a git repository/.test(error.stderr ?? ''))) return;
+    fail('Git tracking could not be checked safely. Install Git and resolve repository errors before saving private settings.');
+  }
+  fail('The private .env.local file is already tracked by Git. Remove it from tracking and review exposed credentials before setup can save a key.');
+}
+async function inputs(root) {
+  const files = await Promise.all(['.env.local', '.gitignore', ...modes].map(file => snapshot(root, file)));
+  const rawConfig = await readProjectFile(root, CONFIG_FILE);
+  let config;
+  if (rawConfig !== null) {
+    try { config = validateConfig(JSON.parse(rawConfig)); }
+    catch { fail('The existing CMS connection configuration needs manual review before setup.'); }
+  }
+  return { files, config, rawConfig, current: environment(files[0].content ?? '') };
+}
+function defaults(input) {
+  const value = input.current.values, config = input.config;
+  // An old placeholder may be replaced interactively. Never echo invalid saved
+  // text in a prompt, especially credentials disguised as a nonsecret value.
+  const available = read => { try { return read(); } catch { return undefined; } };
+  const result = {
+    apiOrigin: available(() => origin(value.CMS_API_BASE_URL || config?.apiOrigin)),
+    siteId: available(() => id(value.CMS_SITE_ID || config?.siteId)),
+    environmentId: available(() => id(value.CMS_ENVIRONMENT_ID || config?.environmentId)),
+    locale: available(() => locale(value.CMS_LOCALE || config?.locale)),
+    websiteOrigin: available(() => origin(value.CMS_WEBSITE_ORIGIN || value.CMS_SOURCE_ORIGIN)),
+    adminOrigin: available(() => origin(value.CMS_ADMIN_ORIGIN)),
+  };
+  return Object.fromEntries(Object.entries(result).filter(([, value]) => value !== undefined));
+}
+export async function readSetupEnvironment(directory) {
+  return protect(async () => {
+    const root = await projectRoot(directory), input = await inputs(root);
+    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 ?? '');
+    for (const [name, value] of Object.entries(parsed.values)) if (value !== values[name]) fail('Mode-specific environment files contain conflicting CMS settings. Review development/production overrides before continuing.');
+  }
+  for (const name of names) if (process.env[name] !== undefined && process.env[name] !== values[name]) fail('The current process has conflicting CMS environment variables. Clear those overrides or use matching values before continuing.');
+}
+export async function planEnvironment(directory, options) {
+  return protect(async () => {
+    if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).some(name => !['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin', 'apiKey'].includes(name))) fail('Private setup received unsupported configuration fields.');
+    const root = await projectRoot(directory), input = await inputs(root);
+    await assertUntracked(root);
+    const apiKey = options.apiKey === undefined ? input.current.values.CMS_API_KEY : options.apiKey;
+    if (typeof apiKey !== 'string' || !keyPattern.test(apiKey)) fail('Provide a valid environment-scoped server delivery key from Developer setup.');
+    const values = { CMS_API_BASE_URL: origin(options.apiOrigin, true), CMS_SITE_ID: id(options.siteId, true), CMS_ENVIRONMENT_ID: id(options.environmentId, true), CMS_LOCALE: locale(options.locale ?? 'en'), CMS_API_KEY: apiKey };
+    if (!values.CMS_LOCALE) fail('Use a valid content locale.');
+    if (options.websiteOrigin !== undefined) { values.CMS_WEBSITE_ORIGIN = origin(options.websiteOrigin, true); values.CMS_SOURCE_ORIGIN = values.CMS_WEBSITE_ORIGIN; }
+    if (options.adminOrigin !== undefined) values.CMS_ADMIN_ORIGIN = origin(options.adminOrigin, true);
+    const effective = { ...input.current.values, ...values };
+    assertOverrides(effective, input);
+    const envContent = renderEnvironment(input.files[0].content ?? '', input.current, values);
+    if (Buffer.byteLength(envContent, 'utf8') > maxFileBytes) fail('The generated private environment file would exceed the setup read limit. Reduce the existing file before continuing.');
+    // Unclosed quotes in unrelated settings can change meaning when the new
+    // quoted CMS values are appended. Verify the entire effective environment,
+    // including every unrelated value, before producing an applicable plan.
+    const expected = { ...input.current.allValues, ...values }, rendered = environment(envContent).allValues;
+    if (Object.keys(expected).length !== Object.keys(rendered).length || Object.entries(expected).some(([name, value]) => rendered[name] !== value)) fail('The generated environment would change unrelated settings or hide CMS values. Review ambiguous quoting before setup.');
+    const ignore = input.files[1].content ?? '', ending = ignore.includes('\r\n') ? '\r\n' : '\n';
+    // The temporary credential file is ignored before it is created as well.
+    const protection = '/.universalcms-private-*.tmp' + ending + '/.env.local' + ending;
+    const separator = ignore && !ignore.endsWith('\n') ? (ignore.endsWith('\r') ? '\n' : ending) : '';
+    const ignoreContent = ignore.endsWith(protection) ? ignore : ignore + separator + protection;
+    if (Buffer.byteLength(ignoreContent, 'utf8') > maxFileBytes) fail('The generated ignore file would exceed the setup read limit. Reduce the existing file before continuing.');
+    const updates = [
+      { ...input.files[1], next: ignoreContent, nextMode: input.files[1].mode ?? 0o644 },
+      { ...input.files[0], next: envContent, nextMode: 0o600 },
+    ];
+    const files = updates.map(file => Object.freeze({ path: file.file, action: file.content === file.next && file.mode === file.nextMode ? 'unchanged' : file.content === null ? 'create' : 'update' }));
+    const plan = Object.freeze({ files: Object.freeze(files), keyConfigured: true, preservesExistingKey: options.apiKey === undefined });
+    plans.set(plan, { root, input, updates, effective, applied: false });
+    return plan;
+  });
+}
+function privatePlan(plan) { const state = plans.get(plan); if (!state) fail('Use the original private environment plan returned by setup.'); return state; }
+async function checkRoot(root) {
+  if (await projectRoot(root) !== root) fail('The project location changed after planning. Run setup again from its ordinary directory.');
+}
+async function recheck(state) {
+  if (state.applied) fail('This private environment plan has already been applied. Create a fresh plan to make another change.');
+  await checkRoot(state.root);
+  await assertUntracked(state.root);
+  const current = await inputs(state.root);
+  if (current.rawConfig !== state.input.rawConfig || current.files.some((file, index) => file.content !== state.input.files[index].content || JSON.stringify(file.metadata) !== JSON.stringify(state.input.files[index].metadata))) fail('Setup files changed after planning. No stale settings will be saved; run setup again.');
+  assertOverrides(state.effective, current);
+}
+export async function validateEnvironmentPlan(plan) { return protect(async () => { await recheck(privatePlan(plan)); return true; }); }
+async function replaceFile(root, update) {
+  await checkRoot(root);
+  const temporary = path.join(root, `.universalcms-private-${randomBytes(12).toString('hex')}.tmp`);
+  let handle;
+  try {
+    handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, update.nextMode);
+    await handle.chmod(update.nextMode); await handle.writeFile(update.next, 'utf8'); await handle.sync(); await handle.close(); handle = undefined;
+    const current = await snapshot(root, update.file);
+    if (current.content !== update.content || JSON.stringify(current.metadata) !== JSON.stringify(update.metadata)) fail('A setup file changed while saving. Retry setup after reviewing the current files.');
+    if (update.file === '.env.local') await assertUntracked(root);
+    await checkRoot(root);
+    await rename(temporary, path.join(root, update.file));
+  } finally { await handle?.close().catch(() => {}); await unlink(temporary).catch(() => {}); }
+}
+export async function applyEnvironment(plan) {
+  return protect(async () => {
+    const state = privatePlan(plan), lockPath = path.join(state.root, '.universalcms-setup.lock');
+    await checkRoot(state.root);
+    let lock, lockStat;
+    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 setup operation holds the private-settings lock. Finish that operation before retrying.'); throw error; }
+      lockStat = await lock.stat();
+      await recheck(state);
+      const changed = [];
+      // Establish ignore protection first. Each file is atomically replaced;
+      // competing setup wizards serialize, and manual edits are rechecked.
+      for (const update of state.updates) if (update.content !== update.next || update.mode !== update.nextMode) { await replaceFile(state.root, update); changed.push(update.file); }
+      state.applied = true;
+      return { changed, keyConfigured: true };
+    } finally {
+      await lock?.close().catch(() => {});
+      if (lockStat) {
+        try { const current = await lstat(lockPath); if (current.dev === lockStat.dev && current.ino === lockStat.ino) await unlink(lockPath); } catch { /* Never remove someone else's replacement lock. */ }
+      }
+    }
+  });
+}
+export async function verifyEnvironment(plan, { slug, fetcher } = {}) {
+  return protect(async () => {
+    const { effective } = privatePlan(plan);
+    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 };
+}
+