@bleedingdev/modern-js-ultramodern-create 3.9.0-ultramodern.2 → 3.9.0-ultramodern.3

package/dist/esm/ultramodern-tooling/commands/migrate-strict-effect/shared-api-infrastructure.js

@@ -0,0 +1,50 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { readFileTemplate } from "../../../ultramodern-workspace/fs-io.js";
+import { createSharedPackage, createSharedPackageTsConfig } from "../../../ultramodern-workspace/package-json.js";
+import { readJsonFile, writeJsonFile } from "./io.js";
+const directory = 'packages/shared-contracts';
+function record(value, label) {
+    if (null === value || 'object' != typeof value || Array.isArray(value)) throw new Error(`${label} must be an object; resolve it before migration.`);
+    return value;
+}
+function ensureSharedApiInfrastructure(io, scope, packageSource) {
+    for (const relativePath of [
+        'packages',
+        directory,
+        `${directory}/package.json`,
+        `${directory}/src`,
+        `${directory}/src/index.ts`
+    ])if (node_fs.lstatSync(node_path.join(io.workspaceRoot, relativePath), {
+        throwIfNoEntry: false
+    })?.isSymbolicLink()) throw new Error(`Shared API migration cannot write through a symbolic link: ${relativePath}`);
+    const manifestPath = node_path.join(io.workspaceRoot, directory, 'package.json');
+    const defaults = createSharedPackage(scope, 'shared-contracts', 'Shared workspace contracts', packageSource);
+    const manifest = node_fs.existsSync(manifestPath) ? record(readJsonFile(manifestPath), `${directory}/package.json`) : defaults;
+    const exports = void 0 === manifest.exports ? {} : 'string' == typeof manifest.exports ? {
+        '.': manifest.exports
+    } : record(manifest.exports, `${directory}/package.json exports`);
+    if (Object.keys(exports).some((key)=>!key.startsWith('.')) || void 0 !== exports['.'] && './src/index.ts' !== exports['.']) throw new Error(`${directory}/package.json exports must expose ./src/index.ts at "." before adding shared API infrastructure; consumer exports were not overwritten.`);
+    for (const [subpath, target] of Object.entries(record(defaults.exports, 'Shared contract exports')))if (void 0 !== exports[subpath] && exports[subpath] !== target) throw new Error(`${directory}/package.json ${subpath} must expose ${String(target)}; consumer exports were not overwritten.`);
+    const dependencies = record(manifest.dependencies ?? {}, `${directory}/package.json dependencies`);
+    manifest.exports = {
+        ...record(defaults.exports, 'Shared contract exports'),
+        ...exports
+    };
+    manifest.dependencies = {
+        ...record(defaults.dependencies, 'Shared contract dependencies'),
+        ...dependencies
+    };
+    const writeMissing = (relativePath, content)=>{
+        const filePath = node_path.join(io.workspaceRoot, directory, relativePath);
+        if (void 0 === node_fs.lstatSync(filePath, {
+            throwIfNoEntry: false
+        })) io.writeGenerated(filePath, content);
+    };
+    writeMissing('src/effect-bff-runtime.ts', readFileTemplate('packages/effect-bff-runtime.ts'));
+    writeMissing('src/microvertical-api-baseline.ts', readFileTemplate('packages/microvertical-api-baseline.ts'));
+    writeMissing('tsconfig.json', `${JSON.stringify(createSharedPackageTsConfig(directory), null, 2)}\n`);
+    writeMissing('src/index.ts', readFileTemplate('packages/shared-contracts-index.ts'));
+    writeJsonFile(io, manifestPath, manifest);
+}
+export { ensureSharedApiInfrastructure };

package/dist/esm/ultramodern-tooling/commands/migrate-strict-effect/toolchain-pins.js

@@ -35,6 +35,7 @@ function updateRootPackageToolchain(packageJson) {
     const devDependencies = ensureRecord(packageJson, 'devDependencies', 'package.json devDependencies');
     for (const packageName of retiredRootToolingDependencies)delete devDependencies[packageName];
     devDependencies["@typescript/native"] = ULTRAMODERN_PACKAGE_PINS.rootDevDependencies["@typescript/native"];
+    devDependencies['@types/node'] = ULTRAMODERN_PACKAGE_PINS.rootDevDependencies["@types/node"];
     devDependencies.miniflare = ULTRAMODERN_PACKAGE_PINS.rootDevDependencies.miniflare;
 }
 function updateMiseTools(content) {

package/dist/esm/ultramodern-tooling/commands/migrate-strict-effect.js

@@ -18,6 +18,7 @@ import { ensureBffEffectDependencies, updateGeneratedPackageScripts, updateGener
 import { createMigrationPackageSource } from "./migrate-strict-effect/package-source.js";
 import { updateGeneratedPnpmWorkspacePolicy, validateGeneratedPnpmLockReleaseAgePolicy } from "./migrate-strict-effect/pnpm-policy.js";
 import { ensureGeneratedModuleFederationBridgeRouterOptOut, preflightModuleFederationBridgeRouter, removeRetiredReactRouterDependency } from "./migrate-strict-effect/react-router-retirement.js";
+import { ensureSharedApiInfrastructure } from "./migrate-strict-effect/shared-api-infrastructure.js";
 import { updateGeneratedToolchainFiles, updateRootPackageToolchain } from "./migrate-strict-effect/toolchain-pins.js";
 import { hasFlag } from "./options.js";
 const retiredMetadataPaths = [
@@ -282,6 +283,7 @@ function migrateStrictEffect(args, context, io, dryRun, skipInstall) {
     const verticalApps = migrated.topology.apps.filter((app)=>'shell' !== app.kind);
     const hasBackendSurface = verticalApps.some((app)=>app.api);
     const shellOnly = 0 === verticalApps.length;
+    if (hasBackendSurface) ensureSharedApiInfrastructure(io, migrated.workspace.packageScope, packageSource);
     if (shellOnly) {
         io.log('Shell-only workspace: skipping backend-federation and Zerops runtime stages.');
         for (const relativePath of [

package/dist/esm/ultramodern-workspace/api/client.js

@@ -2,7 +2,7 @@ import { resolveApiProtocol, resolveApiStem, verticalApiApps } from "../descript
 import { packageName, toPascalCase } from "../naming.js";
 import { createCheckoutCartClientExports, serviceHasCheckoutCartState } from "./checkout-cart.js";
 import { verticalApiErrorStem, verticalApiExport, verticalApiGroupName, verticalApiNotFoundErrorExport } from "./names.js";
-function createApiClient(service, contractImportPath) {
+function createApiClient(service, contractImportPath, options) {
     const apiExport = verticalApiExport(service);
     const contractExport = verticalApiGroupName(service);
     const stem = resolveApiStem(service);
@@ -118,7 +118,7 @@ export const ${readinessName} = (
     operationContext:
       options.operationContext ?? ${groupName}OperationContexts.readiness,
   }).pipe(
-    Effect.flatMap(client => client.${groupName}.readiness({})),
+    Effect.flatMap(client => client.${options ? 'foundation' : groupName}.readiness({})),
   );
 
 export const ${getName} = (

package/dist/esm/ultramodern-workspace/api/service.js

@@ -4,23 +4,22 @@ import { packageName } from "../naming.js";
 import { createCheckoutCartServerHandlers, createCheckoutCartServerState } from "./checkout-cart.js";
 import { verticalApiExport, verticalApiGroupName, verticalApiNotFoundErrorExport } from "./names.js";
 import { createRpcApiServiceEntry, rpcPath, verticalRpcContractExport, verticalRpcGroupExport } from "./rpc.js";
-function createApiServiceEntry(service, contractImportPath) {
+function createApiServiceEntry(service, contractImportPath, options) {
     if ((service.api?.protocol ?? 'rest') === 'rpc') return createRpcApiServiceEntry(service);
     const apiExport = verticalApiExport(service);
     const groupName = verticalApiGroupName(service);
     const notFoundErrorExport = verticalApiNotFoundErrorExport(service);
     const stem = resolveApiStem(service);
-    return `import {
-  defineEffectBff,
+    const assemblyImport = options ? `import { assembleEffectBffRuntime } from '${packageName(options.scope, 'shared-contracts')}/server/effect-bff-runtime';\n` : '';
+    return `${assemblyImport}import {
+  ${options ? '' : 'defineEffectBff,'}
   Effect,
   HttpApiBuilder,
   Layer,
 } from '@modern-js/plugin-bff/effect-edge';
-import type {
-  EffectBffDefinition,
-  EffectBffRuntime,
+${options ? '' : `import type {
   EffectRuntimeLayer,
-} from '@modern-js/plugin-bff/effect-edge';
+} from '@modern-js/plugin-bff/effect-edge';`}
 import { ultramodernApiMarker } from '../shared/ultramodern-build.ts';
 import {
   ${apiExport},
@@ -50,6 +49,31 @@ const operationAttributes = (operationContext: OperationContext) => ({
       : {}),
   });
 
+${options ? `const ${groupName}ReadinessLayer = HttpApiBuilder.group(
+  ${apiExport},
+  'foundation',
+  handlers => handlers
+      .handle('readiness', () =>
+        Effect.succeed({
+          checks: {
+            api: 'ready' as const,
+            moduleFederation: 'ready' as const,
+            ssr: 'ready' as const,
+            translations: 'ready' as const,
+          },
+          marker: ultramodernApiMarker,
+          status: 'ready' as const,
+          versionSkew: 'none' as const,
+        }).pipe(
+          Effect.withSpan('ultramodern.api.${groupName}.readiness', {
+            attributes: operationAttributes(${groupName}OperationContexts.readiness),
+            kind: 'server',
+          }),
+        ),
+      )
+,
+);` : ''}
+
 const ${groupName}Layer = HttpApiBuilder.group(
   ${apiExport},
   '${groupName}',
@@ -68,7 +92,7 @@ const ${groupName}Layer = HttpApiBuilder.group(
           }),
         ),
       )
-      .handle('readiness', () =>
+${options ? '' : `      .handle('readiness', () =>
         Effect.succeed({
           checks: {
             api: 'ready' as const,
@@ -86,6 +110,7 @@ const ${groupName}Layer = HttpApiBuilder.group(
           }),
         ),
       )
+`}
       .handle('get', ({ params }) => {
         const matchedItem = ${groupName}Items.find(
           candidate => candidate.id === params.id,
@@ -125,14 +150,18 @@ const ${groupName}Layer = HttpApiBuilder.group(
       )${createCheckoutCartServerHandlers(service)},
 );
 
-const layer = HttpApiBuilder.layer(${apiExport}).pipe(
-  Layer.provide(${groupName}Layer),
-) satisfies EffectRuntimeLayer;
-const apiRuntime: EffectBffDefinition<typeof ${apiExport}, EffectRuntimeLayer> &
-  EffectBffRuntime<typeof ${apiExport}, EffectRuntimeLayer> = defineEffectBff({
-  api: ${apiExport},
-  layer,
-});
+${options ? `const apiHandlersLive = Layer.mergeAll(${groupName}Layer, ${groupName}ReadinessLayer);
+export const make${apiExport[0].toUpperCase()}${apiExport.slice(1)}Runtime = () =>
+  assembleEffectBffRuntime({
+    api: ${apiExport},
+    handlers: apiHandlersLive,
+  });` : `export const make${apiExport[0].toUpperCase()}${apiExport.slice(1)}Runtime = () => {
+  const layer = HttpApiBuilder.layer(${apiExport}).pipe(
+    Layer.provide(${groupName}Layer),
+  ) satisfies EffectRuntimeLayer;
+  return defineEffectBff({ api: ${apiExport}, layer });
+};`}
+const apiRuntime = make${apiExport[0].toUpperCase()}${apiExport.slice(1)}Runtime();
 
 export default apiRuntime;
 `;

package/dist/esm/ultramodern-workspace/api/shared.js

@@ -1,6 +1,6 @@
 import { resolveApiPrefix, resolveApiStem } from "../descriptors.js";
 import { renderTemplate } from "../fs-io.js";
-import { toPascalCase } from "../naming.js";
+import { packageName, toPascalCase } from "../naming.js";
 import { createCheckoutCartApiContractFields, createCheckoutCartEndpointDefinitions, createCheckoutCartOperationContexts, createCheckoutCartSharedSchemas } from "./checkout-cart.js";
 import { verticalApiCreatePayloadSchemaExport, verticalApiExport, verticalApiGroupName, verticalApiMarkerSchemaExport, verticalApiName, verticalApiNotFoundErrorExport, verticalApiNotFoundSchemaExport, verticalApiReadinessSchemaExport, verticalApiSchemaExport } from "./names.js";
 function createSharedApiImports() {
@@ -13,7 +13,7 @@ function createSharedApiImports() {
 } from '@modern-js/plugin-bff/effect-client';
 `;
 }
-function createSharedApiContract(service) {
+function createSharedApiContract(service, shared = false) {
     const schemaExport = verticalApiSchemaExport(service);
     const markerSchemaExport = verticalApiMarkerSchemaExport(service);
     const readinessSchemaExport = verticalApiReadinessSchemaExport(service);
@@ -70,7 +70,7 @@ function createSharedApiContract(service) {
         listOperationContext,
         readinessOperationContext
     }).trim();
-    return `export interface ${markerType} {
+    return `${shared ? `export type ${markerType} = MicroVerticalBuildMarker;` : `export interface ${markerType} {
   readonly appId: string;
   readonly build: string;
   readonly buildMarker: string;
@@ -80,7 +80,7 @@ function createSharedApiContract(service) {
   readonly surface: string;
   readonly unitId: string;
   readonly version: string;
-}
+}`}
 
 export interface ${itemType} {
   readonly id: string;
@@ -88,7 +88,7 @@ export interface ${itemType} {
   readonly title: string;
 }
 
-export interface ${readinessType} {
+${shared ? `export type ${readinessType} = MicroVerticalReadiness;` : `export interface ${readinessType} {
   readonly checks: {
     readonly api: 'ready';
     readonly moduleFederation: 'ready';
@@ -98,7 +98,7 @@ export interface ${readinessType} {
   readonly marker: ${markerType};
   readonly status: 'ready';
   readonly versionSkew: 'none';
-}
+}`}
 
 export interface ${createPayloadType} {
   readonly title: string;
@@ -117,7 +117,7 @@ export interface ${notFoundErrorExport} {
   readonly id: string;
 }
 
-export const ${markerSchemaExport}: Schema.Codec<${markerType}> = Schema.Struct({
+${shared ? `export const ${markerSchemaExport}: Schema.Codec<${markerType}> = MicroVerticalBuildMarkerSchema;` : `export const ${markerSchemaExport}: Schema.Codec<${markerType}> = Schema.Struct({
   appId: Schema.String,
   build: Schema.String,
   buildMarker: Schema.String,
@@ -127,7 +127,7 @@ export const ${markerSchemaExport}: Schema.Codec<${markerType}> = Schema.Struct(
   surface: Schema.String,
   unitId: Schema.String,
   version: Schema.String,
-});
+});`}
 
 export const ${schemaExport}: Schema.Codec<${itemType}> = Schema.Struct({
   id: Schema.String,
@@ -135,7 +135,7 @@ export const ${schemaExport}: Schema.Codec<${itemType}> = Schema.Struct({
   title: Schema.String,
 });
 
-export const ${readinessSchemaExport}: Schema.Codec<${readinessType}> = Schema.Struct({
+${shared ? `export const ${readinessSchemaExport}: Schema.Codec<${readinessType}> = MicroVerticalReadinessSchema;` : `export const ${readinessSchemaExport}: Schema.Codec<${readinessType}> = Schema.Struct({
   checks: Schema.Struct({
     api: Schema.Literal('ready'),
     moduleFederation: Schema.Literal('ready'),
@@ -145,7 +145,7 @@ export const ${readinessSchemaExport}: Schema.Codec<${readinessType}> = Schema.S
   marker: ${markerSchemaExport},
   status: Schema.Literal('ready'),
   versionSkew: Schema.Literal('none'),
-});
+});`}
 
 export const ${createPayloadSchemaExport}: Schema.Codec<${createPayloadType}> = Schema.Struct({
   title: Schema.String,
@@ -157,7 +157,7 @@ ${checkoutCartSharedSchemaSection}export const ${notFoundSchemaExport}: Schema.C
   HttpApiSchema.status(404),
 );
 
-export interface OperationContext {
+${shared ? 'export type OperationContext = MicroVerticalOperationContext;' : `export interface OperationContext {
   method: string;
   operationId: string;
   routePath: string;
@@ -169,9 +169,14 @@ export interface OperationContext {
     | 'data-platform'
     | 'unknown';
   traceId?: string;
-}
+}`}
 
-export const ${apiExport} = HttpApi.make('${apiName}').add(
+${shared ? `export const ${groupName}FoundationApi = HttpApi.make('${apiName}Foundation').add(
+  HttpApiGroup.make('foundation').add(
+    HttpApiEndpoint.get('readiness', '/${stem}/readiness', { success: ${readinessSchemaExport} }),
+  ),
+);` : ''}
+export const ${apiExport} = HttpApi.make('${apiName}')${shared ? `.addHttpApi(${groupName}FoundationApi)` : ''}.add(
   HttpApiGroup.make('${groupName}')
     .add(
       HttpApiEndpoint.get('list', '/${stem}', {
@@ -183,11 +188,12 @@ export const ${apiExport} = HttpApi.make('${apiName}').add(
         }),
       }),
     )
-    .add(
+${shared ? '' : `    .add(
       HttpApiEndpoint.get('readiness', '/${stem}/readiness', {
         success: ${readinessSchemaExport},
       }),
     )
+`}
     .add(
       HttpApiEndpoint.get('get', '/${stem}/:id', {
         error: ${notFoundSchemaExport},
@@ -208,7 +214,7 @@ export const ${apiExport} = HttpApi.make('${apiName}').add(
 );
 
 export const ${groupName}OperationContexts = {
-${operationContextEntries}
+${shared ? operationContextEntries.replaceAll(/(\w+: )\{([\s\S]*?)\},/gu, (_, key, fields)=>`${key}createMicroVerticalOperationContext({${fields.replace(/\n\s*source: 'generated-client',/u, '')}}),`) : operationContextEntries}
 } satisfies Record<string, OperationContext>;
 
 export const ${groupName}ApiContract = {
@@ -219,8 +225,12 @@ ${createCheckoutCartApiContractFields(service)}  ownerId: '${service.id}',
 } as const;
 `;
 }
-function createSharedApi(service) {
+function createSharedApi(service, options) {
+    const imports = options ? `import { MicroVerticalBuildMarkerSchema, MicroVerticalReadinessSchema, createMicroVerticalOperationContext } from '${packageName(options.scope, 'shared-contracts')}/microvertical-api-baseline';
+import type { MicroVerticalBuildMarker, MicroVerticalReadiness, MicroVerticalOperationContext } from '${packageName(options.scope, 'shared-contracts')}/microvertical-api-baseline';
+` : '';
     return `${createSharedApiImports()}
-${createSharedApiContract(service)}`;
+${imports}
+${createSharedApiContract(service, void 0 !== options)}`;
 }
 export { createSharedApi };

package/dist/esm/ultramodern-workspace/mf-validation/inspect.js

@@ -11,7 +11,11 @@ function extractExposes(configPath, value) {
     if (array) return array.sort();
     throw new Error(`Cannot statically extract Module Federation exposes from ${configPath}; use a literal exposes object or string array.`);
 }
-function extractDtsSettings(configPath, value) {
+function extractDtsSettings(configPath, value, exposes) {
+    if ('false' === value) {
+        if (exposes.length > 0) throw new Error(`Module Federation DTS cannot be disabled for exposed app ${configPath}.`);
+        return {};
+    }
     if (void 0 === value) return {};
     const dts = parseObjectLiteral(value);
     if (!dts || dts.hasSpread) throw new Error(`Cannot statically extract Module Federation DTS settings from ${configPath}; use a literal dts object.`);
@@ -38,7 +42,7 @@ function inspectModuleFederationConfigSource(source, appDir, configPath) {
     return {
         appDir,
         configPath,
-        dts: extractDtsSettings(configPath, properties.properties.get('dts')),
+        dts: extractDtsSettings(configPath, properties.properties.get('dts'), exposes),
         exposes,
         hostOnlyNoExposes
     };

package/dist/esm/ultramodern-workspace/module-federation/reexport-module.js

@@ -45,22 +45,17 @@ const ultramodernBuildArtifact = {
   },
 } as const;
 
-export { ultramodernBuildArtifact };
-
 export const ultramodernDeliveryUnit =
   ultramodernBuildArtifact.deliveryUnit;
-export const ultramodernVerticalIdentity = ultramodernDeliveryUnit;
 export const ultramodernUiMarker = ultramodernBuildArtifact.surfaces.ui;
 export const ultramodernApiMarker = ultramodernBuildArtifact.surfaces.api;
 `;
 }
 function createUltramodernBuildReexportModule() {
     return `export {
-  ultramodernBuildArtifact,
   ultramodernApiMarker,
   ultramodernDeliveryUnit,
   ultramodernUiMarker,
-  ultramodernVerticalIdentity,
 } from '../shared/ultramodern-build';
 `;
 }

package/dist/esm/ultramodern-workspace/package-json.js

@@ -171,7 +171,7 @@ function createAppPackage(scope, app, packageSource, enableTailwind, remotes = [
     if (Object.keys(packageExports).length > 0) packageJson.exports = packageExports;
     return packageJson;
 }
-function createSharedPackage(scope, id, description) {
+function createSharedPackage(scope, id, description, packageSource) {
     const packageJson = {
         private: true,
         name: packageName(scope, id),
@@ -188,6 +188,17 @@ function createSharedPackage(scope, id, description) {
             '@effect/tsgo': ULTRAMODERN_PACKAGE_PINS.appDevDependencies["@effect/tsgo"]
         }
     };
+    if ('shared-contracts' === id) {
+        packageJson.exports = {
+            '.': './src/index.ts',
+            './microvertical-api-baseline': './src/microvertical-api-baseline.ts',
+            './server/effect-bff-runtime': './src/effect-bff-runtime.ts'
+        };
+        packageJson.dependencies = {
+            ...ULTRAMODERN_PACKAGE_PINS.bffEffectDependencies,
+            '@modern-js/plugin-bff': packageSource ? modernPackageSpecifier('@modern-js/plugin-bff', packageSource) : WORKSPACE_PACKAGE_VERSION
+        };
+    }
     if ('shared-design-tokens' === id) packageJson.exports = {
         ...packageJson.exports,
         './tokens.css': './src/tokens.css'

package/dist/esm/ultramodern-workspace/policy.js

@@ -249,6 +249,7 @@ const ULTRAMODERN_PACKAGE_PINS = {
     rootDevDependencies: {
         '@effect/tsgo': EFFECT_TSGO_VERSION,
         "@typescript/native": `npm:typescript@${TYPESCRIPT_VERSION}`,
+        '@types/node': TYPES_NODE_VERSION,
         'cross-env': CROSS_ENV_VERSION,
         lefthook: LEFTHOOK_VERSION,
         miniflare: MINIFLARE_VERSION,

package/dist/esm/ultramodern-workspace/tsconfigs.js

@@ -6,6 +6,9 @@ function createTsConfigBase() {
     return {
         compilerOptions: {
             target: 'ESNext',
+            types: [
+                'node'
+            ],
             lib: [
                 'ESNext',
                 'DOM',

package/dist/esm/ultramodern-workspace/workspace-script-plan.js

@@ -139,7 +139,7 @@ function createWorkspaceRootScriptPlan(remotes = [], options = {}) {
         migrateStrictEffect: rootToolingWrapperCommand('migrateStrictEffect'),
         zeropsMaterialize: "node ./scripts/materialize-zerops-runtime.mjs",
         contractCheck: rootToolingWrapperCommand('validate'),
-        typecheck: options.typecheck ?? `${rootToolingWrapperCommand('typecheck')} --project tsconfig.json`,
+        typecheck: options.typecheck ?? `${rootToolingWrapperCommand('typecheck')} --build tsconfig.json`,
         check: `pnpm format:check && pnpm lint && pnpm typecheck && pnpm skills:check && pnpm i18n:boundaries && pnpm api:check && pnpm contract:check && pnpm performance:readiness${bridgeCheck}`
     };
 }

package/dist/esm/ultramodern-workspace/workspace-scripts.js

@@ -129,6 +129,7 @@ function writeGeneratedWorkspaceScripts(targetDir, scope, enableTailwind, remote
     const hasBackendSurface = remotes.some(appHasApi);
     writeWorkspaceOwnedMtsScript(targetDir, 'check-ultramodern-i18n-boundaries', createWorkspaceI18nBoundaryValidationScript());
     writeWorkspaceOwnedMtsScript(targetDir, 'check-ultramodern-api-boundaries', createWorkspaceApiBoundaryValidationScript());
+    writeWorkspaceOwnedMtsScript(targetDir, 'microvertical-api-baseline-boundary', external_fs_io_js_readFileTemplate("workspace-scripts/microvertical-api-baseline-boundary.mts"));
     if (!shellOnly) {
         writeFileReplacing(targetDir, "scripts/materialize-zerops-runtime.mjs", createZeropsRuntimeMaterializationScript());
         writeWorkspaceOwnedMtsScript(targetDir, 'proof-workerd-ssr', createWorkerdSsrProofScript());
@@ -156,6 +157,10 @@ function migratedWorkspaceScriptArtifacts(options) {
             content: createWorkspaceI18nBoundaryValidationScript(),
             legacyPath: "scripts/check-ultramodern-i18n-boundaries.mjs"
         },
+        {
+            relativePath: "scripts/microvertical-api-baseline-boundary.mts",
+            content: external_fs_io_js_readFileTemplate("workspace-scripts/microvertical-api-baseline-boundary.mts")
+        },
         {
             relativePath: "scripts/check-ultramodern-api-boundaries.mts",
             content: createWorkspaceApiBoundaryValidationScript(),

package/dist/esm/ultramodern-workspace/write-app.js

@@ -88,11 +88,17 @@ function writeAppRouteAndShellFiles({ targetDir, scope, resolvedApp, emitsUi, re
 function writeAppApiAndRemoteExposeFiles({ targetDir, scope, resolvedApp, emitsUi, writeAppFile }) {
     if (appHasApi(resolvedApp)) {
         const rpcProtocol = 'rpc' === resolveApiProtocol(resolvedApp);
-        rpcProtocol ? writeFile(targetDir, `${resolvedApp.directory}/shared/rpc.ts`, createRpcContractFile(resolvedApp)) : writeFile(targetDir, `${resolvedApp.directory}/shared/api.ts`, createSharedApi(resolvedApp));
-        writeFile(targetDir, `${resolvedApp.directory}/api/index.ts`, createApiServiceEntry(resolvedApp, rpcProtocol ? '../shared/rpc.ts' : '../shared/api.ts'));
+        rpcProtocol ? writeFile(targetDir, `${resolvedApp.directory}/shared/rpc.ts`, createRpcContractFile(resolvedApp)) : writeFile(targetDir, `${resolvedApp.directory}/shared/api.ts`, createSharedApi(resolvedApp, {
+            scope
+        }));
+        writeFile(targetDir, `${resolvedApp.directory}/api/index.ts`, createApiServiceEntry(resolvedApp, rpcProtocol ? '../shared/rpc.ts' : '../shared/api.ts', {
+            scope
+        }));
         writeFile(targetDir, `${resolvedApp.directory}/api/backend-federation.ts`, createBackendFederationContractFile(resolvedApp));
         writeFile(targetDir, `${resolvedApp.directory}/api/effect-api.ts`, createBackendEffectApiExpose(scope, resolvedApp));
-        rpcProtocol ? writeFile(targetDir, `${resolvedApp.directory}/src/api/${resolvedApp.api.stem}-rpc-client.ts`, createRpcClientFile(resolvedApp)) : writeFile(targetDir, `${resolvedApp.directory}/src/api/${resolvedApp.api.stem}-client.ts`, createApiClient(resolvedApp, '../../shared/api'));
+        rpcProtocol ? writeFile(targetDir, `${resolvedApp.directory}/src/api/${resolvedApp.api.stem}-rpc-client.ts`, createRpcClientFile(resolvedApp)) : writeFile(targetDir, `${resolvedApp.directory}/src/api/${resolvedApp.api.stem}-client.ts`, createApiClient(resolvedApp, '../../shared/api', {
+            scope
+        }));
     }
     if ('vertical' === resolvedApp.kind && emitsUi) {
         writeAppFile('src/federation-entry.tsx', createRemoteEntry(resolvedApp));

package/dist/esm/ultramodern-workspace/write-workspace.js

@@ -5,7 +5,7 @@ import { createSharedDesignTokensCss } from "./app-files.js";
 import { normalizeUltramodernBridgeConfig } from "./bridge-config.js";
 import { createDevelopmentOverlay, createOwnership, createTopology, createUltramodernConfig } from "./contracts.js";
 import { ULTRAMODERN_CONFIG_PATH, createShellHost, sharedPackages, shellApp } from "./descriptors.js";
-import { copyRootTemplate, formatGeneratedWorkspaceFiles, writeFile, writeFileReplacing, writeJson } from "./fs-io.js";
+import { copyRootTemplate, formatGeneratedWorkspaceFiles, readFileTemplate, writeFile, writeFileReplacing, writeJson } from "./fs-io.js";
 import { createFileSnapshot, createGenerationResult, diffFileSnapshots } from "./generation-result.js";
 import { assertUniqueTailwindPrefixes, toPackageScope } from "./naming.js";
 import { runCodeSmithOverlays } from "./overlays.js";
@@ -19,12 +19,14 @@ import { createZeropsYaml } from "./zerops.js";
 function hasExplicitInstallRequest(options) {
     return void 0 !== options.packageSource && 'workspace' !== options.packageSource.strategy;
 }
-function writeSharedPackages(targetDir, scope) {
+function writeSharedPackages(targetDir, scope, packageSource) {
     for (const sharedPackage of sharedPackages){
-        writeJson(targetDir, `${sharedPackage.directory}/package.json`, createSharedPackage(scope, sharedPackage.id, sharedPackage.description));
+        writeJson(targetDir, `${sharedPackage.directory}/package.json`, createSharedPackage(scope, sharedPackage.id, sharedPackage.description, packageSource));
         writeJson(targetDir, `${sharedPackage.directory}/tsconfig.json`, createSharedPackageTsConfig(sharedPackage.directory));
     }
     writeFile(targetDir, 'packages/shared-contracts/src/index.ts', createSharedContractsIndex());
+    writeFile(targetDir, 'packages/shared-contracts/src/microvertical-api-baseline.ts', readFileTemplate('packages/microvertical-api-baseline.ts'));
+    writeFile(targetDir, 'packages/shared-contracts/src/effect-bff-runtime.ts', readFileTemplate('packages/effect-bff-runtime.ts'));
     writeFile(targetDir, 'packages/shared-design-tokens/src/index.ts', `export const sharedDesignTokens = {
   color: {
     accent: '#2f8f68',
@@ -144,7 +146,7 @@ function generateUltramodernWorkspaceInPlace(options, logicalWorkspaceRoot = opt
     writeJson(options.targetDir, ULTRAMODERN_CONFIG_PATH, createCompactUltramodernConfig(scope, options.modernVersion, packageSource, createdApps, enableTailwind, bridge));
     writeApp(options.targetDir, scope, shellApp, packageSource, enableTailwind, initialVerticals, bridge);
     for (const remote of initialVerticals)writeApp(options.targetDir, scope, remote, packageSource, enableTailwind, initialVerticals, bridge);
-    writeSharedPackages(options.targetDir, scope);
+    writeSharedPackages(options.targetDir, scope, packageSource);
     writeGeneratedWorkspaceScripts(options.targetDir, scope, enableTailwind, initialVerticals, releaseCohort);
     const preliminaryAfterFiles = createFileSnapshot(options.targetDir);
     const preliminaryDiff = diffFileSnapshots(beforeFiles, preliminaryAfterFiles);

package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect/generated-artifacts-typescript.js

@@ -71,6 +71,7 @@ function mergeTypeScriptConfig(generated, existing) {
         ...existingCompilerOptions,
         ...generatedCompilerOptions
     };
+    if (Array.isArray(generatedCompilerOptions.types)) compilerOptions.types = mergeUniqueJsonValues(generatedCompilerOptions.types, existingCompilerOptions.types);
     if (Array.isArray(generatedCompilerOptions.plugins) || Array.isArray(existingCompilerOptions.plugins)) compilerOptions.plugins = mergeTypeScriptPlugins(generatedCompilerOptions.plugins, existingCompilerOptions.plugins);
     const merged = {
         ...existingConfig,

package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect/package-cohort.js

@@ -136,6 +136,8 @@ function mergeGeneratedScript(consumer, framework, canRetireLegacyOxfmtCliExclus
     const frameworkSegmentSet = new Set(frameworkSegments);
     const canonicalFrameworkSegment = (segment)=>{
         if (frameworkSegmentSet.has(segment)) return segment;
+        const referenceBuild = segment.replace('--project tsconfig.json', '--build tsconfig.json');
+        if (frameworkSegmentSet.has(referenceBuild)) return referenceBuild;
         const portableEnvironmentSegment = `cross-env ${segment}`;
         if (frameworkSegmentSet.has(portableEnvironmentSegment)) return portableEnvironmentSegment;
         const portableOxfmtSegment = segment.replace(/ '!repos\/\*\*'$/u, '');

package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect/shared-api-infrastructure.js

@@ -0,0 +1,51 @@
+import "node:module";
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { readFileTemplate } from "../../../ultramodern-workspace/fs-io.js";
+import { createSharedPackage, createSharedPackageTsConfig } from "../../../ultramodern-workspace/package-json.js";
+import { readJsonFile, writeJsonFile } from "./io.js";
+const directory = 'packages/shared-contracts';
+function record(value, label) {
+    if (null === value || 'object' != typeof value || Array.isArray(value)) throw new Error(`${label} must be an object; resolve it before migration.`);
+    return value;
+}
+function ensureSharedApiInfrastructure(io, scope, packageSource) {
+    for (const relativePath of [
+        'packages',
+        directory,
+        `${directory}/package.json`,
+        `${directory}/src`,
+        `${directory}/src/index.ts`
+    ])if (node_fs.lstatSync(node_path.join(io.workspaceRoot, relativePath), {
+        throwIfNoEntry: false
+    })?.isSymbolicLink()) throw new Error(`Shared API migration cannot write through a symbolic link: ${relativePath}`);
+    const manifestPath = node_path.join(io.workspaceRoot, directory, 'package.json');
+    const defaults = createSharedPackage(scope, 'shared-contracts', 'Shared workspace contracts', packageSource);
+    const manifest = node_fs.existsSync(manifestPath) ? record(readJsonFile(manifestPath), `${directory}/package.json`) : defaults;
+    const exports = void 0 === manifest.exports ? {} : 'string' == typeof manifest.exports ? {
+        '.': manifest.exports
+    } : record(manifest.exports, `${directory}/package.json exports`);
+    if (Object.keys(exports).some((key)=>!key.startsWith('.')) || void 0 !== exports['.'] && './src/index.ts' !== exports['.']) throw new Error(`${directory}/package.json exports must expose ./src/index.ts at "." before adding shared API infrastructure; consumer exports were not overwritten.`);
+    for (const [subpath, target] of Object.entries(record(defaults.exports, 'Shared contract exports')))if (void 0 !== exports[subpath] && exports[subpath] !== target) throw new Error(`${directory}/package.json ${subpath} must expose ${String(target)}; consumer exports were not overwritten.`);
+    const dependencies = record(manifest.dependencies ?? {}, `${directory}/package.json dependencies`);
+    manifest.exports = {
+        ...record(defaults.exports, 'Shared contract exports'),
+        ...exports
+    };
+    manifest.dependencies = {
+        ...record(defaults.dependencies, 'Shared contract dependencies'),
+        ...dependencies
+    };
+    const writeMissing = (relativePath, content)=>{
+        const filePath = node_path.join(io.workspaceRoot, directory, relativePath);
+        if (void 0 === node_fs.lstatSync(filePath, {
+            throwIfNoEntry: false
+        })) io.writeGenerated(filePath, content);
+    };
+    writeMissing('src/effect-bff-runtime.ts', readFileTemplate('packages/effect-bff-runtime.ts'));
+    writeMissing('src/microvertical-api-baseline.ts', readFileTemplate('packages/microvertical-api-baseline.ts'));
+    writeMissing('tsconfig.json', `${JSON.stringify(createSharedPackageTsConfig(directory), null, 2)}\n`);
+    writeMissing('src/index.ts', readFileTemplate('packages/shared-contracts-index.ts'));
+    writeJsonFile(io, manifestPath, manifest);
+}
+export { ensureSharedApiInfrastructure };

package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect/toolchain-pins.js

@@ -36,6 +36,7 @@ function updateRootPackageToolchain(packageJson) {
     const devDependencies = ensureRecord(packageJson, 'devDependencies', 'package.json devDependencies');
     for (const packageName of retiredRootToolingDependencies)delete devDependencies[packageName];
     devDependencies["@typescript/native"] = ULTRAMODERN_PACKAGE_PINS.rootDevDependencies["@typescript/native"];
+    devDependencies['@types/node'] = ULTRAMODERN_PACKAGE_PINS.rootDevDependencies["@types/node"];
     devDependencies.miniflare = ULTRAMODERN_PACKAGE_PINS.rootDevDependencies.miniflare;
 }
 function updateMiseTools(content) {

package/dist/esm-node/ultramodern-tooling/commands/migrate-strict-effect.js

@@ -19,6 +19,7 @@ import { ensureBffEffectDependencies, updateGeneratedPackageScripts, updateGener
 import { createMigrationPackageSource } from "./migrate-strict-effect/package-source.js";
 import { updateGeneratedPnpmWorkspacePolicy, validateGeneratedPnpmLockReleaseAgePolicy } from "./migrate-strict-effect/pnpm-policy.js";
 import { ensureGeneratedModuleFederationBridgeRouterOptOut, preflightModuleFederationBridgeRouter, removeRetiredReactRouterDependency } from "./migrate-strict-effect/react-router-retirement.js";
+import { ensureSharedApiInfrastructure } from "./migrate-strict-effect/shared-api-infrastructure.js";
 import { updateGeneratedToolchainFiles, updateRootPackageToolchain } from "./migrate-strict-effect/toolchain-pins.js";
 import { hasFlag } from "./options.js";
 const retiredMetadataPaths = [
@@ -283,6 +284,7 @@ function migrateStrictEffect(args, context, io, dryRun, skipInstall) {
     const verticalApps = migrated.topology.apps.filter((app)=>'shell' !== app.kind);
     const hasBackendSurface = verticalApps.some((app)=>app.api);
     const shellOnly = 0 === verticalApps.length;
+    if (hasBackendSurface) ensureSharedApiInfrastructure(io, migrated.workspace.packageScope, packageSource);
     if (shellOnly) {
         io.log('Shell-only workspace: skipping backend-federation and Zerops runtime stages.');
         for (const relativePath of [