@universalcms/connect 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @universalcms/connect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local, deterministic website setup without AI. Universal CMS stays hosted; this
+package creates a website integration, not a CMS installation. Version 0.1.0 is
+a local prerelease; no public npm publication is claimed.
+
+Supported templates: **Next.js 16 App Router on Node** and **React 19.2+ with
+Vite 6/7/8 plus a private Node server**. Use Node 22.12 or newer (below 27).
+Stable exact, caret and tilde version declarations are recognized. Workspaces,
+Pages Router, static Next exports, dynamic Next configuration, Cache Components,
+custom page extensions/base paths, route groups and
+ambiguous framework evidence require manual review. Analyze the individual
+website folder, not its parent workspace.
+
+Install the reviewed connector tarball from your operator:
+
+```sh
+npm install --save-prod ./vendor/universalcms-connect-0.1.0.tgz
+npx --no-install universalcms-connect setup
+```
+
+Guided setup asks for the API origin, website/environment IDs, locale and a
+hidden server delivery key. Vite also needs the website origin; existing servers
+that use the CMS admin origin are prompted for it. Values provided through the
+CMS's generated command are already filled in. Saved values can be accepted
+with Enter, and an existing saved key can be kept without displaying it.
+
+After one file-summary confirmation it writes `.env.local` with owner-only
+permissions, excludes that file from Git and creates the framework scaffold.
+Reruns can replace connection values in unchanged generated files and the
+private env file; unrelated env settings and custom source edits are preserved.
+Already tracked secrets, unsafe links and conflicting higher-priority env files
+are rejected. An optional published-page slug checks delivery after saving.
+Setup never imports content, calls AI, installs dependencies or changes custom
+server/router code. Install the SDK and renderer from your operator as described
+below; API verification and actual website rendering are separate checks.
+
+The original plan/apply commands remain available for advanced setup without
+writing a secret file:
+
+```sh
+npx --no-install universalcms-connect analyze
+npx --no-install universalcms-connect init \
+  --api-origin https://cms.example.com \
+  --site 11111111-1111-4111-8111-111111111111 \
+  --environment 22222222-2222-4222-8222-222222222222
+```
+
+After a public release, `npx @universalcms/connect@0.1.0 init` is the equivalent
+registry entry point. Copy the real IDs/API origin from **Developer setup**.
+Missing values are prompted in a terminal; `--non-interactive` fails instead.
+Init prints a plan. Run the same command with `--apply` after reviewing it.
+Use `--project <folder>`, `--locale <locale>` and a free Next `--mount /cms` as
+needed. `--dry-run` explicitly selects the default plan-only behavior.
+
+Then follow `.universalcms/SETUP.md`:
+
+1. Install the SDK and renderer (plus the Next adapter for Next). Before their
+   public release, install the supplied tarballs together. Setup never runs
+   package-manager installs or existing project scripts.
+2. Set `CMS_API_KEY` in your private server's secret environment using an
+   environment-scoped server delivery key from Developer setup. No provider key
+   or CMS administrator credentials are needed.
+3. Run `npx --no-install universalcms-connect check --slug YOUR_PUBLISHED_PAGE`.
+   The command uses the process key or a hidden terminal prompt. It honors the
+   same private `CMS_API_BASE_URL` override as the generated server, so run it
+   with that server's environment. It never saves the key.
+4. Run and build the website, verify rendering, then deploy its required server
+   and routing configuration. The generated guide provides exact commands.
+
+Next renders full supported blocks at `/cms/<published-page-slug>`. The original
+routes/design remain yours. Vite includes a standalone development demo, a React
+component, an additive dev-proxy wrapper and a private Node handler. For Vite
+production, deploy the static site **and** the private handler, and configure
+the host to proxy `/api/universalcms/page`; the Vite dev proxy is insufficient.
+
+For Vite websites with a detected existing Node server, setup prints a specific
+warning and an existing-server integration guide. Keep the website's normal
+startup, SSR bootstrap and routes. Register `createPageHandler` from
+`@universalcms/connect/node` with its private fixed-scope SDK client before the
+existing API/SSR fallback; install the connector as a production dependency if
+using that entry point. The exported handler has no dependencies and never calls
+AI. The standalone raw-Vite demo is diagnostic only and must use an unused port;
+it does not replace the website's server. No existing server is edited by init.
+
+The first scaffold connects published **pages** in one locale. Existing design
+mapping, source import, posts/custom collections, taxonomies, navigation, forms,
+preview and SEO are deliberate follow-up integrations through the SDK. It does
+not silently create, import or publish CMS content. Successful API verification
+is distinct from a verified website deployment.
+
+Analysis reads exact bounded project files and installed package metadata; it
+never evaluates configuration, runs website code, loads `.env`, crawls sites,
+uploads source or calls AI. Its sanitized JSON report can be supplied explicitly
+to Developer setup. AI provider configuration and metering belong to the platform;
+this connector works when AI is unavailable or its quota is exhausted.
+
+Init-generated files use exclusive creation; identical reruns are unchanged, conflicts
+stop before writes, symlinks and unsafe paths are rejected. Do not modify the
+project concurrently while setup applies: an interrupted or concurrently changed
+filesystem can leave a partial set of newly created files; rerun the same setup
+after inspection. Init does not replace or delete existing files. Guided setup
+can replace unchanged generated files and private connection assignments after
+confirmation. Each file replacement is atomic; the overall multi-file operation
+can be interrupted after some settings or files have been saved.
+
+`check` performs a bounded published-page read with fixed site/environment/locale,
+no cookies and redirect rejection. It prints constant status messages, not returned
+content or credentials. Keys are never accepted as CLI flags, persisted in output,
+or put in `NEXT_PUBLIC_`/`VITE_` configuration. Guided `setup` is the explicit
+exception for local secret persistence: it saves only to private `.env.local`,
+never generated documentation or public configuration. No install/postinstall hook runs.
+
+Development: `node scripts/build.mjs` makes the packed `dist` artifact and copies
+five reviewed analyzer/checker sources from `integrations/custom`. The tarball
+contains no workspace-relative imports or runtime dependencies. Rebuild whenever
+those shared sources change. Run `tests/connect-package.test.ts` and the existing
+project-analysis, dependency-diagnostics and check-delivery tests before release.
+From the repository root, run `node integrations/connect/scripts/smoke.mjs`
+for production-build/browser verification using clean consumers and a synthetic
+CMS API. It defaults to offline dependency installation; `--online` permits
+public registry downloads and `--vite8` selects Vite 8.3 instead of Vite 7.3.
+It does not use customer records or live provider credentials.

package/dist/cli.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { analyze, planSetup, applyPlan, checkConnection, SetupError } from './core.mjs';
+import { runSetup } from './wizard.mjs';
+
+const help = `Universal CMS connector 0.1.0
+Usage: universalcms-connect <setup|analyze|init|check> [options]
+
+  setup                    Guided setup; saves entered values in private .env.local
+
+  --project <directory>     Website folder (default current directory)
+  --framework <next|vite>  Confirm a supported template
+  --api-origin <origin>    Hosted CMS API HTTPS origin
+  --site <uuid>            Website ID from Developer setup
+  --environment <uuid>     Environment ID from Developer setup
+  --locale <locale>        Published content locale (default en)
+  --mount </cms>           Free Next.js route prefix (default /cms)
+  --website-origin <url>  Browser-facing website origin (guided setup)
+  --admin-origin <url>    CMS admin origin for an existing integration (guided setup)
+  --apply                 Explicitly create the reviewed additive files
+  --dry-run               Print a plan only (the default)
+  --non-interactive       Never ask questions
+  --slug <slug>           Published page used by check
+
+Analyze and init read bounded project evidence without executing project code.
+Init never edits existing files, installs packages, imports content or publishes.
+Check makes one private published-page request. CMS_API_KEY comes only from the
+process environment or a hidden terminal prompt; it is never saved. Use an
+environment-scoped server delivery key from Developer setup, not a provider key.
+No AI or provider credentials are required. All analysis stays on this computer.
+Setup asks for the delivery key with hidden input. It updates only connection
+values in .env.local and unchanged generated files, and preserves unrelated settings.
+`;
+
+function argumentsFor(args) {
+  const command = args.shift();
+  if (!['setup', 'analyze', 'init', 'check'].includes(command)) throw new SetupError('Choose setup, analyze, init or check. Use --help for instructions.');
+  const flags = new Set(['--apply', '--dry-run', '--non-interactive']);
+  const names = new Set(['--project', '--framework', '--api-origin', '--site', '--environment', '--locale', '--mount', '--slug', '--website-origin', '--admin-origin']);
+  const options = {};
+  for (let index = 0; index < args.length; index++) {
+    const name = args[index];
+    if (Object.hasOwn(options, name) || (!flags.has(name) && !names.has(name))) throw new SetupError('Unknown or duplicate option. Secrets are not accepted as command-line options.');
+    if (flags.has(name)) options[name] = true;
+    else {
+      const value = args[++index];
+      if (!value || value.startsWith('--')) throw new SetupError('An option is missing its value.');
+      options[name] = value;
+    }
+  }
+  if (options['--apply'] && options['--dry-run']) throw new SetupError('Choose either --apply or --dry-run.');
+  const allowed = command === 'setup' ? ['--project', '--api-origin', '--site', '--environment', '--locale', '--mount', '--website-origin', '--admin-origin'] : command === 'analyze' ? ['--project'] : command === 'check' ? ['--project', '--slug', '--non-interactive'] : [...flags, ...names].filter(name => !['--slug', '--website-origin', '--admin-origin'].includes(name));
+  if (Object.keys(options).some(name => !allowed.includes(name))) throw new SetupError('An option is not supported for this command.');
+  return { command, options };
+}
+
+/** No echo, history, display mask, or persisted copy of the delivery secret. */
+async function hiddenKey(prompt = 'Server delivery key (hidden; not saved): ') {
+  const input = process.stdin, output = process.stderr;
+  if (!input.isTTY || typeof input.setRawMode !== 'function') return undefined;
+  const previousRaw = input.isRaw;
+  input.setRawMode(true); input.resume();
+  output.write(prompt);
+  try {
+    return await new Promise((resolve, reject) => {
+      let value = '';
+      const finish = (error) => {
+        input.off('data', onData); input.off('end', onEnd);
+        for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.off(signal, onSignal);
+        if (error) reject(error); else resolve(value);
+      };
+      const onEnd = () => finish(new SetupError('Key input was interrupted.'));
+      const onSignal = () => finish(new SetupError('Key input was interrupted.'));
+      const onData = chunk => {
+        for (const character of chunk.toString('utf8')) {
+          if (character === '\u0003' || character === '\u0004') { finish(new SetupError('Key input was canceled.')); return; }
+          if (character === '\r' || character === '\n') { finish(); return; }
+          if (character === '\u007f' || character === '\b') value = value.slice(0, -1);
+          else if (/^[A-Za-z0-9_.-]$/.test(character)) value += character;
+          else { finish(new SetupError('Key input contains an unsupported character.')); return; }
+          if (value.length > 256) { finish(new SetupError('Key input exceeds the supported size.')); return; }
+        }
+      };
+      for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.once(signal, onSignal);
+      input.on('data', onData); input.on('end', onEnd);
+    });
+  } finally { input.setRawMode(previousRaw); input.pause(); output.write('\n'); }
+}
+
+async function ask(prompt) {
+  const input = createInterface({ input: process.stdin, output: process.stderr });
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  input.once('SIGINT', cancel); input.once('close', cancel);
+  try {
+    const answer = await input.question(prompt, { signal: controller.signal });
+    if (answer.length > 2048) throw new SetupError('The entered value is too long. Setup was stopped.');
+    return answer;
+  } catch (error) {
+    if (error?.name === 'AbortError') throw new SetupError('Setup cancelled. No further files were changed.');
+    throw error;
+  } finally { input.off('SIGINT', cancel); input.off('close', cancel); input.close(); }
+}
+
+async function main() {
+  if (process.argv.slice(2).some(value => value === '--help' || value === '-h')) { process.stdout.write(help); return; }
+  const { command, options } = argumentsFor(process.argv.slice(2));
+  const project = options['--project'] ?? process.cwd();
+  if (command === 'setup') {
+    if (!process.stdin.isTTY || !process.stderr.isTTY) throw new SetupError('Guided setup needs an interactive terminal. Use init for non-interactive scaffold generation.');
+    await runSetup(project, {
+      apiOrigin: options['--api-origin'], siteId: options['--site'], environmentId: options['--environment'],
+      locale: options['--locale'], mount: options['--mount'], websiteOrigin: options['--website-origin'], adminOrigin: options['--admin-origin'],
+    }, { ask, hidden: hiddenKey, write: value => process.stdout.write(value) });
+    return;
+  }
+  if (command === 'analyze') { process.stdout.write(`${JSON.stringify(await analyze(project), null, 2)}\n`); return; }
+  if (command === 'check') {
+    if (!options['--slug']) throw new SetupError('Check requires --slug with a published page slug.');
+    const env = { CMS_API_KEY: process.env.CMS_API_KEY, CMS_API_BASE_URL: process.env.CMS_API_BASE_URL };
+    if (!env.CMS_API_KEY && !options['--non-interactive']) env.CMS_API_KEY = await hiddenKey();
+    const result = await checkConnection(project, { slug: options['--slug'], env });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (!result.verified) process.exitCode = 1;
+    return;
+  }
+  const required = [['--api-origin', 'CMS API HTTPS origin: '], ['--site', 'Website UUID: '], ['--environment', 'Environment UUID: ']];
+  if (required.some(([name]) => !options[name]) && !options['--non-interactive'] && process.stdin.isTTY) {
+    const input = createInterface({ input: process.stdin, output: process.stderr });
+    try { for (const [name, question] of required) if (!options[name]) options[name] = (await input.question(question)).trim(); }
+    finally { input.close(); }
+  }
+  if (required.some(([name]) => !options[name])) throw new SetupError('Init requires --api-origin, --site and --environment (or an interactive terminal).');
+  const plan = await planSetup(project, { framework: options['--framework'], apiOrigin: options['--api-origin'], siteId: options['--site'], environmentId: options['--environment'], locale: options['--locale'], mount: options['--mount'] });
+  process.stdout.write(`Template: ${plan.config.framework === 'next' ? 'Next.js App Router' : 'React/Vite with a private Node server'}\n`);
+  if (plan.config.framework === 'vite' && plan.analysis.runtime === 'node' && plan.analysis.rendering === 'server') process.stdout.write('Existing Node server detected: keep its normal startup and SSR routing. Follow the existing-server section in .universalcms/SETUP.md; the separate Vite demo is diagnostic only.\n');
+  for (const file of plan.files) process.stdout.write(`  ${file.state}: ${file.path}\n`);
+  if (options['--apply']) {
+    const result = await applyPlan(plan);
+    process.stdout.write(`Created ${result.created.length} files; preserved ${result.unchanged} identical files.\nRead .universalcms/SETUP.md for dependency installation, server secrets, routing and deployment.\nConnection and website rendering are not yet verified. Run check with a published page slug after configuring the private server.\n`);
+  } else process.stdout.write('Plan only: no files changed. Review the template and run the same command with --apply to create it.\n');
+}
+
+try { await main(); }
+catch (error) {
+  // Filesystem, JSON and upstream errors can contain customer source or secrets.
+  process.stderr.write(`${error instanceof SetupError ? error.message : 'Setup could not complete. Check ordinary project files and permissions. Review any interrupted setup changes before retrying; private settings or generated files may have been saved.'}\n`);
+  process.exitCode = 1;
+}

package/dist/core.mjs

@@ -0,0 +1,224 @@
+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 { analyzeProjectDirectory } from './vendor/analyze-project.mjs';
+import { verifyPublishedDelivery } from './vendor/check-delivery.mjs';
+import { createTemplates, legacySetupGuide } from './templates.mjs';
+
+export class SetupError extends Error {}
+const fail = message => { throw new SetupError(message); };
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const maxFileBytes = 128 * 1024;
+export const CONFIG_FILE = '.universalcms/config.json';
+const plain = value => value && typeof value === 'object' && !Array.isArray(value);
+
+export async function projectRoot(directory) {
+  const requested = path.resolve(directory);
+  const stat = await lstat(requested);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('Choose an ordinary project directory, not a symbolic link.');
+  return realpath(requested);
+}
+
+/** Every segment is checked before reading or creating; external symlinks are never followed. */
+async function inspect(root, relative, directory = false) {
+  if (typeof relative !== 'string' || !relative || relative.includes('\\') || path.isAbsolute(relative) || relative.split('/').some(part => !part || part === '.' || part === '..')) fail('Unsafe generated path.');
+  let target = root;
+  const segments = relative.split('/');
+  for (let index = 0; index < segments.length; index++) {
+    target = path.join(target, segments[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('A setup path is a symbolic link. Use ordinary project files.');
+    const shouldBeDirectory = index < segments.length - 1 || directory;
+    if (shouldBeDirectory ? !stat.isDirectory() : !stat.isFile()) fail('A setup path has an incompatible file type.');
+    if (index === segments.length - 1) return { target, stat };
+  }
+}
+
+export async function readProjectFile(root, relative) {
+  const found = await inspect(root, relative);
+  if (!found) return null;
+  if (found.stat.size > maxFileBytes) fail('A setup file exceeds the read limit.');
+  const handle = await open(found.target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.ino !== found.stat.ino || stat.dev !== found.stat.dev || stat.size > maxFileBytes) fail('A project file changed during inspection. Retry setup.');
+    const buffer = Buffer.alloc(maxFileBytes + 1);
+    let bytes = 0;
+    while (bytes < buffer.length) {
+      const result = await handle.read(buffer, bytes, buffer.length - bytes, bytes);
+      if (!result.bytesRead) break;
+      bytes += result.bytesRead;
+    }
+    if (bytes > maxFileBytes) fail('A setup file exceeds the read limit.');
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, bytes));
+  } finally { await handle.close(); }
+}
+
+function supportedVersion(value, majors, minMinor = 0) {
+  if (typeof value !== 'string') return false;
+  const match = /^(?:\^|~)?(\d+)\.(\d+)\.(\d+)$/.exec(value);
+  return !!match && majors.includes(Number(match[1])) && Number(match[2]) >= minMinor;
+}
+
+export function validateConfig(input) {
+  if (!plain(input) || Object.keys(input).some(key => !['version', 'framework', 'apiOrigin', 'siteId', 'environmentId', 'locale', 'mount', 'appDirectory'].includes(key))) fail('The connection configuration contains unsupported fields. Credentials belong only in the server environment.');
+  let origin, locale;
+  try {
+    const url = new URL(input.apiOrigin);
+    if (typeof input.apiOrigin !== 'string' || input.apiOrigin.length > 2048 || url.username || url.password || url.search || url.hash || url.pathname !== '/' || /[\s\\]|cms_server\.|sk-[A-Za-z0-9_-]{12,}|AIza[A-Za-z0-9_-]{20,}/.test(input.apiOrigin) ||
+      (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) throw Error();
+    origin = url.origin;
+    if (typeof input.locale !== 'string' || input.locale.length > 35) throw Error();
+    locale = Intl.getCanonicalLocales(input.locale)[0];
+  } catch { fail('Use an HTTPS API origin (HTTP loopback is allowed for development) and a valid locale.'); }
+  if (input.version !== 1 || !['next', 'vite'].includes(input.framework) || !uuid.test(input.siteId) || !uuid.test(input.environmentId) || !locale || !/^\/[a-z][a-z0-9-]{0,39}$/.test(input.mount)) fail('Use valid site/environment UUIDs and one lowercase mount segment, such as /cms.');
+  if (input.framework === 'next' ? !['app', 'src/app'].includes(input.appDirectory) : input.appDirectory !== null) fail('Invalid application directory.');
+  if (['/api', '/_next', '/assets', '/public', '/src', '/node_modules'].includes(input.mount)) fail('This route prefix is reserved. Choose a different mount.');
+  return { version: 1, framework: input.framework, apiOrigin: origin, siteId: input.siteId.toLowerCase(), environmentId: input.environmentId.toLowerCase(), locale, mount: input.mount, appDirectory: input.appDirectory };
+}
+
+async function checkNextRoute(root, appDirectory, mount, existingConfig) {
+  const mountName = mount.slice(1);
+  const route = `${appDirectory}/${mountName}`;
+  const found = await inspect(root, route, true);
+  if (found && !existingConfig) fail('The chosen Next.js mount already exists. Choose a free mount or integrate it manually.');
+  // A sibling group/dynamic route can own the same URL. Never guess its semantics.
+  const entries = await readdir(path.join(root, appDirectory), { withFileTypes: true });
+  if (entries.some(entry => entry.name.startsWith('(') || entry.name.startsWith('[') || entry.name.startsWith('@'))) fail('Route groups, parallel routes or dynamic root routes need a manual route review before setup.');
+  for (const directory of ['pages', 'src/pages']) {
+    if (!await inspect(root, directory, true)) continue;
+    const siblings = await readdir(path.join(root, directory), { withFileTypes: true });
+    if (siblings.some(entry => entry.name === mountName || entry.name.startsWith(`${mountName}.`) || entry.name.startsWith('['))) fail('A Pages Router destination may already own this mount. Review the route manually.');
+  }
+  if (found && existingConfig) {
+    const children = await readdir(path.join(root, route));
+    if (children.some(name => !['cms.server.js', '[...slug]'].includes(name))) fail('The generated mount contains additional routes. Review the route tree manually.');
+    if (await inspect(root, `${route}/[...slug]`, true)) {
+      const children = await readdir(path.join(root, route, '[...slug]'));
+      if (children.some(name => !['page.jsx', 'error.jsx'].includes(name))) fail('The generated mount contains additional routes. Review the route tree manually.');
+    }
+  }
+}
+
+export async function analyze(directory) {
+  const root = await projectRoot(directory);
+  return analyzeProjectDirectory(root);
+}
+
+export async function planSetup(directory, options, { reconfigure = false } = {}) {
+  const root = await projectRoot(directory);
+  const analysis = await analyzeProjectDirectory(root);
+  let manifest;
+  try { manifest = JSON.parse(await readProjectFile(root, 'package.json')); }
+  catch { fail('A readable valid package.json is required.'); }
+  if (!plain(manifest)) fail('A readable valid package.json is required.');
+  const deps = { ...manifest.devDependencies, ...manifest.dependencies };
+  if (manifest.workspaces || analysis.warnings.some(warning => /invalid|workspace|Conflicting/.test(warning))) fail('Choose one valid website project. Conflicting, workspace or unreadable configuration needs manual review.');
+  const framework = options.framework ?? (deps.next ? 'next' : deps.vite && deps.react ? 'vite' : null);
+  if (!['next', 'vite'].includes(framework)) fail('Supported templates are Next.js App Router and React/Vite. Other frameworks need manual setup.');
+  if (!supportedVersion(deps.react, [19], 2)) fail('The renderer requires a declared stable React 19.2 or newer 19.x version. Upgrade deliberately or use manual integration.');
+  let appDirectory = null;
+  if (framework === 'next') {
+    if (!supportedVersion(deps.next, [16]) || analysis.framework !== 'Next.js' || analysis.runtime !== 'node') fail('Automatic setup requires Next.js 16 with a confirmed Node runtime. Static export and dynamic configuration need manual setup.');
+    for (const extension of ['js', 'mjs', 'cjs', 'ts']) {
+      const configSource = await readProjectFile(root, `next.config.${extension}`);
+      // These settings can invalidate the generated dynamic exports, filename
+      // routing or documented mount. Even a mention is conservatively reviewed;
+      // this check does not evaluate code or claim to interpret JS configuration.
+      if (configSource && /\b(?:cacheComponents|pageExtensions|basePath)\b/.test(configSource)) fail('Next.js Cache Components, custom page extensions or base-path configuration need manual route integration with this template.');
+    }
+    const rootApp = await inspect(root, 'app', true), srcApp = await inspect(root, 'src/app', true);
+    if (!!rootApp === !!srcApp) fail('Choose a project with exactly one App Router directory (app or src/app). Pages Router needs manual setup.');
+    appDirectory = rootApp ? 'app' : 'src/app';
+    if (!(await Promise.all(['js', 'jsx', 'ts', 'tsx'].map(extension => readProjectFile(root, `${appDirectory}/layout.${extension}`)))).some(Boolean)) fail('The App Router requires an existing root layout.');
+  } else {
+    if (!supportedVersion(deps.vite, [6, 7, 8]) || deps.next || analysis.frontend !== 'React' || analysis.framework !== 'React') fail('Automatic setup requires a React project with Vite 6, 7 or 8. Conflicting frameworks need manual setup.');
+  }
+  const config = validateConfig({ version: 1, framework, apiOrigin: options.apiOrigin, siteId: options.siteId, environmentId: options.environmentId, locale: options.locale ?? 'en', mount: options.mount ?? '/cms', appDirectory });
+  const existingConfig = await readProjectFile(root, CONFIG_FILE);
+  let prior;
+  if (existingConfig && reconfigure) {
+    try { prior = validateConfig(JSON.parse(existingConfig)); }
+    catch { fail('The saved connector configuration is invalid. Restore it before running setup.'); }
+    if (prior.framework !== config.framework || prior.mount !== config.mount || prior.appDirectory !== config.appDirectory) fail('Changing the generated route or framework needs a manual integration review. Existing routes were preserved.');
+  }
+  if (existingConfig && !reconfigure && existingConfig !== `${JSON.stringify(config, null, 2)}\n`) fail('This project already has a different CMS connection. Use interactive setup to update unchanged generated files, or review the integration manually.');
+  if (framework === 'next') await checkNextRoute(root, appDirectory, config.mount, existingConfig);
+  const templateOptions = { existingNodeServer: framework === 'vite' && analysis.runtime === 'node' && analysis.rendering === 'server' };
+  const files = await createTemplates(config, templateOptions);
+  files.unshift({ path: CONFIG_FILE, content: `${JSON.stringify(config, null, 2)}\n` });
+  const previous = prior ? new Map((await createTemplates(prior, templateOptions)).map(file => [file.path, file.content])) : new Map();
+  if (prior) previous.set(CONFIG_FILE, existingConfig);
+  for (const file of files) {
+    const current = await readProjectFile(root, file.path);
+    const old = previous.get(file.path);
+    const generatedBefore = old !== undefined && (old === current || (file.path === '.universalcms/SETUP.md' && legacySetupGuide(old) === current));
+    file.state = current === null ? 'create' : current === file.content ? 'unchanged' : reconfigure && generatedBefore ? 'update' : 'conflict';
+    if (file.state === 'update') file.previous = current;
+  }
+  if (files.some(file => file.state === 'conflict')) fail('A generated file already contains different content. No files were changed. Preserve your edits and finish the integration manually.');
+  return { root, config, analysis, files };
+}
+
+export async function validatePlan(plan) {
+  // Init creates exclusively. Guided reconfiguration replaces only files whose
+  // bytes still match the generated original captured by the reviewed plan.
+  if (await projectRoot(plan.root) !== plan.root) fail('The project directory changed after planning. Run setup again from the intended directory.');
+  for (const file of plan.files) {
+    const current = await readProjectFile(plan.root, file.path);
+    if (file.state === 'update') {
+      if (current !== file.previous) fail('A file changed after planning. No existing file was overwritten.');
+      const found = await inspect(plan.root, file.path);
+      if (!found || found.stat.nlink !== 1) fail('A generated file is linked or changed. Existing files were preserved.');
+    } else if (current !== null && current !== file.content) fail('A file changed after planning. No existing file was overwritten.');
+  }
+}
+
+export async function applyPlan(plan) {
+  await validatePlan(plan);
+  const created = [], updated = [];
+  for (const file of plan.files) {
+    if (await readProjectFile(plan.root, file.path) === file.content) continue;
+    if (file.state === 'update') {
+      const target = path.join(plan.root, file.path);
+      const temporary = path.join(path.dirname(target), `.cms-setup-${randomUUID()}.tmp`);
+      const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+      try {
+        await handle.writeFile(file.content, 'utf8'); await handle.sync(); await handle.close();
+        if (await readProjectFile(plan.root, file.path) !== file.previous) fail('A file changed during setup. Existing edits were preserved; rerun after inspection.');
+        const found = await inspect(plan.root, file.path);
+        if (!found || found.stat.nlink !== 1) fail('A generated file changed during setup. Rerun after inspection.');
+        await rename(temporary, target); updated.push(file.path);
+      } finally { await handle.close().catch(() => {}); await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+      continue;
+    }
+    const segments = file.path.split('/');
+    for (let index = 1; index < segments.length; index++) {
+      const directory = segments.slice(0, index).join('/');
+      if (!await inspect(plan.root, directory, true)) {
+        try { await mkdir(path.join(plan.root, directory), { mode: 0o755 }); }
+        catch (error) { if (error.code !== 'EEXIST') throw error; }
+        await inspect(plan.root, directory, true);
+      }
+    }
+    const handle = await open(path.join(plan.root, file.path), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+    try { await handle.writeFile(file.content, 'utf8'); } finally { await handle.close(); }
+    created.push(file.path);
+  }
+  return { created, updated, unchanged: plan.files.length - created.length - updated.length };
+}
+
+export async function checkConnection(directory, { slug, env = process.env, fetcher } = {}) {
+  const root = await projectRoot(directory);
+  let config;
+  try { config = validateConfig(JSON.parse(await readProjectFile(root, CONFIG_FILE))); }
+  catch { fail('Run init first and keep its valid connection configuration.'); }
+  return verifyPublishedDelivery({ slug, locale: config.locale, env: {
+    // Match the generated runtime's private origin override while retaining its
+    // immutable site/environment/locale. The verifier validates before fetching.
+    CMS_API_BASE_URL: env.CMS_API_BASE_URL ?? config.apiOrigin, CMS_SITE_ID: config.siteId, CMS_ENVIRONMENT_ID: config.environmentId, CMS_API_KEY: env.CMS_API_KEY,
+  }, ...(fetcher ? { fetcher } : {}) });
+}