@universalcms/connect 0.0.0-stage → 0.13.0

package/dist/astro-setup.mjs

@@ -0,0 +1,215 @@
+/** Bounded Astro integration planning. Public source only; never loads project code. */
+import { lstat, opendir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import ts from './vendor/typescript.cjs';
+import { projectRoot, readProjectFile, SetupError } from './core.mjs';
+import { contentDigest, readContentRegistry, readFrozenContent, CONTENT_BINDINGS_FILE } from './content-registry.mjs';
+import { WEBSITE_SECTIONS } from './website-http.mjs';
+import { inspectAstroSource } from './astro-source.mjs';
+import { isExcludedPublicationPath } from './publication.mjs';
+
+export const ASTRO_CONFIG = '.universalcms/astro.config.mjs';
+export const ASTRO_MANIFEST = '.universalcms/astro.integration.json';
+const MIDDLEWARE = '.universalcms/astro.middleware.mjs', PAGE = '.universalcms/astro-page.astro', SERVE = '.universalcms/astro.serve.mjs';
+const SETTINGS = '.universalcms/website.integration.json';
+const json = value => `${JSON.stringify(value, null, 2)}\n`;
+const fail = message => { throw new SetupError(message); };
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const nameOf = node => ts.isIdentifier(node) || ts.isStringLiteral(node) ? node.text : null;
+export function supportedAstroVersion(value) {
+  const m = typeof value === 'string' && /^(?:\^|~)?(\d+)\.(\d+)\.(\d+)$/.exec(value);
+  return !!m && +m[1] === 7 && (+m[2] > 2 || +m[2] === 2 && +m[3] >= 1);
+}
+const version = (value, major, minor = 0) => typeof value === 'string' && new RegExp(`^(?:\\^|~)?${major}\\.(\\d+)\\.\\d+$`).test(value) && +value.replace(/^[~^]/, '').split('.')[1] >= minor;
+async function ordinary(root, name) { const content = await readProjectFile(root, name); if (content !== null && (await lstat(path.join(root, name))).nlink !== 1) fail('Astro integration files must be ordinary files without hard links.'); return content; }
+async function absent(root, name) { try { await lstat(path.join(root, name)); } catch (error) { if (error.code === 'ENOENT') return; throw error; } fail('An Astro middleware, endpoint or public asset conflicts with the managed integration. Preserve it and request a reviewed adapter.'); }
+
+// The standalone Node adapter serves public assets before Astro middleware.
+// Static pages or private/connector paths must never shadow publication checks.
+// Inspect metadata only: no public asset or potential private file is opened.
+export async function inspectAstroPublicAssets(root) {
+  const publicRoot = path.join(root,'public');
+  try { await lstat(publicRoot); } catch(error) { if(error.code==='ENOENT')return; throw error; }
+  const extensions = new Set(['.avif','.bmp','.css','.csv','.eot','.gif','.ico','.jpeg','.jpg','.js','.json','.map','.mjs','.mp3','.mp4','.ogg','.otf','.pdf','.png','.svg','.ttf','.txt','.wasm','.webm','.webmanifest','.webp','.woff','.woff2','.xml']);
+  const reserved = new Set(['robots.txt','sitemap.xml','.well-known/universalcms-publication-client.js']);
+  let files=0,directories=0; const started=Date.now();
+  const refused = () => fail('Astro public assets need review: static pages, private paths, reserved endpoints, linked files or excessive inventories can bypass publication middleware. Existing files were preserved.');
+  const walk = async (directory,relative='',depth=0) => {
+    if(++directories>256||depth>12||Date.now()-started>8000)refused();
+    const info=await lstat(directory);
+    if(!info.isDirectory()||info.isSymbolicLink()||await realpath(directory)!==directory)refused();
+    for await(const item of await opendir(directory)) {
+      if(++files>5000||Date.now()-started>8000)refused();
+      const filename=path.join(directory,item.name), name=relative+item.name, lower=item.name.toLowerCase();
+      if(item.isSymbolicLink()||/[\\%?#:\u0000-\u001f\u007f]/.test(item.name)||lower.startsWith('.')&&lower!=='.well-known'||reserved.has(name.toLowerCase()))refused();
+      const stem=item.isDirectory()?lower:lower.slice(0,lower.length-path.extname(lower).length);
+      if(!['assets','static','.well-known'].includes(stem)&&/^[a-z0-9_.@-]+$/.test(stem)&&isExcludedPublicationPath('/'+stem)||['api','_astro'].includes(lower))refused();
+      if(item.isDirectory()) { await walk(filename,name+'/',depth+1); continue; }
+      const stat=await lstat(filename);
+      if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1||await realpath(filename)!==filename||!extensions.has(path.extname(lower)))refused();
+    }
+  };
+  await walk(publicRoot);
+}
+
+function reviewConfig(source, filename) {
+  if (source === null) return { react: false, node: false };
+  const file = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  if (file.parseDiagnostics.length) fail('The Astro configuration cannot be inspected safely.');
+  const imports = new Map(); let config;
+  for (const statement of file.statements) {
+    if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+      const specifier = statement.moduleSpecifier.text, clause = statement.importClause;
+      if (statement.attributes || !clause || clause.isTypeOnly) fail('Custom Astro configuration imports need review.');
+      if (specifier === 'astro/config' && !clause.name && clause.namedBindings && ts.isNamedImports(clause.namedBindings) && clause.namedBindings.elements.length === 1 && (clause.namedBindings.elements[0].propertyName?.text ?? clause.namedBindings.elements[0].name.text) === 'defineConfig') imports.set(clause.namedBindings.elements[0].name.text, 'defineConfig');
+      else if (['@astrojs/node', '@astrojs/react'].includes(specifier) && clause.name && !clause.namedBindings) imports.set(clause.name.text, specifier);
+      else fail('Only the ordinary Astro configuration and official Node/React integration imports are supported automatically.');
+    } else if (ts.isExportAssignment(statement) && !statement.isExportEquals && !config) {
+      const expression = statement.expression;
+      config = ts.isCallExpression(expression) && ts.isIdentifier(expression.expression) && imports.get(expression.expression.text) === 'defineConfig' && expression.arguments.length === 1 ? expression.arguments[0] : expression;
+    } else if (!ts.isEmptyStatement(statement)) fail('Dynamic Astro configuration requires a reviewed integration. Existing configuration was preserved.');
+  }
+  if (!config || !ts.isObjectLiteralExpression(config)) fail('Use an inspectable literal Astro configuration before automatic setup.');
+  const seen = new Set(), result = { react: false, node: false };
+  const factory = (node, specifier) => ts.isCallExpression(node) && ts.isIdentifier(node.expression) && imports.get(node.expression.text) === specifier;
+  for (const member of config.properties) {
+    const name = ts.isPropertyAssignment(member) ? nameOf(member.name) : null;
+    if (!name || seen.has(name)) fail('Spread, computed or duplicate Astro configuration needs manual review.');
+    seen.add(name); const value = member.initializer;
+    if (name === 'integrations') {
+      if (!ts.isArrayLiteralExpression(value) || value.elements.length > 1 || value.elements.some(item => !factory(item, '@astrojs/react') || item.arguments.length !== 0)) fail('Custom Astro integrations require explicit routing and build review.');
+      result.react = value.elements.length === 1;
+    } else if (name === 'adapter') {
+      if (!factory(value, '@astrojs/node') || value.arguments.length !== 1 || !ts.isObjectLiteralExpression(value.arguments[0]) || value.arguments[0].properties.length !== 1) fail('An existing Astro adapter requires explicit deployment review.');
+      const mode = value.arguments[0].properties[0];
+      if (!ts.isPropertyAssignment(mode) || nameOf(mode.name) !== 'mode' || !ts.isStringLiteral(mode.initializer) || mode.initializer.text !== 'standalone') fail('Automatic Astro setup requires the official Node standalone adapter.');
+      result.node = true;
+    } else if (name === 'output') { if (!ts.isStringLiteral(value) || !['static', 'server'].includes(value.text)) fail('The Astro output needs a reviewed Node server integration.'); }
+    else if (name === 'site') { if (!ts.isStringLiteral(value) || !/^https?:\/\/[^\s]+$/.test(value.text)) fail('The Astro site setting must be a public literal URL.'); }
+    else if (name === 'trailingSlash') { if (!ts.isStringLiteral(value) || !['ignore', 'never'].includes(value.text)) fail('Trailing-slash Astro routing needs explicit review.'); }
+    else if (name === 'compressHTML') { if (![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(value.kind)) fail('Astro configuration values must be literal.'); }
+    else if (name === 'scopedStyleStrategy') { if (!ts.isStringLiteral(value) || !['where', 'class', 'attribute'].includes(value.text)) fail('The Astro style strategy needs review.'); }
+    else fail('Custom Astro roots, routing, environment, Vite hooks or build configuration require a reviewed adapter.');
+  }
+  return result;
+}
+
+function scriptsFor(manifest) {
+  if (!plain(manifest.scripts)) fail('Astro setup requires ordinary astro dev and astro build scripts.');
+  const scripts = { ...manifest.scripts }, suffix = ` --config ${ASTRO_CONFIG}`;
+  for (const operation of ['dev', 'build', 'preview']) {
+    if (operation === 'preview' && scripts.preview === undefined) continue;
+    let command = scripts[operation];
+    if (typeof command !== 'string') fail('Astro setup requires ordinary astro dev and astro build scripts.');
+    if (command.endsWith(suffix)) command = command.slice(0, -suffix.length);
+    const expected = `astro ${operation}`;
+    if (!command.startsWith(expected) || !(operation === 'build' ? /^$/ : /^(?: --(?:host(?: (?:localhost|127\.0\.0\.1|0\.0\.0\.0))?|port [0-9]{1,5}|open))*$/).test(command.slice(expected.length))) fail('Custom Astro scripts, roots, ports or config flags need a reviewed deployment integration.');
+    for (const [, port] of command.matchAll(/--port (\d+)/g)) if (+port < 1 || +port > 65535) fail('Astro startup needs a valid port.');
+    scripts[operation] = command + suffix;
+  }
+  const start = `node ${SERVE}`;
+  if (scripts.start !== undefined && scripts.start !== start && scripts.start !== 'astro dev') fail('An existing Astro production command needs explicit review; it was preserved.');
+  scripts.start = start;
+  // Revalidate source/layout/public ownership before the supported commands.
+  // A custom hook could create static shadow pages after our check; preserve it
+  // and require explicit review instead of guessing its execution order.
+  const validation = 'universalcms-connect sync-source';
+  for(const operation of ['dev','build','start',...(scripts.preview===undefined?[]:['preview'])]) {
+    const hook='pre'+operation;
+    if(scripts[hook]!==undefined&&scripts[hook]!==validation)fail('Existing Astro lifecycle hooks require review before automatic setup. Preserve the hook and integrate source validation explicitly.');
+    scripts[hook]=validation;
+  }
+  return { ...manifest, scripts };
+}
+
+/** Returns only public observations, with no package imports or environment reads. */
+export async function inspectAstroProject(directory, suppliedManifest) {
+  const root = await projectRoot(directory), packageText = await ordinary(root, 'package.json');
+  let manifest; try { manifest = suppliedManifest ?? JSON.parse(packageText); } catch { fail('Astro setup needs a valid package manifest.'); }
+  const deps = { ...manifest.devDependencies, ...manifest.dependencies };
+  if (manifest.workspaces || manifest.type !== 'module' || !supportedAstroVersion(deps.astro)) fail('Automatic setup supports one ESM Astro 7.2.1–7.x website. Older or different Astro versions need a deliberate upgrade or reviewed adapter.');
+  if (!version(deps['@astrojs/node'], 11) || !version(deps['@astrojs/react'], 7) || !version(deps.react, 19, 2) || !version(deps['react-dom'], 19, 2)) fail('Install the supported official Astro Node 11 and React 7 integrations, plus React and React DOM 19.2+, before setup.');
+  const currentNode = process.versions.node.split('.').map(Number);
+  if (currentNode[0] < 22 || currentNode[0] === 22 && currentNode[1] < 22) fail('Astro 7 requires Node 22.22 or newer. Upgrade the Node runtime deliberately before setup.');
+  let configFile = null, configText = null;
+  for (const extension of ['mjs', 'js', 'ts', 'cjs', 'mts', 'cts']) {
+    const name = `astro.config.${extension}`, text = await ordinary(root, name);
+    if (text !== null) { if (configFile || !['mjs', 'js', 'ts'].includes(extension)) fail('Multiple or CommonJS Astro configurations need manual review.'); configFile = name; configText = text; }
+  }
+  const config = reviewConfig(configText, configFile ?? 'astro.config.mjs');
+  for (const extension of ['js', 'ts', 'mjs', 'mts']) await absent(root, `src/middleware.${extension}`);
+  await absent(root, 'src/middleware');
+  await inspectAstroPublicAssets(root);
+  return { root, manifest, packageText, configFile, configText, ...config, nextPackage: scriptsFor(manifest) };
+}
+
+function configTemplate(project, publication) {
+  return `// Generated by @universalcms/connect. The original configuration remains owned by the website.\nimport sourceConfiguration from './source.config.json' with { type: 'json' };\nimport { defineConfig } from 'astro/config';\nimport node from '@astrojs/node';\nimport react from '@astrojs/react';\nimport { fileURLToPath } from 'node:url';\n${project.configFile ? `import existing from '../${project.configFile}';` : 'const existing = {};'}\nconst sourceRoot = new URL('../', import.meta.url);\nconst website = new URL(sourceConfiguration.websiteOrigin);\nconst integration = { name: 'universalcms-reviewed-astro', hooks: {\n  'astro:config:setup': ({ addMiddleware, injectRoute }) => {\n    addMiddleware({ entrypoint: fileURLToPath(new URL('./astro.middleware.mjs', import.meta.url)), order: 'pre' });\n${publication ? "    injectRoute({ pattern: '/[...cmsPath]', entrypoint: fileURLToPath(new URL('./astro-page.astro', import.meta.url)), prerender: false });\n" : ''}  },\n  'astro:route:setup': ({ route }) => { route.prerender = false; },\n} };\nexport default defineConfig({ ...existing, root: fileURLToPath(sourceRoot), output: 'server', security: { allowedDomains: [{ hostname: website.hostname, protocol: website.protocol.slice(0, -1), port: website.port }] }, server: { port: Number(new URL(sourceConfiguration.websiteOrigin).port || (sourceConfiguration.websiteOrigin.startsWith('https:') ? 443 : 80)) }, vite: { server: { strictPort: true }, preview: { strictPort: true } }, adapter: ${project.node ? 'existing.adapter' : "node({ mode: 'standalone' })"}, integrations: [...(existing.integrations ?? []), ${project.react ? '' : 'react(), '}integration] });\n`;
+}
+function middlewareTemplate(publication) {
+  return `// Generated by @universalcms/connect. Server-only imports; never expose delivery credentials.\nimport { fileURLToPath } from 'node:url';\nimport { createAstroRuntime } from '@universalcms/connect/astro-runtime';\nimport sourceConfiguration from './source.config.json' with { type: 'json' };\nimport snapshot from './source.generated.json' with { type: 'json' };\n${publication ? "import configuration from './publication.config.json' with { type: 'json' };\nimport contentBindings from './content.bindings.json' with { type: 'json' };\n" : ''}const runtime = createAstroRuntime({ ${publication ? 'configuration, contentBindings, ' : ''}sourceConfiguration, snapshot, sourceRoot: process.cwd() });\nexport const onRequest = runtime.onRequest;\n`;
+}
+function catchallTemplate() { return `---\nimport { AstroWebsite } from '@universalcms/connect/astro-website';\nimport '@universalcms/connect/publication.css';\nimport '@universalcms/connect/website.css';\nexport const prerender = false;\nconst cms = Astro.locals.universalcms;\n// Excluded native/private paths can reach this fallback without CMS locals.\nif (!cms) return new Response(null, { status: 404, headers: { 'Cache-Control': 'private, no-store', 'X-Content-Type-Options': 'nosniff' } });\n---\n<html><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /></head><body><AstroWebsite pathname={cms.pathname} scope={cms.scope} initialResult={cms.result} initialSettings={cms.settings} client:load /></body></html>\n`; }
+function serveTemplate() { return `// Generated by @universalcms/connect. Run from the website root after astro build.\nimport { fileURLToPath } from 'node:url';\nprocess.chdir(fileURLToPath(new URL('../', import.meta.url)));\nimport configuration from './source.config.json' with { type: 'json' };\nconst port = Number(process.env.PORT ?? (new URL(configuration.websiteOrigin).port || (configuration.websiteOrigin.startsWith('https:') ? 443 : 80)));\nif (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Configure a valid website PORT.');\nprocess.env.PORT = String(port);\nprocess.env.HOST ??= '0.0.0.0';\nawait import('../dist/server/entry.mjs');\n`; }
+function generated(project, publication) { return [[ASTRO_CONFIG, configTemplate(project, publication)], [MIDDLEWARE, middlewareTemplate(publication)], [SERVE, serveTemplate()], ...(publication ? [[PAGE, catchallTemplate()]] : [])]; }
+
+async function previousManifest(root, project) {
+  const text = await ordinary(root, ASTRO_MANIFEST);
+  if (text === null) return null;
+  let value; try { value = JSON.parse(text); } catch { fail('The Astro integration manifest needs review.'); }
+  if (!plain(value) || Object.keys(value).sort().join() !== 'configFile,configHash,files,publication,version' || value.version !== 1 || typeof value.publication !== 'boolean' || value.configFile !== project.configFile || value.configHash !== (project.configText === null ? null : contentDigest(project.configText)) || !Array.isArray(value.files)) fail('The original Astro configuration changed after setup. Preserve it and review the integration.');
+  const expected = generated(project, value.publication).map(([name, content]) => ({ path: name, sha256: contentDigest(content) }));
+  if (json(value.files) !== json(expected)) fail('The Astro integration ownership manifest was changed.');
+  for (const row of value.files) if (contentDigest(await ordinary(root, row.path) ?? '') !== row.sha256) fail('A generated Astro runtime adapter was changed or is missing. Preserve custom edits and review the integration.');
+  return { text, value };
+}
+
+/** Source owns generated runtime files and scripts; publication/content never rewrite them. */
+export async function planAstroIntegration(root, { publication = false, sourceConfiguration } = {}) {
+  const project = await inspectAstroProject(root), prior = await previousManifest(root, project);
+  if (prior?.value.publication && !publication) publication = true;
+  if (!sourceConfiguration) { const text = await ordinary(root, '.universalcms/source.config.json'); if (text !== null) sourceConfiguration = JSON.parse(text); }
+  if (sourceConfiguration) {
+    const expectedPort = Number(new URL(sourceConfiguration.websiteOrigin).port || (sourceConfiguration.websiteOrigin.startsWith('https:') ? 443 : 80));
+    for (const name of ['dev','preview']) for (const [, port] of (project.manifest.scripts?.[name] ?? '').matchAll(/--port (\d+)/g)) if (+port !== expectedPort) fail('The Astro startup port differs from the saved website origin. Review the public origin or command before setup.');
+  }
+  const desired = generated(project, publication), files = [];
+  for (const [name, content] of desired) {
+    const current = await ordinary(root, name), previous = prior && generated(project, prior.value.publication).find(([file]) => file === name)?.[1];
+    if (current !== null && current !== content && current !== previous || current !== null && !prior) fail('An existing Astro adapter needs explicit review; setup preserved it.');
+    files.push({ path: name, content, state: current === content ? 'unchanged' : current === null ? 'create' : 'update', ...(current !== null && current !== content ? { previous: current } : {}) });
+  }
+  const content = json({ version: 1, publication, configFile: project.configFile, configHash: project.configText === null ? null : contentDigest(project.configText), files: desired.map(([name, body]) => ({ path: name, sha256: contentDigest(body) })) });
+  files.push({ path: ASTRO_MANIFEST, content, state: prior?.text === content ? 'unchanged' : prior ? 'update' : 'create', ...(prior && prior.text !== content ? { previous: prior.text } : {}) });
+  const packageContent = JSON.stringify(project.nextPackage) === JSON.stringify(project.manifest) ? project.packageText : json(project.nextPackage);
+  files.push({ path: 'package.json', content: packageContent, state: packageContent === project.packageText ? 'unchanged' : 'update', ...(packageContent !== project.packageText ? { previous: project.packageText } : {}) });
+  if (project.configFile) files.push({ path: project.configFile, content: project.configText, state: 'unchanged' });
+  return { root, framework: 'astro', files };
+}
+
+export async function validateInstalledAstro(root, config) {
+  const plan = await planAstroIntegration(root, { publication: true });
+  if (plan.files.some(file => file.state !== 'unchanged')) fail('The Astro runtime, scripts or middleware are incomplete. Finish the reviewed setup before saving a server key.');
+  const inspection = await inspectAstroSource(root, { locale: config.routes[0]?.locale ?? 'en', websiteOrigin: config.websiteOrigin });
+  if (inspection.routes.length !== config.routes.length || config.routes.some(route => !inspection.routes.some(row => ['path','kind','slug','locale'].every(name => row[name] === route[name])))) fail('Astro routes changed after publication setup. Review route ownership before continuing.');
+  if (await ordinary(root, '.universalcms/source.generated.json') !== json(inspection.snapshot)) fail('The Astro source snapshot changed or is missing. Restore the reviewed frozen inventory.');
+  const registry = await readContentRegistry(root);
+  if (!registry || registry.routes.some(row => !row.sourceFile.endsWith('.astro')) || registry.routes.length !== config.routes.length) fail('Astro published-content bindings are incomplete.');
+  for (const row of registry.routes) {
+    const frozen = await readFrozenContent(root, row);
+    for (const [key, content] of Object.entries(frozen.texts)) plan.files.push({ path: row[`${key}File`], content, state: 'unchanged' });
+  }
+  plan.files.push({ path: CONTENT_BINDINGS_FILE, content: await ordinary(root, CONTENT_BINDINGS_FILE), state: 'unchanged' });
+  for (const row of inspection.sourceFiles) if (!plan.files.some(file => file.path === row.path)) plan.files.push({ path: row.path, content: await ordinary(root, row.path), state: 'unchanged' });
+  return { ...plan, config };
+}
+
+export async function planAstroSettings(root, { config, source }) {
+  const plan = await validateInstalledAstro(root, config);
+  const content = json({ version: 1, framework: 'astro', siteId: config.siteId, environmentId: config.environmentId, apiOrigin: config.apiOrigin, websiteOrigin: config.websiteOrigin, adminOrigin: source.adminOrigin, sections: WEBSITE_SECTIONS, files: plan.files.filter(file => file.path !== 'package.json').map(file => ({ path: file.path, sha256: contentDigest(file.content) })) });
+  const previous = await ordinary(root, SETTINGS);
+  if (previous !== null && previous !== content) fail('The Astro website settings ownership or scope changed. Review it before continuing.');
+  plan.files.push({ path: SETTINGS, content, state: previous === null ? 'create' : 'unchanged' });
+  for (const name of ['.universalcms/publication.config.json', '.universalcms/source.config.json', '.universalcms/source.generated.json']) plan.files.push({ path: name, content: await ordinary(root, name), state: 'unchanged' });
+  return { ...plan, sections: [...WEBSITE_SECTIONS] };
+}