@bleedingdev/modern-js-create 3.2.0-ultramodern.120 → 3.2.0-ultramodern.121

package/templates/workspace-scripts/generate-public-surface-assets.mjs

@@ -0,0 +1,529 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const workspaceRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+);
+const contractPath = path.join(
+  workspaceRoot,
+  '.modernjs/ultramodern-generated-contract.json',
+);
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    appId: undefined,
+    target: 'dist',
+    requirePublicOrigin: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--app') {
+      parsed.appId = argv[index + 1];
+      index += 1;
+    } else if (arg === '--target') {
+      parsed.target = argv[index + 1];
+      index += 1;
+    } else if (arg === '--require-public-origin') {
+      parsed.requirePublicOrigin = true;
+    } else if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!parsed.appId && !parsed.help) {
+    throw new Error('Missing required --app argument');
+  }
+  if (!['dist', 'cloudflare'].includes(parsed.target)) {
+    throw new Error(`Unsupported public surface target: ${parsed.target}`);
+  }
+
+  return parsed;
+}
+
+function printHelp() {
+  process.stdout.write(`Usage:
+  node scripts/generate-public-surface-assets.mjs --app shell-super-app [--target dist|cloudflare] [--require-public-origin]
+
+Set each app's production URL using the contract env key, for example:
+  ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://example.com
+
+Dynamic public routes can opt into sitemap expansion by adding a route-owned
+route.sitemap.mjs provider beside route metadata, or by adding an
+explicit provider to routes.publicSurface.contentSources. Providers should export
+an entries array, entries() function, or default entries/loader returning
+UltramodernPublicSitemapEntry[].
+`);
+}
+
+function normalizeOrigin(value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return undefined;
+  }
+  const url = new URL(value);
+  return url.origin;
+}
+
+function resolveOrigin(app, requirePublicOrigin) {
+  const cloudflare = app.deploy?.cloudflare ?? {};
+  const publicUrlEnv = cloudflare.publicUrlEnv;
+  const fromAppEnv =
+    typeof publicUrlEnv === 'string' ? normalizeOrigin(process.env[publicUrlEnv]) : undefined;
+  const fromGlobalEnv = normalizeOrigin(process.env.MODERN_PUBLIC_SITE_URL);
+  const workersDevSubdomain = process.env.ULTRAMODERN_CLOUDFLARE_WORKERS_DEV_SUBDOMAIN;
+  const fromWorkersDev =
+    typeof workersDevSubdomain === 'string' && workersDevSubdomain.trim() !== ''
+      ? normalizeOrigin(`https://${cloudflare.workerName}.${workersDevSubdomain}.workers.dev`)
+      : undefined;
+
+  // SEO output (sitemap <loc>, robots Sitemap:) uses the site-wide origin
+  // first; the per-app deployment URL is only a fallback.
+  const configuredOrigin = fromGlobalEnv ?? fromAppEnv ?? fromWorkersDev;
+  if (configuredOrigin) {
+    return configuredOrigin;
+  }
+  if (requirePublicOrigin) {
+    throw new Error(
+      `${app.id} has public routes but no production public URL. Set ${publicUrlEnv ?? 'ULTRAMODERN_PUBLIC_URL_<APP>'} or MODERN_PUBLIC_SITE_URL.`,
+    );
+  }
+  return undefined;
+}
+
+function ensureOutputDir(app, target) {
+  const relativeDir =
+    target === 'cloudflare'
+      ? app.routes?.publicSurface?.cloudflareOutputRoot
+      : app.routes?.publicSurface?.outputRoot;
+  if (typeof relativeDir !== 'string') {
+    throw new Error(`${app.id} public surface contract is missing outputRoot for ${target}`);
+  }
+  const outputDir = path.resolve(workspaceRoot, app.path, relativeDir);
+  const appRoot = path.resolve(workspaceRoot, app.path);
+  if (!outputDir.startsWith(appRoot + path.sep)) {
+    throw new Error(`${app.id} public surface output escaped the app directory`);
+  }
+  fs.mkdirSync(outputDir, { recursive: true });
+  return outputDir;
+}
+
+function resolveAppRelativePath(app, relativePath) {
+  if (
+    typeof relativePath !== 'string' ||
+    relativePath.trim() === '' ||
+    path.isAbsolute(relativePath) ||
+    relativePath.split(/[\\/]+/).includes('..')
+  ) {
+    throw new Error(app.id + ' public content source has an unsafe module path');
+  }
+  const appRoot = path.resolve(workspaceRoot, app.path);
+  const resolved = path.resolve(appRoot, relativePath);
+  if (resolved !== appRoot && !resolved.startsWith(appRoot + path.sep)) {
+    throw new Error(app.id + ' public content source escaped the app directory');
+  }
+  return resolved;
+}
+
+function normalizePublicPath(pathname) {
+  if (typeof pathname !== 'string') {
+    throw new Error('Public route path must be a string');
+  }
+  const normalised = pathname
+    .trim()
+    .replaceAll(/\/+/gu, '/')
+    .replace(/\/+$/u, '');
+  return normalised.length > 0 && normalised.startsWith('/')
+    ? normalised
+    : '/' + normalised;
+}
+
+function createLocalisedPublicPath(pathname, language) {
+  const publicPath = normalizePublicPath(pathname);
+  return publicPath === '/' ? '/' + language : '/' + language + publicPath;
+}
+
+function splitPublicPathSegments(pathname) {
+  return normalizePublicPath(pathname).split('/').filter(Boolean);
+}
+
+function routePathParamName(segment) {
+  if (segment.startsWith(':')) {
+    return segment.slice(1).replace(/[?*+]$/u, '');
+  }
+  if (segment.startsWith('[') && segment.endsWith(']')) {
+    return segment.slice(1, -1).replace(/^\.\.\./u, '').replace(/\$$/u, '');
+  }
+  return undefined;
+}
+
+function routeSegmentToDirectory(segment) {
+  const paramName = routePathParamName(segment);
+  if (paramName && segment.startsWith(':')) {
+    return segment.endsWith('?') ? '[' + paramName + '$]' : '[' + paramName + ']';
+  }
+  return segment;
+}
+
+function assertParamValue(routeId, language, paramName, value) {
+  if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+    throw new Error(routeId + ' ' + language + ' sitemap param ' + paramName + ' must be a string, number, or boolean');
+  }
+  const text = String(value).trim();
+  if (text === '' || text.includes('/')) {
+    throw new Error(routeId + ' ' + language + ' sitemap param ' + paramName + ' must be a non-empty path segment');
+  }
+  return encodeURIComponent(text);
+}
+
+function expandPublicPathPattern(routeId, language, pattern, params) {
+  const segments = splitPublicPathSegments(pattern);
+  if (segments.length === 0) {
+    return '/';
+  }
+  const expanded = segments.map(segment => {
+    const paramName = routePathParamName(segment);
+    if (!paramName) {
+      if (segment.includes('*')) {
+        throw new Error(routeId + ' ' + language + ' sitemap expansion does not support wildcard path segment ' + segment);
+      }
+      return segment;
+    }
+    if (!Object.prototype.hasOwnProperty.call(params, paramName)) {
+      throw new Error(routeId + ' ' + language + ' sitemap entry is missing param ' + paramName);
+    }
+    return assertParamValue(routeId, language, paramName, params[paramName]);
+  });
+  return '/' + expanded.join('/');
+}
+
+function assertPlainObject(value, label) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(label + ' must be an object');
+  }
+  return value;
+}
+
+function normalizeSitemapFields(routeId, entry) {
+  const normalized = {};
+  if (entry.lastModified !== undefined) {
+    const lastModified = String(entry.lastModified).trim();
+    if (lastModified === '' || Number.isNaN(Date.parse(lastModified))) {
+      throw new Error(routeId + ' sitemap entry has invalid lastModified');
+    }
+    normalized.lastModified = lastModified;
+  }
+  if (entry.changeFrequency !== undefined) {
+    const allowed = new Set(['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never']);
+    if (!allowed.has(entry.changeFrequency)) {
+      throw new Error(routeId + ' sitemap entry has invalid changeFrequency');
+    }
+    normalized.changeFrequency = entry.changeFrequency;
+  }
+  if (entry.priority !== undefined) {
+    if (typeof entry.priority !== 'number' || entry.priority < 0 || entry.priority > 1) {
+      throw new Error(routeId + ' sitemap entry priority must be a number between 0 and 1');
+    }
+    normalized.priority = entry.priority;
+  }
+  return normalized;
+}
+
+function routePathToProviderDirectory(routePath) {
+  const segments = splitPublicPathSegments(routePath);
+  if (segments.length === 0) {
+    return 'src/routes/[lang]';
+  }
+  return path.posix.join(
+    'src/routes/[lang]',
+    ...segments.map(routeSegmentToDirectory),
+  );
+}
+
+function createDiscoveredContentSources(app, publicSurface) {
+  const explicitRouteIds = new Set(
+    (publicSurface.contentSources ?? []).map(source => source.routeId),
+  );
+  const discovered = [];
+  for (const route of publicSurface.publicRoutes ?? []) {
+    if (
+      explicitRouteIds.has(route.id) ||
+      !Object.values(route.localisedPaths ?? {}).some(routePath =>
+        /(?:^|\/):[^/]+|\[[^\]]+\]/u.test(routePath),
+      )
+    ) {
+      continue;
+    }
+    const providerModule = path.posix.join(
+      routePathToProviderDirectory(route.canonicalPath),
+      'route.sitemap.mjs',
+    );
+    if (fs.existsSync(resolveAppRelativePath(app, providerModule))) {
+      discovered.push({
+        entryExport: 'default-or-entries',
+        module: providerModule,
+        routeId: route.id,
+      });
+    }
+  }
+  return discovered;
+}
+
+function resolveContentSources(app, publicSurface) {
+  return [
+    ...(publicSurface.contentSources ?? []),
+    ...createDiscoveredContentSources(app, publicSurface),
+  ];
+}
+
+async function loadContentSourceEntries(app, contentSource, languages) {
+  if (typeof contentSource?.routeId !== 'string' || contentSource.routeId.trim() === '') {
+    throw new Error(app.id + ' public content source is missing routeId');
+  }
+  const modulePath = resolveAppRelativePath(app, contentSource.module);
+  const moduleExports = await import(pathToFileURL(modulePath).href);
+  const exported = moduleExports.default ?? moduleExports.entries;
+  const rawEntries =
+    typeof exported === 'function'
+      ? await exported({
+          appId: app.id,
+          languages,
+          routeId: contentSource.routeId,
+        })
+      : exported;
+  if (!Array.isArray(rawEntries)) {
+    throw new Error(app.id + ' public content source for ' + contentSource.routeId + ' must export an entries array or loader');
+  }
+  return rawEntries;
+}
+
+async function expandContentSources(app, publicSurface, languages) {
+  const routesById = new Map(
+    (publicSurface.publicRoutes ?? []).map(route => [route.id, route]),
+  );
+  const expanded = [];
+  for (const contentSource of resolveContentSources(app, publicSurface)) {
+    const route = routesById.get(contentSource.routeId);
+    if (!route) {
+      throw new Error(app.id + ' public content source references unknown route ' + contentSource.routeId);
+    }
+    const rawEntries = await loadContentSourceEntries(app, contentSource, languages);
+    for (const rawEntry of rawEntries) {
+      const entry = assertPlainObject(rawEntry, route.id + ' sitemap entry');
+      if (entry.draft === true || entry.indexable === false) {
+        continue;
+      }
+      const baseParams = assertPlainObject(entry.params, route.id + ' sitemap entry params');
+      const localeParams = entry.localeParams === undefined
+        ? {}
+        : assertPlainObject(entry.localeParams, route.id + ' sitemap entry localeParams');
+      const localeUrlPaths = {};
+      for (const language of languages) {
+        const params = {
+          ...baseParams,
+          ...(localeParams[language] ?? {}),
+        };
+        localeUrlPaths[language] = createLocalisedPublicPath(
+          expandPublicPathPattern(route.id, language, route.localisedPaths[language], params),
+          language,
+        );
+      }
+      expanded.push({
+        ...route,
+        ...normalizeSitemapFields(route.id, entry),
+        canonicalUrlPath: localeUrlPaths.en,
+        localeUrlPaths,
+      });
+    }
+  }
+  return expanded;
+}
+
+function mergeRouteEntries(routeEntries, expandedRouteEntries, languages) {
+  const byKey = new Map();
+  const urlPathOwners = new Map();
+  for (const route of [...routeEntries, ...expandedRouteEntries]) {
+    const key = route.id + ':' + route.canonicalUrlPath;
+    if (byKey.has(key)) {
+      throw new Error('Duplicate public sitemap route entry ' + key);
+    }
+    for (const language of languages) {
+      const urlPath = route.localeUrlPaths?.[language];
+      if (typeof urlPath !== 'string') {
+        throw new Error(route.id + ' public route entry is missing ' + language + ' locale URL path');
+      }
+      const existingOwner = urlPathOwners.get(urlPath);
+      if (existingOwner && existingOwner !== route.id) {
+        throw new Error('Duplicate public sitemap URL path ' + urlPath + ' from ' + existingOwner + ' and ' + route.id);
+      }
+      urlPathOwners.set(urlPath, route.id);
+    }
+    byKey.set(key, route);
+  }
+  return Array.from(byKey.values()).sort(
+    (left, right) =>
+      left.canonicalUrlPath.localeCompare(right.canonicalUrlPath) ||
+      left.id.localeCompare(right.id),
+  );
+}
+
+function uniqueSorted(values) {
+  return Array.from(new Set(values)).sort((left, right) =>
+    left.localeCompare(right),
+  );
+}
+
+function createConcreteUrlPaths(routeEntries, languages) {
+  return uniqueSorted(
+    routeEntries.flatMap(route => languages.map(language => route.localeUrlPaths[language])),
+  );
+}
+
+function escapeXmlText(value) {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+function escapeXmlAttribute(value) {
+  return escapeXmlText(value).replaceAll('"', '&quot;');
+}
+
+function renderRobotsTxt(urlPaths, sitemapUrl) {
+  const lines = ['User-agent: *'];
+  if (urlPaths.length === 0) {
+    lines.push('Disallow: /');
+  } else {
+    for (const urlPath of urlPaths) {
+      lines.push(`Allow: ${urlPath}$`);
+    }
+    lines.push('Disallow: /');
+    if (sitemapUrl) {
+      lines.push(`Sitemap: ${sitemapUrl}`);
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function renderSitemapXml(origin, routeEntries, languages) {
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">',
+  ];
+
+  for (const route of routeEntries) {
+    for (const language of languages) {
+      lines.push('  <url>');
+      lines.push(`    <loc>${escapeXmlText(`${origin}${route.localeUrlPaths[language]}`)}</loc>`);
+      for (const alternateLanguage of languages) {
+        lines.push(
+          `    <xhtml:link rel="alternate" hreflang="${alternateLanguage}" href="${escapeXmlAttribute(
+            `${origin}${route.localeUrlPaths[alternateLanguage]}`,
+          )}" />`,
+        );
+      }
+      lines.push(
+        `    <xhtml:link rel="alternate" hreflang="x-default" href="${escapeXmlAttribute(
+          `${origin}${route.localeUrlPaths.en}`,
+        )}" />`,
+      );
+      if (route.lastModified) {
+        lines.push(`    <lastmod>${escapeXmlText(route.lastModified)}</lastmod>`);
+      }
+      if (route.changeFrequency) {
+        lines.push(`    <changefreq>${escapeXmlText(route.changeFrequency)}</changefreq>`);
+      }
+      if (route.priority !== undefined) {
+        lines.push(`    <priority>${route.priority.toFixed(1).replace(/\.0$/u, '')}</priority>`);
+      }
+      lines.push('  </url>');
+    }
+  }
+
+  lines.push('</urlset>');
+  return `${lines.join('\n')}\n`;
+}
+
+function renderWebManifest(app, urlPaths) {
+  const startUrl = urlPaths[0];
+  const manifest = {
+    background_color: '#ffffff',
+    categories: ['business', 'productivity'],
+    display: 'standalone',
+    icons: [],
+    lang: 'en',
+    name: app.marker?.appId ?? app.id,
+    short_name: app.marker?.appId ?? app.id,
+    theme_color: '#133225',
+    ...(startUrl ? { scope: '/', start_url: startUrl } : {}),
+  };
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+function removeIfExists(outputDir, fileName) {
+  fs.rmSync(path.join(outputDir, fileName), { force: true });
+}
+
+function writeText(outputDir, fileName, content) {
+  fs.writeFileSync(path.join(outputDir, fileName), content);
+}
+
+async function generatePublicSurfaceAssets(app, target, requirePublicOrigin) {
+  const publicSurface = app.routes?.publicSurface ?? {};
+  const languages = publicSurface.languages ?? ['en', 'cs'];
+  const outputDir = ensureOutputDir(app, target);
+  const shouldRequirePublicOrigin =
+    requirePublicOrigin ||
+    process.env.ULTRAMODERN_CLOUDFLARE_REQUIRE_PUBLIC_URLS === 'true';
+  const routeEntries = mergeRouteEntries(
+    publicSurface.routeEntries ?? [],
+    await expandContentSources(app, publicSurface, languages),
+    languages,
+  );
+  const urlPaths = createConcreteUrlPaths(routeEntries, languages);
+
+  if (routeEntries.length === 0) {
+    writeText(outputDir, 'robots.txt', renderRobotsTxt([], undefined));
+    removeIfExists(outputDir, 'sitemap.xml');
+    removeIfExists(outputDir, 'site.webmanifest');
+    return;
+  }
+
+  const origin = resolveOrigin(app, shouldRequirePublicOrigin);
+  if (!origin) {
+    writeText(outputDir, 'robots.txt', renderRobotsTxt([], undefined));
+    removeIfExists(outputDir, 'sitemap.xml');
+    removeIfExists(outputDir, 'site.webmanifest');
+    return;
+  }
+
+  writeText(outputDir, 'sitemap.xml', renderSitemapXml(origin, routeEntries, languages));
+  writeText(outputDir, 'site.webmanifest', renderWebManifest(app, urlPaths));
+  writeText(outputDir, 'robots.txt', renderRobotsTxt(urlPaths, `${origin}/sitemap.xml`));
+}
+
+try {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+  const contract = readJson(contractPath);
+  const app = contract.apps?.find(candidate => candidate.id === args.appId);
+  if (!app) {
+    throw new Error(`Unknown app in generated contract: ${args.appId}`);
+  }
+  await generatePublicSurfaceAssets(app, args.target, args.requirePublicOrigin);
+} catch (error) {
+  process.stderr.write(`[public-surface] ${error.message}\n`);
+  process.exitCode = 1;
+}

package/templates/workspace-scripts/proof-cloudflare-version.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateApp } from './ultramodern-cloudflare-proof.mjs';
+
+const workspaceRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+);
+const contractPath = path.join(
+  workspaceRoot,
+  '.modernjs/ultramodern-generated-contract.json',
+);
+const defaultOut = path.join(
+  workspaceRoot,
+  '.codex/reports/cloudflare-version-proof/public-url-proof.json',
+);
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    appId: undefined,
+    out: defaultOut,
+    requirePublicUrls: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--app') {
+      parsed.appId = argv[index + 1];
+      index += 1;
+    } else if (arg === '--out') {
+      parsed.out = argv[index + 1];
+      index += 1;
+    } else if (arg === '--require-public-urls') {
+      parsed.requirePublicUrls = true;
+    } else if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return parsed;
+}
+
+function printHelp() {
+  process.stdout.write(`Usage:
+  node scripts/proof-cloudflare-version.mjs [--app workspace] [--out evidence.json] [--require-public-urls]
+
+Set each app's public URL using the contract env key, for example:
+  ULTRAMODERN_PUBLIC_URL_WORKSPACE=https://workspace.example.workers.dev
+`);
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    printHelp();
+    return 0;
+  }
+
+  const contract = readJson(contractPath);
+  const apps = args.appId
+    ? contract.apps.filter(app => app.id === args.appId)
+    : contract.apps;
+  assert(apps.length > 0, `No generated app matched ${args.appId}`);
+
+  const results = [];
+  const skipped = [];
+  for (const app of apps) {
+    const publicUrlEnv = app.deploy?.cloudflare?.publicUrlEnv;
+    const publicUrl = publicUrlEnv && process.env[publicUrlEnv];
+    if (!publicUrl) {
+      const skippedEntry = {
+        appId: app.id,
+        status: args.requirePublicUrls ? 'fail' : 'skipped',
+        publicUrlEnv,
+        reason: 'public URL environment variable is not set',
+      };
+      skipped.push(skippedEntry);
+      if (args.requirePublicUrls) {
+        throw new Error(`${app.id} requires ${publicUrlEnv}`);
+      }
+      continue;
+    }
+    results.push(await validateApp(app, publicUrl));
+  }
+
+  const report = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    status: results.length > 0 ? 'pass' : 'skipped',
+    contractPath,
+    results,
+    skipped,
+  };
+
+  fs.mkdirSync(path.dirname(args.out), { recursive: true });
+  fs.writeFileSync(args.out, `${JSON.stringify(report, null, 2)}\n`);
+  process.stdout.write(
+    `[cloudflare-version-proof] ${report.status}: ${args.out}\n`,
+  );
+  return 0;
+}
+
+main().then(
+  exitCode => {
+    process.exitCode = exitCode;
+  },
+  error => {
+    process.stderr.write(`[cloudflare-version-proof] ${error.message}\n`);
+    process.exitCode = 1;
+  },
+);