@universalcms/connect 0.0.0-stage → 0.13.0

package/dist/guided.mjs

@@ -0,0 +1,335 @@
+/**
+ * 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';
+
+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;
+    plan = await replan();
+  } catch { return; }
+  const changes = plan.files.filter(file => ['create', 'update'].includes(file.state));
+  if (!changes.length) return;
+  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');
+}
+
+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) settle.resolve(code);
+  });
+  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`);
+    return { code: await result, verifier };
+  } 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 && 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);
+  if (!installed) await reviewLayout(root, manifest, framework, 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 ?? '' } });
+  const paired = await redeem(cms, approval.code, approval.verifier, io.fetch);
+  io.write(`✔ Approved: ${paired.siteName || 'your website'} (${paired.connection.websiteOrigin})\n`);
+  if (saved && (saved.siteId !== paired.connection.siteId || saved.environmentId !== paired.connection.environmentId)) {
+    fail('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.');
+  }
+
+  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);
+}
+
+/** 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};
+}

package/dist/native-chrome-review.mjs

@@ -0,0 +1,49 @@
+/** Explicit literal layout review; no key, network, scope or publication effects. */
+import path from 'node:path';
+import {lstat,readdir,realpath} from 'node:fs/promises';
+import {projectRoot,readProjectFile,applyPlan,SetupError} from './core.mjs';
+import {setupReviewError} from './preflight-recovery.mjs';
+import {contentDigest} from './content-registry.mjs';
+import {nativeFramework,inspectNativeProject} from './native-adapters.mjs';
+import {inspectNativeChromeTemplate} from './native-chrome-source.mjs';
+export const NATIVE_CHROME_FILE='.universalcms/native.chrome.json';
+const installedFiles=['.universalcms/content.bindings.json','.universalcms/publication.config.json','.universalcms/website.integration.json'];
+const json=value=>JSON.stringify(value,null,2)+'\n';
+const fail=message=>{throw new SetupError(message);};
+async function ordinary(root,name){const text=await readProjectFile(root,name);if(text!==null&&(await lstat(path.join(root,name))).nlink!==1)fail('Native layout review requires ordinary files without links.');return text;}
+const safePath=value=>typeof value==='string'&&/^(?:src\/|app\/pages\/|(?:[a-z0-9-]+\/)*index\.html$)/.test(value)&&/^[A-Za-z0-9_+./-]+$/.test(value)&&!value.split('/').some(part=>!part||part==='.'||part==='..'||part.startsWith('.'))&&value.length<300;
+export async function readNativeChromeReview(root,framework){
+ const text=await ordinary(root,NATIVE_CHROME_FILE);if(text===null)return null;
+ let value;try{value=JSON.parse(text);}catch{fail('Native layout review manifest is invalid.');}
+ if(!value||typeof value!=='object'||Object.keys(value).some(key=>!['version','framework','files'].includes(key))||value.version!==1||value.framework!==framework||!Array.isArray(value.files)||!value.files.length||value.files.length>1000||value.files.some(row=>!row||Object.keys(row).some(key=>!['path','sha256'].includes(key))||!safePath(row.path)||!/^[a-f0-9]{64}$/.test(row.sha256))||new Set(value.files.map(row=>row.path)).size!==value.files.length)fail('Native layout review manifest does not match this framework.');
+ return {path:NATIVE_CHROME_FILE,content:text,state:'unchanged',sha256:contentDigest(text),value};
+}
+export function reviewedNativeChrome(review,filename,source){
+ const row=review?.value.files.find(row=>row.path===filename);
+ if(!row){if(/<(?:header|footer)(?:\s|>)/.test(source))throw setupReviewError('native-chrome-layout',[filename]);return false;}
+ if(contentDigest(source)!==row.sha256)fail('Reviewed native layout changed. Preserve the integration and review its source before setup.');
+ return true;
+}
+export async function nativeChromeObservation(root,review){if(!review)return[];if(await ordinary(root,NATIVE_CHROME_FILE)!==review.content)fail('Native layout review changed during planning. No integration files were saved.');return[{path:review.path,content:review.content,state:'unchanged'}];}
+async function candidateFiles(root,framework,project){
+ if(framework==='vue')return['src/App.vue'];
+ if(framework==='angular')return[project.review.template];
+ if(framework==='static')return project.pages.map(row=>row.sourceFile);
+ const base=framework==='nuxt'?'app/pages':'src/routes',files=[];let count=0;
+ async function walk(directory,depth=0){if(depth>12||++count>1200)fail('Native layout route inventory exceeds its budget.');const target=path.join(root,directory),stat=await lstat(target);if(!stat.isDirectory()||stat.isSymbolicLink()||await realpath(target)!==target)fail('Native layout review refuses linked source directories.');for(const item of(await readdir(target,{withFileTypes:true})).sort((a,b)=>a.name.localeCompare(b.name))){if(++count>1200||item.isSymbolicLink())fail('Native layout review refuses linked or oversized routes.');const filename=directory+'/'+item.name;if(item.isDirectory()){if(!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(item.name))fail('Custom route shapes need their existing reviewed adapter.');await walk(filename,depth+1);}else if(item.isFile()&&(framework==='nuxt'?/^[a-z0-9]+(?:-[a-z0-9]+)*\.vue$/.test(item.name):item.name==='+page.svelte'))files.push(filename);else fail('Custom route components or server files need their existing reviewed adapter.');}}
+ await walk(base);return files;
+}
+function templateRegion(source,framework){if(!['vue','nuxt'].includes(framework))return {template:source,start:0,end:source.length};const match=/^\s*(?:<script\s+setup(?:\s+lang="(?:ts|js)")?\s*>\s*<\/script>\s*)?<template\s*>([\s\S]*?)<\/template>\s*((?:<style(?:\s+scoped)?\s*>[\s\S]*?<\/style>\s*)*)$/.exec(source);if(!match)fail('Vue layout review requires one literal template, optional empty script setup and ordinary styles.');const start=source.indexOf('>',source.indexOf('<template'))+1;return {template:match[1],start,end:start+match[1].length};}
+export async function planNativeChromeReview(directory){
+ const root=await projectRoot(directory);
+ for(const name of installedFiles)if(await readProjectFile(root,name)!==null)fail('An integration is already installed. Review its existing adapter update; review-layout never rewrites installed native content.');
+ const packageText=await ordinary(root,'package.json');let manifest;try{manifest=JSON.parse(packageText);}catch{fail('A valid website package.json is required.');}
+ const framework=nativeFramework(manifest);if(!framework)fail('This layout review supports Vue, Nuxt, Angular SSR, SvelteKit and literal HTML. Use the framework-specific review for other websites.');
+ const project=await inspectNativeProject(root,framework,manifest),paths=await candidateFiles(root,framework,project),files=[{path:'package.json',content:packageText,state:'unchanged'},...installedFiles.map(path=>({path,content:null,state:'absent'}))],reviewed=[],pages=[];
+ for(const filename of paths){const source=await ordinary(root,filename);if(typeof source!=='string')fail('A native source disappeared during layout review.');const region=templateRegion(source,framework),checked=await inspectNativeChromeTemplate(region.template,{mark:true});const content=source.slice(0,region.start)+checked.source+source.slice(region.end);files.push({path:filename,content,state:content===source?'unchanged':'update',...(content===source?{}:{previous:source})});if(checked.descriptor){reviewed.push({path:filename,sha256:contentDigest(content)});pages.push({path:filename,slots:checked.descriptor.slots,change:checked.changed?'insert-slots':'verify-slots'});}}
+ if(!reviewed.length)fail('No unambiguous literal header and footer were found. Preserve the native layout and review its component composition.');
+ const before=await ordinary(root,NATIVE_CHROME_FILE),content=json({version:1,framework,files:reviewed});if(before!==null&&before!==content)fail('An existing layout declaration differs. Preserve it and review the changed source explicitly.');
+ files.push({path:NATIVE_CHROME_FILE,content,state:before===null?'create':'unchanged'});
+ return {root,framework,files,pages,review:{preserves:['native-children','native-links','classes','private-credentials','connection-scope','published-content'],adds:'Empty CMS settings slots inside the existing native header and footer; current grants control their contents.',complete:false}};
+}
+export async function runNativeChromeReview(directory,io){const plan=await planNativeChromeReview(directory);io.write('Review native layout changes. Existing native links, labels, controls and CSS classes remain website-owned. CMS settings occupy new empty slots; this does not publish or install the website integration.\n');for(const page of plan.pages)io.write(`  ${page.change}: ${page.path} (${page.slots.length} settings slots)\n`);if(!['y','yes'].includes((await io.ask('Save this native header/footer integration review? [y/N] ')).trim().toLowerCase()))return{saved:false};if(json(await planNativeChromeReview(directory))!==json(plan))fail('Native layout changed during review. No declaration was saved.');await applyPlan(plan);io.write('Native layout review saved. Rerun the scoped preflight and setup, then verify the running website before connecting.\n');return{saved:true,pages:plan.pages.map(row=>row.path)};}

package/dist/native-chrome-source.mjs

@@ -0,0 +1,69 @@
+/** Bounded inert literal chrome review. Never evaluates a website module. */
+import { parse } from './vendor/astro-compiler/node/index.js';
+import { SetupError } from './core.mjs';
+import { publicHref } from './website-model.mjs';
+import { nativeChromeDescriptor, NATIVE_CHROME_SLOTS } from './native-chrome-model.mjs';
+const fail = reason => { throw new SetupError(`Native layout needs review: ${reason} Existing files were preserved.`); };
+const tags = new Set(['header','footer','nav','div','span','a','ul','ol','li','details','summary','small','strong','em','b','i','p','br']);
+const decode = value => value.replace(/&(?:amp|quot|apos|lt|gt);/g, value => ({'&amp;':'&','&quot;':'"','&apos;':"'",'&lt;':'<','&gt;':'>'}[value]));
+const empty = nodes => (nodes ?? []).every(node => node.type === 'text' && !node.value.trim());
+export async function inspectNativeChromeTemplate(source, { mark = false } = {}) {
+  if (typeof source !== 'string' || Buffer.byteLength(source) > 128*1024 || source.includes('\0')) fail('template exceeds the literal source budget');
+  const tree = await parse(source, {position:true});
+  if (tree.diagnostics.some(row => row.severity === 1)) fail('invalid native template');
+  const offsets = new Map([[0,0]]); let bytes=0,characters=0,count=0;
+  for (const character of source) { bytes+=Buffer.byteLength(character); characters+=character.length; offsets.set(bytes,characters); }
+  const roots=[], markers=[];
+  function collect(node, depth=0) {
+    if (++count > 30000 || depth > 80) fail('template exceeds the AST budget');
+    if (node.type === 'element' && ['header','footer'].includes(node.name)) roots.push(node);
+    for (const attribute of node.attributes ?? []) if (/^data-universalcms/i.test(attribute.name)) markers.push({node,attribute});
+    for (const child of node.children ?? []) collect(child,depth+1);
+  }
+  collect(tree.ast);
+  if (!roots.length && !markers.length) return {source, descriptor:undefined, changed:false};
+  if (roots.length !== 2 || roots.filter(node => node.name === 'header').length !== 1 || roots.filter(node => node.name === 'footer').length !== 1) fail('exactly one literal header and footer are required');
+  const slots = new Map(), exclude={header:[],footer:[]}, edits=[], owned=new Set();
+  function range(node) {
+    let start=offsets.get(node.position?.start?.offset), end=offsets.get(node.position?.end?.offset);
+    if (source[start]!=='<' && source[start-1]==='<') start--;
+    if (!Number.isInteger(start) || !Number.isInteger(end) || !source.startsWith('<'+node.name,start) || !source.slice(start,end).endsWith('</'+node.name+'>')) fail('explicit closing tags and exact source positions are required');
+    let quote=null,openEnd;
+    for(let i=start+1;i<end;i++){const char=source[i];if(quote){if(char===quote)quote=null;}else if(char==='"'||char==="'")quote=char;else if(char==='>'){openEnd=i+1;break;}}
+    if(!openEnd)fail('opening tag is incomplete');
+    return {start,end,openEnd,closeStart:end-node.name.length-3};
+  }
+  for (const root of roots) {
+    const wanted=root.name==='header'?NATIVE_CHROME_SLOTS.slice(0,4):NATIVE_CHROME_SLOTS.slice(4);
+    function visit(node) {
+      if (node.type === 'text') { if (/[{}]/.test(node.value)) fail('computed chrome text needs a reviewed adapter'); return; }
+      if (node.type === 'comment') return;
+      if (node.type !== 'element' || !tags.has(node.name) || node !== root && ['header','footer'].includes(node.name)) fail('chrome must contain literal native elements without scripts, forms, images or components');
+      if(node.name!=='br')range(node);
+      owned.add(node); const names=new Set(); let slot;
+      for(const attribute of node.attributes ?? []) {
+        const name=attribute.name;
+        if(names.has(name) || !['quoted','empty'].includes(attribute.kind) || /^(?:on|v-|[:@#*[(])/i.test(name)) fail('dynamic or duplicate chrome attributes need a reviewed adapter');
+        names.add(name);
+        if(name==='data-universalcms-chrome') { if(node!==root || attribute.value!==root.name)fail('chrome markers must identify their exact native header/footer'); continue; }
+        if(name==='data-universalcms-slot') { if(node.name!=='div' || !wanted.includes(attribute.value) || slots.has(attribute.value) || !empty(node.children))fail('each settings slot must be one empty div in its matching header/footer');slot=attribute.value;slots.set(slot,node);continue; }
+        if(!/^(?:class|id|title|role|aria-[a-z-]+|data-[a-z-]+|href|target|rel|open)$/.test(name) || /^data-(?:cms|universalcms)/.test(name))fail('unsupported chrome attributes need a reviewed adapter');
+        if(name==='href') { const href=decode(attribute.value??''); if(node.name!=='a'||!publicHref(href,{mail:true}) || /&/.test(href.replace(/&(?:amp;)?/g,'')))fail('native links need safe literal URLs'); if(!exclude[root.name].includes(href))exclude[root.name].push(href); }
+        if(name==='target' && !['_self','_blank'].includes(attribute.value))fail('unsupported native link target');
+        if(name==='open' && node.name!=='details')fail('only native details controls may use open');
+      }
+      if(node.name==='a'&&!names.has('href'))fail('native links require a literal href');
+      if(slot && (node.attributes??[]).some(attribute=>!['data-universalcms-slot','class','id'].includes(attribute.name)))fail('settings slots may only have marker, class and id attributes');
+      for(const child of node.children??[])visit(child);
+    }
+    visit(root);
+    const region=range(root),marked=(root.attributes??[]).some(attribute=>attribute.name==='data-universalcms-chrome');
+    if(mark && !markers.length) {
+      edits.push({start:region.openEnd-1,end:region.openEnd-1,text:` data-universalcms-chrome="${root.name}"`});
+      edits.push({start:region.closeStart,end:region.closeStart,text:wanted.map(name=>`<div data-universalcms-slot="${name}"></div>`).join('')});
+    } else if(!marked || wanted.some(name=>!slots.has(name))) fail('run review-layout to review and add the complete explicit settings slots');
+  }
+  if(markers.some(({node})=>!owned.has(node)))fail('settings markers outside the inspected chrome require review');
+  if(edits.length){let output=source;for(const edit of edits.sort((a,b)=>b.start-a.start))output=output.slice(0,edit.start)+edit.text+output.slice(edit.end);const checked=await inspectNativeChromeTemplate(output);return {...checked,changed:true};}
+  return {source,descriptor:nativeChromeDescriptor({version:1,slots:[...NATIVE_CHROME_SLOTS],exclude}),changed:false};
+}