@universalcms/connect 0.0.0-stage → 0.1.0

package/dist/vite-handler.mjs

@@ -0,0 +1,54 @@
+/** Public published-page projection. Supply the fixed, private SDK client. */
+export function createPageHandler(cms, { locale, websiteOrigin, maxConcurrent = 16 }) {
+  const origin = new URL(websiteOrigin);
+  if (origin.origin !== websiteOrigin || (origin.protocol !== 'https:' && !(origin.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(origin.hostname)))) throw Error('Configure the website HTTPS origin.');
+  const canonicalLocale = value => {
+    if (typeof value !== 'string' || !value) return null;
+    try { return Intl.getCanonicalLocales(value)[0] ?? null; } catch { return null; }
+  };
+  const requestedLocale = canonicalLocale(locale);
+  if (!requestedLocale) throw Error('Configure a valid content locale.');
+  let active = 0, count = 0, windowStart = Date.now();
+  function publicBlock(block) {
+    if (block.type === 'form') { const { notifyEmail, subscribe, ...data } = block.data; return { ...block, data }; }
+    if (block.type === 'section') return { ...block, data: { ...block.data, blocks: block.data.blocks.map(publicBlock) } };
+    if (block.type === 'columns') return { ...block, data: { ...block.data, columns: block.data.columns.map(column => column.map(publicBlock)) } };
+    return block;
+  }
+  return async function pageHandler(req, res) {
+    const send = (status, value) => {
+      if (res.destroyed || res.writableEnded) return;
+      res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer' });
+      res.end(JSON.stringify(value));
+    };
+    let url;
+    try {
+      if (typeof req.url !== 'string' || req.url.length > 512 || !req.url.startsWith('/') || req.url.startsWith('//') || req.url.includes('\\')) throw Error();
+      url = new URL(req.url, websiteOrigin);
+    } catch { send(400, { error: 'Invalid request.' }); return; }
+    if (url.pathname !== '/api/universalcms/page') { send(404, { error: 'Not found.' }); return; }
+    if (req.method !== 'GET') { send(405, { error: 'Method not allowed.' }); return; }
+    if (req.headers.origin && req.headers.origin !== websiteOrigin) { send(403, { error: 'Origin not allowed.' }); return; }
+    if ([...url.searchParams.keys()].some(key => key !== 'slug') || url.searchParams.getAll('slug').length !== 1) { send(400, { error: 'One page slug is required.' }); return; }
+    const slug = url.searchParams.get('slug');
+    if (!slug || slug.length > 160 || !/^[a-z0-9]+(?:[-/][a-z0-9]+)*$/.test(slug)) { send(400, { error: 'Invalid page slug.' }); return; }
+    const now = Date.now();
+    if (now - windowStart >= 60_000) { windowStart = now; count = 0; }
+    if (active >= maxConcurrent || ++count > 600) { send(429, { error: 'Try again later.' }); return; }
+    active++;
+    const controller = new AbortController();
+    const cancel = () => { if (!res.writableEnded) controller.abort(); };
+    res.on('close', cancel);
+    try {
+      const entry = await cms.content.getBySlug(slug, { kind: 'page', locale: requestedLocale }, { signal: controller.signal });
+      if (!entry) { send(404, { error: 'Page not found.' }); return; }
+      // Keep the response bound to the same query even if a delivery adapter
+      // returns a valid entry for a different slug, type or language.
+      if (entry.kind !== 'page' || entry.slug !== slug || canonicalLocale(entry.locale) !== requestedLocale) throw Error('Invalid delivery identity.');
+      // Browser receives only public renderer fields. No custom fields, form
+      // notification destinations, request headers, config or SDK credentials.
+      send(200, { entry: { id: entry.id, document: { title: entry.document.title, excerpt: entry.document.excerpt, blocks: entry.document.blocks.map(publicBlock) } } });
+    } catch { send(503, { error: 'Content is temporarily unavailable.' }); }
+    finally { active--; res.off('close', cancel); }
+  };
+}

package/dist/wizard.mjs

@@ -0,0 +1,99 @@
+import { analyze, applyPlan, CONFIG_FILE, planSetup, projectRoot, readProjectFile, SetupError, validateConfig, validatePlan } from './core.mjs';
+import { applyEnvironment, planEnvironment, readSetupEnvironment, validateEnvironmentPlan, verifyEnvironment } from './setup-environment.mjs';
+
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const key = /^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}$/;
+function origin(value) {
+  try {
+    const url = new URL(value);
+    return value.length <= 2048 && !/[\s\\]/.test(value) && !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))) ? url.origin : null;
+  } catch { return null; }
+}
+function locale(value) { try { return value.length <= 35 ? Intl.getCanonicalLocales(value)[0] : null; } catch { return null; } }
+
+/** Interactive effects are injected so cancellation and secret handling are testable. */
+export async function runSetup(directory, options, io) {
+  const root = await projectRoot(directory);
+  const analysis = await analyze(root);
+  const saved = await readSetupEnvironment(root);
+  let prior;
+  const configText = await readProjectFile(root, CONFIG_FILE);
+  if (configText) {
+    try { prior = validateConfig(JSON.parse(configText)); }
+    catch { throw new SetupError('The saved connector configuration is invalid. Restore it before running setup.'); }
+  }
+  // Only the environment helper's sanitized defaults may reach terminal text.
+  const defaults = saved.defaults;
+  const framework = analysis.framework === 'Next.js' ? 'next' : 'vite';
+  const field = async (name, label, validate, fallback, message) => {
+    if (options[name] !== undefined) {
+      const value = validate(options[name]);
+      if (!value) throw new SetupError(message);
+      return value;
+    }
+    while (true) {
+      const answer = (await io.ask(`${label}${fallback ? ` [${fallback}]` : ''}: `)).trim();
+      const value = validate(answer || fallback || '');
+      if (value) return value;
+      io.write(`${message}\n`);
+    }
+  };
+  io.write('Connect this website without AI. Enter the connection values from Developer setup.\n');
+  const apiOrigin = await field('apiOrigin', 'CMS API origin', origin, defaults.apiOrigin, 'Use an HTTPS origin, or HTTP localhost for development.');
+  const siteId = await field('siteId', 'Website ID', value => uuid.test(value) && value.toLowerCase(), defaults.siteId, 'Enter a valid website UUID.');
+  const environmentId = await field('environmentId', 'Environment ID', value => uuid.test(value) && value.toLowerCase(), defaults.environmentId, 'Enter a valid environment UUID.');
+  const contentLocale = await field('locale', 'Content locale', locale, defaults.locale || 'en', 'Enter a valid content locale, such as en.');
+  const websiteOrigin = framework === 'vite' || options.websiteOrigin !== undefined
+    ? await field('websiteOrigin', 'Website origin', origin, defaults.websiteOrigin || 'http://localhost:5173', 'Use the exact website HTTPS origin, or HTTP localhost during development.') : undefined;
+  const existingServer = framework === 'vite' && analysis.runtime === 'node' && analysis.rendering === 'server';
+  const serverSource = existingServer ? await readProjectFile(root, 'server/index.mjs') : null;
+  const needsAdmin = !!serverSource?.includes('CMS_ADMIN_ORIGIN');
+  const adminOrigin = needsAdmin || options.adminOrigin !== undefined
+    ? await field('adminOrigin', 'CMS admin origin', origin, defaults.adminOrigin, 'Use the exact CMS admin HTTPS origin, or HTTP localhost during development.') : undefined;
+  const mount = options.mount ?? prior?.mount ?? '/cms';
+  const plan = await planSetup(root, { apiOrigin, siteId, environmentId, locale: contentLocale, mount }, { reconfigure: true });
+  let apiKey;
+  while (true) {
+    const answer = await io.hidden(saved.keyConfigured ? 'Server delivery key (hidden; Enter keeps the saved key): ' : 'Server delivery key (hidden): ');
+    if (!answer && saved.keyConfigured) break;
+    if (key.test(answer)) { apiKey = answer; break; }
+    io.write('Enter a valid server delivery key from Developer setup. It is not an AI provider key.\n');
+  }
+  const environment = await planEnvironment(root, { apiOrigin, siteId, environmentId, locale: contentLocale, websiteOrigin, adminOrigin, ...(apiKey ? { apiKey } : {}) });
+  apiKey = undefined;
+  let slug;
+  while (true) {
+    slug = (await io.ask('Published page slug to verify (optional; Enter skips): ')).trim();
+    if (!slug || (slug.length <= 160 && /^[a-z0-9]+(?:[-/][a-z0-9]+)*$/.test(slug))) break;
+    io.write('Enter a page slug without a leading slash, or leave it empty.\n');
+  }
+  io.write(`\nWebsite: ${siteId}\nEnvironment: ${environmentId}\nAPI: ${apiOrigin}\nLocale: ${contentLocale}\n`);
+  for (const file of plan.files) io.write(`  ${file.state}: ${file.path}\n`);
+  for (const file of environment.files) io.write(`  ${file.action}: ${file.path}\n`);
+  io.write('The delivery key is saved only in private .env.local (owner access), excluded from Git.\n');
+  if (existingServer) io.write('Keep the existing website server and renderer. Setup changes connection values; it does not mount a new handler in custom server code.\n');
+  const confirmation = (await io.ask('Save this setup? [Y/n] ')).trim().toLowerCase();
+  if (confirmation && confirmation !== 'y' && confirmation !== 'yes') {
+    io.write('Setup cancelled. No files changed.\n'); return { saved: false };
+  }
+  await validatePlan(plan);
+  await validateEnvironmentPlan(environment);
+  await applyEnvironment(environment);
+  let scaffold;
+  try { scaffold = await applyPlan(plan); }
+  catch { throw new SetupError('Private connection settings were saved, but generated-file setup did not finish. Existing custom edits were preserved; inspect the generated files and rerun setup.'); }
+  io.write(`Saved connection settings. Created ${scaffold.created.length} files; updated ${scaffold.updated.length} generated files.\n`);
+  if (slug) {
+    const verification = await verifyEnvironment(environment, { slug });
+    io.write(`${verification.message}\n`);
+    if (!verification.verified) io.write('Settings were saved, but delivery is not verified. Correct the connection or publish the requested page, then rerun setup.\n');
+  } else io.write('Delivery was not checked. Rerun setup with a published page slug when ready.\n');
+  const packages = analysis.diagnostics?.packages;
+  if (!packages || ['sdk', 'react', ...(framework === 'next' ? ['next'] : [])].some(name => packages[name]?.installed !== 'present' || packages[name]?.compatibility !== 'compatible')) {
+    io.write('Install the matching SDK and React renderer packages from Developer setup');
+    io.write(framework === 'next' ? ', plus the Next adapter.\n' : '.\n');
+  }
+  io.write('Restart the website using its normal command. See .universalcms/SETUP.md for rendering and deployment steps.\n');
+  return { saved: true };
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@universalcms/connect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Deterministic, local setup for Universal CMS websites using Next.js or React/Vite",
+  "type": "module",
+  "bin": {
+    "universalcms-connect": "dist/cli.mjs"
+  },
+  "exports": {
+    "./node": "./dist/vite-handler.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.12 <27"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "node --check src/cli.mjs && node --check src/core.mjs && node --check src/templates.mjs && node --check src/vite-handler.mjs && node --check src/wizard.mjs && node --check src/setup-environment.mjs"
+  }
 }