@bleedingdev/modern-js-app-tools-extensions 3.8.3-ultramodern.2

package/src/cloudflare-output-plan.ts

@@ -0,0 +1,108 @@
+import path from 'node:path';
+import {
+  CLOUDFLARE_ASSETS_BINDING,
+  CLOUDFLARE_OUTPUT_PACKAGE_FILE,
+  CLOUDFLARE_OUTPUT_PACKAGE_TYPE,
+  CLOUDFLARE_PUBLIC_ASSETS_DIRECTORY,
+  CLOUDFLARE_REQUIRED_COMPATIBILITY_FLAGS,
+  CLOUDFLARE_WORKER_BUNDLE_DIRECTORY,
+  CLOUDFLARE_WORKER_ENTRY,
+  CLOUDFLARE_WORKER_MANIFEST,
+  CLOUDFLARE_WORKER_PACKAGE_FILE,
+  CLOUDFLARE_WORKER_PACKAGE_TYPE,
+  CLOUDFLARE_WRANGLER_CONFIG_FILE,
+} from './cloudflare-output-contract';
+
+type CloudflareOutputPlan = {
+  outputDirectory: string;
+  requiredFiles: string[];
+  publicLeakDirectories: string[];
+  paths: {
+    workerEntry: string;
+    workerManifest: string;
+    wranglerConfig: string;
+    outputPackage: string;
+    workerPackage: string;
+    publicAssets: string;
+    workerBundle: string;
+  };
+  packages: {
+    output: {
+      type: typeof CLOUDFLARE_OUTPUT_PACKAGE_TYPE;
+    };
+    worker: {
+      type: typeof CLOUDFLARE_WORKER_PACKAGE_TYPE;
+    };
+  };
+  wrangler: {
+    main: typeof CLOUDFLARE_WORKER_ENTRY;
+    assets: {
+      binding: typeof CLOUDFLARE_ASSETS_BINDING;
+      directory: `./${typeof CLOUDFLARE_PUBLIC_ASSETS_DIRECTORY}`;
+      run_worker_first: true;
+    };
+    requiredCompatibilityFlags: typeof CLOUDFLARE_REQUIRED_COMPATIBILITY_FLAGS;
+  };
+};
+
+const resolveOutput = (outputDirectory: string, relativePath: string) =>
+  path.join(outputDirectory, relativePath);
+
+export function createCloudflareOutputPlan(
+  outputDirectory: string,
+): CloudflareOutputPlan {
+  return {
+    outputDirectory,
+    requiredFiles: [
+      CLOUDFLARE_WORKER_ENTRY,
+      CLOUDFLARE_WORKER_MANIFEST,
+      CLOUDFLARE_WRANGLER_CONFIG_FILE,
+      CLOUDFLARE_OUTPUT_PACKAGE_FILE,
+    ],
+    publicLeakDirectories: ['server', CLOUDFLARE_WORKER_BUNDLE_DIRECTORY],
+    paths: {
+      workerEntry: resolveOutput(outputDirectory, CLOUDFLARE_WORKER_ENTRY),
+      workerManifest: resolveOutput(
+        outputDirectory,
+        CLOUDFLARE_WORKER_MANIFEST,
+      ),
+      wranglerConfig: resolveOutput(
+        outputDirectory,
+        CLOUDFLARE_WRANGLER_CONFIG_FILE,
+      ),
+      outputPackage: resolveOutput(
+        outputDirectory,
+        CLOUDFLARE_OUTPUT_PACKAGE_FILE,
+      ),
+      workerPackage: resolveOutput(
+        outputDirectory,
+        CLOUDFLARE_WORKER_PACKAGE_FILE,
+      ),
+      publicAssets: resolveOutput(
+        outputDirectory,
+        CLOUDFLARE_PUBLIC_ASSETS_DIRECTORY,
+      ),
+      workerBundle: resolveOutput(
+        outputDirectory,
+        CLOUDFLARE_WORKER_BUNDLE_DIRECTORY,
+      ),
+    },
+    packages: {
+      output: {
+        type: CLOUDFLARE_OUTPUT_PACKAGE_TYPE,
+      },
+      worker: {
+        type: CLOUDFLARE_WORKER_PACKAGE_TYPE,
+      },
+    },
+    wrangler: {
+      main: CLOUDFLARE_WORKER_ENTRY,
+      assets: {
+        binding: CLOUDFLARE_ASSETS_BINDING,
+        directory: `./${CLOUDFLARE_PUBLIC_ASSETS_DIRECTORY}`,
+        run_worker_first: true,
+      },
+      requiredCompatibilityFlags: CLOUDFLARE_REQUIRED_COMPATIBILITY_FLAGS,
+    },
+  };
+}

package/src/cloudflare-output-verifier/identity.ts

@@ -0,0 +1,87 @@
+import {
+  DELIVERY_UNIT_IDENTITY_FIELDS,
+  type DeliveryUnitIdentity,
+  deliveryUnitIdentityFieldValue,
+} from '@modern-js/utils/universal';
+import type { CloudflareOutputVerifierIssue, JsonObject } from './issues';
+import { addIssue, assertEqual } from './issues';
+
+export type CloudflareDeliveryUnitIdentity = DeliveryUnitIdentity & {
+  surfaces?: Partial<
+    Record<'api' | 'ui', DeliveryUnitIdentity & { surface: 'api' | 'ui' }>
+  >;
+};
+
+export const verifyDeliveryUnitIdentity = (
+  issues: CloudflareOutputVerifierIssue[],
+  manifest: JsonObject,
+  manifestPath: string,
+  declared: CloudflareDeliveryUnitIdentity | undefined,
+) => {
+  const stamped = manifest?.deliveryUnit;
+  const hasStamp = Boolean(stamped) && typeof stamped === 'object';
+
+  // Legacy outputs (no topology declaration and no stamp) are unchanged.
+  if (declared) {
+    if (!hasStamp) {
+      addIssue(issues, {
+        code: 'missing-delivery-unit',
+        message: `Cloudflare worker manifest is missing the delivery-unit identity declared by the workspace topology (expected unitId ${declared.unitId}, buildMarker ${declared.buildMarker}).`,
+        path: manifestPath,
+      });
+      return;
+    }
+
+    for (const field of DELIVERY_UNIT_IDENTITY_FIELDS) {
+      const stampedValue = deliveryUnitIdentityFieldValue(stamped, field);
+      assertEqual(issues, stampedValue, declared[field], {
+        code: 'delivery-unit-drift',
+        message: `Cloudflare worker manifest deliveryUnit.${field} must match the topology delivery-unit record (expected ${declared[field]}, received ${
+          stampedValue ?? 'undefined'
+        }).`,
+        path: manifestPath,
+      });
+    }
+  }
+
+  // Every profile-declared surface must derive from the one stamped record;
+  // profiles must not claim a UI/API surface they do not emit.
+  if (hasStamp && stamped.surfaces && typeof stamped.surfaces === 'object') {
+    for (const surface of ['ui', 'api'] as const) {
+      const marker = stamped.surfaces[surface];
+      const expected = declared?.surfaces?.[surface];
+
+      if (declared?.surfaces && !expected) {
+        if (marker) {
+          addIssue(issues, {
+            code: 'delivery-unit-drift',
+            message: `Cloudflare worker manifest declares an unexpected ${surface} delivery-unit surface for this topology profile.`,
+            path: manifestPath,
+          });
+        }
+        continue;
+      }
+
+      if (!marker || typeof marker !== 'object') {
+        addIssue(issues, {
+          code: 'missing-delivery-unit',
+          message: `Cloudflare worker manifest is missing the ${surface} delivery-unit surface marker.`,
+          path: manifestPath,
+        });
+        continue;
+      }
+
+      for (const field of DELIVERY_UNIT_IDENTITY_FIELDS) {
+        const markerValue = deliveryUnitIdentityFieldValue(marker, field);
+        const stampedValue = deliveryUnitIdentityFieldValue(stamped, field);
+        assertEqual(issues, markerValue, stampedValue, {
+          code: 'delivery-unit-drift',
+          message: `Cloudflare worker manifest ${surface} surface deliveryUnit.${field} must derive from one delivery-unit record (expected ${
+            stampedValue ?? 'undefined'
+          }, received ${markerValue ?? 'undefined'}).`,
+          path: manifestPath,
+        });
+      }
+    }
+  }
+};

package/src/cloudflare-output-verifier/index.ts

@@ -0,0 +1,277 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createCloudflareOutputPlan } from '../cloudflare-output-plan';
+import type { CloudflareDeliveryUnitIdentity } from './identity';
+import { verifyDeliveryUnitIdentity } from './identity';
+import type {
+  CloudflareOutputVerifierIssue,
+  CloudflareOutputVerifierResult,
+  JsonObject,
+} from './issues';
+import { addIssue, assertEqual, assertFlag } from './issues';
+import { verifyManifestShape } from './manifest';
+import {
+  getEffectBffWorker,
+  getWorkerBundleReferences,
+  missingWorkerBundleMessage,
+  resolveWorkerBundleReference,
+  verifyWorkerBundleReferences,
+  verifyWorkerImport,
+} from './worker-bundles';
+
+export type { CloudflareDeliveryUnitIdentity } from './identity';
+export type {
+  CloudflareOutputVerifierIssue,
+  CloudflareOutputVerifierIssueCode,
+  CloudflareOutputVerifierResult,
+} from './issues';
+export {
+  type VerifyCloudflareOutputMutationPolicyOptions,
+  verifyCloudflareOutputMutationPolicy,
+} from './mutation-policy';
+
+export interface VerifyCloudflareOutputOptions {
+  outputDirectory: string;
+  importWorker?: boolean;
+  /**
+   * Topology-declared delivery-unit record (from the workspace compact config).
+   * When provided, the Cloudflare worker manifest must carry a matching
+   * `deliveryUnit` stamp so the deployed worker snapshot is proven to derive
+   * from the same delivery unit as the Node/API surfaces (ADR-0019 lane D).
+   */
+  deliveryUnit?: CloudflareDeliveryUnitIdentity;
+}
+
+const pathExists = async (filePath: string) => {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const readJson = async (filePath: string) =>
+  JSON.parse(await fs.readFile(filePath, 'utf-8')) as JsonObject;
+
+export const verifyCloudflareOutput = async (
+  options: VerifyCloudflareOutputOptions,
+): Promise<CloudflareOutputVerifierResult> => {
+  const outputDirectory = path.resolve(options.outputDirectory);
+  const issues: CloudflareOutputVerifierIssue[] = [];
+  const outputPlan = createCloudflareOutputPlan(outputDirectory);
+
+  for (const relativePath of outputPlan.requiredFiles) {
+    const filePath = path.join(outputDirectory, relativePath);
+    if (!(await pathExists(filePath))) {
+      addIssue(issues, {
+        code: 'missing-file',
+        message: `Cloudflare output is missing ${relativePath}.`,
+        path: filePath,
+      });
+    }
+  }
+
+  const manifestPath = outputPlan.paths.workerManifest;
+  const wranglerPath = outputPlan.paths.wranglerConfig;
+  const packagePath = outputPlan.paths.outputPackage;
+  const workerPackagePath = outputPlan.paths.workerPackage;
+
+  const manifest = (await pathExists(manifestPath))
+    ? await readJson(manifestPath)
+    : undefined;
+  const wrangler = (await pathExists(wranglerPath))
+    ? await readJson(wranglerPath)
+    : undefined;
+  const outputPackage = (await pathExists(packagePath))
+    ? await readJson(packagePath)
+    : undefined;
+  const workerPackage = (await pathExists(workerPackagePath))
+    ? await readJson(workerPackagePath)
+    : undefined;
+
+  if (manifest) {
+    verifyManifestShape(issues, manifest, manifestPath);
+    verifyDeliveryUnitIdentity(
+      issues,
+      manifest,
+      manifestPath,
+      options.deliveryUnit,
+    );
+
+    const workerReferences = getWorkerBundleReferences(manifest);
+    const providedWorkerPackages = new Set(
+      workerPackage?.dependencies &&
+        typeof workerPackage.dependencies === 'object'
+        ? Object.keys(workerPackage.dependencies)
+        : [],
+    );
+    if (workerReferences.length > 0 && !(await pathExists(workerPackagePath))) {
+      addIssue(issues, {
+        code: 'missing-file',
+        message:
+          'Cloudflare output is missing worker/package.json for referenced worker bundles.',
+        path: workerPackagePath,
+      });
+    }
+
+    if (
+      manifest.bff?.runtimeFramework === 'effect' &&
+      !getEffectBffWorker(manifest)
+    ) {
+      addIssue(issues, {
+        code: 'missing-worker-bundle',
+        message:
+          'Cloudflare Effect BFF manifest points to a missing worker bundle.',
+      });
+    }
+
+    for (const workerReference of workerReferences) {
+      const resolvedWorker = resolveWorkerBundleReference(
+        issues,
+        outputDirectory,
+        workerReference,
+        manifestPath,
+      );
+      if (!resolvedWorker) {
+        continue;
+      }
+
+      const workerExists = await pathExists(resolvedWorker.path);
+      if (!workerExists) {
+        addIssue(issues, {
+          code: 'missing-worker-bundle',
+          message: missingWorkerBundleMessage(workerReference),
+          path: resolvedWorker.path,
+        });
+      }
+
+      if (workerExists) {
+        const workerSource = await fs.readFile(resolvedWorker.path, 'utf-8');
+        await verifyWorkerBundleReferences(
+          issues,
+          resolvedWorker,
+          workerSource,
+          {
+            providedPackages: providedWorkerPackages,
+            workerRoot: outputPlan.paths.workerBundle,
+          },
+        );
+        if (
+          resolvedWorker.kind === 'effect-bff' &&
+          (workerSource.includes(';entityKind;') ||
+            workerSource.includes(';entityKind,entityKind;'))
+        ) {
+          addIssue(issues, {
+            code: 'invalid-worker-bundle',
+            message:
+              'Cloudflare Effect BFF worker bundle contains invalid Drizzle entityKind marker references.',
+            path: resolvedWorker.path,
+          });
+        }
+      }
+    }
+  }
+
+  if (wrangler) {
+    assertEqual(issues, wrangler.main, outputPlan.wrangler.main, {
+      code: 'invalid-wrangler',
+      message: `wrangler.json main must be ${outputPlan.wrangler.main}.`,
+      path: wranglerPath,
+    });
+    assertEqual(
+      issues,
+      wrangler.assets?.binding,
+      outputPlan.wrangler.assets.binding,
+      {
+        code: 'invalid-wrangler',
+        message: 'wrangler.json assets.binding must be ASSETS.',
+        path: wranglerPath,
+      },
+    );
+    assertEqual(
+      issues,
+      wrangler.assets?.directory,
+      outputPlan.wrangler.assets.directory,
+      {
+        code: 'invalid-wrangler',
+        message: 'wrangler.json assets.directory must be ./public.',
+        path: wranglerPath,
+      },
+    );
+    assertEqual(
+      issues,
+      wrangler.assets?.run_worker_first,
+      outputPlan.wrangler.assets.run_worker_first,
+      {
+        code: 'invalid-wrangler',
+        message: 'wrangler.json assets.run_worker_first must be true.',
+        path: wranglerPath,
+      },
+    );
+    for (const flag of outputPlan.wrangler.requiredCompatibilityFlags) {
+      assertFlag(issues, wrangler.compatibility_flags, flag, {
+        code: 'invalid-wrangler',
+        message: `wrangler.json compatibility_flags must include ${flag}.`,
+        path: wranglerPath,
+      });
+    }
+  }
+
+  if (outputPackage) {
+    assertEqual(issues, outputPackage.type, outputPlan.packages.output.type, {
+      code: 'invalid-package',
+      message: '.output/package.json must declare type module.',
+      path: packagePath,
+    });
+  }
+
+  if (workerPackage) {
+    assertEqual(issues, workerPackage.type, outputPlan.packages.worker.type, {
+      code: 'invalid-package',
+      message: '.output/worker/package.json must declare type commonjs.',
+      path: workerPackagePath,
+    });
+  }
+
+  for (const leakedPath of outputPlan.publicLeakDirectories) {
+    const publicPath = path.join(outputPlan.paths.publicAssets, leakedPath);
+    if (await pathExists(publicPath)) {
+      addIssue(issues, {
+        code: 'public-output-leak',
+        message: `Framework-owned ${leakedPath} output leaked into public assets.`,
+        path: publicPath,
+      });
+    }
+  }
+
+  if (
+    options.importWorker !== false &&
+    (await pathExists(outputPlan.paths.workerEntry))
+  ) {
+    await verifyWorkerImport(issues, outputPlan.paths.workerEntry, manifest);
+  }
+
+  return {
+    ok: issues.length === 0,
+    issues,
+  };
+};
+
+export const assertCloudflareOutput = async (
+  options: VerifyCloudflareOutputOptions,
+) => {
+  const result = await verifyCloudflareOutput(options);
+
+  if (!result.ok) {
+    throw new Error(
+      [
+        'Cloudflare output verification failed:',
+        ...result.issues.map(
+          issue =>
+            `- ${issue.code}: ${issue.message}${issue.path ? ` (${issue.path})` : ''}`,
+        ),
+      ].join('\n'),
+    );
+  }
+};

package/src/cloudflare-output-verifier/issues.ts

@@ -0,0 +1,54 @@
+export type CloudflareOutputVerifierIssueCode =
+  | 'missing-file'
+  | 'invalid-manifest'
+  | 'invalid-wrangler'
+  | 'invalid-package'
+  | 'public-output-leak'
+  | 'missing-worker-bundle'
+  | 'invalid-worker-bundle'
+  | 'worker-import-failed'
+  | 'delivery-unit-drift'
+  | 'missing-delivery-unit'
+  | 'forbidden-mutation-pattern';
+
+export interface CloudflareOutputVerifierIssue {
+  code: CloudflareOutputVerifierIssueCode;
+  message: string;
+  path?: string;
+}
+
+export interface CloudflareOutputVerifierResult {
+  ok: boolean;
+  issues: CloudflareOutputVerifierIssue[];
+}
+
+export type JsonObject = Record<string, any>;
+
+export const addIssue = (
+  issues: CloudflareOutputVerifierIssue[],
+  issue: CloudflareOutputVerifierIssue,
+) => {
+  issues.push(issue);
+};
+
+export const assertEqual = (
+  issues: CloudflareOutputVerifierIssue[],
+  actual: unknown,
+  expected: unknown,
+  issue: CloudflareOutputVerifierIssue,
+) => {
+  if (actual !== expected) {
+    addIssue(issues, issue);
+  }
+};
+
+export const assertFlag = (
+  issues: CloudflareOutputVerifierIssue[],
+  flags: unknown,
+  flag: string,
+  issue: CloudflareOutputVerifierIssue,
+) => {
+  if (!Array.isArray(flags) || !flags.includes(flag)) {
+    addIssue(issues, issue);
+  }
+};

package/src/cloudflare-output-verifier/manifest.ts

@@ -0,0 +1,76 @@
+import { BFF_EFFECT_WORKER_DISPATCHER_EXPORT } from '../cloudflare/constants';
+import {
+  CLOUDFLARE_ASSETS_BINDING,
+  CLOUDFLARE_PUBLIC_ASSETS_DIRECTORY,
+  CLOUDFLARE_RUNTIME_TYPE,
+  CLOUDFLARE_WORKER_ENTRY,
+} from '../cloudflare-output-contract';
+import type { CloudflareOutputVerifierIssue, JsonObject } from './issues';
+import { addIssue, assertEqual } from './issues';
+
+export const verifyManifestShape = (
+  issues: CloudflareOutputVerifierIssue[],
+  manifest: JsonObject,
+  manifestPath: string,
+) => {
+  assertEqual(issues, manifest.runtime?.type, CLOUDFLARE_RUNTIME_TYPE, {
+    code: 'invalid-manifest',
+    message:
+      'Cloudflare output manifest runtime.type must be cloudflare-module-worker.',
+    path: manifestPath,
+  });
+  assertEqual(issues, manifest.runtime?.entry, CLOUDFLARE_WORKER_ENTRY, {
+    code: 'invalid-manifest',
+    message: `Cloudflare output manifest runtime.entry must be ${CLOUDFLARE_WORKER_ENTRY}.`,
+    path: manifestPath,
+  });
+  assertEqual(issues, manifest.runtime?.fetchExport, true, {
+    code: 'invalid-manifest',
+    message: 'Cloudflare output manifest runtime.fetchExport must be true.',
+    path: manifestPath,
+  });
+  assertEqual(issues, manifest.runtime?.nodeListen, false, {
+    code: 'invalid-manifest',
+    message: 'Cloudflare output manifest runtime.nodeListen must be false.',
+    path: manifestPath,
+  });
+  assertEqual(issues, manifest.assets?.binding, CLOUDFLARE_ASSETS_BINDING, {
+    code: 'invalid-manifest',
+    message: 'Cloudflare output manifest assets.binding must be ASSETS.',
+    path: manifestPath,
+  });
+  assertEqual(
+    issues,
+    manifest.assets?.directory,
+    `./${CLOUDFLARE_PUBLIC_ASSETS_DIRECTORY}`,
+    {
+      code: 'invalid-manifest',
+      message: 'Cloudflare output manifest assets.directory must be ./public.',
+      path: manifestPath,
+    },
+  );
+  assertEqual(issues, manifest.assets?.runWorkerFirst, true, {
+    code: 'invalid-manifest',
+    message: 'Cloudflare output manifest assets.runWorkerFirst must be true.',
+    path: manifestPath,
+  });
+  if (!Array.isArray(manifest.routeSpec?.routes)) {
+    addIssue(issues, {
+      code: 'invalid-manifest',
+      message: 'Cloudflare output manifest routeSpec.routes must be array.',
+      path: manifestPath,
+    });
+  }
+  if (manifest.bff?.runtimeFramework === 'effect') {
+    assertEqual(
+      issues,
+      manifest.bff.dispatcherExport,
+      BFF_EFFECT_WORKER_DISPATCHER_EXPORT,
+      {
+        code: 'invalid-manifest',
+        message: `Cloudflare Effect BFF manifest dispatcherExport must be ${BFF_EFFECT_WORKER_DISPATCHER_EXPORT}.`,
+        path: manifestPath,
+      },
+    );
+  }
+};