@bleedingdev/modern-js-create 3.5.0-ultramodern.9 → 3.5.0-ultramodern.90

package/dist/esm/ultramodern-tooling/config/normalize.js

@@ -0,0 +1,173 @@
+import node_path from "node:path";
+import { normalizeUltramodernBridgeConfig } from "../../ultramodern-workspace/bridge-config.js";
+import { ULTRAMODERN_CONFIG_PATH, createNeutralOwnership, shellApp } from "../../ultramodern-workspace/descriptors.js";
+import { toKebabCase } from "../../ultramodern-workspace/naming.js";
+import { resolveConfiguredAdditionalShells } from "../../ultramodern-workspace/shells.js";
+import { isVerticalApiProtocol, isVerticalPreset, isWorkspaceDeliveryUnitKind } from "../../ultramodern-workspace/types.js";
+import { packageScopeFromRoot } from "./metadata.js";
+class UnsupportedUltramodernConfigError extends Error {
+    constructor(sourcePath, issue){
+        const value = formatUnsupportedConfigValue(issue.value);
+        const message = 'schemaVersion' === issue.field ? formatSchemaVersionError(sourcePath, issue.reason, value) : `Unsupported UltraModern config app kind ${value} at ${sourcePath} topology.apps[${issue.index}].kind. Supported kinds: shell, vertical.`;
+        super(message), this.sourcePath = sourcePath, this.issue = issue;
+        this.name = 'UnsupportedUltramodernConfigError';
+    }
+}
+function normalizeCompactConfig(workspaceRoot, sourcePath, config) {
+    const schemaVersion = config.schemaVersion;
+    if (1 !== schemaVersion) throw new UnsupportedUltramodernConfigError(sourcePath, {
+        field: 'schemaVersion',
+        value: schemaVersion,
+        reason: void 0 === schemaVersion ? 'missing' : Number.isInteger(schemaVersion) ? 'unsupported' : 'non-integer'
+    });
+    return normalizeCompactConfigV1(workspaceRoot, sourcePath, config);
+}
+function normalizeCompactConfigV1(workspaceRoot, sourcePath, config) {
+    const packageSource = config.packageSource && 'object' == typeof config.packageSource ? {
+        strategy: 'install' === config.packageSource.strategy ? 'install' : 'workspace',
+        modernPackageVersion: 'string' == typeof config.packageSource.modernPackageVersion ? config.packageSource.modernPackageVersion : 'workspace:*',
+        registry: 'string' == typeof config.packageSource.registry ? config.packageSource.registry : void 0,
+        aliasScope: 'string' == typeof config.packageSource.aliasScope ? config.packageSource.aliasScope : void 0,
+        aliasPackageNamePrefix: 'string' == typeof config.packageSource.aliasPackageNamePrefix ? config.packageSource.aliasPackageNamePrefix : void 0
+    } : void 0;
+    return {
+        schemaVersion: 1,
+        profile: 'string' == typeof config.profile ? config.profile : void 0,
+        source: 'compact',
+        sourcePath,
+        workspace: {
+            packageScope: 'string' == typeof config.workspace?.packageScope ? config.workspace.packageScope : packageScopeFromRoot(workspaceRoot)
+        },
+        packageSource,
+        features: {
+            tailwind: config.features?.tailwind !== false
+        },
+        bridge: normalizeUltramodernBridgeConfig(config.bridge),
+        topology: {
+            apps: Array.isArray(config.topology?.apps) ? config.topology.apps.map((app, index)=>{
+                if ('shell' !== app.kind && 'vertical' !== app.kind) throw new UnsupportedUltramodernConfigError(sourcePath, {
+                    field: 'topology.apps.kind',
+                    index,
+                    value: app.kind
+                });
+                return {
+                    id: String(app.id),
+                    kind: app.kind,
+                    path: 'string' == typeof app.path ? app.path : '.',
+                    package: 'string' == typeof app.package ? app.package : void 0,
+                    packageSuffix: 'string' == typeof app.packageSuffix ? app.packageSuffix : void 0,
+                    displayName: 'string' == typeof app.displayName ? app.displayName : void 0,
+                    domain: 'string' == typeof app.domain ? app.domain : void 0,
+                    ...isVerticalPreset(app.surfaceProfile) ? {
+                        surfaceProfile: app.surfaceProfile
+                    } : {},
+                    ...isWorkspaceDeliveryUnitKind(app.deliveryUnitKind) ? {
+                        deliveryUnitKind: app.deliveryUnitKind
+                    } : {},
+                    port: 'number' == typeof app.port ? app.port : void 0,
+                    portEnv: 'string' == typeof app.portEnv ? app.portEnv : void 0,
+                    moduleFederation: app.moduleFederation && 'object' == typeof app.moduleFederation ? {
+                        role: 'remote' === app.moduleFederation.role ? 'remote' : 'host',
+                        name: 'string' == typeof app.moduleFederation.name ? app.moduleFederation.name : void 0,
+                        exposes: Array.isArray(app.moduleFederation.exposes) ? app.moduleFederation.exposes.filter((expose)=>'string' == typeof expose) : void 0,
+                        exposePaths: null === app.moduleFederation.exposePaths || 'object' != typeof app.moduleFederation.exposePaths || Array.isArray(app.moduleFederation.exposePaths) ? void 0 : Object.fromEntries(Object.entries(app.moduleFederation.exposePaths).filter((entry)=>'string' == typeof entry[0] && 'string' == typeof entry[1])),
+                        verticalRefs: Array.isArray(app.moduleFederation.verticalRefs) ? app.moduleFederation.verticalRefs.filter((ref)=>'string' == typeof ref) : void 0,
+                        hostOnly: true === app.moduleFederation.hostOnly,
+                        noExposes: true === app.moduleFederation.noExposes
+                    } : void 0,
+                    api: app.api && 'object' == typeof app.api ? {
+                        stem: 'string' == typeof app.api.stem ? app.api.stem : String(app.id),
+                        prefix: 'string' == typeof app.api.prefix ? app.api.prefix : `/${String(app.id)}-api`,
+                        consumedBy: Array.isArray(app.api.consumedBy) ? app.api.consumedBy.filter((consumer)=>'string' == typeof consumer) : [
+                            shellApp.id,
+                            String(app.id)
+                        ],
+                        ...isVerticalApiProtocol(app.api.protocol) ? {
+                            protocol: app.api.protocol
+                        } : {}
+                    } : void 0
+                };
+            }) : []
+        },
+        ...Array.isArray(config.shells) && config.shells.length > 0 ? {
+            shells: config.shells.filter((shell)=>null !== shell && 'object' == typeof shell && !Array.isArray(shell))
+        } : {}
+    };
+}
+function formatUnsupportedConfigValue(value) {
+    if (void 0 === value) return 'missing';
+    return JSON.stringify(value) ?? String(value);
+}
+function formatSchemaVersionError(sourcePath, reason, value) {
+    switch(reason){
+        case 'missing':
+            return `UltraModern config schemaVersion is required in ${sourcePath}. Versionless v1 configs are not supported; set schemaVersion to the integer 1.`;
+        case 'non-integer':
+            return `Invalid UltraModern config schemaVersion ${value} in ${sourcePath}. schemaVersion must be the integer 1; versionless v1 configs are not supported.`;
+        case 'unsupported':
+            return `Unsupported UltraModern config schemaVersion ${value} in ${sourcePath}. Supported schema versions: 1. Versionless v1 configs are not supported.`;
+    }
+}
+function normalizeCompactUltramodernConfig(workspaceRoot, compact) {
+    return normalizeCompactConfig(workspaceRoot, node_path.join(workspaceRoot, ULTRAMODERN_CONFIG_PATH), compact);
+}
+function workspaceAppsFromToolingConfig(config) {
+    return config.topology.apps.map((app)=>{
+        if ('shell' === app.kind) return {
+            ...shellApp,
+            directory: app.path,
+            packageSuffix: app.packageSuffix ?? shellApp.packageSuffix,
+            displayName: app.displayName ?? shellApp.displayName,
+            port: app.port ?? shellApp.port,
+            portEnv: app.portEnv ?? shellApp.portEnv,
+            mfName: app.moduleFederation?.name ?? shellApp.mfName,
+            verticalRefs: app.moduleFederation?.verticalRefs ?? []
+        };
+        const domain = app.domain ?? app.id;
+        const packageSuffix = app.packageSuffix ?? domain;
+        const exposePaths = app.moduleFederation?.exposePaths ?? {};
+        const exposes = Object.fromEntries((app.moduleFederation?.exposes ?? []).map((expose)=>{
+            const configuredPath = exposePaths[expose];
+            const inferredPath = './Route' === expose ? './src/federation-entry.tsx' : './Widget' === expose ? `./src/components/${domain}-widget.tsx` : `./src/components/${toKebabCase(expose.replace(/^\.\//u, ''))}.tsx`;
+            return [
+                expose,
+                configuredPath ?? inferredPath
+            ];
+        }));
+        return {
+            id: app.id,
+            directory: app.path,
+            packageSuffix,
+            displayName: app.displayName ?? `${domain} Vertical`,
+            kind: 'vertical',
+            domain,
+            portEnv: app.portEnv ?? `VERTICAL_${domain.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}_PORT`,
+            port: app.port ?? 0,
+            mfName: app.moduleFederation?.name ?? app.id,
+            exposes,
+            ...app.moduleFederation?.verticalRefs ? {
+                verticalRefs: app.moduleFederation.verticalRefs
+            } : {},
+            ...void 0 === app.surfaceProfile ? {} : {
+                surfaceProfile: app.surfaceProfile
+            },
+            ...void 0 === app.deliveryUnitKind ? {} : {
+                deliveryUnitKind: app.deliveryUnitKind
+            },
+            ...app.api ? {
+                api: app.api
+            } : {},
+            ownership: createNeutralOwnership(app.id)
+        };
+    });
+}
+function additionalShellsFromToolingConfig(config) {
+    return resolveConfiguredAdditionalShells(config);
+}
+function allWorkspaceAppsFromToolingConfig(config) {
+    return [
+        ...workspaceAppsFromToolingConfig(config),
+        ...additionalShellsFromToolingConfig(config)
+    ];
+}
+export { UnsupportedUltramodernConfigError, additionalShellsFromToolingConfig, allWorkspaceAppsFromToolingConfig, normalizeCompactConfig, normalizeCompactUltramodernConfig, workspaceAppsFromToolingConfig };

package/dist/esm/ultramodern-tooling/config/synthesize.js

@@ -0,0 +1,108 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { shellApp } from "../../ultramodern-workspace/descriptors.js";
+import { toKebabCase } from "../../ultramodern-workspace/naming.js";
+import { LEGACY_DEVELOPMENT_OVERLAY_PATH, LEGACY_GENERATED_CONTRACT_PATH, LEGACY_PACKAGE_SOURCE_METADATA_PATH } from "./constants.js";
+import { readJsonObject } from "./json.js";
+import { packageScopeFromRoot, packageSourceFromMetadata, readOverlayPorts } from "./metadata.js";
+function synthesizeCompactUltramodernConfig(workspaceRoot) {
+    const contractPath = node_path.join(workspaceRoot, LEGACY_GENERATED_CONTRACT_PATH);
+    if (!node_fs.existsSync(contractPath)) return;
+    const contract = readJsonObject(contractPath);
+    const sources = [
+        LEGACY_GENERATED_CONTRACT_PATH
+    ];
+    const missing = [];
+    const packageSource = packageSourceFromMetadata(workspaceRoot);
+    if (packageSource) sources.push(LEGACY_PACKAGE_SOURCE_METADATA_PATH);
+    else missing.push(LEGACY_PACKAGE_SOURCE_METADATA_PATH);
+    const ports = readOverlayPorts(workspaceRoot);
+    if (node_fs.existsSync(node_path.join(workspaceRoot, LEGACY_DEVELOPMENT_OVERLAY_PATH))) sources.push(LEGACY_DEVELOPMENT_OVERLAY_PATH);
+    else missing.push(LEGACY_DEVELOPMENT_OVERLAY_PATH);
+    const apps = Array.isArray(contract.apps) ? contract.apps : [];
+    const shell = apps.find((app)=>app?.id === shellApp.id);
+    const compact = {
+        schemaVersion: 'number' == typeof contract.schemaVersion ? contract.schemaVersion : 1,
+        ...'string' == typeof contract.profile ? {
+            profile: contract.profile
+        } : {},
+        workspace: {
+            packageScope: packageScopeFromRoot(workspaceRoot)
+        },
+        ...packageSource ? {
+            packageSource: {
+                strategy: packageSource.strategy,
+                modernPackageVersion: packageSource.modernPackageVersion,
+                ...packageSource.registry ? {
+                    registry: packageSource.registry
+                } : {},
+                ...packageSource.aliasScope ? {
+                    aliasScope: packageSource.aliasScope
+                } : {},
+                ...packageSource.aliasPackageNamePrefix ? {
+                    aliasPackageNamePrefix: packageSource.aliasPackageNamePrefix
+                } : {}
+            }
+        } : {},
+        features: {
+            tailwind: shell?.styling?.tailwind !== false
+        },
+        topology: {
+            apps: apps.map((app)=>{
+                const id = String(app.id);
+                const appPath = 'string' == typeof app.path ? app.path : id === shellApp.id ? shellApp.directory : `verticals/${toKebabCase(id)}`;
+                const domain = 'string' == typeof app.i18n?.namespace && 'shell' !== app.i18n.namespace ? app.i18n.namespace : appPath.split('/').at(-1);
+                const moduleFederation = app.moduleFederation && 'object' == typeof app.moduleFederation ? {
+                    role: 'vertical' === app.kind ? 'remote' : 'host',
+                    ...'string' == typeof app.moduleFederation.name ? {
+                        name: app.moduleFederation.name
+                    } : {},
+                    ...Array.isArray(app.moduleFederation.exposes) ? {
+                        exposes: app.moduleFederation.exposes.filter((expose)=>'string' == typeof expose)
+                    } : {},
+                    ...Array.isArray(app.moduleFederation.verticalRefs) ? {
+                        verticalRefs: app.moduleFederation.verticalRefs.filter((ref)=>'string' == typeof ref)
+                    } : {}
+                } : void 0;
+                const api = app.effect && 'object' == typeof app.effect ? {
+                    stem: 'string' == typeof app.effect.prefix ? app.effect.prefix.split('/').filter(Boolean).at(-1) ?? domain ?? id : domain ?? id,
+                    prefix: 'string' == typeof app.effect.prefix ? app.effect.prefix : `/${domain ?? id}-api`,
+                    consumedBy: [
+                        shellApp.id,
+                        id
+                    ]
+                } : void 0;
+                return {
+                    id,
+                    kind: 'vertical' === app.kind ? 'vertical' : 'shell',
+                    path: appPath,
+                    ...'string' == typeof app.package ? {
+                        package: app.package
+                    } : {},
+                    packageSuffix: 'string' == typeof app.package ? app.package.split('/').at(-1) : appPath.split('/').at(-1),
+                    ...id === shellApp.id ? {
+                        displayName: shellApp.displayName
+                    } : {},
+                    ...domain ? {
+                        domain
+                    } : {},
+                    ...'number' == typeof ports[id] ? {
+                        port: ports[id]
+                    } : {},
+                    ...moduleFederation ? {
+                        moduleFederation
+                    } : {},
+                    ...api ? {
+                        api
+                    } : {}
+                };
+            })
+        }
+    };
+    return {
+        compact,
+        missing,
+        sources
+    };
+}
+export { synthesizeCompactUltramodernConfig };

package/dist/esm/ultramodern-tooling/config.js

@@ -1,120 +1 @@
-import node_fs from "node:fs";
-import node_path from "node:path";
-import { normalizeUltramodernBridgeConfig } from "../ultramodern-workspace/bridge-config.js";
-import { ULTRAMODERN_CONFIG_PATH, createNeutralOwnership, shellApp } from "../ultramodern-workspace/descriptors.js";
-import { toKebabCase } from "../ultramodern-workspace/naming.js";
-function readJsonObject(filePath) {
-    const value = JSON.parse(node_fs.readFileSync(filePath, 'utf-8'));
-    if (null === value || 'object' != typeof value || Array.isArray(value)) throw new Error(`UltraModern config must contain a JSON object: ${filePath}`);
-    return value;
-}
-function readOptionalJsonObject(filePath) {
-    return node_fs.existsSync(filePath) ? readJsonObject(filePath) : {};
-}
-function packageScopeFromRoot(workspaceRoot1) {
-    const rootPackage = readOptionalJsonObject(node_path.join(workspaceRoot1, 'package.json'));
-    return 'string' == typeof rootPackage.name && rootPackage.name.length > 0 ? rootPackage.name : node_path.basename(workspaceRoot1);
-}
-function normalizeCompactConfig(sourcePath, config) {
-    const packageSource = config.packageSource && 'object' == typeof config.packageSource ? {
-        strategy: 'install' === config.packageSource.strategy ? 'install' : 'workspace',
-        modernPackageVersion: 'string' == typeof config.packageSource.modernPackageVersion ? config.packageSource.modernPackageVersion : 'workspace:*',
-        registry: 'string' == typeof config.packageSource.registry ? config.packageSource.registry : void 0,
-        aliasScope: 'string' == typeof config.packageSource.aliasScope ? config.packageSource.aliasScope : void 0,
-        aliasPackageNamePrefix: 'string' == typeof config.packageSource.aliasPackageNamePrefix ? config.packageSource.aliasPackageNamePrefix : void 0
-    } : void 0;
-    return {
-        schemaVersion: 'number' == typeof config.schemaVersion ? config.schemaVersion : 1,
-        profile: 'string' == typeof config.profile ? config.profile : void 0,
-        source: 'compact',
-        sourcePath,
-        workspace: {
-            packageScope: 'string' == typeof config.workspace?.packageScope ? config.workspace.packageScope : packageScopeFromRoot(workspaceRoot)
-        },
-        packageSource,
-        features: {
-            tailwind: config.features?.tailwind !== false
-        },
-        bridge: normalizeUltramodernBridgeConfig(config.bridge),
-        topology: {
-            apps: Array.isArray(config.topology?.apps) ? config.topology.apps.map((app)=>({
-                    id: String(app.id),
-                    kind: 'vertical' === app.kind ? 'vertical' : 'shell',
-                    path: 'string' == typeof app.path ? app.path : '.',
-                    package: 'string' == typeof app.package ? app.package : void 0,
-                    packageSuffix: 'string' == typeof app.packageSuffix ? app.packageSuffix : void 0,
-                    displayName: 'string' == typeof app.displayName ? app.displayName : void 0,
-                    domain: 'string' == typeof app.domain ? app.domain : void 0,
-                    port: 'number' == typeof app.port ? app.port : void 0,
-                    portEnv: 'string' == typeof app.portEnv ? app.portEnv : void 0,
-                    moduleFederation: app.moduleFederation && 'object' == typeof app.moduleFederation ? {
-                        role: 'remote' === app.moduleFederation.role ? 'remote' : 'host',
-                        name: 'string' == typeof app.moduleFederation.name ? app.moduleFederation.name : void 0,
-                        exposes: Array.isArray(app.moduleFederation.exposes) ? app.moduleFederation.exposes.filter((expose)=>'string' == typeof expose) : void 0,
-                        exposePaths: null === app.moduleFederation.exposePaths || 'object' != typeof app.moduleFederation.exposePaths || Array.isArray(app.moduleFederation.exposePaths) ? void 0 : Object.fromEntries(Object.entries(app.moduleFederation.exposePaths).filter((entry)=>'string' == typeof entry[0] && 'string' == typeof entry[1])),
-                        verticalRefs: Array.isArray(app.moduleFederation.verticalRefs) ? app.moduleFederation.verticalRefs.filter((ref)=>'string' == typeof ref) : void 0,
-                        hostOnly: true === app.moduleFederation.hostOnly,
-                        noExposes: true === app.moduleFederation.noExposes
-                    } : void 0,
-                    api: app.api && 'object' == typeof app.api ? {
-                        stem: 'string' == typeof app.api.stem ? app.api.stem : String(app.id),
-                        prefix: 'string' == typeof app.api.prefix ? app.api.prefix : `/${String(app.id)}-api`,
-                        consumedBy: Array.isArray(app.api.consumedBy) ? app.api.consumedBy.filter((consumer)=>'string' == typeof consumer) : [
-                            shellApp.id,
-                            String(app.id)
-                        ]
-                    } : void 0
-                })) : []
-        }
-    };
-}
-function readUltramodernConfig(workspaceRoot1 = process.cwd()) {
-    const compactPath = node_path.join(workspaceRoot1, ULTRAMODERN_CONFIG_PATH);
-    if (node_fs.existsSync(compactPath)) return normalizeCompactConfig(compactPath, readJsonObject(compactPath));
-    throw new Error(`Missing UltraModern config. Expected ${ULTRAMODERN_CONFIG_PATH}.`);
-}
-function workspaceAppsFromToolingConfig(config) {
-    return config.topology.apps.map((app)=>{
-        if ('shell' === app.kind) return {
-            ...shellApp,
-            directory: app.path,
-            packageSuffix: app.packageSuffix ?? shellApp.packageSuffix,
-            displayName: app.displayName ?? shellApp.displayName,
-            port: app.port ?? shellApp.port,
-            portEnv: app.portEnv ?? shellApp.portEnv,
-            mfName: app.moduleFederation?.name ?? shellApp.mfName,
-            verticalRefs: app.moduleFederation?.verticalRefs ?? []
-        };
-        const domain = app.domain ?? app.id;
-        const packageSuffix = app.packageSuffix ?? domain;
-        const exposePaths = app.moduleFederation?.exposePaths ?? {};
-        const exposes = Object.fromEntries((app.moduleFederation?.exposes ?? []).map((expose)=>{
-            const configuredPath = exposePaths[expose];
-            const inferredPath = './Route' === expose ? './src/federation-entry.tsx' : './Widget' === expose ? `./src/components/${domain}-widget.tsx` : `./src/components/${toKebabCase(expose.replace(/^\.\//u, ''))}.tsx`;
-            return [
-                expose,
-                configuredPath ?? inferredPath
-            ];
-        }));
-        return {
-            id: app.id,
-            directory: app.path,
-            packageSuffix,
-            displayName: app.displayName ?? `${domain} Vertical`,
-            kind: 'vertical',
-            domain,
-            portEnv: app.portEnv ?? `VERTICAL_${domain.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}_PORT`,
-            port: app.port ?? 0,
-            mfName: app.moduleFederation?.name ?? app.id,
-            exposes,
-            ...app.moduleFederation?.verticalRefs ? {
-                verticalRefs: app.moduleFederation.verticalRefs
-            } : {},
-            ...app.api ? {
-                api: app.api
-            } : {},
-            ownership: createNeutralOwnership(app.id)
-        };
-    });
-}
-export { readUltramodernConfig, workspaceAppsFromToolingConfig };
+export * from "./config/index.js";

package/dist/esm/ultramodern-workspace/add-shell.js

@@ -0,0 +1,221 @@
+import node_fs from "node:fs";
+import node_os from "node:os";
+import node_path from "node:path";
+import { DEVELOPMENT_OVERLAY_PATH, TOPOLOGY_PATH } from "./add-vertical/constants.js";
+import { createPrimaryShellDescriptor } from "./add-vertical/preflight.js";
+import { verticalsFromTopology } from "./add-vertical/topology.js";
+import { runWorkspaceTransaction } from "./add-vertical/transaction.js";
+import { assertGlobalPortUniqueness, configuredDevelopmentPorts, existingBridgeConfig, existingPackageSource, existingTailwindEnabled, nextAvailablePort } from "./add-vertical/workspace-state.js";
+import { ULTRAMODERN_CONFIG_PATH, appEmitsBrowserUi, shellApp } from "./descriptors.js";
+import { formatGeneratedWorkspaceFiles, readJsonFile, writeFileReplacing, writeJsonFile } from "./fs-io.js";
+import { createFileSnapshot, createGenerationResult, diffFileSnapshots } from "./generation-result.js";
+import { assertUniqueTailwindPrefixes, toPackageScope } from "./naming.js";
+import { createRootPackageJson } from "./package-json.js";
+import { FIRST_ADDITIONAL_SHELL_PORT, PRIMARY_SHELL_ID, assertValidShellName, createAdditionalShellConfigEntry, createShellDescriptor, resolveConfiguredAdditionalShells } from "./shells.js";
+import { createRootTsConfig } from "./tsconfigs.js";
+import { isRecord } from "./types.js";
+import { writeGeneratedWorkspaceScripts } from "./workspace-scripts.js";
+import { rewriteAppModernConfig, writeApp } from "./write-app.js";
+import { createZeropsYaml } from "./zerops.js";
+function readRequiredJsonObject(filePath) {
+    if (!node_fs.existsSync(filePath)) throw new Error(`Missing UltraModern workspace file: ${filePath}`);
+    const value = readJsonFile(filePath);
+    if (!isRecord(value)) throw new Error(`UltraModern workspace file must contain a JSON object: ${filePath}`);
+    return value;
+}
+function prepareAddUltramodernShell(options) {
+    const name = assertValidShellName(options.name);
+    const configPath = node_path.join(options.workspaceRoot, ULTRAMODERN_CONFIG_PATH);
+    const overlayPath = node_path.join(options.workspaceRoot, DEVELOPMENT_OVERLAY_PATH);
+    const topologyPath = node_path.join(options.workspaceRoot, TOPOLOGY_PATH);
+    const rootPackage = readRequiredJsonObject(node_path.join(options.workspaceRoot, 'package.json'));
+    const config = readRequiredJsonObject(configPath);
+    const overlay = readRequiredJsonObject(overlayPath);
+    const topology = readRequiredJsonObject(topologyPath);
+    overlay.ports ??= {};
+    const scope = toPackageScope(String(rootPackage.name ?? node_path.basename(options.workspaceRoot)));
+    const packageSource = existingPackageSource(options.workspaceRoot, options.modernVersion, options.packageSource);
+    const enableTailwind = options.enableTailwind ?? existingTailwindEnabled(options.workspaceRoot);
+    const bridge = existingBridgeConfig(options.workspaceRoot);
+    const existingVerticals = verticalsFromTopology(topology, overlay.ports);
+    const existingAdditionalShells = resolveConfiguredAdditionalShells(config);
+    const shellId = `shell-${name}`;
+    if (shellId === PRIMARY_SHELL_ID || existingAdditionalShells.some((existing)=>existing.id === shellId)) throw new Error(`Shell "${shellId}" already exists in this workspace.`);
+    if (node_fs.existsSync(node_path.join(options.workspaceRoot, `apps/${shellId}`))) throw new Error(`Refusing to overwrite existing path: apps/${shellId}`);
+    const overlayPorts = overlay.ports ?? {};
+    const portsWithPrimary = {
+        ...overlayPorts,
+        [shellApp.id]: 'number' == typeof overlayPorts[shellApp.id] ? overlayPorts[shellApp.id] : shellApp.port
+    };
+    assertGlobalPortUniqueness(portsWithPrimary, existingAdditionalShells);
+    const shell = createShellDescriptor(name, nextAvailablePort(portsWithPrimary, existingAdditionalShells, FIRST_ADDITIONAL_SHELL_PORT));
+    const requestedVerticalIds = options.verticals ?? existingVerticals.filter(appEmitsBrowserUi).map((vertical)=>vertical.id);
+    const verticalsById = new Map(existingVerticals.map((vertical)=>[
+            vertical.id,
+            vertical
+        ]));
+    const composedVerticals = requestedVerticalIds.map((id)=>{
+        const vertical = verticalsById.get(id);
+        if (!vertical) {
+            const available = existingVerticals.map((candidate)=>candidate.id).join(', ') || 'none';
+            throw new Error(`Unknown vertical "${id}" for shell ${shellId}. Available verticals: ${available}.`);
+        }
+        return vertical;
+    });
+    shell.verticalRefs = composedVerticals.map((vertical)=>vertical.id);
+    assertUniqueTailwindPrefixes([
+        shellApp,
+        ...existingAdditionalShells,
+        shell,
+        ...existingVerticals
+    ]);
+    return {
+        scope,
+        configPath,
+        overlayPath,
+        config,
+        overlay,
+        packageSource,
+        enableTailwind,
+        bridge,
+        existingVerticals,
+        existingAdditionalShells,
+        shell,
+        composedVerticals
+    };
+}
+function addUltramodernShell(options) {
+    return runWorkspaceTransaction(options.workspaceRoot, ()=>executeAddUltramodernShell(options));
+}
+function executeAddUltramodernShell(options) {
+    const beforeFiles = createFileSnapshot(options.workspaceRoot);
+    const preflight = prepareAddUltramodernShell(options);
+    const { scope, configPath, config, packageSource, enableTailwind, bridge, existingVerticals, existingAdditionalShells, shell, composedVerticals } = preflight;
+    const configuredPrimary = createPrimaryShellDescriptor({}, config);
+    const primaryRefsConfigured = Array.isArray(config.topology?.apps?.find((app)=>app?.id === shellApp.id)?.moduleFederation?.verticalRefs);
+    const primaryShell = {
+        ...configuredPrimary,
+        verticalRefs: primaryRefsConfigured ? configuredPrimary.verticalRefs : existingVerticals.filter(appEmitsBrowserUi).map((v)=>v.id)
+    };
+    const allAdditionalShells = [
+        ...existingAdditionalShells,
+        shell
+    ];
+    const configuredDevPorts = configuredDevelopmentPorts({
+        ...preflight.overlay.ports,
+        [shell.id]: shell.port
+    }, allAdditionalShells).toSorted((left, right)=>left - right);
+    writeApp(options.workspaceRoot, scope, shell, packageSource, enableTailwind, composedVerticals, bridge, configuredDevPorts);
+    const shellsCollection = Array.isArray(config.shells) ? config.shells.filter((entry)=>entry?.id !== shell.id) : [];
+    shellsCollection.push(createAdditionalShellConfigEntry(scope, shell, existingVerticals));
+    config.shells = shellsCollection;
+    writeJsonFile(configPath, config);
+    for (const app of [
+        primaryShell,
+        ...existingVerticals,
+        ...existingAdditionalShells
+    ])rewriteAppModernConfig(options.workspaceRoot, scope, app, existingVerticals, enableTailwind, configuredDevPorts);
+    const rootPackagePath = node_path.join(options.workspaceRoot, 'package.json');
+    const rootPackage = readJsonFile(rootPackagePath);
+    const generatedRootPackage = createRootPackageJson(scope, packageSource, existingVerticals, bridge, allAdditionalShells);
+    rootPackage.scripts = generatedRootPackage.scripts;
+    writeJsonFile(rootPackagePath, rootPackage);
+    writeJsonFile(node_path.join(options.workspaceRoot, 'tsconfig.json'), createRootTsConfig([
+        primaryShell,
+        ...existingVerticals,
+        ...allAdditionalShells
+    ]));
+    writeGeneratedWorkspaceScripts(options.workspaceRoot, scope, enableTailwind, existingVerticals, void 0, allAdditionalShells, primaryShell);
+    writeFileReplacing(options.workspaceRoot, 'zerops.yaml', `${createZeropsYaml(scope, [
+        primaryShell,
+        ...existingVerticals,
+        ...allAdditionalShells
+    ])}\n`);
+    const afterOverlaysFiles = createFileSnapshot(options.workspaceRoot);
+    const changedPaths = diffFileSnapshots(beforeFiles, afterOverlaysFiles);
+    formatGeneratedWorkspaceFiles(options.workspaceRoot, [
+        ...changedPaths.createdPaths,
+        ...changedPaths.rewrittenPaths
+    ]);
+    const afterFiles = createFileSnapshot(options.workspaceRoot);
+    const { createdPaths, rewrittenPaths } = diffFileSnapshots(beforeFiles, afterFiles);
+    return createGenerationResult({
+        operation: 'shell',
+        workspaceRoot: options.workspaceRoot,
+        packageScope: scope,
+        packageSource,
+        createdApps: [
+            shell
+        ],
+        createdPaths,
+        rewrittenPaths
+    });
+}
+function planUltramodernShell(options) {
+    prepareAddUltramodernShell(options);
+    const tempRoot = node_fs.mkdtempSync(node_path.join(node_os.tmpdir(), 'um-shell-plan-'));
+    const copiedWorkspaceRoot = node_path.join(tempRoot, 'workspace');
+    const skippedDirectories = new Set([
+        '.git',
+        '.nx',
+        '.output',
+        'coverage',
+        'dist',
+        'node_modules'
+    ]);
+    try {
+        node_fs.cpSync(options.workspaceRoot, copiedWorkspaceRoot, {
+            recursive: true,
+            filter: (sourcePath)=>!skippedDirectories.has(node_path.basename(sourcePath))
+        });
+        const plannedResult = addUltramodernShell({
+            ...options,
+            workspaceRoot: copiedWorkspaceRoot
+        });
+        const shell = plannedResult.createdApps[0];
+        return {
+            ...plannedResult,
+            workspaceRoot: options.workspaceRoot,
+            dryRun: true,
+            selectedPort: shell?.port ?? 0,
+            moduleFederationRemote: {
+                id: shell?.id ?? '',
+                name: shell?.moduleFederationName ?? '',
+                manifestUrl: `http://localhost:${shell?.port ?? 0}/mf-manifest.json`
+            },
+            jsonMutations: [
+                {
+                    path: ULTRAMODERN_CONFIG_PATH,
+                    pointer: '/shells/-',
+                    description: `Register additional shell ${shell?.id}`
+                },
+                {
+                    path: 'package.json',
+                    pointer: "/scripts",
+                    description: "Enumerate all configured shells in workspace scripts"
+                },
+                {
+                    path: 'tsconfig.json',
+                    pointer: '/references',
+                    description: `Add ${shell?.id} to the root TS-Go build graph`
+                }
+            ],
+            shellDependencyChanges: [],
+            generatedContractChanges: [
+                {
+                    path: ULTRAMODERN_CONFIG_PATH,
+                    addedAppIds: [
+                        shell?.id ?? ''
+                    ],
+                    shellVerticalRefs: options.verticals ?? []
+                }
+            ]
+        };
+    } finally{
+        node_fs.rmSync(tempRoot, {
+            recursive: true,
+            force: true
+        });
+    }
+}
+export { addUltramodernShell, planUltramodernShell };

package/dist/esm/ultramodern-workspace/add-vertical/constants.js

@@ -0,0 +1,5 @@
+const FIRST_VERTICAL_PORT = 4101;
+const TOPOLOGY_PATH = 'topology/reference-topology.json';
+const OWNERSHIP_PATH = 'topology/ownership.json';
+const DEVELOPMENT_OVERLAY_PATH = 'topology/local-overlays/development.json';
+export { DEVELOPMENT_OVERLAY_PATH, FIRST_VERTICAL_PORT, OWNERSHIP_PATH, TOPOLOGY_PATH };