@universalcms/connect 0.1.0 → 0.13.0

package/dist/cli.mjs

@@ -1,13 +1,59 @@
 #!/usr/bin/env node
 import { createInterface } from 'node:readline/promises';
-import { analyze, planSetup, applyPlan, checkConnection, SetupError } from './core.mjs';
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { analyze, planSetup, applyPlan, checkConnection, readProjectFile, projectRoot, SetupError } from './core.mjs';
 import { runSetup } from './wizard.mjs';
+import { preflightSetup } from './preflight.mjs';
+import { inspectPageCandidates } from './page-discovery.mjs';
+import { runPageMappingReview } from './page-mapping-review.mjs';
+import { inspectNativeRouteCandidates, runNativeRouteReview } from './native-route-review.mjs';
+import { setupReviewDiagnostic, setupRecovery } from './preflight-recovery.mjs';
+import { runConnect, runServerKey, runPrepareServerKey, prepareSourceKeyCheck, readConnection } from './staged-setup.mjs';
+import { readSetupEnvironment } from './setup-environment.mjs';
+import { checkSource } from './source-check.mjs';
+import { checkPublication } from './publication-check.mjs';
+import { finalizeSource } from './source-finalize.mjs';
+import { setupWebsiteSettings } from './website-setup.mjs';
+import { checkWebsiteSettings } from './website-check.mjs';
+import { WEBSITE_SECTIONS } from './website-http.mjs';
+import { setupSource, applySourcePlan, syncSource, readSourceSettings } from './source-setup.mjs';
+import { processIo, runGuided } from './guided.mjs';
 
-const help = `Universal CMS connector 0.1.0
-Usage: universalcms-connect <setup|analyze|init|check> [options]
+const help = `Universal CMS connector 0.13.0
 
-  setup                    Guided setup; saves entered values in private .env.local
+Quick start (recommended) — run in your website folder:
+  npx @universalcms/connect@latest --cms https://YOUR_CMS_ADDRESS
 
+  Opens your browser to approve the website, installs this package, connects
+  your pages, header/footer and settings, saves the website key privately and
+  guides the restart, content import and final check. Run it again any time to
+  continue where it stopped.
+
+  --cms <origin>           Your Universal CMS address (or UNIVERSALCMS_URL)
+  --code <code>            One-time code from Developer setup → Connect without a browser
+  --details                Show every file and technical message
+
+Individual steps (advanced):
+Usage: universalcms-connect <start|inspect-pages|review-pages|preflight|review-routes|review-layout|connect|setup|setup-settings|check-settings|server-key|setup-source|sync-source|finalize-source|analyze|init|check|check-source|check-publication> [options]
+
+  inspect-pages            Discover page URLs and screen candidates without writes
+  review-pages             Record local page/screen ownership intent; does not install
+  preflight                Plan original-route setup using public values; no writes or keys
+  review-routes            Review native Next application routes before full setup
+  review-layout            Review supported native header/footer slots before full setup
+  connect                  Save public website connection values, without a key
+  setup                    Prepare pages and required header/footer settings, then key input
+  setup-settings           Install or repair reviewed website settings adapters (--apply)
+  check-settings           Check each settings adapter and key access without credentials
+  server-key               Save the delivery key privately through hidden input
+  setup-source             Prepare source export for a supported native framework
+  sync-source              Refresh the source snapshot before a production build
+  check-source             Read the website source export without credentials
+  check-publication        Verify the managed adapter and an original website URL
+  finalize-source          Close bootstrap source export after CMS import (--apply)
+
+  --check-routes           Audit local Next App Router paths against the source export
   --project <directory>     Website folder (default current directory)
   --framework <next|vite>  Confirm a supported template
   --api-origin <origin>    Hosted CMS API HTTPS origin
@@ -15,28 +61,209 @@ Usage: universalcms-connect <setup|analyze|init|check> [options]
   --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)
+  --original-routes-only   Connect original pages without adding a new SDK demo
+  --prepare-only          Save private server-key settings before adapter setup
+  --skip-key-validation   Skip live key verification with CMS API
+  --require-server-key    Require matching private key settings for setup-source
+  --website-origin <url>  Exact website origin (setup or check-source)
+  --admin-origin <url>    Exact CMS admin origin (setup or check-source)
   --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
+  --path </path>          Original URL path used by check-publication
 
 Analyze and init read bounded project evidence without executing project code.
+Inspect-pages discovers candidates across framework conventions without claiming
+that they have usable content bindings. Screens sharing a URL remain screens;
+no URL is invented for them. Review-pages records CMS-page, connected-screen or
+native ownership intent in .universalcms/pages.review.json after confirmation.
+This review does not change website rendering or satisfy preflight. Unsupported
+bindings still require a supported framework adapter before installation.
+Both commands stay local: no source upload, key access, AI or network requests.
+Preflight checks the actual framework, local runtime and original-route plan
+before key preparation. Use the six public connection flags from Developer setup,
+or an existing saved public connection. It never reads private environment files,
+executes website code, makes network requests or changes files. Review-required
+returns a nonzero exit status. Planned does not mean installed or live verified;
+fresh header/footer settings still require their separate installation review.
 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.
+Run connect, then setup. Connect saves only public values in
+.universalcms/connection.json; setup prepares integration files, then offers
+to save a server key through hidden input. You can defer and run server-key later.
+Setup includes a required header/footer and website settings review. Unsupported
+or deferred settings leave SETUP INCOMPLETE; run setup-settings --apply after a
+reviewed adapter is ready. Original website links remain alongside saved CMS links.
+The key is saved in Git-ignored, owner-only .env.local. No key is accepted
+as a command argument. These steps do not verify delivery or publish content.
+For key-first or source-only setup, use server-key --prepare-only with the public
+connection flags from Developer setup. It saves private delivery settings before
+an adapter exists. It does not install rendering or verify key authorization.
+Replacing a key preserves existing website integration. Restart or deploy, then
+run check-settings. Navigation access permits reading saved header/footer links;
+it does not add a missing website renderer or create menu links automatically.
+Without a saved connect record, setup retains the all-in-one guided flow with
+hidden key input. Existing custom files and unrelated settings are preserved.
+Developer setup provides connector installation, private-key preparation and
+full setup --original-routes-only for reviewed original page rendering. It validates
+the complete source/publication/binding plan before saving. Source-only preparation
+remains a separate import utility and cannot control publication visibility.
+After importing source into CMS drafts, run finalize-source --apply, restart or
+deploy, then check-publication. This closes the bootstrap content export. A checked
+adapter and route still require actual rendered-content verification in a browser.
+Fresh full setups use the bundled renderer; existing SDK demos retain dependency checks.
+Analyze only prints a report. It does not create /api/cms-source or connect a site.
+Next.js setup also prepares /api/cms-source for public static page copy. New static
+pages are discovered on each development request and the production prebuild hook.
+Dynamic/database content, private routes and unresolved components need explicit
+review; diagnostics never claim those are complete. React/Vite can discover a
+mounted static App or flat literal React Router pages. Other layouts need reviewed
+.universalcms/source.entries.json and .universalcms/content.routes.json mappings.
+Setup validates the local framework, source and rendering before saving integration
+files or requesting a key. Unsupported frameworks get a manual integration guide.
+No empty export or guessed content is generated. Full Vite setup pins localhost's
+registered port; stop any old server on that port before restarting the website.
+Setup-source is a plan by default; review then use --apply. It uses only the four
+public scope/origin flags, or saved source configuration; no key or AI is needed.
+For key-first setup, add --require-server-key and the exact --api-origin. This
+checks the saved private key and connection scope before source files are saved;
+the key is never sent to the source endpoint and authorization remains unverified.
+After saving, setup-source checks the live endpoint for up to 10 seconds. Saved
+files alone do not mean a running server loaded them; stop and restart an old
+server using the displayed project command, then run the scoped check-source.
+Full setup checks the running publication adapter for up to 10 seconds after
+saving. CONNECTION NOT READY means the files were saved but the running website
+still needs attention. Restart or deploy, then run the displayed check-publication
+before checking the connection in the CMS. Setup never stops a server or changes
+the registered port automatically.
+Check-source uses --website-origin, --admin-origin, --site and --environment, or
+saved local public values. All four explicit flags bypass saved settings; no init
+or supported scaffold framework is required. It sends no key, cookies or content
+to the CMS and changes no files. It checks the source envelope, scope and CORS,
+not full block-schema validation, complete inventory or actual browser access.
 `;
 
+const publicSourceValues = config => Object.fromEntries(['websiteOrigin', 'adminOrigin', 'siteId', 'environmentId'].map(name => [name, config[name]]));
+const shellQuote = value => `'${value.replaceAll("'", "'\\''")}'`;
+function sourceCheckCommand(config) {
+  return `npx --no-install universalcms-connect check-source --website-origin ${shellQuote(config.websiteOrigin)} --admin-origin ${shellQuote(config.adminOrigin)} --site ${shellQuote(config.siteId)} --environment ${shellQuote(config.environmentId)}`;
+}
+function publicationCheckCommand(config) {
+  return `npx --no-install universalcms-connect check-publication --website-origin ${shellQuote(config.websiteOrigin)} --admin-origin ${shellQuote(config.adminOrigin)} --site ${shellQuote(config.siteId)} --environment ${shellQuote(config.environmentId)}`;
+}
+async function reportReviewedSourceAlternative(project, options) {
+  try {
+    const saved = await readSetupEnvironment(project), connection = await readConnection(project), source = await readSourceSettings(project);
+    const binding = { ...saved.defaults, ...source, ...(connection ?? {}), ...Object.fromEntries(Object.entries(options).filter(([name, value]) => value !== undefined && ['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'].includes(name))) };
+    const plan = await setupSource(project, Object.fromEntries(['siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'].map(name => [name, binding[name]])));
+    if (plan.diagnostics.sourceOnly !== true || plan.diagnostics.publicationRendering !== false) return;
+    if (saved.keyConfigured) await prepareSourceKeyCheck(project, Object.fromEntries(['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'].map(name => [name, binding[name]])));
+    const keyFlags = saved.keyConfigured ? ` --require-server-key --api-origin ${shellQuote(binding.apiOrigin)}` : '';
+    process.stdout.write('Full setup remains unsupported for this website\'s native renderer. Its reviewed public content can be imported with the separate command below; this does not connect published CMS edits to the original design.\n');
+    process.stdout.write(`npx --no-install universalcms-connect setup-source --apply${keyFlags} --website-origin ${shellQuote(plan.config.websiteOrigin)} --admin-origin ${shellQuote(plan.config.adminOrigin)} --site ${shellQuote(plan.config.siteId)} --environment ${shellQuote(plan.config.environmentId)} --locale ${shellQuote(plan.config.locale)}\n`);
+  } catch { /* The original setup error remains authoritative. Never suggest an unvalidated alternative. */ }
+}
+async function sourceRestartCommand(plan) {
+  try {
+    const root = await projectRoot(plan.root);
+    const manifest = JSON.parse(await readProjectFile(root, 'package.json'));
+    const script = manifest?.scripts?.dev;
+    // Display a fixed package-manager command only for a recognized dev script.
+    // Never evaluate project scripts or copy their arbitrary shell text to output.
+    if (typeof script !== 'string') return null;
+    const vite = /^vite(?:\s+--(?:host(?:\s+(?:localhost|127\.0\.0\.1|0\.0\.0\.0|::1))?|port\s+\d{1,5}|strictPort|open|https))* --config \.universalcms\/source\.vite\.config\.mjs$/.test(script);
+    const next = /^next dev(?:\s+(?:--(?:turbo|turbopack|webpack)|(?:--port|-p)\s+\d{1,5}|(?:--hostname|-H)\s+(?:localhost|127\.0\.0\.1|0\.0\.0\.0|::1)))*$/.test(script);
+    const astro = /^astro dev(?: --(?:host(?: (?:localhost|127\.0\.0\.1|0\.0\.0\.0))?|port [0-9]{1,5}|open))* --config \.universalcms\/astro\.config\.mjs$/.test(script);
+    if (!(plan.framework === 'vite' ? vite : plan.framework === 'next' ? next : plan.framework === 'astro' ? astro : vite || next || astro)) return null;
+    const declared = typeof manifest.packageManager === 'string' && /^(npm|pnpm|yarn|bun)@\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.-]+)?$/.exec(manifest.packageManager);
+    if (manifest.packageManager !== undefined) return declared ? `${declared[1]} run dev` : null;
+    const managers = new Set();
+    for (const [filename, manager] of [['package-lock.json', 'npm'], ['npm-shrinkwrap.json', 'npm'], ['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun']]) {
+      try {
+        const stat = await lstat(join(root, filename));
+        if (!stat.isFile() || stat.isSymbolicLink()) return null;
+        managers.add(manager);
+      } catch (error) { if (error.code !== 'ENOENT') return null; }
+    }
+    return managers.size <= 1 ? `${[...managers][0] ?? 'npm'} run dev` : null;
+  } catch { return null; }
+}
+async function sourceStopInstruction(plan) {
+  let astro = plan.framework === 'astro';
+  if (!plan.framework) {
+    try { const manifest = JSON.parse(await readProjectFile(await projectRoot(plan.root), 'package.json')); astro = Boolean(manifest.dependencies?.astro ?? manifest.devDependencies?.astro); } catch { /* Keep generic restart guidance. */ }
+  }
+  return astro
+    ? 'Astro 7 may run in the background. From this exact website folder run: npx --no-install astro dev stop. Ctrl+C stops a foreground server only. Confirm the registered port is free before restarting.'
+    : 'Stop the existing website server (Ctrl+C in its terminal).';
+}
+
+async function reportSourceReadiness(plan) {
+  process.stdout.write('Checking the live source endpoint (up to 10 seconds; no credentials).\n');
+  const outcome = await checkSource(plan.root, publicSourceValues(plan.config));
+  process.stdout.write(`${outcome.checked ? 'SOURCE READY' : 'SOURCE NOT READY'} (${outcome.status}): ${outcome.message}\n`);
+  if (!outcome.checked) {
+    if (['missing-route', 'not-json'].includes(outcome.status)) process.stdout.write('Files are saved, but the running server has not loaded the source endpoint at the configured origin.\n');
+    const restart = await sourceRestartCommand(plan);
+    process.stdout.write(restart
+      ? `${await sourceStopInstruction(plan)} Then from the website folder run: ${restart}\n`
+      : 'Stop the existing website server, then restart it with the project\'s normal command or deploy the updated website.\n');
+    process.stdout.write('Rerun the check below and confirm it passes before Connect & fetch content.\n');
+  }
+  process.stdout.write(`From the website folder, verify this exact scope:\n${sourceCheckCommand(plan.config)}\nPublished rendering remains unverified.\n`);
+}
+
+async function reportSetupReadiness(project) {
+  let config;
+  try {
+    config = publicSourceValues(await readSourceSettings(project));
+    if (Object.values(config).some(value => typeof value !== 'string' || !value)) throw Error();
+  } catch {
+    process.stdout.write('CONNECTION NOT READY: Integration files were saved, but their public connection settings could not be read. Review the saved setup in this website folder before checking the running website.\n');
+    return;
+  }
+  process.stdout.write('Integration files saved. Checking the running publication adapter (up to 10 seconds; no credentials).\n');
+  process.stdout.write('Checking the running header/footer settings adapter (up to 10 seconds; no credentials).\n');
+  const [outcome, settings] = await Promise.all([checkPublication(project, config), checkWebsiteSettings(project, config)]);
+  process.stdout.write(`${outcome.checked ? 'PUBLICATION CHECK PASSED' : 'CONNECTION NOT READY'} (${outcome.status}): ${outcome.message}\n`);
+  if (!outcome.checked) {
+    if (['missing-adapter', 'invalid-response'].includes(outcome.status)) process.stdout.write('Saved files do not prove that the server at this URL loaded them. An older server may still be serving the website. Removing integration files or reinstalling packages does not stop that process.\n');
+    const url = new URL(config.websiteOrigin);
+    if (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+      const restart = await sourceRestartCommand({ root: project });
+      process.stdout.write(`Use the registered website origin ${url.origin} (port ${url.port || '80'}). If the port is in use, stop the old website server in its terminal before starting this project. Do not start a second server on another port.\n`);
+      process.stdout.write(`${await sourceStopInstruction({ root: project })}\n`);
+      process.stdout.write(restart ? `From this website folder, restart with: ${restart}\n` : 'Restart with this project\'s normal website command after reviewing its server configuration.\n');
+    } else process.stdout.write('Deploy the updated integration and private server configuration to this exact website origin, then verify the running deployment.\n');
+    process.stdout.write('Run the check below after restart or deployment and confirm it passes before checking the connection in Universal CMS.\n');
+  }
+  process.stdout.write(`Verify this exact website and environment:\n${publicationCheckCommand(config)}\nA source-export check alone cannot verify publication control. Actual rendered content and access from the CMS browser still need verification. No content was imported or published.\n`);
+  const navigation = settings.sections?.navigation;
+  if (!settings.checked || navigation?.installed === false || !navigation || navigation.state === 'unavailable') {
+    process.stdout.write('HEADER/FOOTER NOT READY: The running website has not verified its navigation adapter. Run setup-settings --apply if it is missing, then restart or deploy and run check-settings. Replacing a key alone cannot install the adapter.\n');
+  } else if (navigation.state === 'denied') {
+    process.stdout.write('HEADER/FOOTER ACCESS DENIED: The current server key cannot read Navigation. Review the intended key access yourself; setup has not changed it. Restart or deploy after an authorized key update, then run check-settings.\n');
+  } else if (navigation.state === 'missing') {
+    process.stdout.write('HEADER/FOOTER ADAPTER CHECK PASSED: No navigation configuration is saved for this connection. Save the intended links in CMS Header & footer, then verify their placement in the actual website.\n');
+  } else {
+    process.stdout.write('HEADER/FOOTER ADAPTER CHECK PASSED: Navigation configuration is available. Verify saved header and footer links in the actual desktop and mobile website; this diagnostic does not verify appearance.\n');
+  }
+  if (settings.checked) {
+    const missing = WEBSITE_SECTIONS.filter(name => settings.sections?.[name]?.installed !== true);
+    if (missing.length) process.stdout.write(`SETTINGS INCOMPLETE: Website adapters are not installed for ${missing.join(', ')}. Key access alone does not install them.\n`);
+  }
+  process.stdout.write('Configuration check: npx --no-install universalcms-connect check-settings\n');
+}
+
 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']);
+  if (!['inspect-pages', 'review-pages', 'preflight', 'review-routes', 'review-layout', 'connect', 'setup', 'server-key', 'setup-source', 'sync-source', 'finalize-source', 'analyze', 'init', 'check', 'check-source', 'check-publication', 'setup-settings', 'check-settings'].includes(command)) throw new SetupError('Choose inspect-pages, review-pages, preflight, review-routes, review-layout, connect, setup, setup-settings, check-settings, server-key, setup-source, sync-source, finalize-source, analyze, init, check, check-source or check-publication. Use --help for instructions.');
+  const flags = new Set(['--apply', '--dry-run', '--non-interactive', '--check-routes', '--original-routes-only', '--prepare-only', '--require-server-key', '--skip-key-validation']);
+  const names = new Set(['--project', '--framework', '--api-origin', '--site', '--environment', '--locale', '--mount', '--slug', '--path', '--website-origin', '--admin-origin']);
   const options = {};
   for (let index = 0; index < args.length; index++) {
     const name = args[index];
@@ -49,7 +276,7 @@ function argumentsFor(args) {
     }
   }
   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));
+  const allowed = ['inspect-pages','review-pages'].includes(command) ? ['--project','--locale','--website-origin','--dry-run','--non-interactive'] : ['review-routes','review-layout'].includes(command) ? ['--project','--dry-run','--non-interactive'] : command === 'preflight' ? ['--project', '--api-origin', '--site', '--environment', '--locale', '--website-origin', '--admin-origin'] : command === 'setup-settings' ? ['--project','--apply','--dry-run','--non-interactive'] : command === 'check-settings' ? ['--project','--site','--environment','--website-origin','--admin-origin','--non-interactive'] : command === 'connect' ? ['--project', '--api-origin', '--site', '--environment', '--locale', '--website-origin', '--admin-origin'] : command === 'server-key' ? ['--project', '--prepare-only', '--skip-key-validation', ...(options['--prepare-only'] ? ['--api-origin', '--site', '--environment', '--locale', '--website-origin', '--admin-origin'] : [])] : command === 'setup' ? ['--project', '--api-origin', '--site', '--environment', '--locale', '--mount', '--website-origin', '--admin-origin', '--original-routes-only'] : command === 'setup-source' ? ['--project', '--site', '--environment', '--website-origin', '--admin-origin', '--locale', '--apply', '--dry-run', '--non-interactive', '--require-server-key', ...(options['--require-server-key'] ? ['--api-origin'] : [])] : command === 'sync-source' ? ['--project'] : command === 'finalize-source' ? ['--project', '--apply', '--dry-run'] : command === 'check-publication' ? ['--project', '--site', '--environment', '--website-origin', '--admin-origin', '--path', '--non-interactive'] : command === 'check-source' ? ['--project', '--site', '--environment', '--website-origin', '--admin-origin', '--non-interactive', '--check-routes'] : command === 'analyze' ? ['--project'] : command === 'check' ? ['--project', '--slug', '--non-interactive'] : [...flags, ...names].filter(name => !['--slug', '--path', '--website-origin', '--admin-origin', '--check-routes', '--original-routes-only', '--prepare-only', '--require-server-key', '--skip-key-validation'].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 };
 }
@@ -60,7 +287,6 @@ async function hiddenKey(prompt = 'Server delivery key (hidden; not saved): ') {
   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 = '';
@@ -83,6 +309,7 @@ async function hiddenKey(prompt = 'Server delivery key (hidden; not saved): ') {
       };
       for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.once(signal, onSignal);
       input.on('data', onData); input.on('end', onEnd);
+      output.write(prompt);
     });
   } finally { input.setRawMode(previousRaw); input.pause(); output.write('\n'); }
 }
@@ -102,19 +329,195 @@ async function ask(prompt) {
   } finally { input.off('SIGINT', cancel); input.off('close', cancel); input.close(); }
 }
 
+function guidedArguments(args) {
+  if (args[0] === 'start') args = args.slice(1);
+  const names = new Set(['--cms', '--code', '--project']), options = {};
+  for (let index = 0; index < args.length; index++) {
+    const name = args[index];
+    if (Object.hasOwn(options, name)) throw new SetupError('Each option can be given once.');
+    if (name === '--details') { options[name] = true; continue; }
+    if (!names.has(name)) throw new SetupError(`Unknown option ${JSON.stringify(name.slice(0, 40))}. Use --help for instructions.`);
+    const value = args[++index];
+    if (!value || value.startsWith('--')) throw new SetupError('An option is missing its value.');
+    options[name] = value;
+  }
+  return options;
+}
+
 async function main() {
   if (process.argv.slice(2).some(value => value === '--help' || value === '-h')) { process.stdout.write(help); return; }
+  const first = process.argv[2];
+  if (first === undefined || first === 'start' || first.startsWith('--')) {
+    // The one-time pairing code is the only accepted credential-like argument:
+    // it expires in ten minutes, works once and never reaches project files.
+    const options = guidedArguments(process.argv.slice(2));
+    if (!process.stdin.isTTY || !process.stderr.isTTY) throw new SetupError('This setup needs an interactive terminal. Run it directly in your website folder.');
+    await runGuided(options['--project'] ?? process.cwd(), { cms: options['--cms'], code: options['--code'], details: options['--details'] === true }, processIo({ ask, write: value => process.stdout.write(value) }));
+    return;
+  }
   const { command, options } = argumentsFor(process.argv.slice(2));
   const project = options['--project'] ?? process.cwd();
+  if (command === 'inspect-pages' || command === 'review-pages') {
+    const mappingOptions = { locale: options['--locale'] ?? 'en', ...(options['--website-origin'] ? { websiteOrigin: options['--website-origin'] } : {}) };
+    if (command === 'inspect-pages' || options['--dry-run'] || options['--non-interactive']) {
+      const inventory = await inspectPageCandidates(project, mappingOptions);
+      process.stdout.write(JSON.stringify({ ...inventory, installed: false, bindingsVerified: false, liveVerified: false,
+        message: 'Discovery only. Candidates are not verified content bindings. Review-pages can record ownership intent; it does not install website routes, resolve preflight blockers, or publish content.' }, null, 2) + '\n');
+      return;
+    }
+    if (!process.stdin.isTTY || !process.stderr.isTTY) throw new SetupError('Page mapping review requires an interactive terminal. Use inspect-pages or review-pages --dry-run to inspect without writes.');
+    await runPageMappingReview(project, { ask, write: value => process.stdout.write(value) }, mappingOptions);
+    return;
+  }
+  if (command === 'review-layout') {
+    const {nativeFramework} = await import('./native-adapters.mjs');
+    const reviewRoot = await projectRoot(project);
+    let reviewManifest; try { reviewManifest = JSON.parse(await readProjectFile(reviewRoot,'package.json')); } catch { throw new SetupError('A valid website package.json is required for layout review.'); }
+    if(nativeFramework(reviewManifest)) {
+      const {planNativeChromeReview,runNativeChromeReview} = await import('./native-chrome-review.mjs');
+      if(options['--dry-run'] || options['--non-interactive']) {
+        const plan=await planNativeChromeReview(project);
+        process.stdout.write('Native layout plan: preserve existing native links, controls and classes; add empty settings slots and a hashed review declaration.\n');
+        for(const page of plan.pages)process.stdout.write(`  ${page.change}: ${page.path} (${page.slots.length} settings slots)\n`);
+        process.stdout.write('Plan only. No files changed. Run review-layout in an interactive terminal to review and save.\n');return;
+      }
+      if(!process.stdin.isTTY || !process.stderr.isTTY)throw new SetupError('Layout review requires an interactive terminal. Use --dry-run to inspect without writes.');
+      await runNativeChromeReview(project,{write:value=>process.stdout.write(value),ask});return;
+    }
+    const { planSettingsLayoutReview } = await import('./next-settings-layout.mjs');
+    const plan = await planSettingsLayoutReview(project);
+    process.stdout.write('Review existing website header/footer slots. Native controls and links are preserved; CMS settings consumers will be installed during full setup. This command saves a public review declaration only.\n');
+    for (const slot of plan.slots) process.stdout.write(`  ${slot.kind}: ${slot.path} — append ${slot.kind === 'header' ? 'CMS branding, navigation and language links' : 'CMS navigation, social links and consent controls'}; preserve existing native content.\n`);
+    process.stdout.write(`  Review covers ${plan.files.filter(file => file.state === 'unchanged').length} existing source/configuration files.\n`);
+    for (const file of plan.files.filter(file => ['create','update'].includes(file.state))) process.stdout.write(`  ${file.state}: ${file.path}\n`);
+    if (options['--dry-run'] || options['--non-interactive']) {
+      process.stdout.write('Plan only. No files changed. Run review-layout in an interactive terminal to review and save.\n');
+      return;
+    }
+    if (!process.stdin.isTTY || !process.stderr.isTTY) throw new SetupError('Layout review requires an interactive terminal. Use --dry-run to inspect without writes.');
+    const answer = (await ask('Save this header/footer layout review? [y/N] ')).trim().toLowerCase();
+    if (!['y','yes'].includes(answer)) { process.stdout.write('Layout review cancelled. No files changed.\n'); return; }
+    if (JSON.stringify(await planSettingsLayoutReview(project)) !== JSON.stringify(plan)) throw new SetupError('The layout changed during review. No declaration was saved.');
+    await applyPlan(plan);
+    process.stdout.write('Layout review saved. Rerun scoped preflight, then complete full setup and the running-website checks. This review alone does not install an endpoint or verify settings.\n');
+    return;
+  }
+  if (command === 'review-routes') {
+    if (options['--dry-run'] || options['--non-interactive']) {
+      const {root, ...result} = await inspectNativeRouteCandidates(project);
+      process.stdout.write(JSON.stringify({ ...result, installed: false, message: 'Plan only. Run review-routes in an interactive terminal to select and confirm native routes.' }, null, 2) + '\n');
+    } else {
+      if (!process.stdin.isTTY || !process.stderr.isTTY) throw new SetupError('Route review requires an interactive terminal. Use --dry-run to inspect without writes.');
+      await runNativeRouteReview(project, { ask, write: value => process.stdout.write(value) });
+    }
+    return;
+  }
+  if (command === 'preflight') {
+    const result = await preflightSetup(project, {
+      apiOrigin: options['--api-origin'], siteId: options['--site'], environmentId: options['--environment'],
+      locale: options['--locale'], websiteOrigin: options['--website-origin'], adminOrigin: options['--admin-origin'],
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (result.status !== 'planned') process.exitCode = 1;
+    return;
+  }
+  if (command === 'connect' || command === 'server-key') {
+    if (!process.stdin.isTTY || !process.stderr.isTTY) throw new SetupError('Connect and server-key need an interactive terminal. No credentials are accepted as command-line options.');
+    const io = { ask, hidden: hiddenKey, write: value => process.stdout.write(value) };
+    const skipValidation = options['--skip-key-validation'] === true;
+    if (command === 'server-key' && options['--prepare-only']) await runPrepareServerKey(project, {
+      apiOrigin: options['--api-origin'], siteId: options['--site'], environmentId: options['--environment'],
+      locale: options['--locale'], websiteOrigin: options['--website-origin'], adminOrigin: options['--admin-origin'],
+    }, io);
+    else if (command === 'server-key') await runServerKey(project, io, {
+      validateKey: !skipValidation,
+    });
+    else await runConnect(project, {
+      apiOrigin: options['--api-origin'], siteId: options['--site'], environmentId: options['--environment'],
+      locale: options['--locale'], websiteOrigin: options['--website-origin'], adminOrigin: options['--admin-origin'],
+    }, io);
+    return;
+  }
+  if (command === 'setup-settings') {
+    process.stdout.write(`${JSON.stringify(await setupWebsiteSettings(project, {apply: options['--apply'] === true}),null,2)}\n`);
+    return;
+  }
+  if (command === 'check-settings') {
+    const result=await checkWebsiteSettings(project,{siteId:options['--site'],environmentId:options['--environment'],websiteOrigin:options['--website-origin'],adminOrigin:options['--admin-origin']});
+    process.stdout.write(`${JSON.stringify(result)}\n`);if(!result.checked||WEBSITE_SECTIONS.some(name=>result.sections?.[name]?.installed!==true))process.exitCode=1;return;
+  }
+  if (command === 'sync-source') {
+    process.stdout.write(`${JSON.stringify(await syncSource(project))}\n`);
+    return;
+  }
+  if (command === 'finalize-source') {
+    process.stdout.write(`${JSON.stringify(await finalizeSource(project, { apply: options['--apply'] === true }))}\n`);
+    return;
+  }
+  if (command === 'check-publication') {
+    const result = await checkPublication(project, { websiteOrigin: options['--website-origin'], adminOrigin: options['--admin-origin'], siteId: options['--site'], environmentId: options['--environment'], path: options['--path'] });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (!result.checked) process.exitCode = 1;
+    return;
+  }
+  if (command === 'setup-source') {
+    if (options['--require-server-key'] && !options['--api-origin']) throw new SetupError('Key-first source setup requires --api-origin from Developer setup so the prepared key cannot be rebound to a different CMS API.');
+    const saved = await readSourceSettings(project);
+    const required = [['--website-origin', 'Website origin', saved.websiteOrigin], ['--admin-origin', 'CMS admin origin', saved.adminOrigin], ['--site', 'Website UUID', saved.siteId], ['--environment', 'Environment UUID', saved.environmentId]];
+    for (const [flag, label, fallback] of required) {
+      if (!options[flag] && !fallback && !options['--non-interactive'] && process.stdin.isTTY) options[flag] = (await ask(`${label}: `)).trim();
+    }
+    const keyCheck = options['--require-server-key'] ? await prepareSourceKeyCheck(project, {
+      apiOrigin: options['--api-origin'], siteId: options['--site'] ?? saved.siteId, environmentId: options['--environment'] ?? saved.environmentId,
+      locale: options['--locale'] ?? saved.locale ?? 'en', websiteOrigin: options['--website-origin'] ?? saved.websiteOrigin, adminOrigin: options['--admin-origin'] ?? saved.adminOrigin,
+    }) : null;
+    const plan = await setupSource(project, { websiteOrigin: options['--website-origin'], adminOrigin: options['--admin-origin'], siteId: options['--site'], environmentId: options['--environment'], locale: options['--locale'] });
+    if (keyCheck) process.stdout.write('SERVER KEY PREPARED: Saved private settings match this source setup. Key authorization and published rendering remain unverified; no key is sent to the source endpoint.\n');
+    process.stdout.write('CONTENT IMPORT ONLY: This command prepares the public source endpoint. It does not connect published CMS edits to the original website pages, install publication checks, or request a server key.\n');
+    process.stdout.write(plan.framework === 'astro'
+      ? 'Astro exports the reviewed literal public pages through its Node server. Private, dynamic or custom routes require a reviewed adapter; source exclusions are not guessed. No credentials or CMS writes are used.\n'
+      : plan.framework === 'vite' ? 'Vite export serves reviewed public pages/posts from .universalcms/source.entries.json. No credentials or CMS writes are used.\n' : 'Automatic export includes public static page copy. Exclude private paths in source.config.json; dynamic content and unresolved components need review. No credentials or CMS writes are used.\n');
+    for (const file of plan.files) process.stdout.write(`  ${file.state}: ${file.path}\n`);
+    process.stdout.write(`${JSON.stringify(plan.diagnostics)}\n`);
+    if (plan.retainedAdapter) process.stdout.write('Existing source adapter retained. Its reviewed base mappings are preserved; verify that the adapter serves the refreshed automatic snapshot with check-source.\n');
+    if (options['--apply']) {
+      if (keyCheck) await keyCheck();
+      const result = await applySourcePlan(plan, keyCheck ? { beforeWrite: keyCheck } : undefined);
+      process.stdout.write(`Source setup saved: ${result.created.length} created; ${result.updated.length} updated.\n`);
+      await reportSourceReadiness(plan);
+    } else process.stdout.write('Plan only: no files changed. Review the public-content scope and run again with --apply.\n');
+    return;
+  }
   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, {
+    const setupOptions = {
+      originalRoutesOnly: options['--original-routes-only'],
       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) });
+    };
+    try {
+      const result = await runSetup(project, setupOptions, { ask, hidden: hiddenKey, write: value => process.stdout.write(value) });
+      if (result.settingsInstalled === false) process.exitCode = 1;
+      else if (result.saved) await reportSetupReadiness(project);
+    }
+    catch (error) {
+      const blocker = setupReviewDiagnostic(error);
+      if (blocker) process.stderr.write(`${JSON.stringify({ status: 'review-required', blockers: [blocker], recovery: setupRecovery({ phase: blocker.stage, framework: 'Next.js', blocker }) }, null, 2)}\n`);
+      if (error instanceof SetupError && /custom history\/location router|Vite source export is missing|content route mapping/.test(error.message)) await reportReviewedSourceAlternative(project, setupOptions);
+      throw error;
+    }
     return;
   }
   if (command === 'analyze') { process.stdout.write(`${JSON.stringify(await analyze(project), null, 2)}\n`); return; }
+  if (command === 'check-source') {
+    const result = await checkSource(project, {
+      websiteOrigin: options['--website-origin'], adminOrigin: options['--admin-origin'],
+      siteId: options['--site'], environmentId: options['--environment'], checkRoutes: options['--check-routes'],
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (!result.checked) process.exitCode = 1;
+    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 };