@universalcms/connect 0.1.0 → 0.13.1

package/dist/guided.mjs

@@ -0,0 +1,514 @@
+/**
+ * One-command website connection: `npx @universalcms/connect`.
+ *
+ * Pairs with the CMS (browser approval or a one-time code), installs the
+ * matching connector, then runs the same reviewed setup, key, check, import
+ * and finalize steps as the individual commands. Every effect is injected so
+ * the flow is testable; rerunning it continues from the first unfinished step.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { analyze, applyPlan, projectRoot, readProjectFile, SetupError } from './core.mjs';
+import { runSetup } from './wizard.mjs';
+import { readConnection, runServerKey, validateConnection } from './staged-setup.mjs';
+import { readSetupEnvironment } from './setup-environment.mjs';
+import { readSourceSettings } from './source-setup.mjs';
+import { checkPublication } from './publication-check.mjs';
+import { finalizeSource } from './source-finalize.mjs';
+import { preflightSetup } from './preflight.mjs';
+import { planSettingsOnly, SETTINGS_ONLY_FILE } from './settings-only-setup.mjs';
+import { applyEnvironment, planEnvironment } from './setup-environment.mjs';
+
+export const PAIRING_WAIT_MS = 10 * 60 * 1000;
+export const WEBSITE_WAIT_MS = 15 * 60 * 1000;
+const codePattern = /^cms_pair\.[0-9a-f-]{36}\.[0-9a-f-]{36}\.[A-Za-z0-9_-]{43}$/;
+const serverKey = /^cms_server\.[0-9a-f-]{36}\.[0-9a-f-]{36}\.[A-Za-z0-9_-]{43}$/;
+const fail = message => { throw new SetupError(message); };
+const yes = answer => ['', 'y', 'yes'].includes(answer.trim().toLowerCase());
+// Prompts from the reviewed setup that the single plain-language review already covers.
+const covered = new Map([
+  ['Install header/footer and website settings? [Y/n] ', 'y'],
+  ['Save a server key now? [Y/n] ', 'y'],
+  ['Save this server key? [Y/n] ', 'y'],
+]);
+
+export function cmsOrigin(value) {
+  if (typeof value !== 'string' || value.length > 2048) return null;
+  try {
+    const url = new URL(value.includes('://') ? value : `https://${value}`);
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/') return null;
+    return url.protocol === 'https:' || url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) ? url.origin : null;
+  } catch { return null; }
+}
+
+async function connectorVersion() {
+  const manifest = JSON.parse(await readFile(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
+  return manifest.version;
+}
+
+async function manifestOf(root) {
+  try {
+    const value = JSON.parse(await readProjectFile(root, 'package.json'));
+    if (value && typeof value === 'object' && !Array.isArray(value)) return value;
+  } catch { /* Fixed guidance follows. */ }
+  return fail('Run this command inside your website folder — the folder that contains package.json.');
+}
+
+export async function packageManager(root, manifest) {
+  const declared = typeof manifest.packageManager === 'string' && /^(npm|pnpm|yarn|bun)@/.exec(manifest.packageManager);
+  if (declared) return declared[1];
+  for (const [file, manager] of [['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun']]) {
+    try { if ((await lstat(path.join(root, file))).isFile()) return manager; } catch { /* Not this manager. */ }
+  }
+  return 'npm';
+}
+export function installArguments(manager, spec) { return manager === 'npm' ? ['install', '--save-prod', spec] : ['add', spec]; }
+
+/** Best guess for the address the website runs on locally; the person confirms it in the browser. */
+export function suggestedOrigin(manifest, framework) {
+  const dev = typeof manifest.scripts?.dev === 'string' ? manifest.scripts.dev : '';
+  const port = /(?:--port|-p)[ =](\d{2,5})\b/.exec(dev)?.[1];
+  const defaults = { 'Next.js': 3000, Nuxt: 3000, React: 5173, Vue: 5173, SvelteKit: 5173, Astro: 4321, Angular: 4200 };
+  const chosen = port ? Number(port) : defaults[framework];
+  return chosen && chosen <= 65535 ? `http://localhost:${chosen}` : null;
+}
+
+async function installedConnector(root) {
+  try { return JSON.parse(await readFile(path.join(root, 'node_modules', '@universalcms', 'connect', 'package.json'), 'utf8')).version ?? null; }
+  catch { return null; }
+}
+
+/** The website imports the connector at runtime, so it must be a matching production dependency. */
+async function ensureConnector(root, manifest, io) {
+  const version = await connectorVersion();
+  if (typeof manifest.dependencies?.['@universalcms/connect'] === 'string' && await installedConnector(root) === version) return;
+  const override = io.env.UNIVERSALCMS_CONNECT_PACKAGE;
+  if (override !== undefined && !/^[^\s'"`;&|<>$]{1,2048}$/.test(override)) fail('UNIVERSALCMS_CONNECT_PACKAGE must be a package spec, file path or URL without spaces.');
+  const spec = override ?? `@universalcms/connect@${version}`;
+  const manager = await packageManager(root, manifest);
+  const args = installArguments(manager, spec);
+  io.write(`\nYour website needs the Universal CMS package. I'll run:\n  ${manager} ${args.join(' ')}\n`);
+  if (!yes(await io.ask('Add it now? [Y/n] '))) fail(`Nothing was changed. When you're ready, run the same command again.`);
+  if (await io.run(manager, args, root) !== 0) fail(`The package could not be installed. Check your internet connection, then run:\n  ${manager} ${args.join(' ')}\nand start this command again.`);
+  if (await installedConnector(root) !== version) fail(`The installed package version does not match this setup (${version}). Run the same command again; if it repeats, run ${manager} ${args.join(' ')} yourself.`);
+  io.write('✔ Universal CMS package added\n');
+}
+
+/**
+ * A website that already renders its own header and footer needs a saved
+ * layout review before setup. Present that same review in plain language;
+ * when it does not apply, setup reports its own reason.
+ */
+async function reviewLayout(root, manifest, framework, io) {
+  const { nativeFramework } = await import('./native-adapters.mjs');
+  let plan, replan;
+  try {
+    if (nativeFramework(manifest)) {
+      const { planNativeChromeReview } = await import('./native-chrome-review.mjs');
+      replan = () => planNativeChromeReview(root);
+    } else if (framework === 'Next.js') {
+      const { planSettingsLayoutReview } = await import('./next-settings-layout.mjs');
+      replan = () => planSettingsLayoutReview(root);
+    } else return false;
+    plan = await replan();
+  } catch { return false; }
+  const changes = plan.files.filter(file => ['create', 'update'].includes(file.state));
+  if (!changes.length) return false;
+  const sources = [...new Set((plan.slots ?? plan.pages ?? []).map(item => item.path))];
+  io.write(`\nYour website already has its own header and footer${sources.length ? ` (${sources.join(', ')})` : ''}.\nI'll keep them exactly as they are and add places where menus and settings from the CMS can appear.\n`);
+  if (!yes(await io.ask('Okay? [Y/n] '))) fail('Nothing was changed. Run the same command again when you are ready.');
+  if (JSON.stringify(await replan()) !== JSON.stringify(plan)) fail('Your website files changed while reviewing. Nothing was saved; run the same command again.');
+  await applyPlan(plan);
+  io.write('✔ Header and footer reviewed\n');
+  return true;
+}
+
+// Static paths that are usually interactive application screens rather than
+// editable pages. They are proposed as website-owned; the person can change it.
+export const ALL_APP_SCREENS = 'Every page in this website is an interactive app screen (built with state, tabs or data lists), so none of its page text can be made editable automatically yet.';
+const appScreen = /(^|\/)(cart|basket|bag|checkout|payment|pay|orders?|order-history|track(ing)?|account|my-account|profile|settings|login|log-in|signin|sign-in|signup|sign-up|register|logout|auth|dashboard|admin|portal|wishlist|favou?rites|search|upload[\w-]*|book(ing)?s?|reservations?|messages|inbox|notifications|api)(\/|$)/i;
+
+/** Propose which routes stay part of the website app; ask once; save the reviewed manifest. */
+async function reviewRoutes(root, blocker, io, reason) {
+  const { inspectNativeRouteCandidates, planNativeRouteReview } = await import('./native-route-review.mjs');
+  let inventory;
+  try { inventory = await inspectNativeRouteCandidates(root); } catch { return false; }
+  const files = new Set(blocker?.paths ?? []);
+  const flagged = new Set([...files].map(name => name.replace(/^(?:src\/)?app/, '')));
+  for (const row of inventory.candidates) if (files.has(row.file)) flagged.add(row.path);
+  const existing = await readProjectFile(root, '.universalcms/native.routes.json').then(text => text ? JSON.parse(text) : null).catch(() => null);
+  for (const path of [...existing?.nativePaths ?? [], ...existing?.nativePatterns ?? []]) flagged.add(path);
+  // Client components render from state, so their text cannot be bound to CMS content.
+  const client = new Set();
+  for (const row of inventory.candidates) {
+    const text = await readProjectFile(root, row.file).catch(() => null);
+    if (text && /^\s*(?:\/\/[^\n]*\n|\/\*[\s\S]*?\*\/\s*)*['"]use client['"]/.test(text)) client.add(row.path);
+  }
+  let owned = inventory.candidates.filter(row => row.kind === 'dynamic' || flagged.has(row.path) || client.has(row.path) || appScreen.test(row.path)).map(row => row.path);
+  if (!inventory.candidates.some(row => row.kind === 'static' && !owned.includes(row.path)) && inventory.candidates.filter(row => row.kind === 'static').every(row => client.has(row.path) || flagged.has(row.path) || appScreen.test(row.path)) && inventory.candidates.some(row => client.has(row.path) || flagged.has(row.path))) throw new SetupError(ALL_APP_SCREENS);
+  const cmsPages = () => inventory.candidates.filter(row => row.kind === 'static' && !owned.includes(row.path));
+  if (!cmsPages().length) {
+    if (reason) throw new SetupError(ALL_APP_SCREENS);
+    owned = owned.filter(path => path !== '/');
+  }
+  const show = () => {
+    io.write('\nI looked at every page in your website:\n');
+    inventory.candidates.forEach((row, index) => io.write(`  ${String(index + 1).padStart(2)}. ${row.path === '/' ? '/ (home page)' : row.path}${row.kind === 'dynamic' ? ' (one page per item)' : client.has(row.path) && owned.includes(row.path) ? ' (interactive)' : ''} — ${owned.includes(row.path) ? 'stays as part of your website app' : 'editable in the CMS'}\n`));
+  };
+  if (reason) io.write(`\n${reason}\n`);
+  show();
+  io.write('Pages that stay part of your website app keep working exactly as they do now (shopping, accounts, forms, product details).\nAll other pages become editable in the CMS. Header, footer and site settings are managed in the CMS either way.\n');
+  while (true) {
+    const answer = (await io.ask('Use this? [Y/n, or type page numbers to switch them, e.g. 3,5] ')).trim();
+    if (yes(answer)) break;
+    if (/^n(o)?$/i.test(answer)) fail('Nothing was changed. Run the same command again when you are ready.');
+    if (!/^\d+(\s*,\s*\d+)*$/.test(answer)) { io.write('Type Y, n, or page numbers separated by commas.\n'); continue; }
+    for (const index of answer.split(',').map(value => Number(value.trim()) - 1)) {
+      const row = inventory.candidates[index];
+      if (!row) continue;
+      owned = owned.includes(row.path) ? owned.filter(path => path !== row.path) : [...owned, row.path];
+    }
+    if (!cmsPages().length) { io.write('At least one page must stay editable in the CMS.\n'); owned = owned.filter(path => path !== '/'); }
+    show();
+  }
+  if (!owned.length) return false;
+  const plan = await planNativeRouteReview(root, owned);
+  if (JSON.stringify(await planNativeRouteReview(root, owned)) !== JSON.stringify(plan)) fail('Your website files changed while reviewing. Nothing was saved; run the same command again.');
+  await applyPlan(plan);
+  io.write('✔ Website app pages reviewed\n');
+  return true;
+}
+
+/** Plain-language guidance for what to change in the website when a blocker cannot be fixed automatically. */
+export function siteChangeAdvice(blocker) {
+  const message = blocker?.message ?? '', paths = blocker?.paths ?? [];
+  const where = paths.length ? ` (${paths.slice(0, 6).join(', ')}${paths.length > 6 ? ', …' : ''})` : '';
+  if (/next\.config|Configuration needs developer inspection|Dynamic Next configuration|configuration uses values/i.test(message)) return [`Your Next.js config is computed when it runs, so it can't be read safely. Make next.config export a plain object, for example:\n      module.exports = { reactStrictMode: true };`];
+  if (/static export|output:\s*'export'/i.test(message)) return ['Your site is built as static files only. The CMS needs your site to run its Node server: remove `output: "export"` from next.config and deploy with `next start` (or another Node host).'];
+  if (/Pages Router|pages\//.test(message)) return ['Your site uses the older Next.js Pages Router (pages/ folder). Move the pages you want editable into the App Router (app/ folder), or ask your developer for a custom integration.'];
+  if (/Workspaces|workspace/i.test(message)) return ['Run this command inside the single website folder (the one with its own package.json), not the monorepo root.'];
+  if (/version|Node\.js|supported/i.test(message) && /requires?|supports?|unsupported/i.test(message)) return [`A framework or Node.js version is outside the supported range. ${message}`];
+  if (message === ALL_APP_SCREENS) return [message, 'To make a page editable from the CMS, write its main text directly in the page file (headings, paragraphs, images as plain JSX in a server component, without \'use client\'), and keep interactive parts like carts, tabs and product lists in separate components. Then run this command again.', 'Ask your developer if you need a custom integration for data-driven pages.'];
+  if (blocker?.code === 'content-bindings-review' || /content adapter|bindings|repeated|data-driven|route props/i.test(message)) return [`Some pages${where} build their text from data, props or loops, so the CMS can't tell which words to make editable. Either keep those pages as part of your website app (rerun and switch them), or write the editable text directly in the page (headings, paragraphs and images as plain JSX).`];
+  if (/header|footer|layout|chrome/i.test(message)) return [`Your header or footer${where} is built from components or logic the CMS can't safely extend. Put the header and footer markup directly in the root layout (plain <header>/<footer> elements), then rerun.`];
+  if (/route|dynamic|parallel/i.test(message)) return [`Some routes${where} use patterns that need a developer: catch-all, parallel or intercepted routes. Keep them in your app and ask your developer for a reviewed adapter.`];
+  return ['This website uses a pattern the automatic setup does not support yet.'];
+}
+
+/**
+ * Check the website before anything is installed, fix what can be fixed safely
+ * with one plain question each, and explain the rest. Resolving one finding can
+ * reveal the next, so it loops a bounded number of times.
+ */
+async function prepareWebsite(root, connection, manifest, framework, io) {
+  const scope = Object.fromEntries(['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'].map(name => [name, connection[name]]));
+  const attempted = new Set();
+  for (let round = 0; round < 6; round++) {
+    const result = await preflightSetup(root, scope);
+    if (result.status === 'planned') return 'full';
+    const blocker = result.blockers?.[0];
+    const key = `${blocker?.code}:${blocker?.message}:${(blocker?.paths ?? []).join(',')}`;
+    let advice = blocker;
+    if (blocker && !attempted.has(key)) try {
+      attempted.add(key);
+      if (blocker.code === 'next-route-ownership' && await reviewRoutes(root, blocker, io)) continue;
+      if (blocker.code === 'content-bindings-review' && framework === 'Next.js' && blocker.paths?.length && await reviewRoutes(root, blocker, io, `${blocker.paths.join(', ')} builds its text from data or loops, so its words can't be made editable automatically. I've switched it to stay part of your website app (it keeps working as it does now).`)) continue;
+      if (['native-chrome-layout', 'native-settings-layout'].includes(blocker.code) && await reviewLayout(root, manifest, framework, io)) continue;
+    } catch (error) { if (error?.message !== ALL_APP_SCREENS) throw error; advice = { message: ALL_APP_SCREENS }; }
+    // Pages that cannot be edited automatically can still have their site
+    // settings managed by the CMS while the website keeps rendering every page.
+    if (framework === 'Next.js' && (advice?.message === ALL_APP_SCREENS || ['content-bindings-review', 'next-route-ownership'].includes(blocker?.code))) {
+      io.write(`\n${advice?.message === ALL_APP_SCREENS ? ALL_APP_SCREENS : 'Some pages in this website can\'t be made editable automatically.'}\n`);
+      io.write('You can still connect it for site settings: the CMS manages your menus, logo and branding, SEO (titles, descriptions, social previews), analytics, scripts, cookie consent and redirects. Every page keeps working exactly as it does now.\n');
+      if (yes(await io.ask('Connect for site settings? [Y/n] '))) return 'settings-only';
+    }
+    io.write('\n✋ Your website needs a small change before it can connect:\n');
+    for (const line of siteChangeAdvice(advice)) io.write(`   • ${line}\n`);
+    io.write(`\nDetails for your developer:\n   ${result.message ?? blocker?.message ?? 'Preflight did not pass.'}\n`);
+    fail('Your website files were not changed (only the Universal CMS package was added). Make the change above, then run the same command again.');
+  }
+  fail('Setup found more items to review than it can handle automatically. Ask your developer to run the step-by-step setup in Developer setup.');
+}
+
+function pkce() {
+  const verifier = randomBytes(32).toString('base64url');
+  return { verifier, challenge: createHash('sha256').update(verifier).digest('base64url'), state: randomBytes(32).toString('base64url') };
+}
+const page = (title, body) => `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${title}</title></head><body style="font:16px/1.6 system-ui,sans-serif;margin:0;padding:64px 16px;text-align:center;color:#0f172a;background:#f8fafc"><h1 style="font-size:22px">${title}</h1><p>${body}</p></body></html>`;
+
+/** Listen on loopback for the admin to hand back a pairing code bound to this run's state. */
+export async function waitForBrowserApproval({ cms, request, io, timeoutMs = PAIRING_WAIT_MS }) {
+  const { verifier, challenge, state } = pkce();
+  let settle;
+  const result = new Promise((resolve, reject) => { settle = { resolve, reject }; });
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+    if (req.method !== 'GET' || url.pathname !== '/callback') { res.writeHead(404).end(); return; }
+    const code = url.searchParams.get('code') ?? '', returned = Buffer.from(url.searchParams.get('state') ?? ''), expected = Buffer.from(state);
+    const valid = returned.length === expected.length && timingSafeEqual(returned, expected) && codePattern.test(code);
+    res.writeHead(valid ? 200 : 400, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer' });
+    res.end(valid ? page('Approved — back to your terminal', 'You can close this tab. Setup continues in your terminal.') : page('This link is not valid', 'Start the connection again from your terminal.'));
+    if (valid) {
+      let scope = null;
+      try { scope = validateConnection({ version: 1, ...Object.fromEntries(['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'].map(name => [name, url.searchParams.get(name) ?? undefined])) }); } catch { /* Older CMS: check after redemption. */ }
+      settle.resolve({ code, scope });
+    }
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  const timer = setTimeout(() => settle.reject(new SetupError('No approval arrived within 10 minutes. Run the same command again to start over.')), timeoutMs);
+  try {
+    const { port } = server.address();
+    const query = new URLSearchParams({ callback: `http://127.0.0.1:${port}/callback`, state, challenge, ...Object.fromEntries(Object.entries(request).filter(([, value]) => value)) });
+    const link = `${cms}/connect?${query}`;
+    io.write('\nOpening your browser to approve this website…\n');
+    if (!await io.openUrl(link)) io.write('Your browser did not open. Open this link to continue:\n');
+    io.write(`  ${link}\n\nWaiting for approval… (no browser on this computer? In the CMS open Developer setup → “Connect without a browser”)\n`);
+    const { code, scope } = await result;
+    return { code, verifier, scope };
+  } finally { clearTimeout(timer); server.close(); }
+}
+
+export async function redeem(cms, code, verifier, fetcher) {
+  let response;
+  try {
+    response = await fetcher(`${cms}/api/cms/connect/pairings/redeem`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ code, ...(verifier ? { verifier } : {}) }), redirect: 'error', signal: AbortSignal.timeout(15000) });
+  } catch { fail(`The CMS at ${cms} could not be reached. Check the address and your internet connection, then try again.`); }
+  if (response.status === 401) fail('This approval expired or was already used. Run the same command again to start over.');
+  let body;
+  try { body = await response.json(); } catch { /* Fixed guidance follows. */ }
+  if (!response.ok || !body?.data) fail(`The CMS could not finish the connection (HTTP ${response.status}). Try again in a minute.`);
+  const data = body.data;
+  const connection = validateConnection({ version: 1, apiOrigin: data.apiOrigin, siteId: data.siteId, environmentId: data.environmentId, locale: data.locale, websiteOrigin: data.websiteOrigin, adminOrigin: data.adminOrigin });
+  if (typeof data.serverKey !== 'string' || !serverKey.test(data.serverKey)) fail('The CMS returned an unexpected response. No key was saved.');
+  return { connection, siteName: typeof data.siteName === 'string' ? data.siteName.slice(0, 100) : '', serverKey: data.serverKey };
+}
+
+function describeRoute(route) { return route.path === '/' ? '/ (home page)' : route.path; }
+
+/** Adapts the reviewed setup's terminal prompts: one review for the person, the key from pairing. */
+function setupIo(io, key, details) {
+  let pending = key;
+  const log = [];
+  return {
+    log,
+    write: text => { log.push(text); if (details) io.write(text); },
+    ask: async prompt => covered.has(prompt) ? covered.get(prompt) : (io.write(log.splice(0).join('')), io.ask(prompt)),
+    hidden: async () => {
+      if (!pending) fail('The website key from the CMS was not accepted. Run the same command again.');
+      const value = pending; pending = undefined; return value;
+    },
+    review: async ({ framework, routes, files }) => {
+      const added = files.filter(file => file.state === 'create').length, changed = files.filter(file => ['update', 'append', 'replace'].includes(file.state)).length;
+      io.write(`\nReady to connect your ${framework} website:\n`);
+      if (routes.length) io.write(`  • These pages become editable in the CMS: ${routes.slice(0, 8).map(describeRoute).join(', ')}${routes.length > 8 ? ` and ${routes.length - 8} more` : ''}\n`);
+      io.write('  • Header, footer and site settings can be managed in the CMS\n');
+      io.write(`  • ${added} file${added === 1 ? '' : 's'} will be added${changed ? ` and ${changed} updated` : ''} — your design stays the same\n`);
+      io.write('  • The website key is saved privately in .env.local (never committed to Git)\n');
+      if (routes.length) io.write('  ! After setup, these pages show “not found” until you publish them in the CMS.\n');
+      if (details) for (const file of files) io.write(`      ${file.state}: ${file.path}\n`);
+      else io.write('  (run with --details to list every file)\n');
+      return yes(await io.ask('\nGo ahead? [Y/n] '));
+    },
+  };
+}
+
+async function restartHint(root, manifest) {
+  const manager = await packageManager(root, manifest);
+  return typeof manifest.scripts?.dev === 'string' ? `${manager} run dev` : null;
+}
+
+/** Poll until the running website serves the installed integration. */
+async function waitForWebsite(root, connection, manifest, io, reason) {
+  const values = { websiteOrigin: connection.websiteOrigin, adminOrigin: connection.adminOrigin, siteId: connection.siteId, environmentId: connection.environmentId };
+  let outcome = await io.checkPublication(root, values);
+  if (outcome.checked) return true;
+  const local = /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|$)/.test(connection.websiteOrigin);
+  const command = await restartHint(root, manifest);
+  io.write(`\n→ ${reason}\n`);
+  io.write(local
+    ? `   1. In the terminal where your website is running, press Ctrl+C\n   2. Start it again${command ? ` with: ${command}` : ''}\n   It must run at ${connection.websiteOrigin}\n`
+    : `   Deploy your website the way you normally do. It must be reachable at ${connection.websiteOrigin}\n`);
+  io.write(`   Waiting for ${connection.websiteOrigin} … (Ctrl+C stops waiting; run this command again later to continue)\n`);
+  const deadline = io.now() + WEBSITE_WAIT_MS;
+  while (io.now() < deadline) {
+    await io.sleep(3000);
+    outcome = await io.checkPublication(root, values);
+    if (outcome.checked) return true;
+  }
+  io.write(`\nThe website at ${connection.websiteOrigin} is not responding with the CMS connection yet (${outcome.message})\nRun this command again once it's running.\n`);
+  return false;
+}
+
+/** After setup: confirm the running site, guide the content import, close the bootstrap export. */
+async function goLive(root, connection, manifest, io) {
+  if (!await waitForWebsite(root, connection, manifest, io, 'Restart your website so the changes take effect:')) return { connected: false };
+  io.write('✔ Your website is connected to the CMS\n');
+  const pages = `${connection.adminOrigin}/sites/${connection.siteId}`, setup = `${pages}#setup?environmentId=${connection.environmentId}&step=import`;
+  if (!(await readSourceSettings(root)).exportClosed) {
+    io.write('\nNext, copy your existing page text into the CMS:\n');
+    io.write(`   In the CMS page that just opened, click “Connect & fetch content”\n      ${setup}\n`);
+    await io.openUrl(setup);
+    // Closing the export before the import ran would strand the original content,
+    // so this needs an explicit yes; anything else leaves it open for a rerun.
+    const answer = (await io.ask('\nDid the CMS show “Website content fetched”? [y/N] ')).trim().toLowerCase();
+    if (!['y', 'yes'].includes(answer)) { io.write('No problem — nothing was closed. Run this command again after the import shows “Website content fetched”.\n'); return { connected: true, imported: false }; }
+    await finalizeSource(root, { apply: true });
+    io.write('✔ Import finished; the temporary content export is closed\n');
+    if (!await waitForWebsite(root, connection, manifest, io, 'Restart your website one more time:')) return { connected: true, imported: true };
+  }
+  io.write(`\n🎉 All done! Your website is connected to Universal CMS.\n   Edit your pages: ${pages}\n   Publish a page in the CMS to show your changes on the website.\n   Run this command again any time to check the connection.\n`);
+  return { connected: true, imported: true, done: true };
+}
+
+/**
+ * @param {string} directory website folder
+ * @param {{ cms?: string, code?: string, details?: boolean }} options
+ * @param {{ ask, write, openUrl, run, fetch, env, sleep, now, checkPublication }} io
+ */
+export async function runGuided(directory, options, io) {
+  const root = await projectRoot(directory);
+  const manifest = await manifestOf(root);
+  io.write('\nUniversal CMS · connect your website\n');
+  const analysis = await analyze(root).catch(() => ({}));
+  const framework = typeof analysis.framework === 'string' && analysis.framework !== 'Unknown' ? analysis.framework : null;
+  io.write(`✔ Found ${framework ? `a ${framework} website` : 'a website'} in ${path.basename(root)}\n`);
+
+  const saved = await readConnection(root);
+  const environment = await readSetupEnvironment(root);
+  const installed = await readProjectFile(root, '.universalcms/website.integration.json') !== null;
+  if (saved && environment.keyConfigured && !options.code && await readProjectFile(root, SETTINGS_ONLY_FILE) !== null) {
+    io.write(`✔ Already connected for site settings (${saved.websiteOrigin})\n`);
+    return finishSettingsOnly(root, saved, manifest, io);
+  }
+  if (saved && installed && environment.keyConfigured && !options.code) {
+    io.write(`✔ Already set up for ${saved.websiteOrigin}\n`);
+    return goLive(root, saved, await manifestOf(root), io);
+  }
+
+  const cms = cmsOrigin(options.cms ?? io.env.UNIVERSALCMS_URL ?? saved?.adminOrigin ?? '') ?? await (async () => {
+    while (true) {
+      const value = cmsOrigin((await io.ask('Your Universal CMS address (for example https://cms.example.com): ')).trim());
+      if (value) return value;
+      io.write('Enter the address you use to sign in to the CMS.\n');
+    }
+  })();
+  if (options.code !== undefined && !codePattern.test(options.code)) fail('That connection code is not valid. Copy the whole command from the CMS again.');
+
+  await ensureConnector(root, manifest, io);
+  const approval = options.code
+    ? { code: options.code, verifier: undefined }
+    : await waitForBrowserApproval({ cms, io, request: { origin: saved?.websiteOrigin ?? suggestedOrigin(manifest, framework) ?? '', project: path.basename(root).slice(0, 80), framework: framework ?? '' } });
+  let mode = 'full';
+  const mismatch = connection => saved && (saved.siteId !== connection.siteId || saved.environmentId !== connection.environmentId);
+  const different = 'This folder is already connected to a different website or environment in the CMS. Choose the same website when approving, or ask your developer to review .universalcms/connection.json. Nothing was changed.';
+  // Check (and safely fix) the website before redeeming, so a blocked site
+  // never leaves an unused key behind. The approval expires on its own.
+  if (approval.scope && !installed) {
+    if (mismatch(approval.scope)) fail(different);
+    io.write('✔ Approved in the CMS — checking your website…\n');
+    mode = await prepareWebsite(root, approval.scope, manifest, framework, io);
+  }
+  const paired = await redeem(cms, approval.code, approval.verifier, io.fetch);
+  io.write(`✔ Connected to ${paired.siteName || 'your website'} (${paired.connection.websiteOrigin})\n`);
+  if (mismatch(paired.connection)) fail(different);
+  if (approval.scope && JSON.stringify(approval.scope) !== JSON.stringify(paired.connection)) fail('The approved website changed before connecting. Nothing was changed; run the same command again.');
+  if (!approval.scope && !installed) mode = await prepareWebsite(root, paired.connection, manifest, framework, io);
+  if (mode === 'settings-only') return runSettingsOnly(root, paired, manifest, options, io);
+
+  const adapter = setupIo(io, paired.serverKey, options.details === true);
+  try {
+    if (saved && installed) {
+      io.write('Saving the new website key…\n');
+      if (!(await runServerKey(root, adapter, { validateKey: true })).saved) fail('The website key was not saved.');
+    } else {
+      const result = await runSetup(root, { originalRoutesOnly: true, ...Object.fromEntries(['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'].map(name => [name, paired.connection[name]])) }, adapter);
+      if (!result.saved) { io.write('Cancelled. Nothing was changed. The approval expires on its own in 10 minutes.\n'); return { connected: false }; }
+      if (result.settingsInstalled === false) {
+        io.write(adapter.log.splice(0).join(''));
+        fail('Your pages were connected, but the header/footer part could not be finished automatically. Ask your developer to review the messages above.');
+      }
+    }
+  } catch (error) {
+    // The reviewed setup explains blockers in technical detail; show it on failure only.
+    const technical = adapter.log.splice(0).join('').trim();
+    if (technical && !options.details) io.write(`\nDetails for your developer:\n${technical}\n\n`);
+    throw error;
+  }
+  io.write('✔ Website files and private key saved\n');
+  return goLive(root, paired.connection, await manifestOf(root), io);
+}
+
+/** Ask the running website's settings endpoint, as the CMS admin does. */
+async function settingsReady(connection, io) {
+  try {
+    const url = new URL('/api/universalcms/settings', connection.websiteOrigin);
+    url.search = new URLSearchParams({ check: 'connection', siteId: connection.siteId, environmentId: connection.environmentId }).toString();
+    const response = await io.fetch(url, { headers: { Origin: connection.adminOrigin, Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(10000) });
+    const body = response.ok ? await response.json() : null;
+    return body?.mode === 'settings-only' && body.siteId === connection.siteId && body.environmentId === connection.environmentId;
+  } catch { return false; }
+}
+
+async function finishSettingsOnly(root, connection, manifest, io) {
+  if (!await settingsReady(connection, io)) {
+    const local = /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|$)/.test(connection.websiteOrigin), command = await restartHint(root, manifest);
+    io.write(local
+      ? `\n→ Restart your website so the changes take effect:\n   1. In the terminal where your website is running, press Ctrl+C\n   2. Start it again${command ? ` with: ${command}` : ''}\n   It must run at ${connection.websiteOrigin}\n`
+      : `\n→ Deploy your website the way you normally do. It must be reachable at ${connection.websiteOrigin}\n`);
+    io.write(`   Waiting for ${connection.websiteOrigin} … (Ctrl+C stops waiting; run this command again later to continue)\n`);
+    const deadline = io.now() + WEBSITE_WAIT_MS;
+    let ready = false;
+    while (!ready && io.now() < deadline) { await io.sleep(3000); ready = await settingsReady(connection, io); }
+    if (!ready) { io.write(`\nThe website at ${connection.websiteOrigin} is not serving CMS settings yet. Run this command again once it's running.\n`); return { connected: false, mode: 'settings-only' }; }
+  }
+  const settings = `${connection.adminOrigin}/sites/${connection.siteId}`;
+  io.write(`✔ Your website is connected for site settings\n\n🎉 All done! Manage it from Universal CMS:\n   ${settings}\n`);
+  io.write('   • SEO, branding, analytics, scripts, cookie consent and redirects apply automatically.\n');
+  io.write('   • To show the CMS menu in your own header or footer, add one line where it should appear:\n');
+  io.write("       import { CmsNavigation } from '@universalcms/connect/react-website';\n       <CmsNavigation location=\"header\" />   (or location=\"footer\")\n");
+  io.write('     Other drop-ins: <CmsBranding />, <CmsSocialLinks />, and useWebsiteSettings() for anything custom.\n');
+  return { connected: true, mode: 'settings-only', done: true };
+}
+
+/** Install the settings-only integration and save the website key privately. */
+async function runSettingsOnly(root, paired, manifest, options, io) {
+  const plan = await planSettingsOnly(root, Object.fromEntries(['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'].map(name => [name, paired.connection[name]])));
+  const environment = await planEnvironment(root, { ...Object.fromEntries(['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'].map(name => [name, paired.connection[name]])), apiKey: paired.serverKey });
+  const added = plan.files.filter(file => file.state === 'create').length, changed = plan.files.filter(file => file.state === 'update').length;
+  io.write(`\nReady to connect your website for site settings:\n  • ${added} file${added === 1 ? '' : 's'} will be added${changed ? ` and ${changed} updated (your root layout gets one wrapper)` : ''} — your pages and design stay the same\n  • The website key is saved privately in .env.local (never committed to Git)\n`);
+  if (options.details) for (const file of plan.files) io.write(`      ${file.state}: ${file.path}\n`);
+  else io.write('  (run with --details to list every file)\n');
+  if (!yes(await io.ask('\nGo ahead? [Y/n] '))) { io.write('Cancelled. Nothing was changed.\n'); return { connected: false }; }
+  const current = await planSettingsOnly(root, plan.connection);
+  if (JSON.stringify(current.files) !== JSON.stringify(plan.files)) fail('Your website files changed while reviewing. Nothing was saved; run the same command again.');
+  await applyEnvironment(environment);
+  await applyPlan(plan);
+  io.write('✔ Website files and private key saved\n');
+  return finishSettingsOnly(root, paired.connection, await manifestOf(root), io);
+}
+
+/** Process-backed effects for the CLI. */
+export function processIo({ ask, write }) {
+  return {
+    ask, write, env: process.env, fetch: globalThis.fetch, checkPublication,
+    sleep: ms => new Promise(resolve => setTimeout(resolve, ms)), now: () => Date.now(),
+    openUrl: url => new Promise(resolve => {
+      // Fixed launcher per platform with the URL as a single argument; never a shell string.
+      const [command, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : ['xdg-open', [url]];
+      try {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true });
+        child.once('error', () => resolve(false)); child.once('spawn', () => { child.unref(); resolve(true); });
+      } catch { resolve(false); }
+    }),
+    run: (command, args, cwd) => new Promise(resolve => {
+      // Windows package managers are .cmd shims, which Node only starts through a shell.
+      // The spec is validated above; arguments contain no shell metacharacters.
+      const child = spawn(process.platform === 'win32' ? `${command}.cmd` : command, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
+      child.once('error', () => resolve(1)); child.once('exit', code => resolve(code ?? 1));
+    }),
+  };
+}

package/dist/native-adapters.mjs

@@ -0,0 +1,31 @@
+/** Framework dispatch belongs in the connector, never in tenant services. */
+export const nativeFrameworks = Object.freeze(['vue', 'nuxt', 'angular', 'svelte', 'static']);
+export const nativeFrameworkLabels = Object.freeze({ vue: 'Vue', nuxt: 'Nuxt', angular: 'Angular', svelte: 'SvelteKit', static: 'Static' });
+export const isNativeFramework = value => nativeFrameworks.includes(value);
+export function nativeFramework(manifest) {
+  const dependencies = { ...manifest?.devDependencies, ...manifest?.dependencies };
+  if (dependencies.nuxt) return 'nuxt';
+  if (dependencies['@sveltejs/kit']) return 'svelte';
+  if (dependencies['@angular/core']) return 'angular';
+  if (dependencies.vue) return 'vue';
+  if (!Object.keys(dependencies).some(name => name !== '@universalcms/connect') && dependencies['@universalcms/connect']) return 'static';
+  return null;
+}
+async function adapter(framework) {
+  if (framework === 'vue' || framework === 'nuxt') {
+    const setup = await import('./vue-setup.mjs'), source = await import('./vue-source.mjs');
+    return { inspect: (root, manifest) => setup.inspectVueProject(root, manifest, framework), source: (root, options) => source.inspectVueSource(root, {...options,framework}), integration: (root, options) => setup.planVueIntegration(root,{...options,framework}), content: (root, config) => source.planVueContent(root,config,undefined,framework), installed: (root, config) => setup.validateInstalledVue(root,config,framework), settings: (root, options) => setup.planVueSettings(root,{...options,framework}) };
+  }
+  const name = framework;
+  if (!['angular','svelte','static'].includes(name)) throw Error('Unsupported native framework.');
+  const setup = name === 'angular' ? await import('./angular-setup.mjs') : name === 'svelte' ? await import('./svelte-setup.mjs') : await import('./static-setup.mjs');
+  const source = setup;
+  const prefix = name[0].toUpperCase()+name.slice(1);
+  return { inspect: setup[`inspect${prefix}Project`], source: source[`inspect${prefix}Source`], integration: setup[`plan${prefix}Integration`], content: source[`plan${prefix}Content`], installed: setup[`validateInstalled${prefix}`], settings: setup[`plan${prefix}Settings`] };
+}
+export async function inspectNativeProject(root,framework,manifest) { return (await adapter(framework)).inspect(root,manifest); }
+export async function inspectNativeSource(root,framework,options) { return (await adapter(framework)).source(root,options); }
+export async function planNativeIntegration(root,framework,options) { return (await adapter(framework)).integration(root,options); }
+export async function planNativeContent(root,framework,config) { return (await adapter(framework)).content(root,config); }
+export async function validateInstalledNative(root,framework,config) { return (await adapter(framework)).installed(root,config); }
+export async function planNativeSettings(root,framework,options) { return (await adapter(framework)).settings(root,options); }

package/dist/native-chrome-model.d.mts

@@ -0,0 +1,3 @@
+export type NativeChromeDescriptor = {version:1; slots:string[]; exclude:{header:string[];footer:string[]}};
+export const NATIVE_CHROME_SLOTS: readonly string[];
+export function nativeChromeDescriptor(value: unknown): NativeChromeDescriptor;

package/dist/native-chrome-model.mjs

@@ -0,0 +1,14 @@
+/** Public structural contract only. No frozen native text or credential crosses it. */
+import { publicHref } from './website-model.mjs';
+export const NATIVE_CHROME_SLOTS = Object.freeze(['branding','header-navigation','mobile-navigation','languages','footer-navigation','social','experience']);
+export function nativeChromeDescriptor(value) {
+  const fail = () => { throw Error('Reviewed native chrome is unavailable.'); };
+  if (!value || value.version !== 1 || !Array.isArray(value.slots) || JSON.stringify(value.slots) !== JSON.stringify(NATIVE_CHROME_SLOTS) || !value.exclude || Object.keys(value).some(key => !['version','slots','exclude'].includes(key)) || Object.keys(value.exclude).some(key => !['header','footer'].includes(key))) fail();
+  const exclude = {};
+  for (const name of ['header','footer']) {
+    const links = value.exclude[name];
+    if (!Array.isArray(links) || links.length > 100 || new Set(links).size !== links.length || links.some(link => typeof link !== 'string' || link.length > 2000 || publicHref(link, {mail:true}) !== link)) fail();
+    exclude[name] = [...links];
+  }
+  return {version:1, slots:[...NATIVE_CHROME_SLOTS], exclude};
+}