@universalcms/connect 0.0.0-stage → 0.1.0

package/dist/setup-environment.mjs

@@ -0,0 +1,237 @@
+import { constants } from 'node:fs';
+import { lstat, open, rename, unlink } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify, parseEnv } from 'node:util';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { projectRoot, readProjectFile, validateConfig, CONFIG_FILE, SetupError } from './core.mjs';
+import { verifyPublishedDelivery } from './vendor/check-delivery.mjs';
+
+const run = promisify(execFile);
+const plans = new WeakMap();
+const maxFileBytes = 128 * 1024;
+const names = ['CMS_API_BASE_URL', 'CMS_SITE_ID', 'CMS_ENVIRONMENT_ID', 'CMS_LOCALE', 'CMS_API_KEY', 'CMS_WEBSITE_ORIGIN', 'CMS_SOURCE_ORIGIN', 'CMS_ADMIN_ORIGIN'];
+const managed = new Set(names);
+const modes = ['.env.development', '.env.development.local', '.env.production', '.env.production.local'];
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// Tokens encode organization/key IDs. Only an authenticated delivery read can
+// establish whether a credential authorizes the selected site/environment.
+const keyPattern = /^cms_server\.([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.[A-Za-z0-9_-]{43}$/;
+const fail = message => { throw new SetupError(message); };
+async function protect(action) {
+  try { return await action(); }
+  catch (error) { if (error instanceof SetupError) throw error; fail('Private setup settings could not be inspected or saved. Check ordinary files and permissions; no credential details are displayed.'); }
+}
+function origin(value, required = false) {
+  if ((value === undefined || value === '') && !required) return undefined;
+  try {
+    if (typeof value !== 'string' || /[\s\\]|cms_server\.|sk-[A-Za-z0-9_-]{12,}|AIza[A-Za-z0-9_-]{20,}/i.test(value)) throw Error();
+    const url = new URL(value);
+    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();
+    return url.origin;
+  } catch { fail('Use an HTTPS origin without credentials, path or query (HTTP loopback is allowed for local development).'); }
+}
+function id(value, required = false) {
+  if ((value === undefined || value === '') && !required) return undefined;
+  if (typeof value !== 'string' || !uuid.test(value)) fail('Use valid website and environment UUIDs from Developer setup.');
+  return value.toLowerCase();
+}
+function locale(value) {
+  if (value === undefined || value === '') return undefined;
+  try {
+    if (typeof value !== 'string' || value.length > 35 || /[\s\\]/.test(value)) throw Error();
+    const result = Intl.getCanonicalLocales(value)[0]; if (!result) throw Error(); return result;
+  } catch { fail('Use a valid content locale.'); }
+}
+function metadata(stat) { return [stat.dev, stat.ino, stat.mode, stat.nlink, stat.size, stat.mtimeMs, stat.ctimeMs]; }
+async function snapshot(root, file) {
+  let before;
+  try { before = await lstat(path.join(root, file)); } catch (error) { if (error.code === 'ENOENT') return { file, content: null, metadata: null, mode: null }; throw error; }
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1) fail('Private setup files must be ordinary files with no symbolic links or hard links.');
+  const content = await readProjectFile(root, file), after = await lstat(path.join(root, file));
+  if (JSON.stringify(metadata(before)) !== JSON.stringify(metadata(after))) fail('A setup file changed during inspection. Retry setup.');
+  return { file, content, metadata: metadata(after), mode: after.mode & 0o777 };
+}
+function environment(source = '') {
+  if (source.includes('\0')) fail('The environment file contains ambiguous data. Review it manually before setup.');
+  const parsed = parseEnv(source), assignments = new Map();
+  const lines = source.match(/[^\r\n]*(?:\r\n|\n|\r|$)/g).filter(Boolean);
+  for (let index = 0; index < lines.length; index++) {
+    const raw = lines[index], ending = /(?:\r\n|\n|\r)$/.exec(raw)?.[0] ?? '', line = raw.slice(0, raw.length - ending.length);
+    const candidate = /^\s*(?:export\s+)?(CMS_[A-Z_]+)\b/.exec(line);
+    if (!candidate || !managed.has(candidate[1])) continue;
+    const match = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(\s*=\s*)(.*)$/.exec(line);
+    if (!match || assignments.has(match[2])) fail('Duplicate or ambiguous managed CMS assignments require manual review before setup.');
+    const value = match[4]; let tail = '', literal;
+    if (value.startsWith('"') || value.startsWith("'")) {
+      const quote = value[0], end = value.indexOf(quote, 1);
+      if (end < 0 || value.slice(1, end).includes('\\')) fail('Multiline or escaped managed CMS values require manual review before setup.');
+      literal = value.slice(0, end + 1); tail = value.slice(end + 1);
+      if (!/^\s*(?:#.*)?$/.test(tail)) fail('An ambiguous managed CMS value requires manual review before setup.');
+    } else {
+      if (value.includes('`') || value.includes('\\')) fail('An ambiguous managed CMS value requires manual review before setup.');
+      const comment = value.indexOf('#'), body = comment < 0 ? value : value.slice(0, comment);
+      literal = body.trimEnd(); tail = body.slice(literal.length) + (comment < 0 ? '' : value.slice(comment));
+    }
+    const isolated = parseEnv(`${match[2]}=${literal}`)[match[2]];
+    if (typeof isolated !== 'string' || parsed[match[2]] !== isolated) fail('An ambiguous managed CMS assignment requires manual review before setup.');
+    assignments.set(match[2], { index, prefix: match[1], equals: match[3], tail, ending });
+  }
+  for (const name of names) if (Object.hasOwn(parsed, name) && !assignments.has(name)) fail('Managed CMS values could not be read unambiguously. Review the environment file manually.');
+  return { values: Object.fromEntries(names.filter(name => Object.hasOwn(parsed, name)).map(name => [name, parsed[name]])), allValues: parsed, assignments, lines };
+}
+function renderEnvironment(source, parsed, values) {
+  const lines = [...parsed.lines], ending = source.includes('\r\n') ? '\r\n' : '\n';
+  const appended = [];
+  for (const [name, value] of Object.entries(values)) {
+    // All values were validated into a quote/control-free ASCII form.
+    const assignment = parsed.assignments.get(name), quoted = `"${value}"`;
+    if (assignment) lines[assignment.index] = `${assignment.prefix}${name}${assignment.equals}${quoted}${assignment.tail}${assignment.ending}`;
+    else appended.push(`${name}=${quoted}${ending}`);
+  }
+  const existing = lines.join('');
+  return existing + (appended.length && existing && !/[\r\n]$/.test(existing) ? ending : '') + appended.join('');
+}
+async function assertUntracked(root) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')));
+  Object.assign(env, { LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0', GIT_CONFIG_NOSYSTEM: '1' });
+  try {
+    await run('git', ['-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', '-c', 'core.hooksPath=/dev/null', '-C', root, 'ls-files', '--error-unmatch', '--', '.env.local'], { env, timeout: 5000, maxBuffer: 16 * 1024 });
+  } catch (error) {
+    if (error.code === 1 || (error.code === 128 && /not a git repository/.test(error.stderr ?? ''))) return;
+    fail('Git tracking could not be checked safely. Install Git and resolve repository errors before saving private settings.');
+  }
+  fail('The private .env.local file is already tracked by Git. Remove it from tracking and review exposed credentials before setup can save a key.');
+}
+async function inputs(root) {
+  const files = await Promise.all(['.env.local', '.gitignore', ...modes].map(file => snapshot(root, file)));
+  const rawConfig = await readProjectFile(root, CONFIG_FILE);
+  let config;
+  if (rawConfig !== null) {
+    try { config = validateConfig(JSON.parse(rawConfig)); }
+    catch { fail('The existing CMS connection configuration needs manual review before setup.'); }
+  }
+  return { files, config, rawConfig, current: environment(files[0].content ?? '') };
+}
+function defaults(input) {
+  const value = input.current.values, config = input.config;
+  // An old placeholder may be replaced interactively. Never echo invalid saved
+  // text in a prompt, especially credentials disguised as a nonsecret value.
+  const available = read => { try { return read(); } catch { return undefined; } };
+  const result = {
+    apiOrigin: available(() => origin(value.CMS_API_BASE_URL || config?.apiOrigin)),
+    siteId: available(() => id(value.CMS_SITE_ID || config?.siteId)),
+    environmentId: available(() => id(value.CMS_ENVIRONMENT_ID || config?.environmentId)),
+    locale: available(() => locale(value.CMS_LOCALE || config?.locale)),
+    websiteOrigin: available(() => origin(value.CMS_WEBSITE_ORIGIN || value.CMS_SOURCE_ORIGIN)),
+    adminOrigin: available(() => origin(value.CMS_ADMIN_ORIGIN)),
+  };
+  return Object.fromEntries(Object.entries(result).filter(([, value]) => value !== undefined));
+}
+export async function readSetupEnvironment(directory) {
+  return protect(async () => {
+    const root = await projectRoot(directory), input = await inputs(root);
+    return { defaults: defaults(input), keyConfigured: keyPattern.test(input.current.values.CMS_API_KEY ?? '') };
+  });
+}
+function assertOverrides(values, input) {
+  for (const file of input.files.slice(2)) {
+    const parsed = environment(file.content ?? '');
+    for (const [name, value] of Object.entries(parsed.values)) if (value !== values[name]) fail('Mode-specific environment files contain conflicting CMS settings. Review development/production overrides before continuing.');
+  }
+  for (const name of names) if (process.env[name] !== undefined && process.env[name] !== values[name]) fail('The current process has conflicting CMS environment variables. Clear those overrides or use matching values before continuing.');
+}
+export async function planEnvironment(directory, options) {
+  return protect(async () => {
+    if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).some(name => !['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin', 'apiKey'].includes(name))) fail('Private setup received unsupported configuration fields.');
+    const root = await projectRoot(directory), input = await inputs(root);
+    await assertUntracked(root);
+    const apiKey = options.apiKey === undefined ? input.current.values.CMS_API_KEY : options.apiKey;
+    if (typeof apiKey !== 'string' || !keyPattern.test(apiKey)) fail('Provide a valid environment-scoped server delivery key from Developer setup.');
+    const values = { CMS_API_BASE_URL: origin(options.apiOrigin, true), CMS_SITE_ID: id(options.siteId, true), CMS_ENVIRONMENT_ID: id(options.environmentId, true), CMS_LOCALE: locale(options.locale ?? 'en'), CMS_API_KEY: apiKey };
+    if (!values.CMS_LOCALE) fail('Use a valid content locale.');
+    if (options.websiteOrigin !== undefined) { values.CMS_WEBSITE_ORIGIN = origin(options.websiteOrigin, true); values.CMS_SOURCE_ORIGIN = values.CMS_WEBSITE_ORIGIN; }
+    if (options.adminOrigin !== undefined) values.CMS_ADMIN_ORIGIN = origin(options.adminOrigin, true);
+    const effective = { ...input.current.values, ...values };
+    assertOverrides(effective, input);
+    const envContent = renderEnvironment(input.files[0].content ?? '', input.current, values);
+    if (Buffer.byteLength(envContent, 'utf8') > maxFileBytes) fail('The generated private environment file would exceed the setup read limit. Reduce the existing file before continuing.');
+    // Unclosed quotes in unrelated settings can change meaning when the new
+    // quoted CMS values are appended. Verify the entire effective environment,
+    // including every unrelated value, before producing an applicable plan.
+    const expected = { ...input.current.allValues, ...values }, rendered = environment(envContent).allValues;
+    if (Object.keys(expected).length !== Object.keys(rendered).length || Object.entries(expected).some(([name, value]) => rendered[name] !== value)) fail('The generated environment would change unrelated settings or hide CMS values. Review ambiguous quoting before setup.');
+    const ignore = input.files[1].content ?? '', ending = ignore.includes('\r\n') ? '\r\n' : '\n';
+    // The temporary credential file is ignored before it is created as well.
+    const protection = '/.universalcms-private-*.tmp' + ending + '/.env.local' + ending;
+    const separator = ignore && !ignore.endsWith('\n') ? (ignore.endsWith('\r') ? '\n' : ending) : '';
+    const ignoreContent = ignore.endsWith(protection) ? ignore : ignore + separator + protection;
+    if (Buffer.byteLength(ignoreContent, 'utf8') > maxFileBytes) fail('The generated ignore file would exceed the setup read limit. Reduce the existing file before continuing.');
+    const updates = [
+      { ...input.files[1], next: ignoreContent, nextMode: input.files[1].mode ?? 0o644 },
+      { ...input.files[0], next: envContent, nextMode: 0o600 },
+    ];
+    const files = updates.map(file => Object.freeze({ path: file.file, action: file.content === file.next && file.mode === file.nextMode ? 'unchanged' : file.content === null ? 'create' : 'update' }));
+    const plan = Object.freeze({ files: Object.freeze(files), keyConfigured: true, preservesExistingKey: options.apiKey === undefined });
+    plans.set(plan, { root, input, updates, effective, applied: false });
+    return plan;
+  });
+}
+function privatePlan(plan) { const state = plans.get(plan); if (!state) fail('Use the original private environment plan returned by setup.'); return state; }
+async function checkRoot(root) {
+  if (await projectRoot(root) !== root) fail('The project location changed after planning. Run setup again from its ordinary directory.');
+}
+async function recheck(state) {
+  if (state.applied) fail('This private environment plan has already been applied. Create a fresh plan to make another change.');
+  await checkRoot(state.root);
+  await assertUntracked(state.root);
+  const current = await inputs(state.root);
+  if (current.rawConfig !== state.input.rawConfig || current.files.some((file, index) => file.content !== state.input.files[index].content || JSON.stringify(file.metadata) !== JSON.stringify(state.input.files[index].metadata))) fail('Setup files changed after planning. No stale settings will be saved; run setup again.');
+  assertOverrides(state.effective, current);
+}
+export async function validateEnvironmentPlan(plan) { return protect(async () => { await recheck(privatePlan(plan)); return true; }); }
+async function replaceFile(root, update) {
+  await checkRoot(root);
+  const temporary = path.join(root, `.universalcms-private-${randomBytes(12).toString('hex')}.tmp`);
+  let handle;
+  try {
+    handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, update.nextMode);
+    await handle.chmod(update.nextMode); await handle.writeFile(update.next, 'utf8'); await handle.sync(); await handle.close(); handle = undefined;
+    const current = await snapshot(root, update.file);
+    if (current.content !== update.content || JSON.stringify(current.metadata) !== JSON.stringify(update.metadata)) fail('A setup file changed while saving. Retry setup after reviewing the current files.');
+    if (update.file === '.env.local') await assertUntracked(root);
+    await checkRoot(root);
+    await rename(temporary, path.join(root, update.file));
+  } finally { await handle?.close().catch(() => {}); await unlink(temporary).catch(() => {}); }
+}
+export async function applyEnvironment(plan) {
+  return protect(async () => {
+    const state = privatePlan(plan), lockPath = path.join(state.root, '.universalcms-setup.lock');
+    await checkRoot(state.root);
+    let lock, lockStat;
+    try {
+      try { lock = await open(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+      catch (error) { if (error.code === 'EEXIST') fail('Another setup operation holds the private-settings lock. Finish that operation before retrying.'); throw error; }
+      lockStat = await lock.stat();
+      await recheck(state);
+      const changed = [];
+      // Establish ignore protection first. Each file is atomically replaced;
+      // competing setup wizards serialize, and manual edits are rechecked.
+      for (const update of state.updates) if (update.content !== update.next || update.mode !== update.nextMode) { await replaceFile(state.root, update); changed.push(update.file); }
+      state.applied = true;
+      return { changed, keyConfigured: true };
+    } finally {
+      await lock?.close().catch(() => {});
+      if (lockStat) {
+        try { const current = await lstat(lockPath); if (current.dev === lockStat.dev && current.ino === lockStat.ino) await unlink(lockPath); } catch { /* Never remove someone else's replacement lock. */ }
+      }
+    }
+  });
+}
+export async function verifyEnvironment(plan, { slug, fetcher } = {}) {
+  return protect(async () => {
+    const { effective } = privatePlan(plan);
+    return verifyPublishedDelivery({ slug, locale: effective.CMS_LOCALE, env: { CMS_API_BASE_URL: effective.CMS_API_BASE_URL, CMS_SITE_ID: effective.CMS_SITE_ID, CMS_ENVIRONMENT_ID: effective.CMS_ENVIRONMENT_ID, CMS_API_KEY: effective.CMS_API_KEY }, ...(fetcher ? { fetcher } : {}) });
+  });
+}

package/dist/templates.mjs

@@ -0,0 +1,84 @@
+import { readFile } from 'node:fs/promises';
+
+export async function createTemplates(config, { existingNodeServer = false } = {}) {
+  const json = value => JSON.stringify(value);
+  const env = `# Set these in your PRIVATE hosting/server environment. This file contains no key.\nCMS_API_BASE_URL=${config.apiOrigin}\nCMS_SITE_ID=${config.siteId}\nCMS_ENVIRONMENT_ID=${config.environmentId}\nCMS_API_KEY=\n${config.framework === 'vite' ? 'CMS_WEBSITE_ORIGIN=http://localhost:5173\nCMS_CONNECT_PORT=4318\nCMS_CONNECT_HOST=127.0.0.1\n' : ''}`;
+  const common = [
+    { path: '.universalcms/server.env.example', content: env },
+    { path: '.universalcms/SETUP.md', content: instructions(config, existingNodeServer) },
+  ];
+  const clientOptions = `baseUrl: process.env.CMS_API_BASE_URL ?? ${json(config.apiOrigin)},\n    siteId: ${json(config.siteId)},\n    environmentId: ${json(config.environmentId)},\n    apiKey: process.env.CMS_API_KEY,\n    retries: 0,`;
+  if (config.framework === 'next') {
+    const route = `${config.appDirectory}${config.mount}`;
+    return [...common,
+      { path: `${route}/cms.server.js`, content: `import 'server-only';\nimport { createNextCmsClient } from '@universalcms/next';\n\n// Called during a server request; never imported into a client component.\nexport function getCms() {\n  return createNextCmsClient({\n    ${clientOptions}\n  });\n}\n` },
+      { path: `${route}/[...slug]/page.jsx`, content: `import { notFound } from 'next/navigation';\nimport { CmsDocument } from '@universalcms/react';\nimport '@universalcms/react/styles.css';\nimport { getCms } from '../cms.server.js';\n\nexport const runtime = 'nodejs';\nexport const dynamic = 'force-dynamic';\n\nexport default async function CmsPage({ params }) {\n  const { slug: segments } = await params;\n  const slug = Array.isArray(segments) ? segments.join('/') : '';\n  if (slug.length > 160 || !/^[a-z0-9]+(?:[-/][a-z0-9]+)*$/.test(slug)) notFound();\n  const entry = await getCms().content.getBySlug(slug, { kind: 'page', locale: ${json(config.locale)} });\n  if (!entry) notFound();\n  return <article><h1>{entry.document.title}</h1>\n    <CmsDocument document={entry.document} entryId={entry.id} />\n  </article>;\n}\n` },
+      { path: `${route}/[...slug]/error.jsx`, content: `'use client';\nexport default function CmsError({ reset }) {\n  return <section role="alert"><h1>Content is temporarily unavailable</h1>\n    <button type="button" onClick={reset}>Try again</button></section>;\n}\n` },
+    ];
+  }
+  const handler = await readFile(new URL('./vite-handler.mjs', import.meta.url), 'utf8');
+  return [...common,
+    { path: '.universalcms/page-handler.mjs', content: handler },
+    { path: '.universalcms/server.mjs', content: `import { createServer } from 'node:http';\nimport { createCmsClient } from '@universalcms/sdk';\nimport { createPageHandler } from './page-handler.mjs';\n\ntry {\n  const cms = createCmsClient({\n    ${clientOptions}\n  });\n  const port = Number(process.env.CMS_CONNECT_PORT ?? '4318');\n  if (!Number.isInteger(port) || port < 1 || port > 65535) throw Error();\n  const handler = createPageHandler(cms, { locale: ${json(config.locale)}, websiteOrigin: process.env.CMS_WEBSITE_ORIGIN });\n  const server = createServer({ requestTimeout: 15_000, headersTimeout: 10_000, maxHeaderSize: 8192 }, (req, res) => { void handler(req, res); });\n  server.on('error', () => { console.error('CMS connector could not start. Check server configuration.'); process.exitCode = 1; });\n  server.listen(port, process.env.CMS_CONNECT_HOST ?? '127.0.0.1', () => console.log('CMS connector listening. Route /api/universalcms/page through your website proxy.'));\n  for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => { server.close(); server.closeAllConnections(); });\n} catch { console.error('CMS connector requires valid private server configuration.'); process.exitCode = 1; }\n` },
+    { path: '.universalcms/CmsPage.jsx', content: `import React, { useEffect, useState } from 'react';\nimport { CmsDocument } from '@universalcms/react';\nimport '@universalcms/react/styles.css';\n\n// Mount in your existing router; this module contains no CMS credentials.\nexport default function CmsPage({ slug = 'home' }) {\n  const [result, setResult] = useState({ slug: '', state: 'loading', entry: null });\n  useEffect(() => {\n    const controller = new AbortController();\n    let current = true;\n    setResult({ slug, state: 'loading', entry: null });\n    async function load() {\n      try {\n        const response = await fetch('/api/universalcms/page?slug=' + encodeURIComponent(slug), { credentials: 'omit', cache: 'no-store', redirect: 'error', signal: controller.signal });\n        if (response.status === 404) { if (current) setResult({ slug, state: 'missing', entry: null }); return; }\n        if (!response.ok || !response.headers.get('content-type')?.startsWith('application/json')) throw Error();\n        const body = await response.json();\n        if (!body.entry?.document || typeof body.entry.document.title !== 'string' || !Array.isArray(body.entry.document.blocks)) throw Error();\n        if (current) setResult({ slug, state: 'ready', entry: body.entry });\n      } catch { if (current) setResult({ slug, state: 'error', entry: null }); }\n    }\n    void load();\n    return () => { current = false; controller.abort(); };\n  }, [slug]);\n  if (result.slug !== slug || result.state === 'loading') return <p role="status">Loading content…</p>;\n  if (result.state === 'missing') return <h1>Page not found</h1>;\n  if (result.state === 'error') return <p role="alert">Content is temporarily unavailable.</p>;\n  return <article><h1>{result.entry.document.title}</h1><CmsDocument document={result.entry.document} entryId={result.entry.id} /></article>;\n}\n` },
+    { path: '.universalcms/vite.config.mjs', content: `import { defineConfig, loadConfigFromFile } from 'vite';\n\n// Explicit wrapper: preserves the project's config without editing it.\n// Run only when you choose: npx vite --config .universalcms/vite.config.mjs\nexport default defineConfig(async env => {\n  const existing = (await loadConfigFromFile(env, undefined, process.cwd()))?.config ?? {};\n  const proxies = existing.server?.proxy ?? {};\n  const endpoint = '^/api/universalcms/page(?:[?]|$)';\n  if (Object.hasOwn(proxies, '/api/universalcms/page') || Object.hasOwn(proxies, endpoint)) throw new Error('The CMS proxy endpoint already exists. Review it manually before using this wrapper.');\n  // Vite selects the first matching proxy. The exact CMS endpoint must precede\n  // an existing broad /api proxy; all unrelated routes retain their destinations.\n  return { ...existing, server: { ...existing.server, proxy: { [endpoint]: { target: 'http://127.0.0.1:4318', changeOrigin: false }, ...proxies } } };\n});\n` },
+    { path: 'universalcms-demo.html', content: '<!doctype html>\n<html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>CMS connection demo</title><meta name="robots" content="noindex,nofollow"></head><body><div id="universalcms-demo"></div><script type="module" src="/.universalcms/demo.jsx"></script></body></html>\n' },
+    { path: '.universalcms/demo.jsx', content: `import React from 'react';\nimport { createRoot } from 'react-dom/client';\nimport CmsPage from './CmsPage.jsx';\nconst slug = new URLSearchParams(window.location.search).get('slug') || 'home';\ncreateRoot(document.getElementById('universalcms-demo')).render(<CmsPage slug={slug} />);\n` },
+  ];
+}
+
+// Exact prior prerelease guide variant, used only to recognize an untouched
+// generated document during guided upgrades. Custom bytes still fail closed.
+export function legacySetupGuide(content) {
+  return content
+    .replace('Guided setup saves the entered values in private .env.local. The analyze, init and check commands do not load that file automatically.', 'The CLI neither saves nor reads an .env file.')
+    .replace('node --env-file=.env.local .universalcms/server.mjs', 'node .universalcms/server.mjs')
+    .replace('Run npx --no-install universalcms-connect setup to enter and save connection values locally. For hosted deployment, copy the nonsecret values in server.env.example into the private server/hosting', 'Copy the nonsecret values in server.env.example into the private server/hosting')
+    .replace('Init preserves existing project files. Guided setup can update its unchanged generated files and the entered connection values in .env.local; unrelated settings and custom edits are preserved.', 'Existing project configuration and source are never overwritten.');
+}
+
+function instructions(config, existingNodeServer) {
+  const next = config.framework === 'next';
+  return `# Connect this website to Universal CMS\n\nThe scaffold is created, but connection and rendering are not yet verified. No\nexisting source was replaced and no content was imported or published.\n\n## Install the runtime packages\n\nAfter the platform operator publishes the 0.1.0 packages, run:\n\n\`\`\`sh\nnpm install @universalcms/sdk@0.1.0 @universalcms/react@0.1.0${next ? ' @universalcms/next@0.1.0' : ''}\n\`\`\`\n\nFor a prerelease, install the operator's SDK and React${next ? ' and Next' : ''} tarballs together instead.\nDo not run the registry command until those reviewed packages are available.\nUse your project's package manager and commit its reviewed lockfile.\n\n## Configure server secrets and verify\n\nRun npx --no-install universalcms-connect setup to enter and save connection values locally. For hosted deployment, copy the nonsecret values in server.env.example into the private server/hosting\nenvironment. Obtain an environment-scoped server delivery key from this site's\nDeveloper setup and set CMS_API_KEY using your secret manager. Never use a\nNEXT_PUBLIC_ or VITE_ variable. Guided setup saves the entered values in private .env.local. The analyze, init and check commands do not load that file automatically.\nIf using a local env file, keep it ignored by Git and outside public directories.\nThe site/environment in generated server code are fixed; create separate reviewed\nconfiguration for another environment. CMS_API_BASE_URL may override the API\norigin only in the private server environment.\n\nRun \`npx --no-install universalcms-connect check --slug YOUR_PUBLISHED_PAGE\` from this project.\nIt uses CMS_API_KEY from the process environment or a hidden terminal prompt.\nIt honors the same private CMS_API_BASE_URL override as the generated server.\nRun it with the same private environment used by that server.\nA successful check verifies one published API response, not deployment or rendering.\n\n${next ? `## Next.js\n\nStart your existing Next.js app. Visit \`${config.mount}/YOUR_PUBLISHED_PAGE\`. Nested\nslugs retain their slash separators. The generated page uses request-time delivery\nand no persistent cache; missing/unpublished pages return 404, upstream failures\nshow a retry state. This route is an additive connection demo under ${config.mount};\nit does not replace your existing routes or imply the CMS's canonical paths changed.\nProduction requires a Node-capable Next deployment and private server secrets.\nStatic export and Edge runtimes are unsupported by this scaffold.\n` : `## React/Vite\n\n${existingNodeServer ? existingServerInstructions(config) : ""}Set CMS_WEBSITE_ORIGIN to the exact browser-facing origin (localhost:5173 during\ndevelopment). Start the private server in one terminal:\n\n\`\`\`sh\nnode --env-file=.env.local .universalcms/server.mjs\n\`\`\`\n\nStart Vite with the supplied wrapper in another terminal:\n\n\`\`\`sh\nnpx vite --config .universalcms/vite.config.mjs\n\`\`\`\n\nThe wrapper merges your existing Vite configuration and proxies only\n/api/universalcms/page to port 4318. If changing the connector port, update the\nreviewed wrapper target too. Visit\n/universalcms-demo.html?slug=YOUR_PUBLISHED_PAGE to verify rendering. The wrapper\nloads your normal Vite config only when you explicitly run Vite, never during\nanalysis/setup. No private key is passed to Vite or included in the demo.\n\nImport .universalcms/CmsPage.jsx into your existing React router and give it the\npage slug, or map the returned public document to your own components. The demo\nHTML is a development entry and is not automatically included in Vite's production\nbuild. Production needs both your normal Vite static build AND this Node server\nor an equivalent serverless handler. The host/reverse proxy must route the exact\n/api/universalcms/page path to the private connector and other paths to your static\nsite; Vite dev proxy settings do not configure a production proxy. Keep the server\non a private network, set the exact HTTPS CMS_WEBSITE_ORIGIN, apply ingress request\nlimits, and do not expose a general-purpose CMS proxy or server environment.\nThe handler provides no CORS, bounds input/concurrency, and forwards only a fixed\nsite/environment/locale published page lookup. It returns 404 for a missing page\nand 503 for upstream failure; the client clears stale content. It does not provide\nSSR or production HTTP 404 status for a client-only router.\n`}\n## What remains deliberate\n\nThis first scaffold renders published pages in one configured locale. Posts,\ncustom collections, taxonomy archive routes, navigation, forms, previews, SEO\nmetadata and existing design/content mapping use the SDK's documented APIs and\nneed explicit integration. Form blocks are displayed disabled until a reviewed\nsubmission endpoint is supplied. No existing source is sent to the platform.\n\nRun your website typecheck/build and review rendered pages before deployment.\nA backend connection does not mean existing content has been imported. Use the\nCMS's authorized import-as-drafts flow for that separate step. Nothing here\npublishes content or installs the Universal CMS backend on the website.\n\n## Optional assistance\n\n\`npx --no-install universalcms-connect analyze\` prints a sanitized local report. You may choose\nto supply that report in the CMS's setup assistant. This command never uploads\nsource or calls a model. Platform AI provider keys, limits and metering remain on\nthe platform; the deterministic/manual instructions above work without AI.\n\n## Reruns and removal\n\nThe same init command preserves identical files. Differing files stop setup before\nwriting; inspect and merge your edits manually. Remove only the generated files\nlisted by init to uninstall this scaffold, then review any router/proxy changes\nyou made. Init preserves existing project files. Guided setup can update its unchanged generated files and the entered connection values in .env.local; unrelated settings and custom edits are preserved.\n`;
+}
+
+function existingServerInstructions(config) {
+  return `### Existing Node server detected
+
+Keep your current website startup (for example, npm run dev), SSR bootstrap and
+production server. Starting raw Vite replaces that server and can break an SSR
+website. The separate server/Vite commands below are optional connection-demo
+diagnostics on unused ports, not a replacement for your website startup.
+
+For the real website, register the published-page handler inside its existing
+private server before a generic /api handler or SSR catch-all. Reuse that server's
+fixed site/environment SDK client and deploy @universalcms/connect as a production
+dependency when importing its Node entry point. For this prerelease, install the
+reviewed connector tarball with npm install --save-prod (not --save-dev).
+
+\`\`\`js
+import { createPageHandler } from '@universalcms/connect/node';
+// cms is the existing private, fixed-scope SDK client, never a browser client.
+const cmsPage = createPageHandler(cms, {
+  locale: ${JSON.stringify(config.locale)},
+  websiteOrigin: process.env.CMS_WEBSITE_ORIGIN,
+});
+// In the existing request listener, BEFORE its /api or SSR fallback:
+if (req.url?.split('?')[0] === '/api/universalcms/page') {
+  await cmsPage(req, res);
+  return;
+}
+\`\`\`
+
+Mount the supplied CmsPage component explicitly through your router, or keep your
+existing CMS renderer. The CLI does not replace an existing integration. Confirm
+both direct page loads and client navigation using the normal website server.
+The standalone demo verifies rendering separately; it does not prove SSR,
+existing routes, navigation, or production routing work.
+
+If using the optional raw-Vite demo, choose an unused port explicitly and set
+CMS_WEBSITE_ORIGIN to that exact origin. Do not visit the SSR website root through
+that diagnostic server; use /universalcms-demo.html?slug=YOUR_PUBLISHED_PAGE.
+
+`;
+}

package/dist/vendor/analyze-project.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/** Local read-only inspection; neither installs dependencies nor runs project code. */
+import { constants } from 'node:fs';
+import { lstat, realpath, open, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { analyzeProjectFiles, PROJECT_ANALYSIS_FILES, MAX_ANALYSIS_FILE_BYTES, MAX_ANALYSIS_TOTAL_BYTES } from './project-analysis.mjs';
+import { inspectInstalledDependencies } from './inspect-installed-dependencies.mjs';
+
+function inside(root, target) { const relative = path.relative(root, target); return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative); }
+
+/** A missing file is fine; unreadable, symlinked or excessive evidence is never silently trusted. */
+export async function analyzeProjectDirectory(directory) {
+  const requested = path.resolve(directory);
+  const rootStat = await lstat(requested);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw Error('Select an ordinary project directory, not a symbolic link.');
+  const root = await realpath(requested), files = Object.create(null);
+  let total = 0;
+  for (const name of PROJECT_ANALYSIS_FILES) {
+    const segments = name.split('/');
+    let target = root, missing = false, unsafe = false;
+    for (let index = 0; index < segments.length; index++) {
+      target = path.join(target, segments[index]);
+      let info;
+      try { info = await lstat(target); }
+      catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') { missing = true; break; } unsafe = true; break; }
+      if (info.isSymbolicLink() || (index < segments.length - 1 && !info.isDirectory()) || (index === segments.length - 1 && !info.isFile())) { unsafe = true; break; }
+      if (index === segments.length - 1 && (info.size > MAX_ANALYSIS_FILE_BYTES || total + info.size > MAX_ANALYSIS_TOTAL_BYTES)) { unsafe = true; break; }
+    }
+    if (missing) continue;
+    if (unsafe) { files[name] = null; continue; }
+    let handle;
+    try {
+      const actual = await realpath(target);
+      if (!inside(root, actual) || actual !== target) { files[name] = null; continue; }
+      handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const opened = await handle.stat(), current = await lstat(target);
+      if (!opened.isFile() || opened.ino !== current.ino || opened.dev !== current.dev || current.isSymbolicLink() || opened.size > MAX_ANALYSIS_FILE_BYTES || total + opened.size > MAX_ANALYSIS_TOTAL_BYTES || await realpath(target) !== target) { files[name] = null; continue; }
+      // Read at most the budget plus one, even if the file grows after stat.
+      const buffer = Buffer.alloc(MAX_ANALYSIS_FILE_BYTES + 1);
+      let count = 0;
+      while (count < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, count, buffer.length - count, count);
+        if (!bytesRead) break;
+        count += bytesRead;
+      }
+      total += count;
+      if (count > MAX_ANALYSIS_FILE_BYTES || total > MAX_ANALYSIS_TOTAL_BYTES) files[name] = null;
+      else files[name] = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, count));
+    } catch { files[name] = null; }
+    finally { await handle?.close(); }
+  }
+  const core = analyzeProjectFiles(files);
+  const diagnostics = await inspectInstalledDependencies(root, files['package.json']);
+  return { ...core, version: 2, diagnostics };
+}
+
+async function main(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write('Usage: node analyze-project.mjs [project-directory] [--output report.json]\nReads allowlisted project files and exact installed package metadata locally. Does not execute code, install packages, read .env, contact websites, or upload source. Reports contain timestamped, sanitized setup evidence and dependency diagnostics, without package versions. Existing output files are never overwritten.\n');
+    return;
+  }
+  let directory = null, output = null;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--output' && !output && args[i + 1] && !args[i + 1].startsWith('-')) output = args[++i];
+    else if (!arg.startsWith('-') && directory === null) directory = arg;
+    else throw Error('Use one project directory and an optional --output filename.');
+  }
+  const report = await analyzeProjectDirectory(directory ?? process.cwd());
+  const result = `${JSON.stringify(report, null, 2)}\n`;
+  if (output) await writeFile(path.resolve(output), result, { flag: 'wx', mode: 0o600 });
+  else process.stdout.write(result);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch(() => {
+    // Filesystem and parse errors can contain paths or source. Never echo them.
+    process.stderr.write('Project analysis could not finish. Check the directory, file permissions and output filename. Existing output files are not overwritten.\n');
+    process.exitCode = 1;
+  });
+}

package/dist/vendor/check-delivery.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/** Private, read-only delivery check. Never reads .env or imports website code. */
+import { pathToFileURL } from 'node:url';
+
+export const DELIVERY_CHECK_TIMEOUT_MS = 10_000;
+export const DELIVERY_CHECK_MAX_BYTES = 8 * 1024 * 1024;
+export const DELIVERY_CHECK_MESSAGES = Object.freeze({
+  verified: 'The requested published page was returned. Website rendering, installed dependencies and content updates need separate checks.',
+  'not-published': 'No matching published page was returned. Verify the slug, locale and publication in the selected environment.',
+  'missing-key': 'Delivery was not checked. Set CMS_API_KEY in the private verification process.',
+  'configuration-error': 'Delivery was not checked. Configure a valid API origin, site, environment, server key, page slug and locale.',
+  'authorization-rejected': 'Delivery authorization was rejected. Check the server key, its environment, expiry, revocation and current issuer access.',
+  'invalid-response': 'Delivery was not verified. The API returned an unexpected, redirected, ambiguous or oversized response.',
+  'http-error': 'Delivery was not verified. The API rejected the read request or is unavailable.',
+  'transport-error': 'Delivery was not verified. The private process could not complete the API request.',
+  timeout: 'Delivery was not verified. The API request exceeded the verification deadline.',
+});
+
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const keyPattern = /^cms_server\.([0-9a-f-]{36})\.([0-9a-f-]{36})\.[A-Za-z0-9_-]{43}$/;
+const object = value => !!value && typeof value === 'object' && !Array.isArray(value);
+const invalid = Symbol('Invalid delivery response');
+const result = status => ({ status, verified: status === 'verified', message: DELIVERY_CHECK_MESSAGES[status] });
+const positiveBoundedInteger = (value, limit) => Number.isSafeInteger(value) && value > 0 && value <= limit;
+
+function apiOrigin(value) {
+  if (typeof value !== 'string') return null;
+  try {
+    const url = new URL(value);
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (!url.username && !url.password && !url.search && !url.hash && url.pathname === '/' &&
+      (url.protocol === 'https:' || (url.protocol === 'http:' && loopback))) return url.origin;
+  } catch { /* Configuration is never echoed. */ }
+  return null;
+}
+
+function untilAborted(pending, signal) {
+  return new Promise((resolve, reject) => {
+    const cancel = () => reject(new Error('Delivery check canceled'));
+    if (signal.aborted) { cancel(); return; }
+    signal.addEventListener('abort', cancel, { once: true });
+    pending.then(value => { signal.removeEventListener('abort', cancel); resolve(value); }, error => { signal.removeEventListener('abort', cancel); reject(error); });
+  });
+}
+
+function cancelBody(response) {
+  try { if (response?.body && !response.body.locked) void response.body.cancel().catch(() => {}); }
+  catch { /* Cleanup must not replace the sanitized outcome. */ }
+}
+
+async function boundedBody(response, maxBytes, signal, checkDeadline) {
+  const declared = response.headers.get('content-length');
+  if (declared !== null && (!/^\d+$/.test(declared) || Number(declared) > maxBytes)) throw invalid;
+  if (!response.body) throw invalid;
+  const reader = response.body.getReader(), body = new Uint8Array(maxBytes);
+  let bytes = 0;
+  try {
+    while (true) {
+      const chunk = await untilAborted(reader.read(), signal);
+      checkDeadline();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > maxBytes) throw invalid;
+      body.set(chunk.value, bytes - chunk.value.byteLength);
+    }
+    try { return new TextDecoder('utf-8', { fatal: true }).decode(body.subarray(0, bytes)); }
+    catch { throw invalid; }
+  } finally {
+    // Even a stalled cancellation cannot hold the verification deadline open.
+    void reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
+function publishedPage(raw, slug, locale) {
+  let envelope;
+  try { envelope = JSON.parse(raw); } catch { throw invalid; }
+  const data = envelope?.data;
+  if (!object(envelope) || !object(data) || !Array.isArray(data.items) || !Number.isSafeInteger(data.total) || data.total < 0) throw invalid;
+  if (data.items.length === 0 && data.total === 0) return 'not-published';
+  if (data.items.length !== 1 || data.total !== 1) throw invalid;
+  const item = data.items[0], document = item?.document;
+  // Check the published-delivery envelope, not renderer or full block compatibility.
+  if (!object(item) || !uuid.test(item.id) || item.kind !== 'page' || item.slug !== slug || item.locale !== locale ||
+    !Number.isSafeInteger(item.version) || item.version < 0 || typeof item.publishedAt !== 'string' || !Number.isFinite(Date.parse(item.publishedAt)) ||
+    item.preview === true || (item.status !== undefined && item.status !== 'published') || !object(document) || document.schemaVersion !== 1 ||
+    typeof document.title !== 'string' || !document.title.trim() || document.title.length > 200 ||
+    typeof document.excerpt !== 'string' || document.excerpt.length > 1000 || !Array.isArray(document.blocks) || document.blocks.length > 200) throw invalid;
+  return 'verified';
+}
+
+/** Returns constant outcomes only; neither configuration nor response content is returned or printed. */
+export async function verifyPublishedDelivery({ env = process.env, slug, locale = 'en', fetcher = globalThis.fetch, timeoutMs = DELIVERY_CHECK_TIMEOUT_MS, maxResponseBytes = DELIVERY_CHECK_MAX_BYTES } = {}) {
+  let origin, siteId, environmentId, key, canonicalLocale;
+  try {
+    key = env?.CMS_API_KEY;
+    if (typeof key !== 'string' || !key.trim()) return result('missing-key');
+    origin = apiOrigin(env?.CMS_API_BASE_URL); siteId = env?.CMS_SITE_ID; environmentId = env?.CMS_ENVIRONMENT_ID;
+    const keyParts = keyPattern.exec(key);
+    if (!origin || typeof siteId !== 'string' || !uuid.test(siteId) || typeof environmentId !== 'string' || !uuid.test(environmentId) ||
+      !keyParts || !uuid.test(keyParts[1]) || !uuid.test(keyParts[2]) || typeof slug !== 'string' || slug.length > 160 || !/^[a-z0-9]+(?:[-/][a-z0-9]+)*$/.test(slug) ||
+      typeof locale !== 'string' || locale.length < 2 || locale.length > 35 || typeof fetcher !== 'function' ||
+      !positiveBoundedInteger(timeoutMs, DELIVERY_CHECK_TIMEOUT_MS) || !positiveBoundedInteger(maxResponseBytes, DELIVERY_CHECK_MAX_BYTES)) return result('configuration-error');
+    canonicalLocale = Intl.getCanonicalLocales(locale)[0];
+    if (!canonicalLocale) return result('configuration-error');
+  } catch { return result('configuration-error'); }
+  const url = new URL(`/api/v1/delivery/sites/${siteId}/content`, origin);
+  url.search = new URLSearchParams({ environmentId, kind: 'page', slug, locale: canonicalLocale, limit: '2' }).toString();
+  const controller = new AbortController();
+  let timedOut = false, response;
+  const deadline = Date.now() + timeoutMs;
+  const checkDeadline = () => { if (Date.now() >= deadline) { timedOut = true; controller.abort(); throw new Error('Delivery check deadline'); } };
+  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+  try {
+    response = await untilAborted(fetcher(url, {
+      method: 'GET', headers: { Authorization: `Bearer ${key}`, Accept: 'application/json' },
+      credentials: 'omit', redirect: 'error', cache: 'no-store', referrerPolicy: 'no-referrer', signal: controller.signal,
+    }), controller.signal);
+    checkDeadline();
+    if (!(response instanceof Response) || response.redirected || ['opaque', 'opaqueredirect'].includes(response.type) ||
+      (response.url && response.url !== url.href) || (response.status >= 300 && response.status < 400)) return result('invalid-response');
+    if ([401, 403].includes(response.status)) return result('authorization-rejected');
+    if (!response.ok) return result('http-error');
+    if (response.status !== 200 || response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json') throw invalid;
+    const status = publishedPage(await boundedBody(response, maxResponseBytes, controller.signal, checkDeadline), slug, canonicalLocale);
+    checkDeadline();
+    return result(status);
+  } catch (error) {
+    return result(timedOut ? 'timeout' : error === invalid ? 'invalid-response' : 'transport-error');
+  } finally { clearTimeout(timer); controller.abort(); cancelBody(response); }
+}
+
+export function parseDeliveryArguments(args) {
+  if (!Array.isArray(args)) return null;
+  const options = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const name = args[index], value = args[index + 1];
+    if (!['--slug', '--locale'].includes(name) || typeof value !== 'string' || !value || value.startsWith('-') || Object.hasOwn(options, name.slice(2))) return null;
+    options[name.slice(2)] = value;
+  }
+  return options.slug ? options : null;
+}
+
+async function main() {
+  if (process.argv.length === 3 && process.argv[2] === '--help') {
+    process.stdout.write('Usage: check-delivery --slug <published-page-slug> [--locale <locale>]\nUses private CMS_API_BASE_URL, CMS_SITE_ID, CMS_ENVIRONMENT_ID and CMS_API_KEY. Reads published content only; does not read .env or verify website rendering.\n');
+    return;
+  }
+  let outcome;
+  try {
+    const options = parseDeliveryArguments(process.argv.slice(2));
+    outcome = options ? await verifyPublishedDelivery(options) : result('configuration-error');
+  } catch { outcome = result('configuration-error'); }
+  process.stdout.write(JSON.stringify(outcome) + '\n');
+  if (!outcome.verified) process.exitCode = 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();