@universalcms/connect 0.0.0-stage → 0.13.0

package/dist/page-discovery.mjs

@@ -0,0 +1,236 @@
+/** Local page/screen discovery only. It never establishes public content or binding ownership. */
+import { createHash } from 'node:crypto';
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import ts from './vendor/typescript.cjs';
+import { projectRoot, readProjectFile, SetupError } from './core.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const plain = value => value && typeof value === 'object' && !Array.isArray(value);
+const limits = { files: 1000, nodes: 5000, bytes: 8 * 1024 * 1024, depth: 12, candidates: 1000 };
+const hidden = /^(?:\.|node_modules$|dist$|build$|coverage$|vendor$|\.next$)/;
+const sensitive = /^(?:env|credentials?|secrets?)(?:[.-]|$)/i;
+const sourceExtension = /\.(?:[cm]?[jt]sx?|vue|svelte|astro|html?|mdx?)$/;
+const moduleExtensions = ['.jsx', '.tsx', '.js', '.ts', '.mjs', '.vue', '.svelte', '.astro'];
+const nativePath = /(?:^|\/)(?:api|admin|auth|account|dashboard|billing|checkout|private|internal|patients?|vault)(?:\/|$)/i;
+const safeRelative = value => typeof value === 'string' && value.length <= 500 && !value.includes('\\') && !/cms_(?:server|public)[._]|sk-[A-Za-z0-9_-]{12,}|AIza[A-Za-z0-9_-]{20,}/i.test(value) && !path.posix.isAbsolute(value) && value.split('/').every(part => part && part !== '.' && part !== '..' && !hidden.test(part) && !sensitive.test(part) && /^[A-Za-z0-9_@()[\].+ -]+$/.test(part));
+const display = value => typeof value === 'string' && /^[A-Za-z0-9_./:@()[\] -]{1,120}$/.test(value) ? value : 'Unresolved component';
+const unwrap = node => { while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node))) node = node.expression; return node; };
+const jsxName = node => ts.isJsxSelfClosingElement(node) ? node.tagName : ts.isJsxElement(node) ? node.openingElement.tagName : null;
+const jsxAttributes = node => ts.isJsxSelfClosingElement(node) ? node.attributes.properties : ts.isJsxElement(node) ? node.openingElement.attributes.properties : [];
+const propertyName = node => node && (ts.isIdentifier(node) || ts.isStringLiteral(node)) ? node.text : null;
+const literalString = node => { node = unwrap(node); return node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : null; };
+
+/** A deterministic metadata inventory. Literal discovery is NOT a CMS-ready capability. */
+export async function inspectPageCandidates(directory, options = {}) {
+  if (!plain(options) || Object.keys(options).some(key => !['locale', 'websiteOrigin'].includes(key))) throw new SetupError('Page discovery accepts only locale and optional website origin.');
+  try { if (typeof (options.locale ?? 'en') !== 'string' || (options.locale ?? 'en').length > 35 || !Intl.getCanonicalLocales(options.locale ?? 'en').length) throw Error(); } catch { throw new SetupError('Use a valid discovery locale.'); }
+  if (options.websiteOrigin !== undefined) {
+    try { const url = new URL(options.websiteOrigin); if (typeof options.websiteOrigin !== 'string' || url.origin !== options.websiteOrigin || url.username || url.password || !['https:', 'http:'].includes(url.protocol) || url.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) throw Error(); } catch { throw new SetupError('Use an exact HTTPS website origin or HTTP loopback origin.'); }
+  }
+  const root = await projectRoot(directory), observations = new Map(), cache = new Map(), candidates = new Map(), blockers = new Map();
+  let bytes = 0, nodes = 0, framework = 'custom', exhausted = false;
+  const block = (code, sourceFile, message) => {
+    const value = { code, ...(sourceFile && safeRelative(sourceFile) ? { path: sourceFile } : {}), message };
+    blockers.set(JSON.stringify(value), value);
+  };
+  const budget = () => { exhausted = true; block('inventory-budget', null, 'Discovery exceeded its bounded file, byte, depth or candidate budget. Preserve undiscovered routes and review the project.'); };
+  async function info(relative, directoryOnly = false) {
+    if (!safeRelative(relative)) { block('unsafe-path', null, 'A source path is outside the allowed local inventory. It was not read.'); return null; }
+    let target = root;
+    for (const [index, part] of relative.split('/').entries()) {
+      target = path.join(target, part);
+      let stat; try { stat = await lstat(target); } catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null; block('unreadable-path', relative, 'A local source path could not be inspected.'); return null; }
+      if (stat.isSymbolicLink() || await realpath(target) !== target) { block('linked-path', relative, 'Linked source paths are not followed. Preserve this route for manual review.'); return null; }
+      if (index < relative.split('/').length - 1 || directoryOnly) { if (!stat.isDirectory()) return null; }
+      else return stat;
+    }
+    return { isDirectory: () => true };
+  }
+  async function read(relative) {
+    if (cache.has(relative)) return cache.get(relative);
+    if (exhausted) return null;
+    const stat = await info(relative);
+    if (!stat) { cache.set(relative, null); return null; }
+    if (!stat.isFile() || stat.nlink !== 1) { block('nonordinary-file', relative, 'Only ordinary unlinked source files can be observed.'); cache.set(relative, null); return null; }
+    if (stat.size > 128 * 1024 || observations.size >= limits.files || bytes + stat.size > limits.bytes) { budget(); return null; }
+    let text;
+    try { text = await readProjectFile(root, relative); } catch { block('unreadable-source', relative, 'A source file changed, exceeded its read limit or could not be read safely.'); return null; }
+    if (text !== null) { bytes += Buffer.byteLength(text); observations.set(relative, hash(text)); }
+    cache.set(relative, text); return text;
+  }
+  async function walk(base, visit, depth = 0) {
+    if (exhausted) return;
+    if (depth > limits.depth) { budget(); return; }
+    if (base && !await info(base, true)) return;
+    let entries;
+    try { entries = await readdir(base ? path.join(root, base) : root, { withFileTypes: true }); } catch { block('unreadable-directory', base, 'A source directory could not be inventoried.'); return; }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (exhausted) return;
+      if (++nodes > limits.nodes) { budget(); return; }
+      if (hidden.test(entry.name) || sensitive.test(entry.name)) continue;
+      const name = base ? `${base}/${entry.name}` : entry.name;
+      if (!safeRelative(name)) { block('unsafe-path', null, 'An unsupported source filename was omitted. Preserve it for review.'); continue; }
+      if (entry.isSymbolicLink()) { block('linked-path', name, 'Linked source paths are not followed. Preserve this route for manual review.'); continue; }
+      if (entry.isDirectory()) await walk(name, visit, depth + 1);
+      else if (entry.isFile()) await visit(name);
+    }
+  }
+  const add = (value, locator = '') => {
+    if (candidates.size >= limits.candidates) { budget(); return; }
+    const identity = JSON.stringify([framework, value.kind, value.path, value.hostPath, value.sourceFile, value.exportName ?? null, locator]);
+    const candidate = { id: `page-${hash(identity).slice(0, 24)}`, ...value, label: display(value.label) };
+    if (!candidate.reason) candidate.reason = nativePath.test(candidate.path ?? candidate.sourceFile) ? 'Application or protected ownership requires review; preserve native behavior.' : 'Discovery only; public content, bindings and publication ownership require review.';
+    candidates.set(candidate.id, candidate);
+  };
+  function parse(source, filename) {
+    if (source === null) return null;
+    const ast = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, /x$/.test(filename) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    if (ast.parseDiagnostics.length) { block('source-syntax', filename, 'Source syntax could not be parsed. Preserve its pages for review.'); return null; }
+    return ast;
+  }
+  function imports(ast) {
+    const values = new Map();
+    for (const statement of ast.statements) if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.importClause && !statement.importClause.isTypeOnly) {
+      const specifier = statement.moduleSpecifier.text, clause = statement.importClause;
+      if (clause.name) values.set(clause.name.text, { specifier, exportName: 'default' });
+      if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) for (const item of clause.namedBindings.elements) if (!item.isTypeOnly) values.set(item.name.text, { specifier, exportName: item.propertyName?.text ?? item.name.text });
+      if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) values.set(clause.namedBindings.name.text, { specifier, exportName: '*' });
+    }
+    return values;
+  }
+  async function resolveModule(from, imported) {
+    if (!imported?.specifier?.startsWith('.') || /[?#\\]/.test(imported.specifier)) return null;
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(from), imported.specifier));
+    const choices = sourceExtension.test(base) ? [base] : path.posix.extname(base) ? [] : [...moduleExtensions.map(ext => base + ext), ...moduleExtensions.map(ext => `${base}/index${ext}`)];
+    const found = [];
+    for (const name of choices.filter(safeRelative)) { const stat = await info(name); if (stat?.isFile()) found.push(name); }
+    if (found.length !== 1) { block('module-resolution', from, 'A referenced page module is missing, linked or ambiguous. Keep it native until reviewed.'); return null; }
+    const text = await read(found[0]);
+    return text === null ? null : { sourceFile: found[0], text, exportName: imported.exportName };
+  }
+  function componentReferences(node, imported) {
+    const names = new Set();
+    const scan = current => { const name = jsxName(current); if (name && ts.isIdentifier(name) && imported.has(name.text)) names.add(name.text); ts.forEachChild(current, scan); };
+    scan(node); return [...names].sort();
+  }
+  const routePath = value => typeof value === 'string' && /^\/(?:[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*)?$/.test(value) ? value : null;
+  async function reactScreens(file, ast, hostPath) {
+    const imported = imports(ast), states = new Set(), selections = [];
+    const isState = expression => ts.isIdentifier(expression) ? imported.get(expression.text)?.specifier === 'react' && imported.get(expression.text)?.exportName === 'useState' : ts.isPropertyAccessExpression(expression) && expression.name.text === 'useState' && ts.isIdentifier(expression.expression) && imported.get(expression.expression.text)?.specifier === 'react';
+    const scanStates = node => { if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.name.elements[0] && ts.isBindingElement(node.name.elements[0]) && ts.isIdentifier(node.name.elements[0].name) && ts.isCallExpression(unwrap(node.initializer)) && isState(unwrap(node.initializer).expression)) states.add(node.name.elements[0].name.text); ts.forEachChild(node, scanStates); }; scanStates(ast);
+    const condition = expression => { const node = unwrap(expression); if (!node || !ts.isBinaryExpression(node) || ![ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.EqualsEqualsToken].includes(node.operatorToken.kind)) return null; for (const [identifier, literal] of [[unwrap(node.left), unwrap(node.right)], [unwrap(node.right), unwrap(node.left)]]) { const value = literalString(literal); if (identifier && ts.isIdentifier(identifier) && states.has(identifier.text) && value !== null && /^[a-zA-Z0-9_-]{1,80}$/.test(value)) return { selector: identifier.text, value }; } return null; };
+    const collect = (node, selected, fallback) => { const names = new Set(); const visit = child => { const tag = jsxName(child); if (tag && ts.isIdentifier(tag) && /^[A-Z]/.test(tag.text)) names.add(tag.text); ts.forEachChild(child, visit); }; visit(node); for (const name of names) selections.push({ name, selected, fallback }); };
+    const scan = node => {
+      if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) collect(node.right, condition(node.left), 'Conditional component ownership is unresolved; preserve native behavior.');
+      if (ts.isConditionalExpression(node)) { collect(node.whenTrue, condition(node.condition), 'Conditional component ownership is unresolved; preserve native behavior.'); collect(node.whenFalse, null, 'Alternative conditional component ownership is unresolved; preserve native behavior.'); }
+      if (ts.isSwitchStatement(node)) for (const clause of node.caseBlock.clauses) { const literal = ts.isCaseClause(clause) ? literalString(clause.expression) : null; const selected = ts.isIdentifier(unwrap(node.expression)) && states.has(unwrap(node.expression).text) && literal !== null && /^[a-zA-Z0-9_-]{1,80}$/.test(literal) ? { selector: unwrap(node.expression).text, value: literal } : null; collect(clause, selected, 'Dynamic or default screen ownership is unresolved; preserve native behavior.'); }
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && /^[A-Z]/.test(node.name.text) && node.initializer && ts.isElementAccessExpression(unwrap(node.initializer))) selections.push({ name: node.name.text, selected: null, fallback: 'Computed screen selection requires review; preserve native behavior.' });
+      ts.forEachChild(node, scan);
+    }; scan(ast);
+    for (const selection of selections) {
+      const resolved = await resolveModule(file, imported.get(selection.name));
+      const literal = selection.selected && resolved;
+      add({ kind: 'screen', path: null, hostPath, sourceFile: resolved?.sourceFile ?? file, ...(resolved ? { exportName: resolved.exportName } : {}), label: selection.selected ? `${selection.name} (${selection.selected.selector} = ${selection.selected.value})` : selection.name, discovery: literal ? 'literal' : 'unresolved', reason: literal ? 'Literal screen under an existing host, not a separate URL. Preserve native behavior until content bindings and publication ownership are reviewed.' : selection.fallback }, `${selection.name}:${selection.selected?.selector ?? '?'}:${selection.selected?.value ?? '?'}`);
+    }
+  }
+  async function jsxRoutes(file, ast, parent = '/') {
+    const imported = imports(ast), discovered = [];
+    function scan(node, host) {
+      const tag = jsxName(node), binding = tag && ts.isIdentifier(tag) ? imported.get(tag.text) : null;
+      if (binding?.exportName === 'Route' && ['react-router', 'react-router-dom'].includes(binding.specifier)) {
+        const attributes = jsxAttributes(node), pathAttribute = attributes.find(item => ts.isJsxAttribute(item) && item.name.text === 'path');
+        const index = attributes.some(item => ts.isJsxAttribute(item) && item.name.text === 'index');
+        const literal = pathAttribute && ts.isJsxAttribute(pathAttribute) ? literalString(pathAttribute.initializer) : null;
+        const joined = literal?.startsWith('/') ? literal : literal !== null && host ? `${host === '/' ? '' : host}/${literal}` : index ? host : null;
+        const pathname = routePath(joined), element = attributes.find(item => ts.isJsxAttribute(item) && item.name.text === 'element');
+        const refs = element && ts.isJsxAttribute(element) && element.initializer ? componentReferences(element.initializer, imported) : [];
+        if (refs.length) for (const name of refs) discovered.push({ name, pathname, label: literal ?? (index ? host : 'Unresolved route') });
+        else if (pathAttribute || index) discovered.push({ name: null, pathname: null, label: literal ?? 'Unresolved route' });
+        ts.forEachChild(node, child => scan(child, pathname)); return;
+      }
+      ts.forEachChild(node, child => scan(child, host));
+    }
+    scan(ast, parent);
+    for (const row of discovered) { const resolved = row.name && await resolveModule(file, imported.get(row.name)); add({ kind: 'route', path: row.pathname, hostPath: row.pathname, sourceFile: resolved?.sourceFile ?? file, ...(resolved ? { exportName: resolved.exportName } : {}), label: row.pathname ?? display(row.label), discovery: row.pathname && resolved ? 'literal' : 'unresolved', ...(!row.pathname || !resolved ? { reason: 'Dynamic, guarded or unresolved route component; preserve native ownership.' } : {}) }, `jsx:${row.label}:${row.name}`); }
+    return discovered.length;
+  }
+  async function objectRoutes(file, source, parent = '/') {
+    const ast = parse(source, file); if (!ast) return 0;
+    const imported = imports(ast), rows = [];
+    function scan(node, host) {
+      if (ts.isObjectLiteralExpression(node)) {
+        const properties = new Map(node.properties.filter(ts.isPropertyAssignment).map(item => [propertyName(item.name), item.initializer]));
+        if (properties.has('path') && ['component', 'components', 'loadComponent', 'loadChildren', 'children', 'redirectTo'].some(key => properties.has(key))) {
+          const literal = literalString(properties.get('path')), joined = literal?.startsWith('/') ? literal : literal !== null && host ? `${host === '/' ? '' : host}/${literal}` : null;
+          const pathname = routePath(joined === '' ? '/' : joined), component = unwrap(properties.get('component'));
+          if (component || properties.has('loadComponent') || properties.has('loadChildren') || properties.has('components')) rows.push({ pathname, label: literal ?? 'Unresolved route', name: component && ts.isIdentifier(component) ? component.text : null });
+          if (properties.has('children')) scan(properties.get('children'), pathname);
+          return;
+        }
+      }
+      ts.forEachChild(node, child => scan(child, host));
+    }
+    scan(ast, parent);
+    for (const row of rows) { const resolved = row.name && await resolveModule(file, imported.get(row.name)); add({ kind: 'route', path: row.pathname, hostPath: row.pathname, sourceFile: resolved?.sourceFile ?? file, ...(resolved ? { exportName: resolved.exportName } : {}), label: row.pathname ?? display(row.label), discovery: row.pathname && resolved ? 'literal' : 'unresolved', ...(!row.pathname || !resolved ? { reason: 'Dynamic route loading or component ownership requires review; preserve native behavior.' } : {}) }, `object:${row.label}:${row.name}`); }
+    return rows.length;
+  }
+  async function fileRoutes(base, type) {
+    await walk(base, async file => {
+      if (!sourceExtension.test(file)) return;
+      const relative = file.slice(base.length + 1), parts = relative.split('/'), filename = parts.pop();
+      const isPage = type === 'next' ? /^page\.[jt]sx?$/.test(filename) : type === 'svelte' ? /^\+page\.(?:svelte|md|mdx)$/.test(filename) : type === 'nuxt' ? /\.vue$/.test(filename) : /\.(?:astro|md|mdx)$/.test(filename);
+      if (!isPage) { if (sourceExtension.test(file)) await read(file); return; }
+      if (await read(file) === null) return;
+      let segments = [...parts], unresolved = false;
+      if (['next', 'svelte'].includes(type)) segments = segments.filter(part => { if (/^\([A-Za-z0-9_-]+\)$/.test(part)) return false; if (part.startsWith('@') || part.startsWith('_')) unresolved = true; return true; });
+      else { const stem = filename.replace(/\.[^.]+$/, ''); if (stem !== 'index') segments.push(stem); }
+      const pathname = unresolved ? null : routePath('/' + segments.join('/'));
+      add({ kind: 'route', path: pathname, hostPath: pathname, sourceFile: file, exportName: 'default', label: '/' + segments.join('/'), discovery: pathname ? 'literal' : 'unresolved', ...(!pathname ? { reason: 'Dynamic, parallel or ambiguous file route; preserve native ownership until reviewed.' } : {}) }, `file:${relative}`);
+    });
+  }
+
+  let manifest = {};
+  const packageText = await read('package.json');
+  if (packageText !== null) { try { manifest = JSON.parse(packageText); if (!plain(manifest) || ['dependencies', 'devDependencies'].some(key => manifest[key] !== undefined && !plain(manifest[key]))) throw Error(); } catch { manifest = {}; block('manifest-invalid', 'package.json', 'Package metadata is invalid; framework and ownership require review.'); } }
+  const deps = { ...manifest.devDependencies, ...manifest.dependencies };
+  const selected = [deps.next && 'next', deps.nuxt && 'nuxt', deps['@sveltejs/kit'] && 'svelte', deps['@angular/core'] && 'angular', deps.astro && 'astro', deps.vue && !deps.nuxt && 'vue', deps.react && deps.vite && !deps.next && !deps.astro && 'vite'].filter(Boolean);
+  if (selected.length === 1) framework = selected[0];
+  else if (selected.length > 1) block('framework-conflict', 'package.json', 'Multiple framework owners were detected. Preserve the project and review its routing.');
+  else if (!Object.keys(deps).some(name => name !== '@universalcms/connect') && await read('index.html') !== null) framework = 'static';
+  else block('framework-unresolved', 'package.json', 'This project has no unambiguous supported page discovery profile.');
+  if (manifest.workspaces) block('workspace-review', 'package.json', 'Workspace boundaries require review; this inventory covers only the selected folder.');
+  for (const config of ['tsconfig.json', 'jsconfig.json', ...(framework === 'next' ? ['next.config.js', 'next.config.mjs', 'next.config.cjs', 'next.config.ts', 'middleware.ts', 'middleware.js', 'src/middleware.ts', 'src/middleware.js'] : framework === 'nuxt' ? ['nuxt.config.ts', 'nuxt.config.js'] : framework === 'angular' ? ['angular.json'] : framework === 'svelte' ? ['svelte.config.js', 'svelte.config.ts', 'vite.config.js', 'vite.config.ts'] : framework === 'astro' ? ['astro.config.mjs', 'astro.config.ts'] : ['vite.config.js', 'vite.config.mjs', 'vite.config.ts'])]) await read(config);
+  if (framework === 'next') {
+    for (const base of ['app', 'src/app']) await fileRoutes(base, 'next');
+    for (const base of ['pages', 'src/pages']) if (await info(base, true)) block('pages-router-review', base, 'Next Pages Router needs a separate discovery profile; preserve these routes.');
+  } else if (framework === 'nuxt') { for (const base of ['app/pages', 'pages']) await fileRoutes(base, 'nuxt'); }
+  else if (framework === 'svelte') await fileRoutes('src/routes', 'svelte');
+  else if (framework === 'astro') await fileRoutes('src/pages', 'astro');
+  else if (framework === 'vite') {
+    const index = await read('index.html'), sourceMatches = [...(index ?? '').matchAll(/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/gi)].map(match => match[1].replace(/^\//, '')).filter(name => /^src\//.test(name) && sourceExtension.test(name));
+    const mounted = [];
+    for (const mainFile of sourceMatches) { const ast = parse(await read(mainFile), mainFile); if (!ast) continue; const imported = imports(ast); const scan = node => { if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'render') for (const argument of node.arguments) for (const name of componentReferences(argument, imported)) mounted.push({ mainFile, imported: imported.get(name) }); ts.forEachChild(node, scan); }; scan(ast); }
+    const resolved = [];
+    for (const mount of mounted) { const value = await resolveModule(mount.mainFile, mount.imported); if (value && !resolved.some(row => row.sourceFile === value.sourceFile)) resolved.push(value); }
+    if (resolved.length !== 1) { block('mount-review', 'index.html', 'The mounted React page is missing or ambiguous; preserve native mounting.'); for (const file of ['src/App.jsx', 'src/App.tsx', 'src/App.js', 'src/App.ts']) { const text = await read(file); if (text !== null) resolved.push({ sourceFile: file, text, exportName: 'default' }); } }
+    for (const app of resolved) { const ast = parse(app.text, app.sourceFile); if (!ast) continue; const routes = await jsxRoutes(app.sourceFile, ast); if (!routes) add({ kind: 'route', path: '/', hostPath: '/', sourceFile: app.sourceFile, exportName: app.exportName, label: '/', discovery: mounted.length && resolved.length === 1 ? 'literal' : 'unresolved' }); await reactScreens(app.sourceFile, ast, routes ? null : '/'); }
+  } else if (framework === 'vue') {
+    let routes = 0;
+    for (const base of ['src/router', 'src/routes']) await walk(base, async file => { if (/\.[cm]?[jt]s$/.test(file)) routes += await objectRoutes(file, await read(file)); });
+    for (const file of ['src/router.ts', 'src/router.js']) { const text = await read(file); if (text !== null) routes += await objectRoutes(file, text); }
+    const app = await read('src/App.vue'); if (app !== null && !routes) add({ kind: 'route', path: '/', hostPath: '/', sourceFile: 'src/App.vue', exportName: 'default', label: '/', discovery: 'literal' });
+    for (const file of ['src/main.ts', 'src/main.js']) await read(file);
+  } else if (framework === 'angular') {
+    let routes = 0;
+    await walk('src/app', async file => { if (/routes\.[jt]s$/.test(file)) routes += await objectRoutes(file, await read(file)); });
+    for (const file of ['src/app/app.ts', 'src/app/app.component.ts']) { const text = await read(file); if (text !== null && !routes) add({ kind: 'route', path: '/', hostPath: '/', sourceFile: file, label: '/', discovery: 'literal' }); }
+    for (const file of ['src/main.ts', 'src/main.server.ts', 'src/app/app.config.ts', 'src/app/app.config.server.ts']) await read(file);
+  } else if (framework === 'static') {
+    await walk('', async file => { if (!/\.html?$/.test(file) || await read(file) === null) return; const pathname = routePath('/' + file.replace(/(?:^|\/)index\.html?$/, '').replace(/\/$/, '')); add({ kind: 'route', path: pathname, hostPath: pathname, sourceFile: file, label: '/' + file, discovery: pathname ? 'literal' : 'unresolved', ...(!pathname ? { reason: 'Hosting URL for this HTML file requires review; preserve the original file.' } : {}) }, `html:${file}`); });
+  }
+  const result = [...candidates.values()].sort((a, b) => a.kind.localeCompare(b.kind) || (a.path ?? '').localeCompare(b.path ?? '') || a.sourceFile.localeCompare(b.sourceFile) || a.id.localeCompare(b.id));
+  const seenPaths = new Set(); for (const candidate of result.filter(row => row.kind === 'route' && row.path !== null)) { if (seenPaths.has(candidate.path)) block('route-overlap', candidate.sourceFile, 'More than one candidate owns the same literal path. Review before selecting CMS ownership.'); seenPaths.add(candidate.path); }
+  if (!result.length) block('no-page-candidates', null, 'No supported page candidates were found. Existing application behavior remains native.');
+  return { version: 1, framework, profile: `page-discovery-${framework}-v1`, candidates: result, observations: [...observations].sort(([a], [b]) => a.localeCompare(b)).map(([path, sha256]) => ({ path, sha256 })), blockers: [...blockers.values()].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))) };
+}

package/dist/page-mapping-review.mjs

@@ -0,0 +1,160 @@
+/** Local owner intent only. A review never installs bindings or changes publication ownership. */
+import { createHash } from 'node:crypto';
+import { lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { projectRoot, readProjectFile, applyPlan, SetupError } from './core.mjs';
+import { inspectPageCandidates } from './page-discovery.mjs';
+
+export const PAGE_MAPPING_REVIEW_FILE = '.universalcms/pages.review.json';
+const profile = 'page-mapping-review-v1';
+const modes = ['cms-page', 'connected-screen', 'native'];
+const installedFiles = ['.universalcms/content.bindings.json', '.universalcms/publication.config.json', '.universalcms/website.integration.json', '.universalcms/reviewed.integration.json'];
+const plans = new WeakMap();
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = message => { throw new SetupError(message); };
+const digest = value => createHash('sha256').update(value).digest('hex');
+const json = value => JSON.stringify(value, null, 2) + '\n';
+const canonical = value => JSON.stringify(value, (_, item) => plain(item) ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
+const freeze = value => { if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); } return value; };
+
+function optionsFor(input, allowSelections = true) {
+  if (!plain(input) || Object.keys(input).some(key => ![...(allowSelections ? ['selections'] : []), 'locale', 'websiteOrigin'].includes(key))) fail('Page mapping review accepts exact selections, a locale and an optional public website origin. Do not provide credentials.');
+  let locale;
+  try { if (typeof (input.locale ?? 'en') !== 'string' || (input.locale ?? 'en').length > 35) throw Error(); locale = Intl.getCanonicalLocales(input.locale ?? 'en')[0]; if (!locale) throw Error(); }
+  catch { fail('Use a valid page mapping locale.'); }
+  let websiteOrigin;
+  if (input.websiteOrigin !== undefined) {
+    try {
+      if (typeof input.websiteOrigin !== 'string' || input.websiteOrigin.length > 2048 || /[\s\\]|cms_server\.|sk-[A-Za-z0-9_-]{12,}|AIza[A-Za-z0-9_-]{20,}/i.test(input.websiteOrigin)) throw Error();
+      const url = new URL(input.websiteOrigin);
+      if (url.username || url.password || url.search || url.hash || url.pathname !== '/' || url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw Error();
+      websiteOrigin = url.origin;
+    } catch { fail('Use an exact HTTPS website origin without credentials, paths or queries (HTTP loopback is allowed for development).'); }
+  }
+  return { locale, ...(websiteOrigin ? { websiteOrigin } : {}) };
+}
+
+// Check presence without opening installed connector files, which are not part
+// of the public source inventory. Mapping review never reassigns an installation.
+async function beforeInstallation(root) {
+  let directory;
+  try { directory = await lstat(path.join(root, '.universalcms')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (directory && (!directory.isDirectory() || directory.isSymbolicLink() || await realpath(path.join(root, '.universalcms')) !== path.join(root, '.universalcms'))) fail('The local review directory must be an ordinary directory without links.');
+  for (const filename of installedFiles) {
+    try { await lstat(path.join(root, filename)); }
+    catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+    fail('A website integration is already installed. Preserve its ownership and use a reviewed adapter update; page mapping review does not reassign installed content.');
+  }
+}
+
+function exactSelections(input, candidates) {
+  if (!Array.isArray(input) || input.length > 1000) fail('Provide a list of exact candidate id and mode choices.');
+  const seen = new Set();
+  for (const row of input) {
+    if (!plain(row) || Object.keys(row).sort().join(',') !== 'id,mode' || typeof row.id !== 'string' || !modes.includes(row.mode) || seen.has(row.id) || !candidates.some(candidate => candidate.id === row.id)) fail('Select each discovered candidate at most once using only its exact id and cms-page, connected-screen or native mode.');
+    seen.add(row.id);
+  }
+  return candidates.filter(row => seen.has(row.id)).map(row => ({ id: row.id, mode: input.find(value => value.id === row.id).mode }));
+}
+
+function reviewedChoice(candidate, selected, candidates, blockers) {
+  const mode = selected?.mode ?? 'native';
+  const needsAdapter = mode !== 'native' && (blockers.length > 0 || mode === 'connected-screen' || candidate.kind !== 'route' || candidate.discovery !== 'literal' || candidate.path === null);
+  const sharedHost = mode === 'cms-page' && candidate.path !== null && candidates.some(row => row.kind === 'screen' && row.hostPath === candidate.path);
+  return {
+    id: candidate.id, mode, explicit: !!selected, kind: candidate.kind, path: candidate.path, hostPath: candidate.hostPath, sourceFile: candidate.sourceFile,
+    bindingStatus: mode === 'native' ? 'not-requested' : 'not-checked', automatic: false,
+    requiresAdapter: mode === 'native' ? false : needsAdapter ? true : null,
+    publicationEffect: mode === 'native' ? 'unchanged' : mode === 'connected-screen' ? 'proposed-hide-cms-content-keep-native-app' : needsAdapter ? 'requires-decision' : 'proposed-url-gate',
+    reason: mode === 'native' ? 'Keep current website behavior. No content is imported or publication ownership changed.'
+      : mode === 'connected-screen' ? 'Requested behavior: hide this screen\'s CMS content when unpublished, keep native forms and app controls working, and leave other screens at the same URL unaffected. This is intent only; an adapter must implement and verify that boundary.'
+      : blockers.length ? 'Discovery has blockers. Preserve current behavior until those blockers, the content bindings and publication ownership are reviewed.'
+      : needsAdapter ? 'This discovery is not a resolved page URL. A reviewed adapter must establish a real URL and publication ownership before integration.'
+      : sharedHost ? 'A CMS-owned page would gate this whole URL, including native screens that share it. Review that effect and the content bindings before integration.'
+      : 'A CMS-owned page would require a published entry at this URL. Existing setup planners must still validate its content bindings and publication ownership.',
+  };
+}
+
+function validPreviousReview(text) {
+  let value;
+  try { value = JSON.parse(text); } catch { fail('The existing page mapping review is not valid JSON. Preserve it and review it manually.'); }
+  const keys = ['version', 'profile', 'status', 'framework', 'discoveryProfile', 'locale', 'websiteOrigin', 'inventoryHash', 'observations', 'selections'];
+  const selectionKeys = ['id', 'mode', 'explicit', 'kind', 'path', 'hostPath', 'sourceFile', 'bindingStatus', 'automatic', 'requiresAdapter', 'publicationEffect', 'reason'];
+  if (!plain(value) || Object.keys(value).sort().join(',') !== keys.sort().join(',') || value.version !== 1 || value.profile !== profile || value.status !== 'intent-only' || typeof value.framework !== 'string' || typeof value.discoveryProfile !== 'string' || !/^[a-f0-9]{64}$/.test(value.inventoryHash) || !Array.isArray(value.observations) || !Array.isArray(value.selections) || value.observations.length > 1000 || value.selections.length > 1000) fail('The existing page mapping review has an unsupported format. Preserve it and review it manually.');
+  optionsFor({ locale: value.locale, ...(value.websiteOrigin === null ? {} : { websiteOrigin: value.websiteOrigin }) }, false);
+  if (value.observations.some(row => !plain(row) || Object.keys(row).sort().join(',') !== 'path,sha256' || typeof row.path !== 'string' || !/^[a-f0-9]{64}$/.test(row.sha256)) || new Set(value.observations.map(row => row.path)).size !== value.observations.length || value.selections.some(row => !plain(row) || Object.keys(row).sort().join(',') !== selectionKeys.sort().join(',') || typeof row.id !== 'string' || !modes.includes(row.mode) || typeof row.explicit !== 'boolean' || !['route', 'screen'].includes(row.kind) || ![row.path, row.hostPath].every(item => item === null || typeof item === 'string') || typeof row.sourceFile !== 'string' || !['not-requested', 'not-checked'].includes(row.bindingStatus) || row.automatic !== false || ![null, false, true].includes(row.requiresAdapter) || !['unchanged', 'requires-decision', 'proposed-url-gate', 'proposed-hide-cms-content-keep-native-app'].includes(row.publicationEffect) || typeof row.reason !== 'string') || new Set(value.selections.map(row => row.id)).size !== value.selections.length) fail('The existing page mapping review has unsupported choices. Preserve it and review it manually.');
+}
+
+/** Plan one local intent record. Use applyPageMappingReview to revalidate before saving. */
+export async function planPageMappingReview(directory, options = {}) {
+  const publicOptions = optionsFor(options), root = await projectRoot(directory);
+  await beforeInstallation(root);
+  const inventory = await inspectPageCandidates(root, publicOptions);
+  const selections = exactSelections(options.selections ?? [], inventory.candidates);
+  const previous = await readProjectFile(root, PAGE_MAPPING_REVIEW_FILE);
+  if (previous !== null) {
+    if ((await lstat(path.join(root, PAGE_MAPPING_REVIEW_FILE))).nlink !== 1) fail('The existing page mapping review is linked. Preserve it and review manually.');
+    validPreviousReview(previous);
+  }
+  const review = { version: 1, profile, status: 'intent-only', framework: inventory.framework, discoveryProfile: inventory.profile,
+    locale: publicOptions.locale, websiteOrigin: publicOptions.websiteOrigin ?? null, inventoryHash: digest(canonical(inventory)),
+    observations: inventory.observations.map(row => ({ ...row })), selections: inventory.candidates.map(candidate => reviewedChoice(candidate, selections.find(row => row.id === candidate.id), inventory.candidates, inventory.blockers)),
+  };
+  const content = json(review);
+  if (Buffer.byteLength(content) > 128 * 1024) fail('The page mapping review exceeds its bounded file size. Review a smaller website project.');
+  const file = { path: PAGE_MAPPING_REVIEW_FILE, content, state: previous === null ? 'create' : previous === content ? 'unchanged' : 'update', ...(previous !== null && previous !== content ? { previous } : {}) };
+  const plan = freeze({ root, framework: inventory.framework, status: 'intent-only', installed: false, liveVerified: false, renderedVerified: false, review, candidates: inventory.candidates, blockers: inventory.blockers, files: [file] });
+  plans.set(plan, { publicOptions, selections, inventory: canonical(inventory), previous, root, file });
+  return plan;
+}
+
+/** Only an issued, unchanged plan can save; never writes source or installed ownership. */
+export async function applyPageMappingReview(plan) {
+  const state = plans.get(plan);
+  if (!state) fail('Use the original page mapping review plan. Edited or reconstructed plans cannot be saved.');
+  if (await projectRoot(state.root) !== state.root) fail('The project directory changed during review. No review was saved.');
+  await beforeInstallation(state.root);
+  const current = await inspectPageCandidates(state.root, state.publicOptions);
+  if (canonical(current) !== state.inventory) fail('The page inventory or public sources changed during review. No review was saved; inspect the project again.');
+  if (await readProjectFile(state.root, PAGE_MAPPING_REVIEW_FILE) !== state.previous) fail('The local page review changed during review. Existing edits were preserved.');
+  if (state.previous !== null && (await lstat(path.join(state.root, PAGE_MAPPING_REVIEW_FILE))).nlink !== 1) fail('The local page review became linked. Existing files were preserved.');
+  return applyPlan({ root: state.root, files: [...installedFiles.map(path => ({ path, content: null, state: 'absent' })), state.file] });
+}
+
+function numberedChoices(answer, candidates, mode) {
+  if (typeof answer !== 'string') fail('Enter displayed item numbers or cancel the review.');
+  const value = answer.trim();
+  if (!value) return [];
+  if (!/^\d+(?:\s*,\s*\d+)*$/.test(value)) fail('Use only the displayed item numbers separated by commas.');
+  const indexes = value.split(',').map(item => Number(item.trim()) - 1);
+  if (new Set(indexes).size !== indexes.length || indexes.some(index => !Number.isSafeInteger(index) || index < 0 || index >= candidates.length)) fail('Choose each displayed item at most once.');
+  return indexes.map(index => ({ id: candidates[index].id, mode }));
+}
+
+/** Cancellation is the default. No keys, execution, network or integration changes. */
+export async function runPageMappingReview(directory, io, options = {}) {
+  const publicOptions = optionsFor(options);
+  const initial = await planPageMappingReview(directory, { ...publicOptions, selections: options.selections ?? [] });
+  io.write('Review page and screen ownership. This saves local intent only; it does not install routes or bindings, import content, publish, or verify a connection. All unselected items keep native behavior.\n');
+  initial.candidates.forEach((row, index) => io.write(`  ${index + 1}. ${row.label} — ${row.kind === 'route' ? `URL ${row.path ?? '(unresolved)'}` : `screen within ${row.hostPath ?? '(unresolved native URL)'}, not a separate URL`} — ${row.sourceFile}\n`));
+  if (initial.blockers.length) io.write(`Discovery has ${initial.blockers.length} blocker(s). Unresolved and undiscovered behavior stays native; adapter review is still required.\n`);
+  if (!initial.candidates.length) { io.write('No page or screen candidates were safely discovered. No review was saved.\n'); return { saved: false }; }
+  io.write('CMS page: proposed ownership of a whole URL; unpublished content would gate that URL and any screens sharing it. Connected screen: request hiding its CMS content when unpublished while native forms, app controls and other screens keep working. This boundary still requires an adapter. Neither choice establishes an installed capability.\n');
+  let selections = options.selections;
+  if (selections === undefined) {
+    const pageAnswer = await io.ask('CMS page item numbers, comma-separated (blank selects none; cancel stops): ');
+    if (typeof pageAnswer === 'string' && pageAnswer.trim().toLowerCase() === 'cancel') return { saved: false };
+    const screenAnswer = await io.ask('Connected screen item numbers, comma-separated (blank selects none; cancel stops): ');
+    if (typeof screenAnswer === 'string' && screenAnswer.trim().toLowerCase() === 'cancel') return { saved: false };
+    selections = [...numberedChoices(pageAnswer, initial.candidates, 'cms-page'), ...numberedChoices(screenAnswer, initial.candidates, 'connected-screen')];
+  }
+  const plan = await planPageMappingReview(directory, { ...publicOptions, selections });
+  if (plan.review.inventoryHash !== initial.review.inventoryHash) fail('The page inventory or public sources changed during review. No review was saved.');
+  for (const row of plan.review.selections) io.write(`  ${row.mode}: ${row.kind === 'screen' ? `screen in ${row.hostPath ?? 'an unresolved URL'}` : row.path ?? 'unresolved URL'} — ${row.sourceFile}\n    ${row.reason}\n`);
+  io.write(`Only ${PAGE_MAPPING_REVIEW_FILE} will be saved. Existing application files remain unchanged. The review is not consumed automatically by setup; supported planners and any required adapter must still validate the choices.\n`);
+  const confirmation = await io.ask('Save this local intent review? [y/N] ');
+  if (typeof confirmation !== 'string' || !['y', 'yes'].includes(confirmation.trim().toLowerCase())) { io.write('Page mapping review cancelled. No files changed.\n'); return { saved: false }; }
+  await applyPageMappingReview(plan);
+  io.write('Local page mapping intent saved. Nothing was integrated or published. Review unresolved bindings and publication behavior before running supported setup and live website checks.\n');
+  return { saved: true, status: 'intent-only', review: plan.review };
+}

package/dist/preflight-recovery.mjs

@@ -0,0 +1,122 @@
+/** Public setup diagnostics. Never echo arbitrary exceptions or project source. */
+import { SetupError } from './core.mjs';
+import { validateNativeRoutes } from './native-routes.mjs';
+
+const diagnostics = new WeakMap();
+const catalog = {
+  'native-chrome-layout': {stage:'content',message:'This native page owns its header and footer. Run review-layout to inspect and add supported literal settings slots before setup; custom components need a reviewed framework adapter.'},
+  'next-route-ownership': {
+    stage: 'content',
+    message: 'Unreviewed dynamic, parallel or custom website routes need explicit content ownership before full setup. Existing routes were preserved; automatic publication control cannot silently hide them.',
+  },
+  'native-settings-layout': {
+    stage: 'settings',
+    message: 'This website already owns its header or footer. Preserve its native links and add WebsiteProvider with CmsNavigation slots to the existing desktop header, mobile menu and footer using a reviewed adapter. Automatic setup is incomplete until those slots are verified.',
+  },
+};
+// Fixed messages from existing planners may be surfaced verbatim without
+// copying arbitrary error text. Interpolated paths must use setupReviewError.
+const fixedReasons = new Map([
+  ...[
+    'Existing content bindings need review; they are never wrapped a second time.',
+    'This page filters out source rows in its initial presentation state. Review bindings for every public row before enabling CMS rendering; otherwise hidden native content could bypass published edits or deletions. Existing source was preserved.',
+    'This page needs a reviewed content adapter. Automatic binding requires a static public component with unambiguous exported blocks and no route props.',
+    'Custom route exports need a reviewed content adapter. Existing code was preserved.',
+    'A repeated source block needs an explicit immutable row identity. Index-based content binding is unsafe.',
+    'Repeated content has ambiguous row identities. Provide reviewed bindings before enabling rendering.',
+    'Overlapping source content requires a reviewed renderer.',
+    'Public React source needs explicit review for repeated, nested or data-driven content. Literal native bindings are required before private setup.',
+    'Public React source needs explicit review: automatic fallback discovery has no verified native content bindings. Provide a reviewed source manifest and renderer mapping before full setup. Existing source was preserved.',
+    'Public React source retains editorial copy outside its literal bindings. Review the source dependencies before private setup.',
+  ].map(message => [message, {code: 'content-bindings-review', stage: 'content'}]),
+  ...[
+    'An existing settings, sitemap or robots route needs manual composition. It was preserved.',
+    'A custom Vite router needs reviewed settings and new-page slots. Original pages were preserved.',
+    'This reviewed native application needs explicit shared settings slots. Existing routing, commerce and custom adapters were preserved.',
+  ].map(message => [message, {code: 'settings-composition-review', stage: 'settings'}]),
+]);
+
+const secretLike = /cms_(?:server|public)[._]|sk-[A-Za-z0-9_-]{12,}|AIza[A-Za-z0-9_-]{20,}|(?:^|\/)(?:\.env[^/]*|\.git|\.ssh|\.aws|credentials|secrets?)(?:\/|$)/i;
+export function sanitizeSetupPaths(paths) {
+  const input = Array.isArray(paths) ? paths : [];
+  const accepted = new Set();
+  for (const value of input.slice(0, 4000)) {
+    if (typeof value !== 'string' || value.length > 500 || !/^(?:app\/|src\/|pages\/|components\/|\.universalcms\/content\/)[A-Za-z0-9_+@()[\]./-]+$|^(?:[a-z0-9-]+\/)*index\.html$/.test(value) || secretLike.test(value)) continue;
+    if (value.split('/').some(part => !part || part === '.' || part === '..' || part.startsWith('.') && part !== '.universalcms')) continue;
+    accepted.add(value);
+  }
+  const result = [...accepted].sort().slice(0, 20);
+  return { paths: result, omittedPathCount: input.length - result.length };
+}
+
+/** Only errors created here carry public diagnostic metadata. */
+export function setupReviewError(code, paths = []) {
+  if (!Object.hasOwn(catalog, code)) throw new SetupError('The setup review diagnostic is invalid. Preserve the project and inspect the connector installation.');
+  const definition = catalog[code], safe = sanitizeSetupPaths(paths);
+  const locations = safe.paths.length ? ` Review paths: ${safe.paths.join(', ')}.` : '';
+  const omitted = safe.omittedPathCount ? ' Additional paths require local review and were omitted from this diagnostic.' : '';
+  const error = new SetupError(definition.message + locations + omitted);
+  diagnostics.set(error, { code, stage: definition.stage, message: error.message, ...safe });
+  return error;
+}
+
+export function setupReviewDiagnostic(error) {
+  const value = diagnostics.get(error);
+  if (value) return { ...value, paths: [...value.paths] };
+  const fixed = error instanceof SetupError && fixedReasons.get(error.message);
+  return fixed ? {...fixed, message: error.message, paths: [], omittedPathCount: 0} : null;
+}
+
+const cli = (name, args = []) => ({ executable: 'npx', args: ['--no-install', 'universalcms-connect', name, ...args] });
+const scopeFields = { apiOrigin: '--api-origin', siteId: '--site', environmentId: '--environment', locale: '--locale', websiteOrigin: '--website-origin', adminOrigin: '--admin-origin' };
+const simpleNativeDirectory = /^(?:src\/)?app\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\/)+\[[A-Za-z][A-Za-z0-9_]*\]$/;
+function canReviewRoutes(paths) {
+  if (!paths.every(name => simpleNativeDirectory.test(name))) return false;
+  try {
+    validateNativeRoutes({nativePaths: [], nativePatterns: paths.map(name => name.replace(/^(?:src\/)?app/, ''))});
+    return true;
+  } catch { return false; }
+}
+
+/** Connection has already passed publicConnection; never use raw CLI options. */
+export function setupRecovery({ phase, framework, blocker, connection }) {
+  const retry = connection ? cli('preflight', Object.entries(scopeFields).flatMap(([name, flag]) => [flag, connection[name]])) : null;
+  const reviewablePaths = phase !== 'installed-integration' && blocker?.paths.length && !blocker.omittedPathCount;
+  const routeReview = framework === 'Next.js' && blocker?.code === 'next-route-ownership' && reviewablePaths && canReviewRoutes(blocker.paths);
+  const nativeLayoutReview = ['Vue','Nuxt','Angular','SvelteKit','Static'].includes(framework) && blocker?.code === 'native-chrome-layout' && reviewablePaths;
+  const layoutReview = (framework === 'Next.js' && blocker?.code === 'native-settings-layout' || nativeLayoutReview) && reviewablePaths;
+  const commandName = routeReview ? 'review-routes' : layoutReview ? 'review-layout' : null;
+  const kind = commandName ? routeReview ? 'native-route-review' : 'native-layout-review'
+    : phase === 'installed-integration' ? 'repair-installation'
+      : phase === 'runtime' ? 'repair-runtime'
+        : phase === 'framework' ? 'review-framework'
+          : phase === 'public-scope' ? 'correct-public-scope' : 'reviewed-adapter';
+  const first = routeReview
+    ? 'Review which exact routes stay website-owned. The CLI inspects supported Next.js native routes and their local dependencies, then asks before saving an ownership manifest. It does not bind application data to CMS content.'
+    : layoutReview
+      ? nativeLayoutReview ? 'Review the existing literal native header and footer. The CLI proposes explicit empty settings slots, preserves native children and classes, and saves the reviewed source hashes only after confirmation. Unsupported components still require a framework adapter.' : 'Review the existing Next.js layout and navigation slots. The CLI can save a reviewed layout plan only for its supported structure; custom components and interactions must remain intact. A refusal still needs a developer adapter.'
+      : phase === 'installed-integration'
+        ? 'Inspect and repair the existing adapter in place. Restore its matching public connection and reviewed files; do not rerun scaffold setup, delete manifests or replace a key to bypass this failure.'
+        : phase === 'runtime'
+          ? 'Install or repair the matching runtime package using this website’s Developer setup and existing package manager. Preserve the framework, lockfile and current integration.'
+          : phase === 'framework'
+            ? 'Use the actual framework and runtime detected in this folder. Review its supported version/profile or implement the appropriate native server or private-build adapter; changing the CMS framework label does not repair code.'
+            : phase === 'public-scope'
+              ? 'Open the matching website folder and compare the six public Developer setup values with its saved connection. Keep existing scope and private credentials; never overwrite a conflicting connection to make a command pass.'
+              : 'Give the blocker and affected public files to your developer or AI coding assistant. Implement and verify a reviewed native adapter that preserves route ownership, content, layout and interactions. Do not delete routes or weaken publication checks to bypass the refusal.';
+  const steps = [
+    { stage: 'review', message: first },
+    { stage: 'preflight', message: commandName
+      ? 'After the reviewed change, rerun the exact scoped preflight command. Continue only when it reports planned; resolving one blocker can reveal another independent compatibility requirement.'
+      : 'For the supported generated profile, rerun scoped preflight after repair. For a custom adapter, use its reviewed validator, build and runtime checks; do not force generic setup over customized integration files.' },
+    { stage: 'installation', message: 'For a new supported installation, run the scoped setup --original-routes-only command after preflight passes and review every proposed file and managed URL. A saved review manifest is not an installed source, publication, content or settings runtime.' },
+    { stage: 'verification', message: 'Keep keys private. Restart or deploy the completed adapter, verify source/publication and all twelve settings consumers at the exact saved website origin, then verify native controls and new published navigation in a browser. Import and publication remain separate owner actions.' },
+  ];
+  return {
+    version: 1, kind, requiresReview: true, automatic: false,
+    preserves: ['source', 'native-routes', 'private-credentials', 'connection-scope', 'published-content'],
+    steps,
+    ...(commandName ? { command: cli(commandName), planCommand: cli(commandName, ['--dry-run']) } : {}),
+    ...(retry ? { retry } : {}),
+  };
+}