@universalcms/connect 0.13.2 → 0.13.3

package/README.md

@@ -1,7 +1,7 @@
 # @universalcms/connect
 
 Local, deterministic website setup without AI. Universal CMS stays hosted; this
-package creates a website integration, not a CMS installation. Version 0.13.2 is
+package creates a website integration, not a CMS installation. Version 0.13.3 is
 prepared locally; this repository does not establish its public npm availability.
 
 ## Quick start
@@ -262,7 +262,7 @@ custom adapter still requires review, not forced overwriting.
 For an operator's downloaded artifact, the installation is:
 
 ```sh
-npm install --save-prod ./vendor/universalcms-connect-0.13.2.tgz
+npm install --save-prod ./vendor/universalcms-connect-0.13.3.tgz
 ```
 
 Use your project's package manager. These paths are examples for downloaded
@@ -539,7 +539,7 @@ npx --no-install universalcms-connect init \
   --environment 22222222-2222-4222-8222-222222222222
 ```
 
-After a public release, `npx @universalcms/connect@0.13.2 init` is the equivalent
+After a public release, `npx @universalcms/connect@0.13.3 init` is the equivalent
 registry entry point. Copy the real IDs/API origin from **Developer setup**.
 Missing values are prompted in a terminal; `--non-interactive` fails instead.
 Init prints a plan. Run the same command with `--apply` after reviewing it.
@@ -589,7 +589,7 @@ The CMS button reads the website's **`/api/cms-source`** endpoint. Current Next.
 prepares delivery scaffolding. React/Vite setup serves its reviewed public manifest through the normal dev command.
 Custom exporters need their explicit adapter; a delivery check alone is insufficient.
 
-Use the CMS's reviewed 0.13.2 package for the staged commands and current source
+Use the CMS's reviewed 0.13.3 package for the staged commands and current source
 discovery. Review source diagnostics and complete public
 mappings for unsupported pages. Restart the website using its normal server command, then run:
 

package/dist/cli.mjs

@@ -20,7 +20,7 @@ import { WEBSITE_SECTIONS } from './website-http.mjs';
 import { setupSource, applySourcePlan, syncSource, readSourceSettings } from './source-setup.mjs';
 import { processIo, runCreate, runGuided } from './guided.mjs';
 
-const help = `Universal CMS connector 0.13.2
+const help = `Universal CMS connector 0.13.3
 
 Quick start (recommended) — run in your website folder:
   npx @universalcms/connect@latest --cms https://YOUR_CMS_ADDRESS

package/dist/guided.mjs

@@ -392,6 +392,21 @@ export async function runGuided(directory, options, io) {
   const installed = await readProjectFile(root, '.universalcms/website.integration.json') !== null;
   if (saved && environment.keyConfigured && !options.code && await readProjectFile(root, SETTINGS_ONLY_FILE) !== null) {
     io.write(`✔ Already connected for site settings (${saved.websiteOrigin})\n`);
+    // Bring generated files up to date with this connector version.
+    const update = await planSettingsOnly(root, Object.fromEntries(['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'].map(name => [name, saved[name]])));
+    const stale = update.files.filter(file => file.state !== 'unchanged');
+    if (stale.length) {
+      await ensureConnector(root, manifest, io);
+      io.write(`\nThis connector version updates ${stale.length} Universal CMS file${stale.length === 1 ? '' : 's'} in your website (your pages and design stay the same):\n`);
+      for (const file of stale) io.write(`  ${file.state}: ${file.path}\n`);
+      if (yes(await io.ask('Update them? [Y/n] '))) {
+        const again = await planSettingsOnly(root, update.connection);
+        if (JSON.stringify(again.files) !== JSON.stringify(update.files)) fail('Your website files changed while reviewing. Nothing was saved; run the same command again.');
+        await applyPlan(update);
+        io.write('✔ Universal CMS files updated — restart your website to load them\n');
+        return finishSettingsOnly(root, saved, await manifestOf(root), io, true);
+      }
+    }
     return finishSettingsOnly(root, saved, manifest, io);
   }
   if (saved && installed && environment.keyConfigured && !options.code) {
@@ -520,12 +535,12 @@ async function settingsReady(connection, io) {
     url.search = new URLSearchParams({ check: 'connection', siteId: connection.siteId, environmentId: connection.environmentId }).toString();
     const response = await io.fetch(url, { headers: { Origin: connection.adminOrigin, Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(10000) });
     const body = response.ok ? await response.json() : null;
-    return body?.mode === 'settings-only' && body.siteId === connection.siteId && body.environmentId === connection.environmentId;
+    return body?.mode === 'settings-only' && body.siteId === connection.siteId && body.environmentId === connection.environmentId && body.discovered?.version === 1;
   } catch { return false; }
 }
 
-async function finishSettingsOnly(root, connection, manifest, io) {
-  if (!await settingsReady(connection, io)) {
+async function finishSettingsOnly(root, connection, manifest, io, restart = false) {
+  if (restart || !await settingsReady(connection, io)) {
     const local = /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|$)/.test(connection.websiteOrigin), command = await restartHint(root, manifest);
     io.write(local
       ? `\n→ Restart your website so the changes take effect:\n   1. In the terminal where your website is running, press Ctrl+C\n   2. Start it again${command ? ` with: ${command}` : ''}\n   It must run at ${connection.websiteOrigin}\n`
@@ -538,7 +553,7 @@ async function finishSettingsOnly(root, connection, manifest, io) {
   }
   const settings = `${connection.adminOrigin}/sites/${connection.siteId}#setup?environmentId=${connection.environmentId}`;
   io.write(`✔ Your website is connected for site settings\n\n🎉 All done! Manage it from Universal CMS (this link opens the right environment):\n   ${settings}\n`);
-  io.write('   • SEO, branding, analytics, scripts, cookie consent and redirects apply automatically.\n');
+  io.write('   • In Developer setup, import the pages and header/footer links found on your website, so they appear in the CMS.\n   • Page text stays in your website\'s code; each page\'s SEO (title, description, social image) and your menus, logo, analytics, scripts and redirects are managed in the CMS.\n');
   io.write('   • To show the CMS menu in your own header or footer, add one line where it should appear:\n');
   io.write("       import { CmsNavigation } from '@universalcms/connect/react-website';\n       <CmsNavigation location=\"header\" />   (or location=\"footer\")\n");
   io.write('     Other drop-ins: <CmsBranding />, <CmsSocialLinks />, and useWebsiteSettings() for anything custom.\n');

package/dist/settings-only-setup.mjs

@@ -8,6 +8,7 @@ import ts from './vendor/typescript.cjs';
 import { projectRoot, readProjectFile, SetupError } from './project-files.mjs';
 import { inspectSourceRoutes } from './source-routes.mjs';
 import { CONNECTION_FILE, validateConnection } from './staged-setup.mjs';
+import { discoverSite, DISCOVERED_FILE } from './site-discovery.mjs';
 
 export const SETTINGS_ONLY_FILE = '.universalcms/settings-only.json';
 const fail = message => { throw new SetupError(message); };
@@ -45,8 +46,9 @@ const settingsRoute = (app, file) => `${MARK} Site settings served to the websit
 import { createSettingsOnlyHandler } from '@universalcms/connect/settings-only';
 import configuration from '${relative(file, SETTINGS_ONLY_FILE)}';
 import connection from '${relative(file, CONNECTION_FILE)}';
+import discovered from '${relative(file, DISCOVERED_FILE)}';
 
-const handle = createSettingsOnlyHandler({ configuration: configuration as Parameters<typeof createSettingsOnlyHandler>[0]['configuration'], adminOrigin: connection.adminOrigin });
+const handle = createSettingsOnlyHandler({ configuration: configuration as Parameters<typeof createSettingsOnlyHandler>[0]['configuration'], adminOrigin: connection.adminOrigin, discovered });
 export const dynamic = 'force-dynamic';
 export const GET = handle;
 export const HEAD = handle;
@@ -84,6 +86,10 @@ export async function planSettingsOnly(directory, connectionInput) {
   };
   await add(CONNECTION_FILE, json(connection));
   await add(SETTINGS_ONLY_FILE, json({ version: 1, apiOrigin: connection.apiOrigin, siteId: connection.siteId, environmentId: connection.environmentId, websiteOrigin: connection.websiteOrigin, routes: [] }));
+  // Public page titles and header/footer links found in the source; the CMS offers to import them.
+  const discovered = await discoverSite(root);
+  const previousDiscovery = await readProjectFile(root, DISCOVERED_FILE), discoveryContent = json(discovered);
+  files.push({ path: DISCOVERED_FILE, content: discoveryContent, state: previousDiscovery === null ? 'create' : previousDiscovery === discoveryContent ? 'unchanged' : 'update', ...(previousDiscovery !== null && previousDiscovery !== discoveryContent ? { previous: previousDiscovery } : {}) });
   for (const name of ['settings', 'page']) { const path = `${app}/api/universalcms/${name}/route.${ext}`; await add(path, settingsRoute(app, path).replace(typed ? '' : / as Parameters<[^>]+>\[0\]\['configuration'\]/, '')); }
   const wrapper = `${app}/universalcms.settings.${typed ? 'tsx' : 'jsx'}`;
   await add(wrapper, wrapperTemplate(wrapper, typed));

package/dist/settings-only.d.mts

@@ -1,4 +1,4 @@
 export const SETTINGS_ONLY_MODE: 'settings-only';
 export type SettingsOnlyConfiguration = { version: 1; apiOrigin: string; siteId: string; environmentId: string; websiteOrigin: string; routes: [] };
-export function createSettingsOnlyHandler(options: { configuration: SettingsOnlyConfiguration; adminOrigin: string; env?: () => Record<string, string | undefined>; fetcher?: typeof fetch }): (request: Request) => Promise<Response>;
+export function createSettingsOnlyHandler(options: { configuration: SettingsOnlyConfiguration; adminOrigin: string; discovered?: unknown; env?: () => Record<string, string | undefined>; fetcher?: typeof fetch }): (request: Request) => Promise<Response>;
 export function createSettingsOnlyRuntime(options: { configuration: SettingsOnlyConfiguration; env?: () => Record<string, string | undefined>; fetcher?: typeof fetch }): { settings(): Promise<unknown> };

package/dist/settings-only.mjs

@@ -6,6 +6,7 @@
  */
 import { createWebsiteRuntime } from './website-runtime.mjs';
 import { WEBSITE_PAGE_PATH, WEBSITE_SECTIONS, WEBSITE_SETTINGS_PATH } from './website-http.mjs';
+import { normalizePublicationPath, publicationRevision } from './publication.mjs';
 
 export const SETTINGS_ONLY_MODE = 'settings-only';
 const base = { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer' };
@@ -13,7 +14,17 @@ const base = { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff',
 /**
  * @param {{ configuration: { version: 1, apiOrigin: string, siteId: string, environmentId: string, websiteOrigin: string, routes: [] }, adminOrigin: string, env?: () => Record<string, string | undefined>, fetcher?: typeof fetch }} options
  */
-export function createSettingsOnlyHandler({ configuration, adminOrigin, env = () => process.env, fetcher = globalThis.fetch }) {
+const short = (value, max) => typeof value === 'string' ? value.slice(0, max) : '';
+/** Only bounded public strings from the website source reach the admin. */
+function publicDiscovery(value) {
+  if (!value || value.version !== 1) return undefined;
+  const link = item => ({ label: short(item?.label, 80), url: short(item?.url, 200) });
+  return { version: 1, pages: (Array.isArray(value.pages) ? value.pages : []).slice(0, 100).map(page => ({ path: short(page?.path, 200), title: short(page?.title, 120), description: short(page?.description, 320) })),
+    navigation: { header: (value.navigation?.header ?? []).slice(0, 20).map(link), footer: (value.navigation?.footer ?? []).slice(0, 20).map(link) } };
+}
+
+export function createSettingsOnlyHandler({ configuration, adminOrigin, discovered, env = () => process.env, fetcher = globalThis.fetch }) {
+  const discovery = publicDiscovery(discovered);
   const runtime = createWebsiteRuntime({ configuration, settingsOnly: true, env, fetcher });
   const admin = new URL(adminOrigin).origin;
   if (admin !== adminOrigin) throw new Error('Invalid CMS admin origin');
@@ -21,9 +32,16 @@ export function createSettingsOnlyHandler({ configuration, adminOrigin, env = ()
     const method = request.method, url = new URL(request.url), origin = request.headers.get('origin');
     const reply = (body, status = 200, extra = {}) => new Response(method === 'HEAD' || status === 204 ? null : JSON.stringify(body), { status, headers: { ...base, 'Content-Type': 'application/json', ...extra } });
     if (url.pathname === WEBSITE_PAGE_PATH) {
-      // Every page belongs to the website in settings-only mode.
+      // The website renders every page. A published CMS page at the same path
+      // supplies only its SEO metadata (title, description, social tags).
       if (!['GET', 'HEAD'].includes(method)) return reply({ error: 'Method not allowed' }, 405, { Allow: 'GET, HEAD' });
-      return reply({ state: 'missing' }, 404);
+      if (origin && origin !== configuration.websiteOrigin || request.headers.get('sec-fetch-site') === 'cross-site') return reply({ error: 'Request not allowed' }, 403);
+      let pathname;
+      try { pathname = normalizePublicationPath(url.searchParams.get('path') ?? ''); } catch { return reply({ state: 'missing' }, 404); }
+      const result = await runtime.page(pathname === '/' ? '/home' : pathname);
+      if (result.state !== 'published') return reply({ state: result.state === 'unavailable' ? 'unavailable' : 'missing' }, result.state === 'unavailable' ? 503 : 404);
+      const entry = { ...result.entry, path: pathname };
+      return reply({ ...result, path: pathname, entry, revision: publicationRevision(entry) });
     }
     if (url.pathname !== WEBSITE_SETTINGS_PATH) return reply({ error: 'Not found' }, 404);
     const diagnostic = url.searchParams.get('check') === 'connection';
@@ -39,7 +57,7 @@ export function createSettingsOnlyHandler({ configuration, adminOrigin, env = ()
         return reply({ error: 'Website scope mismatch', ...(sameSite ? { siteId: configuration.siteId, environmentId: configuration.environmentId } : {}) }, 409, cors);
       }
       const snapshot = await runtime.settings();
-      return reply({ version: 1, mode: SETTINGS_ONLY_MODE, siteId: configuration.siteId, environmentId: configuration.environmentId, renderedVerified: false,
+      return reply({ version: 1, mode: SETTINGS_ONLY_MODE, siteId: configuration.siteId, environmentId: configuration.environmentId, renderedVerified: false, ...(discovery ? { discovered: discovery } : {}),
         settings: Object.fromEntries(WEBSITE_SECTIONS.map(section => [section, { installed: true, state: snapshot.sections[section]?.state ?? 'unavailable', version: snapshot.sections[section]?.version ?? 0 }])) }, 200, cors);
     }
     if (!['GET', 'HEAD'].includes(method)) return reply({ error: 'Method not allowed' }, 405, { Allow: 'GET, HEAD' });

package/dist/site-discovery.mjs

@@ -0,0 +1,130 @@
+/**
+ * Reads a Next.js App Router website's public structure without running it:
+ * its static pages (path, title, description) and the literal links in its
+ * header and footer. The result seeds the CMS for settings-only websites and
+ * contains only public text already present in the website source.
+ */
+import path from 'node:path';
+import ts from './vendor/typescript.cjs';
+import { projectRoot, readProjectFile } from './project-files.mjs';
+import { inspectSourceRoutes } from './source-routes.mjs';
+
+export const DISCOVERED_FILE = '.universalcms/discovered.json';
+const MAX_PAGES = 100, MAX_LINKS = 20;
+const entities = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", rsquo: '’', lsquo: '‘', rdquo: '”', ldquo: '“', nbsp: ' ', ndash: '–', mdash: '—', hellip: '…', copy: '©', reg: '®', trade: '™' };
+const decode = value => value.replace(/&(#\d+|#x[0-9a-f]+|[a-z]+);/gi, (match, name) => name[0] === '#' ? String.fromCodePoint(Number.parseInt(name.slice(name[1] === 'x' || name[1] === 'X' ? 2 : 1), name[1] === 'x' || name[1] === 'X' ? 16 : 10)) : entities[name.toLowerCase()] ?? match);
+const clean = (value, max) => typeof value === 'string' ? decode(value).replace(/\s+/g, ' ').trim().slice(0, max) : '';
+const parse = (filename, text) => ts.createSourceFile(filename, text, ts.ScriptTarget.Latest, true, /x$/.test(filename) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+// Same rule as CMS navigation: plain site paths (no query or fragment) or HTTPS URLs.
+const publicUrl = value => typeof value === 'string' && value.length <= 200 && (/^\/(?!\/)[a-zA-Z0-9/_\-]*$/.test(value) || /^https:\/\/[^\s<>"'`]+$/.test(value)) && !/^\/(api|_next)(\/|$)/.test(value);
+
+/** Literal string of a property in `export const metadata = { ... }` (title may be a string or { default }). */
+function metadataOf(ast) {
+  for (const statement of ast.statements) {
+    if (!ts.isVariableStatement(statement) || !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== 'metadata' || !declaration.initializer || !ts.isObjectLiteralExpression(declaration.initializer)) continue;
+      const read = name => {
+        const property = declaration.initializer.properties.find(item => ts.isPropertyAssignment(item) && item.name.getText(ast) === name);
+        if (!property) return '';
+        const value = property.initializer;
+        if (ts.isStringLiteralLike(value)) return value.text;
+        if (ts.isObjectLiteralExpression(value)) { const fallback = value.properties.find(item => ts.isPropertyAssignment(item) && item.name.getText(ast) === 'default'); return fallback && ts.isStringLiteralLike(fallback.initializer) ? fallback.initializer.text : ''; }
+        return '';
+      };
+      return { title: clean(read('title'), 120), description: clean(read('description'), 320) };
+    }
+  }
+  return { title: '', description: '' };
+}
+
+/** Text written directly inside a JSX element (ignores expressions and icons). */
+function literalText(node) {
+  let text = '';
+  (function visit(child) { if (ts.isJsxText(child)) text += ` ${child.text}`; else if (ts.isJsxExpression(child) && child.expression && ts.isStringLiteralLike(child.expression)) text += ` ${child.expression.text}`; else ts.forEachChild(child, visit); })(node);
+  return clean(text, 60);
+}
+
+function firstHeading(ast) {
+  let found = '';
+  (function visit(node) { if (found) return; if (ts.isJsxElement(node) && node.openingElement.tagName.getText(ast) === 'h1') { found = literalText(node); return; } ts.forEachChild(node, visit); })(ast);
+  return found;
+}
+
+/** Literal <Link href> / <a href> elements, labelled by their nearest <header>/<footer> ancestor. */
+function linksOf(ast, fallbackArea) {
+  const links = [];
+  (function visit(node, area) {
+    if (ts.isJsxElement(node)) {
+      const tag = node.openingElement.tagName.getText(ast);
+      if (tag === 'header' || tag === 'nav' && !area) area = 'header';
+      if (tag === 'footer') area = 'footer';
+      if (tag === 'Link' || tag === 'a') {
+        const href = node.openingElement.attributes.properties.find(attribute => ts.isJsxAttribute(attribute) && attribute.name.getText(ast) === 'href');
+        const value = href && ts.isJsxAttribute(href) && href.initializer && (ts.isStringLiteral(href.initializer) ? href.initializer.text : ts.isJsxExpression(href.initializer) && href.initializer.expression && ts.isStringLiteralLike(href.initializer.expression) ? href.initializer.expression.text : null);
+        const label = literalText(node);
+        if (publicUrl(value) && label && (area ?? fallbackArea)) links.push({ area: area ?? fallbackArea, label, url: value });
+        return;
+      }
+    }
+    ts.forEachChild(node, child => visit(child, area));
+  })(ast, null);
+  return links;
+}
+
+/** Local components imported by the root layout (one level), with their likely area. */
+function layoutComponents(ast, layoutFile, app) {
+  const result = [];
+  for (const statement of ast.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !statement.importClause?.name && !statement.importClause?.namedBindings) continue;
+    const specifier = statement.moduleSpecifier.text, name = statement.importClause.name?.text ?? specifier.split('/').at(-1);
+    const area = /footer/i.test(name) ? 'footer' : /header|nav|menu/i.test(name) ? 'header' : null;
+    if (!area) continue;
+    const base = specifier.startsWith('@/') ? `${app.startsWith('src/') ? 'src/' : ''}${specifier.slice(2)}` : specifier.startsWith('.') ? path.posix.normalize(path.posix.join(path.posix.dirname(layoutFile), specifier)) : null;
+    if (base) result.push({ base, area });
+  }
+  return result;
+}
+
+async function readFirst(root, base) {
+  for (const candidate of [base, ...['.tsx', '.jsx', '.ts', '.js', '/index.tsx', '/index.jsx'].map(suffix => base + suffix)]) {
+    try { const text = await readProjectFile(root, candidate); if (text !== null) return { file: candidate, text }; } catch { /* Not this candidate. */ }
+  }
+  return null;
+}
+
+const titleFromPath = route => route === '/' ? 'Home' : clean(route.split('/').filter(Boolean).at(-1).replace(/[-_]+/g, ' ').replace(/\b\w/g, letter => letter.toUpperCase()), 120);
+
+export async function discoverSite(directory) {
+  const root = await projectRoot(directory), inventory = await inspectSourceRoutes(root);
+  const files = Object.entries(inventory.files);
+  const app = files[0]?.[1].startsWith('src/app/') ? 'src/app' : 'app';
+  const pages = [];
+  for (const [route, file] of files.slice(0, MAX_PAGES)) {
+    const pathname = route === 'home' || route === '' ? '/' : `/${route}`;
+    const text = await readProjectFile(root, file).catch(() => null);
+    const ast = text ? parse(file, text) : null;
+    const meta = ast ? metadataOf(ast) : { title: '', description: '' };
+    pages.push({ path: pathname, title: meta.title || (ast && firstHeading(ast)) || titleFromPath(pathname), description: meta.description });
+  }
+  pages.sort((a, b) => a.path.localeCompare(b.path));
+  const links = [];
+  for (const ext of ['tsx', 'jsx', 'js', 'ts']) {
+    const layoutFile = `${app}/layout.${ext}`, text = await readProjectFile(root, layoutFile).catch(() => null);
+    if (!text) continue;
+    const ast = parse(layoutFile, text);
+    links.push(...linksOf(ast, null));
+    for (const component of layoutComponents(ast, layoutFile, app)) {
+      const found = await readFirst(root, component.base);
+      if (found) links.push(...linksOf(parse(found.file, found.text), component.area));
+    }
+    break;
+  }
+  const navigation = { header: [], footer: [] }, seen = { header: new Set(), footer: new Set() };
+  for (const link of links) {
+    const key = `${link.label}\n${link.url}`;
+    if (seen[link.area].has(key) || navigation[link.area].length >= MAX_LINKS) continue;
+    seen[link.area].add(key); navigation[link.area].push({ label: link.label, url: link.url });
+  }
+  return { version: 1, pages, navigation };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@universalcms/connect",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "Deterministic framework-aware Universal CMS setup for reviewed native websites",
   "type": "module",
   "bin": {