@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.3 → 3.5.0-ultramodern.30

package/dist/esm-node/plugins/deploy/platforms/cloudflare-output-verifier.mjs

@@ -0,0 +1,348 @@
+import "node:module";
+import promises from "node:fs/promises";
+import node_path from "node:path";
+import { pathToFileURL } from "node:url";
+import { CLOUDFLARE_ASSETS_BINDING, CLOUDFLARE_PUBLIC_ASSETS_DIRECTORY, CLOUDFLARE_RUNTIME_TYPE, CLOUDFLARE_WORKER_BUNDLE_DIRECTORY, CLOUDFLARE_WORKER_ENTRY } from "./cloudflare-output-contract.mjs";
+import { createCloudflareOutputPlan } from "./cloudflare-output-plan.mjs";
+const SOURCE_SCAN_FILE_PATTERN = /\.(?:[cm]?[jt]s|json)$/u;
+const SOURCE_SCAN_IGNORED_DIRECTORY_NAMES = new Set([
+    '.codex',
+    '.fastcontext',
+    '.git',
+    '.mf',
+    '.modernjs',
+    '.output',
+    'coverage',
+    'dist',
+    'dist-cloudflare',
+    'node_modules',
+    'repos',
+    'topology'
+]);
+const FORBIDDEN_MUTATION_PATTERNS = [
+    {
+        code: 'forbidden-mutation-pattern',
+        message: "Generated Cloudflare server worker output must not be rewritten by app scripts.",
+        pattern: /\.output\/server\/index\.mjs/u
+    },
+    {
+        code: 'forbidden-mutation-pattern',
+        message: "Generated Cloudflare server worker output must not be rewritten by app scripts.",
+        pattern: /path\.join\(\s*['"`]\.output['"`]\s*,\s*['"`]server['"`]\s*,\s*['"`]index\.mjs['"`]\s*\)/u
+    },
+    {
+        code: 'forbidden-mutation-pattern',
+        message: "Generated Cloudflare BFF worker bundles must not be rewritten by app scripts.",
+        pattern: /\.output\/worker\/[^'"`]*\.(?:mjs|cjs|js)/u
+    },
+    {
+        code: 'forbidden-mutation-pattern',
+        message: "Generated Cloudflare BFF worker bundles must not be rewritten by app scripts.",
+        pattern: /path\.join\(\s*['"`]\.output['"`]\s*,\s*['"`]worker['"`]\s*,\s*['"`][^'"`]+\.(?:mjs|cjs|js)['"`]\s*\)/u
+    },
+    {
+        code: 'forbidden-mutation-pattern',
+        message: "Drizzle entityKind worker bundle markers must be fixed in the framework toolchain, not post-build scripts.",
+        pattern: /replaceAll\(\s*['"`];entityKind(?:,entityKind)?;/u
+    },
+    {
+        code: 'forbidden-mutation-pattern',
+        message: "Effect BFF Cloudflare dispatch must not depend on duck-typed runtime helper probing in app scripts.",
+        pattern: /(?:typeof\s+[^;\n]*dispatchEffectBffRequest|['"`]dispatchEffectBffRequest['"`]\s+in\s+|\.dispatchEffectBffRequest\b)/u
+    },
+    {
+        code: 'forbidden-mutation-pattern',
+        message: "Effect BFF Cloudflare dispatch must not branch on handler.length in app scripts.",
+        pattern: /\bhandler\s*\.\s*length\b/u
+    }
+];
+const pathExists = async (filePath)=>{
+    try {
+        await promises.access(filePath);
+        return true;
+    } catch  {
+        return false;
+    }
+};
+const readJson = async (filePath)=>JSON.parse(await promises.readFile(filePath, 'utf-8'));
+const addIssue = (issues, issue)=>{
+    issues.push(issue);
+};
+const assertEqual = (issues, actual, expected, issue)=>{
+    if (actual !== expected) addIssue(issues, issue);
+};
+const assertFlag = (issues, flags, flag, issue)=>{
+    if (!Array.isArray(flags) || !flags.includes(flag)) addIssue(issues, issue);
+};
+const getReferencedRouteWorkers = (manifest)=>Array.isArray(manifest?.routeSpec?.routes) ? manifest.routeSpec.routes.map((route)=>'string' == typeof route?.worker && route.worker.length > 0 ? route.worker : void 0).filter((worker)=>'string' == typeof worker) : [];
+const getEffectBffWorker = (manifest)=>manifest?.bff?.runtimeFramework === 'effect' && 'string' == typeof manifest.bff.worker ? manifest.bff.worker : void 0;
+const getWorkerBundleReferences = (manifest)=>{
+    const effectBffWorker = getEffectBffWorker(manifest);
+    return [
+        ...effectBffWorker ? [
+            {
+                kind: 'effect-bff',
+                reference: effectBffWorker
+            }
+        ] : [],
+        ...getReferencedRouteWorkers(manifest).map((reference)=>({
+                kind: 'route',
+                reference
+            }))
+    ];
+};
+const resolveWorkerBundleReference = (issues, outputDirectory, reference, manifestPath)=>{
+    const workerRoot = node_path.resolve(outputDirectory, CLOUDFLARE_WORKER_BUNDLE_DIRECTORY);
+    const workerPath = node_path.resolve(outputDirectory, reference.reference);
+    const relativeToWorkerRoot = node_path.relative(workerRoot, workerPath);
+    if (node_path.isAbsolute(reference.reference) || relativeToWorkerRoot.startsWith('..') || node_path.isAbsolute(relativeToWorkerRoot)) {
+        addIssue(issues, {
+            code: 'invalid-manifest',
+            message: 'Cloudflare output manifest worker bundle references must stay under worker/.',
+            path: manifestPath
+        });
+        return null;
+    }
+    return {
+        ...reference,
+        path: workerPath
+    };
+};
+const missingWorkerBundleMessage = (reference)=>'effect-bff' === reference.kind ? 'Cloudflare Effect BFF manifest points to a missing worker bundle.' : 'Cloudflare route worker manifest points to a missing worker bundle.';
+const DELIVERY_UNIT_IDENTITY_FIELDS = [
+    'unitId',
+    'buildMarker',
+    'sourceRevision'
+];
+const verifyDeliveryUnitIdentity = (issues, manifest, manifestPath, declared)=>{
+    const stamped = manifest?.deliveryUnit;
+    const hasStamp = Boolean(stamped) && 'object' == typeof stamped;
+    if (declared) {
+        if (!hasStamp) return void 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
+        });
+        for (const field of DELIVERY_UNIT_IDENTITY_FIELDS)assertEqual(issues, stamped[field], declared[field], {
+            code: 'delivery-unit-drift',
+            message: `Cloudflare worker manifest deliveryUnit.${field} must match the topology delivery-unit record (expected ${declared[field]}, received ${stamped[field] ?? 'undefined'}).`,
+            path: manifestPath
+        });
+    }
+    if (hasStamp && stamped.surfaces && 'object' == typeof stamped.surfaces) for (const surface of [
+        'ui',
+        'api'
+    ]){
+        const marker = stamped.surfaces[surface];
+        if (!marker || 'object' != typeof marker) {
+            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)assertEqual(issues, marker[field], stamped[field], {
+            code: 'delivery-unit-drift',
+            message: `Cloudflare worker manifest ${surface} surface deliveryUnit.${field} must derive from one delivery-unit record (expected ${stamped[field] ?? 'undefined'}, received ${marker[field] ?? 'undefined'}).`,
+            path: manifestPath
+        });
+    }
+};
+const verifyManifestShape = (issues, manifest, manifestPath)=>{
+    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
+    });
+};
+const walkFiles = async (root)=>{
+    if (!await pathExists(root)) return [];
+    const entries = await promises.readdir(root, {
+        withFileTypes: true
+    });
+    const files = [];
+    for (const entry of entries){
+        if (SOURCE_SCAN_IGNORED_DIRECTORY_NAMES.has(entry.name)) continue;
+        const entryPath = node_path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await walkFiles(entryPath));
+            continue;
+        }
+        if (SOURCE_SCAN_FILE_PATTERN.test(entry.name)) files.push(entryPath);
+    }
+    return files;
+};
+const verifyCloudflareOutputMutationPolicy = async (options)=>{
+    const issues = [];
+    const files = (await Promise.all(options.scanRoots.map((scanRoot)=>walkFiles(node_path.resolve(scanRoot))))).flat();
+    for (const file of files){
+        const source = await promises.readFile(file, 'utf-8');
+        for (const forbidden of FORBIDDEN_MUTATION_PATTERNS)if (forbidden.pattern.test(source)) addIssue(issues, {
+            code: forbidden.code,
+            message: forbidden.message,
+            path: file
+        });
+    }
+    return {
+        ok: 0 === issues.length,
+        issues
+    };
+};
+const verifyWorkerImport = async (issues, entryPath)=>{
+    try {
+        const worker = (await import(`${pathToFileURL(entryPath).href}?t=${Date.now()}`)).default;
+        if (!worker || 'function' != typeof worker.fetch) addIssue(issues, {
+            code: 'worker-import-failed',
+            message: 'Cloudflare server entry must default-export a Worker with fetch.',
+            path: entryPath
+        });
+    } catch (error) {
+        addIssue(issues, {
+            code: 'worker-import-failed',
+            message: `Cloudflare server entry could not be imported: ${error instanceof Error ? error.message : String(error)}`,
+            path: entryPath
+        });
+    }
+};
+const verifyCloudflareOutput = async (options)=>{
+    const outputDirectory = node_path.resolve(options.outputDirectory);
+    const issues = [];
+    const outputPlan = createCloudflareOutputPlan(outputDirectory);
+    for (const relativePath of outputPlan.requiredFiles){
+        const filePath = node_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) : void 0;
+    const wrangler = await pathExists(wranglerPath) ? await readJson(wranglerPath) : void 0;
+    const outputPackage = await pathExists(packagePath) ? await readJson(packagePath) : void 0;
+    const workerPackage = await pathExists(workerPackagePath) ? await readJson(workerPackagePath) : void 0;
+    if (manifest) {
+        verifyManifestShape(issues, manifest, manifestPath);
+        verifyDeliveryUnitIdentity(issues, manifest, manifestPath, options.deliveryUnit);
+        const workerReferences = getWorkerBundleReferences(manifest);
+        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 && 'effect-bff' === resolvedWorker.kind) {
+                const workerSource = await promises.readFile(resolvedWorker.path, 'utf-8');
+                if (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 = node_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 (false !== options.importWorker && await pathExists(outputPlan.paths.workerEntry)) await verifyWorkerImport(issues, outputPlan.paths.workerEntry);
+    return {
+        ok: 0 === issues.length,
+        issues
+    };
+};
+const assertCloudflareOutput = async (options)=>{
+    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'));
+};
+export { assertCloudflareOutput, verifyCloudflareOutput, verifyCloudflareOutputMutationPolicy };