@universalcms/connect 0.1.0 → 0.13.0

package/dist/native-route-review.mjs

@@ -0,0 +1,152 @@
+/** Explicit website-owned route review. No source execution or private reads. */
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import ts from './vendor/typescript.cjs';
+import { projectRoot, readProjectFile, applyPlan, SetupError } from './core.mjs';
+import { inspectSetupFramework } from './framework.mjs';
+import { inspectSourceRoutes } from './source-routes.mjs';
+import { inspectReviewedNativeOwnership, NATIVE_ROUTES_FILE } from './reviewed-native-ownership.mjs';
+import { REVIEWED_NEXT_NATIVE_PROFILE, isNativeReviewFilePath, validateNativeRoutes } from './native-routes.mjs';
+import { isExcludedPublicationPath } from './publication.mjs';
+import { sanitizeSetupPaths } from './preflight-recovery.mjs';
+
+const fail = message => { throw new SetupError(message); };
+const digest = text => createHash('sha256').update(text).digest('hex');
+const json = value => JSON.stringify(value, null, 2) + '\n';
+const extensions = ['ts', 'tsx', 'js', 'jsx'];
+const installedFiles = ['.universalcms/content.bindings.json', '.universalcms/publication.config.json', '.universalcms/website.integration.json', '.universalcms/reviewed.integration.json'];
+const configurationFiles = ['package.json', 'tsconfig.json', 'jsconfig.json', ...['js','mjs','cjs','ts'].map(ext => `next.config.${ext}`)];
+
+async function beforeInstallation(root) {
+  for (const name of installedFiles) {
+    if (await readProjectFile(root, name) !== null) fail('An integration is already installed. Preserve its route ownership and use a reviewed adapter update; review-routes never reassigns installed content.');
+  }
+}
+
+export async function inspectNativeRouteCandidates(directory) {
+  const root = await projectRoot(directory);
+  const framework = await inspectSetupFramework(root);
+  if (framework.framework !== 'next') fail('review-routes supports Next.js App Router native routes. Other custom routers need their framework-specific reviewed adapter; no files changed.');
+  await beforeInstallation(root);
+  const inventory = await inspectSourceRoutes(root);
+  if (!Object.values(inventory.files).length) fail('Native route review requires at least one existing public App Router page.');
+  const app = Object.values(inventory.files)[0].startsWith('src/app/') ? 'src/app' : 'app';
+  const candidates = [], unsupported = [];
+  for (const route of inventory.routes.sort()) {
+    const pathname = '/' + route, file = inventory.files[route || 'home'];
+    // Route groups do not imply ownership of their siblings or layouts.
+    if (!extensions.some(ext => file === `${app}${route ? '/' + route : ''}/page.${ext}`)) continue;
+    try { validateNativeRoutes({ nativePaths: [pathname], nativePatterns: [] }); }
+    catch { continue; }
+    candidates.push({ path: pathname, kind: 'static', file });
+  }
+  for (const directory of inventory.unresolvedPaths.sort()) {
+    const pathname = directory.startsWith(app + '/') ? directory.slice(app.length) : '';
+    try { validateNativeRoutes({ nativePaths: [], nativePatterns: [pathname] }); }
+    catch { unsupported.push(directory); continue; }
+    const files = [];
+    for (const extension of extensions) if (await readProjectFile(root, `${directory}/page.${extension}`) !== null) files.push(`${directory}/page.${extension}`);
+    if (files.length !== 1) { unsupported.push(directory); continue; }
+    candidates.push({ path: pathname, kind: 'dynamic', file: files[0] });
+  }
+  const safe = sanitizeSetupPaths(unsupported);
+  return { root, framework: 'next', app, candidates, unsupported: safe.paths, omittedPathCount: safe.omittedPathCount };
+}
+
+// Only local, bounded public source modules may be inventoried. Private env
+// files, paths outside the project, aliases and computed imports are not read.
+async function dependencyClosure(root, app, seeds) {
+  const seen = new Map(); let bytes = 0;
+  async function visit(filename) {
+    if (seen.has(filename)) return;
+    if (!isNativeReviewFilePath(filename)) fail('A native dependency is outside ordinary application source. Review it manually; private files were not read.');
+    const content = await readProjectFile(root, filename);
+    if (content === null || (await lstat(path.join(root, filename))).nlink !== 1) fail('Native review requires existing ordinary source files without links.');
+    bytes += Buffer.byteLength(content);
+    if (seen.size >= 200 || bytes > 8 * 1024 * 1024) fail('Native source review exceeds its file or byte budget.');
+    seen.set(filename, content);
+    if (!/\.[cm]?[jt]sx?$/.test(filename)) return;
+    const ast = ts.createSourceFile(filename, content, ts.ScriptTarget.Latest, true, /x$/.test(filename) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    if (ast.parseDiagnostics.length) fail('A native source module cannot be parsed. Correct its syntax before route review.');
+    const imports = [];
+    function scan(node) {
+      if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) imports.push(node.moduleSpecifier.text);
+      if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === 'require')) {
+        if (node.arguments.length !== 1 || !ts.isStringLiteral(node.arguments[0])) fail('Computed native imports require a reviewed adapter.');
+        imports.push(node.arguments[0].text);
+      }
+      ts.forEachChild(node, scan);
+    }
+    scan(ast);
+    for (const specifier of imports) {
+      if (!specifier.startsWith('.') && !specifier.startsWith('@/')) continue;
+      const base = specifier.startsWith('@/') ? (app.startsWith('src/') ? 'src/' : '') + specifier.slice(2) : path.posix.normalize(path.posix.join(path.posix.dirname(filename), specifier));
+      const choices = (/\.(?:[cm]?[jt]sx?|json|css)$/.test(base) ? [base] : [base, ...['.ts','.tsx','.js','.jsx','.mjs','.cjs','.mts','.cts','.json','/index.ts','/index.tsx','/index.js','/index.jsx'].map(suffix => base + suffix)]).filter(isNativeReviewFilePath);
+      const found = [];
+      for (const choice of choices) { try { if (await readProjectFile(root, choice) !== null) found.push(choice); } catch (error) { if (choice !== base || choices.length === 1 || error.message !== 'A setup path has an incompatible file type.') throw error; } }
+      if (found.length !== 1) fail('A local native dependency is missing or ambiguous. Resolve it before route review.');
+      await visit(found[0]);
+    }
+  }
+  for (const seed of seeds) await visit(seed);
+  return [...seen].sort(([a], [b]) => a.localeCompare(b)).map(([path, content]) => ({ path, content, state: 'unchanged' }));
+}
+
+export async function planNativeRouteReview(directory, selection) {
+  const discovered = await inspectNativeRouteCandidates(directory), { root, app, candidates } = discovered;
+  if (!Array.isArray(selection) || !selection.length || selection.length > 1100 || selection.some(value => typeof value !== 'string') || new Set(selection).size !== selection.length) fail('Select exact existing website-owned routes for review.');
+  const selected = selection.map(value => candidates.find(row => row.path === value));
+  if (selected.some(row => !row)) fail('A selected route is not an existing supported native route.');
+  if (!candidates.some(row => row.kind === 'static' && !selection.includes(row.path) && !isExcludedPublicationPath(row.path))) fail('Keep at least one public page mapped to CMS content. A fully native application needs a settings-only adapter, not an empty publication setup.');
+  const seeds = selected.map(row => row.file);
+  for (const row of selected) {
+    let directory = path.posix.dirname(row.file);
+    while (directory !== app) {
+      for (const name of ['layout','template','loading','error','default','not-found']) for (const ext of extensions) {
+        const filename = `${directory}/${name}.${ext}`;
+        if (await readProjectFile(root, filename) !== null) seeds.push(filename);
+      }
+      directory = path.posix.dirname(directory);
+    }
+  }
+  const observations = await dependencyClosure(root, app, seeds);
+  const value = { version: 1, profile: REVIEWED_NEXT_NATIVE_PROFILE,
+    nativePaths: selected.filter(row => row.kind === 'static').map(row => row.path).sort(),
+    nativePatterns: selected.filter(row => row.kind === 'dynamic').map(row => row.path).sort(),
+    files: observations.map(({path, content}) => ({path, sha256: digest(content)})) };
+  const text = json(value);
+  await inspectReviewedNativeOwnership(root, { candidate: text });
+  const previous = await readProjectFile(root, NATIVE_ROUTES_FILE);
+  if (previous !== null && (await lstat(path.join(root, NATIVE_ROUTES_FILE))).nlink !== 1) fail('The existing native review is linked. Preserve it and review manually.');
+  for (const filename of configurationFiles) {
+    const content = await readProjectFile(root, filename);
+    observations.push({ path: filename, content, state: content === null ? 'absent' : 'unchanged' });
+  }
+  return { root, framework: 'next', routes: selected, unsupported: discovered.unsupported, files: [...observations, ...installedFiles.map(path => ({path,content:null,state:'absent'})), {
+    path: NATIVE_ROUTES_FILE, content: text, state: previous === null ? 'create' : previous === text ? 'unchanged' : 'update', ...(previous !== null && previous !== text ? { previous } : {}),
+  }] };
+}
+
+export async function runNativeRouteReview(directory, io) {
+  const inventory = await inspectNativeRouteCandidates(directory);
+  io.write('Review website-owned application routes. Selected routes keep their existing rendering and are excluded from CMS source import and publication control. This does not install the connection or grant key access.\n');
+  inventory.candidates.forEach((row, index) => io.write(`  ${index + 1}. ${row.path} (${row.kind}) — ${row.file}\n`));
+  if (inventory.unsupported.length) io.write(`Additional routes require an adapter review: ${inventory.unsupported.join(', ')}\n`);
+  if (inventory.omittedPathCount) io.write('Additional unsupported paths were omitted from output; they still require local adapter review.\n');
+  const answer = (await io.ask('Enter comma-separated route numbers to keep native (blank cancels): ')).trim();
+  if (!answer) { io.write('Route review cancelled. No files changed.\n'); return { saved: false }; }
+  if (!/^\d+(?:\s*,\s*\d+)*$/.test(answer)) fail('Use only the displayed route numbers, separated by commas.');
+  const indexes = answer.split(',').map(value => Number(value.trim()) - 1);
+  if (new Set(indexes).size !== indexes.length || indexes.some(index => !Number.isSafeInteger(index) || index < 0 || index >= inventory.candidates.length)) fail('Select each displayed route number at most once.');
+  const selection = indexes.map(index => inventory.candidates[index].path);
+  const plan = await planNativeRouteReview(directory, selection);
+  if (JSON.stringify(await inspectNativeRouteCandidates(directory)) !== JSON.stringify(inventory)) fail('Route inventory changed during review. No manifest was saved.');
+  for (const row of plan.routes) io.write(`  Keep native: ${row.path}\n`);
+  io.write(`Review includes ${plan.files.length - 1} source/configuration files. It preserves all website files and changes only ${NATIVE_ROUTES_FILE}.\n`);
+  if (!['y','yes'].includes((await io.ask('Save this native route review? [y/N] ')).trim().toLowerCase())) return { saved: false };
+  if (JSON.stringify(await planNativeRouteReview(directory, selection)) !== JSON.stringify(plan)) fail('Native sources changed during review. No manifest was saved.');
+  await applyPlan(plan);
+  io.write('Native route review saved. Rerun the scoped preflight. If it reports existing header/footer ownership, run review-layout. Complete setup and running-website checks before connecting.\n');
+  return { saved: true, routes: selection };
+}

package/dist/native-routes.mjs

@@ -0,0 +1,27 @@
+/** Explicit native Next route ownership. No prefix or wildcard expansion. */
+export const REVIEWED_NEXT_NATIVE_PROFILE = 'reviewed-next-native-v1';
+const pathPattern = /^\/(?:[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*)?$/;
+const dynamicPattern = /^(\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\/)+)\[([a-zA-Z][a-zA-Z0-9_]*)\]$/;
+const reserved = new Set(['api', 'admin', 'auth', 'login', 'logout', 'signin', 'signout', 'sign-in', 'sign-out', 'signup', 'sign-up', 'register', 'dashboard', 'settings', 'billing', 'preview', 'draft-preview', 'cms-preview', 'node-modules', 'src', 'public', 'assets', 'static']);
+const safePath = value => typeof value === 'string' && value.length <= 500 && pathPattern.test(value) && !value.split('/').some(segment => reserved.has(segment));
+export const isNativeReviewFilePath = value => typeof value === 'string' && value.length <= 500 && /^(?:src\/)?(?:app|components|context|data|lib)\/[A-Za-z0-9_()[\]./-]+\.(?:[cm]?[jt]sx?|json|css)$/.test(value) && value.split('/').every(part => !!part && part !== '.' && part !== '..' && !part.startsWith('.'));
+const fail = () => { throw Error('Invalid reviewed native route ownership. Use exact native paths and single final dynamic segments without reserved routes or overlaps.'); };
+export function nativePatternMatches(pattern, pathname) {
+  const match = typeof pattern === 'string' && dynamicPattern.exec(pattern);
+  if (!match || typeof pathname !== 'string' || !pathname.startsWith(match[1])) return false;
+  const value = pathname.slice(match[1].length);
+  return /^[A-Za-z0-9_-]+$/.test(value) && !reserved.has(value.toLowerCase());
+}
+export function matchesNativeRoutes(value, pathname) {
+  return value?.nativePaths?.includes(pathname) || value?.nativePatterns?.some(pattern => nativePatternMatches(pattern, pathname)) || false;
+}
+export function validateNativeRoutes(value, cmsRoutes = []) {
+  if (!value || !Array.isArray(value.nativePaths) || !Array.isArray(value.nativePatterns) ||
+      value.nativePaths.length + value.nativePatterns.length < 1 || value.nativePaths.length > 1000 || value.nativePatterns.length > 100 ||
+      value.nativePaths.some(name => !safePath(name)) || new Set(value.nativePaths).size !== value.nativePaths.length ||
+      value.nativePatterns.some(name => typeof name !== 'string' || name.length > 500 || !dynamicPattern.test(name) || !safePath(name.replace(/\[[^/]+\]$/, 'reviewed-native-value')))) return fail();
+  const parents = value.nativePatterns.map(name => name.slice(0, name.lastIndexOf('/') + 1));
+  if (new Set(parents).size !== parents.length || value.nativePaths.some(name => value.nativePatterns.some(pattern => nativePatternMatches(pattern, name))) ||
+      cmsRoutes.some(row => matchesNativeRoutes(value, typeof row === 'string' ? row : row?.path))) return fail();
+  return value;
+}

package/dist/native-website-model.d.mts

@@ -0,0 +1,18 @@
+import type { WebsiteResult, WebsiteSnapshot } from './website-runtime.mjs';
+import type { PublishedDocumentEntry } from './publication.mjs';
+import type {NativeChromeDescriptor} from './native-chrome-model.mjs';
+export type NativeWebsiteInventory = {
+  nativeChrome?: NativeChromeDescriptor;
+  identity: { kind: 'page' | 'post'; slug: string; locale: string };
+  baseline: PublishedDocumentEntry['document'];
+  bindings: Record<string, { variants: Array<{ id: string; values: string[] }> }>;
+};
+export type NativeWebsitePayload = {
+  pathname: string;
+  scope: string;
+  initialResult: WebsiteResult;
+  initialSettings: WebsiteSnapshot;
+  inventory?: NativeWebsiteInventory;
+};
+export function nativeWebsitePayload(value: unknown): NativeWebsitePayload;
+export function serializeNativeWebsite(value: unknown): string;

package/dist/native-website-model.mjs

@@ -0,0 +1,67 @@
+/** Public boundary for framework-native hosts. Never serialize a frozen source. */
+import { publicPublishedEntry, normalizePublicationPath, isExcludedPublicationPath, publicationRevision } from './publication.mjs';
+import { parseWebsiteSettings } from './website-model.mjs';
+import { parseWebsiteSection, parseWebsiteEntryMetadata } from './website-schema.mjs';
+import { validatePublishedDocumentEntry } from './publication-document.mjs';
+
+import {nativeChromeDescriptor} from './native-chrome-model.mjs';
+const fail = () => { throw Error('Native website payload is unavailable.'); };
+const plain = value => value && typeof value === 'object' && !Array.isArray(value);
+const uuid = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const scopePattern = new RegExp(`^${uuid}:${uuid}$`, 'i');
+const path = value => { const result = normalizePublicationPath(value); if (result !== value || isExcludedPublicationPath(result)) fail(); return result; };
+const flatten = blocks => blocks.flatMap(block => [block, ...(block.type === 'section' ? flatten(block.data.blocks) : block.type === 'columns' ? flatten(block.data.columns.flat()) : [])]);
+function entry(value) {
+  if (!plain(value) || !['page','post'].includes(value.kind) || typeof value.slug !== 'string' || !/^[a-z0-9]+(?:[-/][a-z0-9]+)*$/.test(value.slug) || value.slug.length > 160 || typeof value.locale !== 'string' || value.locale.length > 35) fail();
+  try { if (Intl.getCanonicalLocales(value.locale)[0] !== value.locale) fail(); } catch { fail(); }
+  const projected = publicPublishedEntry(value);
+  validatePublishedDocumentEntry(projected, {kind:value.kind,slug:value.slug,locale:value.locale});
+  return { ...projected, ...parseWebsiteEntryMetadata(value), path: path(value.path) };
+}
+function currentInventory(value, published) {
+  if (!plain(value) || !plain(value.identity) || !plain(value.baseline) || !Array.isArray(value.baseline.blocks) || !plain(value.bindings)) fail();
+  const identity = { kind: published.kind, slug: published.slug, locale: published.locale };
+  if (Object.keys(identity).some(key => value.identity[key] !== identity[key]) || value.baseline.blocks.length > 400 || Object.keys(value.bindings).length > 400) fail();
+  const current = new Map(flatten(published.document.blocks).map(block => [block.id, block.type]));
+  const original = new Map(flatten(value.baseline.blocks).map(block => [block.id, block.type]));
+  const bindings = {}, ids = new Set();
+  for (const [name, slot] of Object.entries(value.bindings)) {
+    if (!/^[A-Za-z0-9_.:-]{1,200}$/.test(name) || !plain(slot) || !Array.isArray(slot.variants) || slot.variants.length > 400) fail();
+    const variants = [];
+    for (const row of slot.variants) {
+      if (!plain(row) || typeof row.id !== 'string') fail();
+      if (!current.has(row.id) || original.get(row.id) !== current.get(row.id)) continue;
+      ids.add(row.id); variants.push({ id: row.id, values: [] });
+    }
+    if (variants.length) bindings[name] = { variants };
+  }
+  return { identity, baseline: { schemaVersion: 1, title: '', excerpt: '', blocks: [...ids].map(id => ({ id, version: 1, type: current.get(id), text: '' })) }, bindings, ...(value.nativeChrome ? {nativeChrome:nativeChromeDescriptor(value.nativeChrome)} : {}) };
+}
+export function nativeWebsitePayload(value) {
+  if (!plain(value) || !scopePattern.test(value.scope)) fail();
+  const pathname = path(value.pathname), raw = value.initialResult;
+  let result;
+  if (raw?.state === 'published') {
+    const document = entry(raw.entry);
+    if (document.path !== pathname || raw.path !== undefined && raw.path !== pathname || raw.revision !== undefined && raw.revision !== publicationRevision(document)) fail();
+    result = { state: 'published', status: 200, path: pathname, entry: document, revision: publicationRevision(document), related: [] };
+  } else if (raw?.state === 'archive') {
+    if (raw.path !== pathname || !['category', 'tag'].includes(raw.kind) || typeof raw.title !== 'string' || raw.title.length > 200 || typeof raw.description !== 'string' || raw.description.length > 1000 || !Array.isArray(raw.entries) || raw.entries.length > 1000) fail();
+    result = { state: 'archive', status: 200, path: pathname, kind: raw.kind, title: raw.title, description: raw.description, entries: raw.entries.map(entry) };
+  } else fail();
+  const settings = parseWebsiteSettings(value.initialSettings);
+  for (const [name, section] of Object.entries(settings.sections)) {
+    if (section.state === 'ready' && settings.state === 'ready') section.data = parseWebsiteSection(name, { section: name, version: section.version, data: section.data }).data;
+  }
+  const payload = { pathname, scope: value.scope, initialResult: result, initialSettings: settings };
+  if (value.inventory !== undefined) {
+    if (result.state !== 'published') fail();
+    payload.inventory = currentInventory(value.inventory, result.entry);
+  }
+  const encoded = JSON.stringify(payload);
+  if (encoded.length > 8 * 1024 * 1024 || /cms_server\.|sk-[A-Za-z0-9_-]{12,}|AIza[A-Za-z0-9_-]{20,}/i.test(encoded)) fail();
+  return payload;
+}
+export function serializeNativeWebsite(value) {
+  return JSON.stringify(nativeWebsitePayload(value)).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+}

package/dist/native-website-server.d.mts

@@ -0,0 +1 @@
+export function renderNativeWebsite(value: unknown, childrenHtml?: string): string;