@bleedingdev/modern-js-create 3.4.0-ultramodern.2 → 3.4.0-ultramodern.20

package/templates/workspace-scripts/assert-mf-types.mjs.handlebars

@@ -2,15 +2,58 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 const root = process.cwd();
-const generatedContractPath = path.join(
-  root,
-  '.modernjs/ultramodern-generated-contract.json',
-);
-const generatedContract = fs.existsSync(generatedContractPath)
-  ? JSON.parse(fs.readFileSync(generatedContractPath, 'utf-8'))
-  : undefined;
+const compactConfigPath = path.join(root, '.modernjs/ultramodern.json');
 const defaultAppDirs = {{defaultAppDirsJson}};
 
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}
+
+function normalizeRelativePath(value) {
+  return String(value ?? '').replace(/\\/gu, '/').replace(/^\.\/+/u, '');
+}
+
+function readGeneratedContractView() {
+  if (fs.existsSync(compactConfigPath)) {
+    const compactConfig = readJson(compactConfigPath);
+    return {
+      sourcePath: compactConfigPath,
+      apps: Array.isArray(compactConfig.topology?.apps)
+        ? compactConfig.topology.apps.map(app => {
+            const moduleFederation =
+              app.moduleFederation && typeof app.moduleFederation === 'object'
+                ? app.moduleFederation
+                : {};
+            return {
+              id: String(app.id),
+              path:
+                typeof app.path === 'string'
+                  ? normalizeRelativePath(app.path)
+                  : '.',
+              moduleFederation: {
+                exposes: Array.isArray(moduleFederation.exposes)
+                  ? moduleFederation.exposes.filter(
+                      expose => typeof expose === 'string',
+                    )
+                  : [],
+                dts: {
+                  compilerInstance:
+                    moduleFederation.dts?.compilerInstance ?? 'tsgo',
+                  tsConfigPath:
+                    moduleFederation.dts?.tsConfigPath ??
+                    './tsconfig.mf-types.json',
+                },
+              },
+            };
+          })
+        : [],
+    };
+  }
+  throw new Error('Missing UltraModern config. Expected .modernjs/ultramodern.json.');
+}
+
+const generatedContract = readGeneratedContractView();
+
 const args = process.argv.slice(2);
 if (args.includes('--help') || args.includes('-h')) {
   process.stdout.write(`Usage:
@@ -48,6 +91,15 @@ for (const appDir of appDirs) {
       `Module Federation DTS must use the workspace TypeScript compiler: ${appDir}`,
     );
   }
+  if (
+    contractEntry &&
+    contractEntry.moduleFederation?.dts?.tsConfigPath !==
+      './tsconfig.mf-types.json'
+  ) {
+    throw new Error(
+      `Module Federation DTS must use the dedicated public-surface tsconfig: ${appDir}`,
+    );
+  }
 
   if (contractEntry && contractEntry.moduleFederation?.exposes?.length === 0) {
     continue;

package/templates/workspace-scripts/check-ultramodern-api-boundaries.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const workspaceRoot = process.env.ULTRAMODERN_WORKSPACE_ROOT ?? process.cwd();
+const failures = [];
+
+const ignoredDirectories = new Set([
+  '.git',
+  '.modern',
+  '.output',
+  'coverage',
+  'dist',
+  'node_modules',
+  'repos',
+]);
+
+function normalize(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+function relative(filePath) {
+  return normalize(path.relative(workspaceRoot, filePath));
+}
+
+function exists(relativePath) {
+  return fs.existsSync(path.join(workspaceRoot, relativePath));
+}
+
+function readText(relativePath) {
+  return fs.readFileSync(path.join(workspaceRoot, relativePath), 'utf8');
+}
+
+function fail(message) {
+  failures.push(message);
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    fail(message);
+  }
+}
+
+function listFiles(startDirectory) {
+  const absoluteStart = path.join(workspaceRoot, startDirectory);
+  if (!fs.existsSync(absoluteStart)) {
+    return [];
+  }
+
+  const files = [];
+  const visit = directory => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (ignoredDirectories.has(entry.name)) {
+        continue;
+      }
+
+      const absoluteEntry = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        visit(absoluteEntry);
+        continue;
+      }
+
+      if (entry.isFile()) {
+        files.push(relative(absoluteEntry));
+      }
+    }
+  };
+
+  visit(absoluteStart);
+  return files;
+}
+
+function listDirectories(startDirectory) {
+  const absoluteStart = path.join(workspaceRoot, startDirectory);
+  if (!fs.existsSync(absoluteStart)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(absoluteStart, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && !ignoredDirectories.has(entry.name))
+    .map(entry => path.posix.join(startDirectory, entry.name));
+}
+
+function assertNoPath(relativePath, message) {
+  if (exists(relativePath)) {
+    fail(message);
+  }
+}
+
+function assertContains(relativePath, content, pattern, message) {
+  assert(pattern.test(content), `${relativePath}: ${message}`);
+}
+
+function assertNotContains(relativePath, content, pattern, message) {
+  assert(!pattern.test(content), `${relativePath}: ${message}`);
+}
+
+const generatedFiles = [
+  ...listFiles('apps'),
+  ...listFiles('verticals'),
+  ...listFiles('packages'),
+];
+
+for (const forbiddenPath of [
+  'apps/shell-super-app/src/effect',
+  ...listDirectories('verticals').flatMap(verticalPath => [
+    `${verticalPath}/api/effect`,
+    `${verticalPath}/api/lambda`,
+    `${verticalPath}/shared/effect`,
+    `${verticalPath}/src/effect`,
+  ]),
+]) {
+  assertNoPath(
+    forbiddenPath,
+    `${forbiddenPath} is forbidden in UltraModern strictEffectApproach workspaces; use api/index.ts, shared/api.ts and src/api/* instead.`,
+  );
+}
+
+const textFiles = generatedFiles.filter(file =>
+  /\.(?:[cm]?[jt]sx?|json|md|mjs|mts|cts)$/u.test(file),
+);
+
+for (const file of textFiles) {
+  const content = readText(file);
+
+  if (/\/api\//u.test(file)) {
+    assertNotContains(
+      file,
+      content,
+      /\bnew\s+Response\s*\(|\bResponse\.json\s*\(/u,
+      'API modules must not hand-build Response objects; model the endpoint through Effect HttpApi and schemas.',
+    );
+    assertNotContains(
+      file,
+      content,
+      /\brequest\.(?:json|text|formData|arrayBuffer)\s*\(/u,
+      'API modules must not manually parse request bodies; use HttpApiEndpoint payload/query/params schemas.',
+    );
+    assertNotContains(
+      file,
+      content,
+      /\bexport\s+const\s+handler\b|\bexport\s+default\s+async\b/u,
+      'API modules must not export raw request handlers; export defineEffectBff(...) from api/index.ts.',
+    );
+    assertNotContains(
+      file,
+      content,
+      /\bcreateHandler\s*[:=]\s*(?!defineEffectBff\b)/u,
+      'API modules must not define unbranded handler factories; use defineEffectBff(...).',
+    );
+  }
+
+  assertNotContains(
+    file,
+    content,
+    /@modern-js\/plugin-bff\/hono-server/u,
+    'Hono server helpers are not part of generated UltraModern API workspaces.',
+  );
+  assertNotContains(
+    file,
+    content,
+    /runtimeFramework:\s*['"]hono['"]/u,
+    'Generated UltraModern API apps must use the Effect runtime.',
+  );
+}
+
+const shellClient = 'apps/shell-super-app/src/api/vertical-clients.ts';
+if (exists('apps/shell-super-app')) {
+  assert(exists(shellClient), `${shellClient} must aggregate vertical API clients.`);
+}
+
+for (const verticalPath of listDirectories('verticals')) {
+  const apiEntry = `${verticalPath}/api/index.ts`;
+  const sharedApi = `${verticalPath}/shared/api.ts`;
+  const srcApiDirectory = `${verticalPath}/src/api`;
+  const modernConfig = `${verticalPath}/modern.config.ts`;
+  const packageJsonPath = `${verticalPath}/package.json`;
+
+  assert(exists(apiEntry), `${apiEntry} is required.`);
+  assert(exists(sharedApi), `${sharedApi} is required.`);
+  assert(exists(srcApiDirectory), `${srcApiDirectory} is required.`);
+
+  if (exists(srcApiDirectory)) {
+    const clientFiles = listFiles(srcApiDirectory).filter(file =>
+      /-client\.ts$/u.test(file),
+    );
+    assert(
+      clientFiles.length > 0,
+      `${srcApiDirectory} must contain a generated API client.`,
+    );
+  }
+
+  if (exists(apiEntry)) {
+    const entry = readText(apiEntry);
+    assertContains(
+      apiEntry,
+      entry,
+      /\bdefineEffectBff\b/u,
+      'must export a defineEffectBff(...) runtime definition.',
+    );
+    assertContains(
+      apiEntry,
+      entry,
+      /\bHttpApiBuilder\b/u,
+      'must implement handlers through HttpApiBuilder.',
+    );
+    assertContains(
+      apiEntry,
+      entry,
+      /\bLayer\b/u,
+      'must compose dependencies with Effect Layer.',
+    );
+    assertContains(
+      apiEntry,
+      entry,
+      /from ['"]\.\.\/shared\/api\.ts['"]/u,
+      'must import the contract from ../shared/api.ts.',
+    );
+  }
+
+  if (exists(sharedApi)) {
+    const contract = readText(sharedApi);
+    assertContains(
+      sharedApi,
+      contract,
+      /\bHttpApi\.make\b/u,
+      'must declare the HttpApi contract.',
+    );
+    assertContains(
+      sharedApi,
+      contract,
+      /\bHttpApiGroup\.make\b/u,
+      'must declare HttpApi groups.',
+    );
+    assertContains(
+      sharedApi,
+      contract,
+      /\bHttpApiEndpoint\./u,
+      'must declare endpoints through HttpApiEndpoint.',
+    );
+    assertContains(
+      sharedApi,
+      contract,
+      /\bSchema\./u,
+      'must use Schema for request, response and error shapes.',
+    );
+  }
+
+  if (exists(modernConfig)) {
+    const config = readText(modernConfig);
+    assertContains(
+      modernConfig,
+      config,
+      /runtimeFramework:\s*['"]effect['"]/u,
+      'must use bff.runtimeFramework: effect.',
+    );
+    assertContains(
+      modernConfig,
+      config,
+      /entry:\s*['"]\.\/api\/index['"]/u,
+      'must point bff.effect.entry at ./api/index.',
+    );
+    assertContains(
+      modernConfig,
+      config,
+      /strictEffectApproach:\s*true/u,
+      'must enable strictEffectApproach explicitly.',
+    );
+  }
+
+  if (exists(packageJsonPath)) {
+    const packageJson = JSON.parse(readText(packageJsonPath));
+    assert(
+      packageJson.exports?.['./api'] === './shared/api.ts',
+      `${packageJsonPath}: package must export ./api from shared/api.ts.`,
+    );
+    assert(
+      typeof packageJson.exports?.['./api/client'] === 'string' &&
+        packageJson.exports['./api/client'].startsWith('./src/api/'),
+      `${packageJsonPath}: package must export ./api/client from src/api/*.`,
+    );
+  }
+}
+
+if (exists('apps/shell-super-app/package.json')) {
+  const shellPackageJson = JSON.parse(
+    readText('apps/shell-super-app/package.json'),
+  );
+  assert(
+    shellPackageJson.exports?.['./api/clients'] ===
+      './src/api/vertical-clients.ts',
+    'apps/shell-super-app/package.json must export ./api/clients.',
+  );
+}
+
+if (exists('package.json')) {
+  const rootPackageJson = JSON.parse(readText('package.json'));
+  assert(
+    rootPackageJson.scripts?.['api:check'] ===
+      'node ./scripts/check-ultramodern-api-boundaries.mjs',
+    'Root package.json must expose api:check.',
+  );
+  assert(
+    rootPackageJson.scripts?.check?.includes('pnpm api:check'),
+    'Root check script must include pnpm api:check.',
+  );
+}
+
+if (exists('topology/reference-topology.json')) {
+  const topology = JSON.parse(readText('topology/reference-topology.json'));
+  for (const vertical of topology.verticals ?? []) {
+    if (vertical.api?.runtime === 'effect') {
+      assert(
+        vertical.api.bff?.strictEffectApproach === true,
+        `${vertical.id} topology must mark strictEffectApproach as true.`,
+      );
+      assert(
+        typeof vertical.api.serverEntry === 'string' &&
+          vertical.api.serverEntry.endsWith('/api/index.ts'),
+        `${vertical.id} topology must use api/index.ts as the server entry.`,
+      );
+    }
+    assert(
+      !vertical.api?.effect,
+      `${vertical.id} topology must describe the API directly, not under api.effect.`,
+    );
+  }
+}
+
+if (failures.length > 0) {
+  console.error('UltraModern API boundary check failed:');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('UltraModern API boundary check passed.');

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

@@ -4,18 +4,255 @@ 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',
+  process.env.ULTRAMODERN_WORKSPACE_ROOT ??
+    path.join(path.dirname(fileURLToPath(import.meta.url)), '..'),
 );
+const compactConfigPath = path.join(workspaceRoot, '.modernjs/ultramodern.json');
 
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
 }
 
+function toKebabCase(value) {
+  return String(value)
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/gu, '$1-$2')
+    .replace(/[^a-zA-Z0-9._-]+/gu, '-')
+    .replace(/[._]+/gu, '-')
+    .toLowerCase()
+    .replace(/-+/gu, '-')
+    .replace(/^-+|-+$/gu, '');
+}
+
+function toEnvSegment(value) {
+  return toKebabCase(value).replace(/-/gu, '_').toUpperCase();
+}
+
+function normalizeRelativePath(value) {
+  return String(value ?? '').replace(/\\/gu, '/').replace(/^\.\/+/u, '');
+}
+
+function appNamespace(app) {
+  return app.kind === 'shell' ? 'shell' : (app.domain ?? app.id);
+}
+
+function defaultPortEnv(app) {
+  return app.kind === 'shell'
+    ? 'SHELL_SUPER_APP_PORT'
+    : `VERTICAL_${toEnvSegment(app.domain ?? app.id)}_PORT`;
+}
+
+function defaultPort(app) {
+  return app.kind === 'shell' ? 3020 : 3030;
+}
+
+function normalizeCompactApp(rawApp) {
+  const id = String(rawApp.id);
+  const kind = rawApp.kind === 'vertical' ? 'vertical' : 'shell';
+  const appPath =
+    typeof rawApp.path === 'string'
+      ? normalizeRelativePath(rawApp.path)
+      : kind === 'shell'
+        ? 'apps/shell-super-app'
+        : `verticals/${toKebabCase(id)}`;
+  const packageSuffix =
+    typeof rawApp.packageSuffix === 'string'
+      ? rawApp.packageSuffix
+      : appPath.split('/').at(-1) ?? id;
+  const domain =
+    typeof rawApp.domain === 'string'
+      ? rawApp.domain
+      : kind === 'vertical'
+        ? packageSuffix
+        : undefined;
+  const moduleFederation =
+    rawApp.moduleFederation && typeof rawApp.moduleFederation === 'object'
+      ? rawApp.moduleFederation
+      : {};
+
+  return {
+    id,
+    kind,
+    path: appPath,
+    packageSuffix,
+    domain,
+    port:
+      typeof rawApp.port === 'number'
+        ? rawApp.port
+        : defaultPort({ id, kind, domain }),
+    portEnv:
+      typeof rawApp.portEnv === 'string'
+        ? rawApp.portEnv
+        : defaultPortEnv({ id, kind, domain }),
+    mfName:
+      typeof moduleFederation.name === 'string'
+        ? moduleFederation.name
+        : kind === 'shell'
+          ? 'shellSuperApp'
+          : `vertical${toKebabCase(domain ?? id)
+              .split('-')
+              .filter(Boolean)
+              .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+              .join('')}`,
+    exposes: Array.isArray(moduleFederation.exposes)
+      ? moduleFederation.exposes.filter(expose => typeof expose === 'string')
+      : [],
+    verticalRefs: Array.isArray(moduleFederation.verticalRefs)
+      ? moduleFederation.verticalRefs.filter(ref => typeof ref === 'string')
+      : [],
+    marker: {
+      appId: id,
+    },
+    routes:
+      rawApp.routes && typeof rawApp.routes === 'object'
+        ? rawApp.routes
+        : undefined,
+    effectApi:
+      rawApp.effectApi && typeof rawApp.effectApi === 'object'
+        ? {
+            stem:
+              typeof rawApp.effectApi.stem === 'string'
+                ? rawApp.effectApi.stem
+                : domain ?? id,
+            prefix:
+              typeof rawApp.effectApi.prefix === 'string'
+                ? rawApp.effectApi.prefix
+                : `/${domain ?? id}-api`,
+          }
+        : undefined,
+  };
+}
+
+function createRouteOwnedEntries(app) {
+  const namespace = appNamespace(app);
+  const base = {
+    descriptionKey: `${namespace}.seo.description`,
+    mfBoundaryId: app.mfName,
+    namespace,
+    ownerAppId: app.id,
+    public: false,
+    indexable: false,
+    publicSurface: 'private-app-screen',
+  };
+
+  return [
+    {
+      ...base,
+      canonicalPath: '/',
+      id: app.kind === 'shell' ? 'shell-home' : `${app.id}-home`,
+      localisedPaths: {
+        cs: '/',
+        en: '/',
+      },
+      titleKey: app.kind === 'shell' ? 'shell.title' : `${namespace}.title`,
+    },
+  ];
+}
+
+function createPublicRoutes(app) {
+  return createRouteOwnedEntries(app)
+    .filter(route => route.public && route.indexable)
+    .map(route => ({
+      canonicalPath: route.canonicalPath,
+      id: route.id,
+      localisedPaths: route.localisedPaths,
+      namespace: route.namespace,
+      ownerAppId: route.ownerAppId,
+      descriptionKey: route.descriptionKey,
+      titleKey: route.titleKey,
+    }));
+}
+
+function createPublicSurface(app) {
+  const publicRoutes = createPublicRoutes(app);
+  const basePublicSurface = {
+    authoring: 'colocated-route-meta',
+    artifactLifecycle: 'build-and-deploy-output',
+    generatedManifest: './src/routes/ultramodern-route-metadata',
+    source: 'route-owned-public-routes',
+    metadataExport: './src/routes/ultramodern-route-metadata',
+    generator: 'scripts/generate-public-surface-assets.mjs',
+    outputRoot: 'dist/public',
+    cloudflareOutputRoot: '.output/public',
+    privateRoutePolicy: 'omit-from-generated-public-surface',
+    files:
+      publicRoutes.length > 0
+        ? ['robots.txt', 'sitemap.xml', 'site.webmanifest']
+        : ['robots.txt'],
+    omittedByDefault: ['api-catalog.json', 'llms.txt', 'security.txt'],
+    languages: ['en', 'cs'],
+    contentExpansion: {
+      authoring: 'route-owned-esm-provider',
+      defaultProviderFile: 'route.sitemap.mjs',
+      entryExport: 'default-or-entries',
+      paramsSource: 'params-or-localeParams',
+      draftPolicy: 'omit-draft-by-default',
+      indexablePolicy: 'omit-indexable-false',
+      lifecycle: 'executed-during-public-surface-generation',
+    },
+    contentSources: [],
+    publicRoutes,
+    routeEntries: [],
+    concreteUrlPaths: [],
+  };
+
+  return app.routes?.publicSurface &&
+    typeof app.routes.publicSurface === 'object'
+    ? {
+        ...basePublicSurface,
+        ...app.routes.publicSurface,
+      }
+    : basePublicSurface;
+}
+
+function createCloudflareDeploy(config, app) {
+  const packageScope =
+    typeof config.workspace?.packageScope === 'string'
+      ? config.workspace.packageScope
+      : path.basename(workspaceRoot);
+  const compatibilityDate =
+    typeof config.deploy?.worker?.compatibilityDate === 'string'
+      ? config.deploy.worker.compatibilityDate
+      : '2026-06-02';
+  return {
+    workerName: `${toKebabCase(packageScope)}-${app.packageSuffix}`.slice(0, 63),
+    publicUrlEnv: `ULTRAMODERN_PUBLIC_URL_${toEnvSegment(app.id)}`,
+    compatibilityDate,
+    compatibilityFlags: ['nodejs_compat', 'global_fetch_strictly_public'],
+  };
+}
+
+function synthesizeContractFromCompactConfig(config) {
+  const apps = Array.isArray(config.topology?.apps)
+    ? config.topology.apps.map(normalizeCompactApp)
+    : [];
+
+  return {
+    sourcePath: compactConfigPath,
+    apps: apps.map(app => ({
+      ...app,
+      deploy: {
+        cloudflare: createCloudflareDeploy(config, app),
+      },
+      routes: {
+        publicSurface: createPublicSurface(app),
+      },
+    })),
+  };
+}
+
+function readGeneratedContractView() {
+  if (fs.existsSync(compactConfigPath)) {
+    return synthesizeContractFromCompactConfig(readJson(compactConfigPath));
+  }
+  throw new Error(
+    `Missing UltraModern config. Expected ${path.relative(
+      workspaceRoot,
+      compactConfigPath,
+    )}.`,
+  );
+}
+
 function parseArgs(argv) {
   const parsed = {
     appId: undefined,
@@ -517,10 +754,10 @@ try {
     printHelp();
     process.exit(0);
   }
-  const contract = readJson(contractPath);
+  const contract = readGeneratedContractView();
   const app = contract.apps?.find(candidate => candidate.id === args.appId);
   if (!app) {
-    throw new Error(`Unknown app in generated contract: ${args.appId}`);
+    throw new Error(`Unknown app in UltraModern config: ${args.appId}`);
   }
   await generatePublicSurfaceAssets(app, args.target, args.requirePublicOrigin);
 } catch (error) {