@empire-builder-kit/nx 1.0.0-rc.37 → 1.0.0-rc.39

package/src/foundation/private-smoke-admission.d.ts

@@ -1,4 +1,5 @@
 export interface SmokeAdmissionContext {
+    authority?: 'local';
     run: string;
     attempt: string;
     source: string;
@@ -14,6 +15,7 @@ export interface SmokeIpSetStore {
     update(previous: SmokeIpSet, next: Pick<SmokeIpSet, 'addresses' | 'description'>): Promise<void>;
 }
 export interface SmokeAdmissionLease {
+    authority?: 'local';
     run: string;
     attempt: string;
     source: string;
@@ -33,7 +35,7 @@ export declare function withPrivateSmokeAdmission<T>(input: {
     context: SmokeAdmissionContext;
     cidr: string;
     run: (lease: SmokeAdmissionLease) => Promise<T>;
-    awaitAdmission: () => Promise<void>;
+    awaitAdmission: (signal: AbortSignal) => Promise<void>;
     awaitRevocation: () => Promise<void>;
     now?: () => number;
     signals?: {

package/src/foundation/private-smoke-admission.js

@@ -9,6 +9,7 @@ exports.withPrivateSmokeAdmission = withPrivateSmokeAdmission;
 const node_crypto_1 = require("node:crypto");
 const node_net_1 = require("node:net");
 const prefix = 'ebk-smoke-v1:';
+const localPrefix = 'ebk-smoke-local-v1:';
 const sorted = (values) => [...values].sort();
 const same = (a, b) => JSON.stringify(sorted(a)) === JSON.stringify(sorted(b));
 const baselineDigest = (values) => (0, node_crypto_1.createHash)('sha256')
@@ -47,20 +48,31 @@ function publicRunnerIpv4(value) {
 function parseSmokeAdmissionLease(description) {
     if (description === '')
         return undefined;
-    requireCondition(description.startsWith(prefix) && description.length <= 256, 'unrecognized IP-set description; do not overwrite it');
-    const parts = description.slice(prefix.length).split(',');
+    const local = description.startsWith(localPrefix);
+    const leasePrefix = local ? localPrefix : prefix;
+    requireCondition(description.startsWith(leasePrefix) && description.length <= 256, 'unrecognized IP-set description; do not overwrite it');
+    const parts = description.slice(leasePrefix.length).split(',');
     requireCondition(parts.length === 6, 'malformed admission lease');
     const [run, attempt, source, cidr, baseline, expires] = parts;
-    requireCondition(/^[1-9][0-9]*$/.test(run) &&
+    requireCondition((local ? /^[a-f0-9]{32}$/.test(run) : /^[1-9][0-9]*$/.test(run)) &&
         /^[1-9][0-9]*$/.test(attempt) &&
         /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(source) &&
         /^[a-f0-9]{64}$/.test(baseline) &&
         /^[0-9]{13}$/.test(expires), 'malformed admission identity');
     requireCondition(cidr === publicRunnerIpv4(cidr.replace(/\/32$/, '')), 'admission is not an exact /32');
-    return { run, attempt, source, cidr, baseline, expiresAt: Number(expires) };
+    return {
+        ...(local ? { authority: 'local' } : {}),
+        run,
+        attempt,
+        source,
+        cidr,
+        baseline,
+        expiresAt: Number(expires),
+    };
 }
 function belongsTo(lease, context) {
-    return (lease.run === context.run &&
+    return (lease.authority === context.authority &&
+        lease.run === context.run &&
         lease.attempt === context.attempt &&
         lease.source === context.source);
 }
@@ -91,7 +103,10 @@ async function cleanupSmokeAdmission(store, context) {
             return;
         }
     }
-    throw new Error('Private smoke access: cleanup unproved; deployment acceptance is prohibited. Run protected smoke-access cleanup before retrying.');
+    throw new Error('Private smoke access: cleanup unproved; deployment acceptance is prohibited. ' +
+        (context.authority === 'local'
+            ? 'Preserve the private recovery receipt, stop the owning invocation, then retry ebk deploy from the same workspace and stage with its verified credential profile.'
+            : 'Run protected smoke-access cleanup before retrying.'));
 }
 /** A retained lease alone, or its expiry, is not proof that a different run ended. */
 async function recoverSmokeAdmission(store, baseline, completedRun) {
@@ -112,7 +127,7 @@ async function withPrivateSmokeAdmission(input) {
     requireCondition(!parseSmokeAdmissionLease(before.description), 'recover the existing admission before starting smoke');
     requireCondition(same(before.addresses, context.baseline), 'live allowlist differs from committed baseline');
     const alreadyAllowed = runnerAlreadyAllowed(cidr, context.baseline);
-    const description = prefix +
+    const description = (context.authority === 'local' ? localPrefix : prefix) +
         [
             context.run,
             context.attempt,
@@ -125,8 +140,10 @@ async function withPrivateSmokeAdmission(input) {
     requireCondition(lease !== undefined, 'admission lease is unreadable');
     const signals = input.signals ?? process;
     let interrupted = false;
+    const admissionAbort = new AbortController();
     const stop = () => {
         interrupted = true;
+        admissionAbort.abort(new Error('Private smoke interrupted'));
     };
     signals.on('SIGINT', stop);
     signals.on('SIGTERM', stop);
@@ -138,7 +155,8 @@ async function withPrivateSmokeAdmission(input) {
             });
         const after = await store.read();
         requireCondition(same(after.addresses, alreadyAllowed ? context.baseline : [...context.baseline, cidr]) && after.description === (alreadyAllowed ? '' : description), 'admission readback differs');
-        await input.awaitAdmission();
+        requireCondition(!interrupted, 'interrupted before admission');
+        await input.awaitAdmission(admissionAbort.signal);
         requireCondition(!interrupted, 'interrupted before smoke');
         const result = await input.run(lease);
         requireCondition(!interrupted, 'smoke interrupted');
@@ -149,6 +167,9 @@ async function withPrivateSmokeAdmission(input) {
             await cleanupSmokeAdmission(store, context);
             if (!alreadyAllowed)
                 await input.awaitRevocation();
+            // Signals must not abort revocation, but they must invalidate the pending
+            // return value even when smoke itself already completed successfully.
+            requireCondition(!interrupted, 'smoke interrupted during cleanup');
         }
         finally {
             signals.removeListener('SIGINT', stop);

package/src/foundation/private-smoke-control-plane.js

@@ -29,7 +29,7 @@ async function openPrivateSmokeControlPlane(identity, smokeUrl, clients = {
     const url = smokeUrl === undefined ? undefined : new URL(smokeUrl);
     if (url)
         check(url.protocol === 'https:' && !url.username && !url.password && !url.port, 'credential-free HTTPS Router required');
-    const name = `foundation-${identity.stage}-router-ipv4-allowlist`;
+    const name = `foundation-${identity.stage}-router-smoke-access`;
     const ipSets = [];
     let marker;
     const seen = new Set();
@@ -47,7 +47,7 @@ async function openPrivateSmokeControlPlane(identity, smokeUrl, clients = {
         check(seen.size <= 100, 'IP-set inventory exceeds bounded inspection');
     } while (marker);
     const matches = ipSets.filter((set) => set.Name === name);
-    check(matches.length === 1 && matches[0].Id, 'exact stage IPv4 IP set missing or ambiguous; configure a baseline IPv4 CIDR before private hosted smoke');
+    check(matches.length === 1 && matches[0].Id, 'exact stage smoke-access IP set missing or ambiguous; deploy the upgraded Foundation before private smoke');
     const selected = matches[0];
     const arn = `arn:aws:wafv2:us-east-1:${identity.account}:global/ipset/${name}/${selected.Id}`;
     check(selected.ARN === arn, 'IP-set account/scope/identity mismatch');
@@ -56,7 +56,6 @@ async function openPrivateSmokeControlPlane(identity, smokeUrl, clients = {
         'ebk:owner': 'foundation',
         'ebk:stage': identity.stage,
         'ebk:workspace': identity.workspace,
-        'ebk:policy-digest': identity.policyDigest,
     };
     async function attestTags(resourceArn) {
         const tags = {};
@@ -80,6 +79,15 @@ async function openPrivateSmokeControlPlane(identity, smokeUrl, clients = {
         } while (tagMarker);
         for (const [key, value] of Object.entries(expectedTags))
             check(tags[key] === value, 'WAF ownership or committed policy differs');
+        if (resourceArn === arn) {
+            // The dedicated smoke set has stable ownership, not mutable WAF policy.
+            // An older creation-time digest tag is inert. Policy binding is checked
+            // on the attached Web ACL before any admission, never during revocation.
+            check(tags['ebk:purpose'] === 'private-smoke-access', 'IP set is not owned exclusively by private smoke');
+        }
+        else {
+            check(tags['ebk:policy-digest'] === identity.policyDigest, 'WAF ownership or committed policy differs');
+        }
     }
     await attestTags(arn);
     // Cleanup never expands access; exact tagged IP-set identity and lease are sufficient.
@@ -135,12 +143,15 @@ async function openPrivateSmokeControlPlane(identity, smokeUrl, clients = {
             : statement?.OrStatement?.Statements?.map((item) => item.IPSetReferenceStatement);
         check(rules.length === 1 &&
             rules[0].Action?.Block &&
-            refs?.length &&
+            refs &&
+            refs.length >= 2 &&
+            refs.length <= 3 &&
             refs.every((ref) => ref?.ARN) &&
+            new Set(refs.map((ref) => ref?.ARN)).size === refs.length &&
             refs.filter((ref) => ref?.ARN === arn).length === 1, 'Router blocking rule does not reference the exact IP set');
-        // A dual-stack rule may have only its same-stage IPv6 companion, never an arbitrary second set.
+        // Only the unchanged same-stage baseline sets may accompany the smoke set.
         check(refs.every((ref) => ref?.ARN === arn ||
-            ref?.ARN?.startsWith(`arn:aws:wafv2:us-east-1:${identity.account}:global/ipset/foundation-${identity.stage}-router-ipv6-allowlist/`)), 'Router allowlist contains an out-of-stage reference');
+            ['ipv4', 'ipv6'].some((family) => ref?.ARN?.startsWith(`arn:aws:wafv2:us-east-1:${identity.account}:global/ipset/foundation-${identity.stage}-router-${family}-allowlist/`))), 'Router allowlist contains an out-of-stage reference');
     }
     const key = { Name: name, Id: selected.Id, Scope: 'CLOUDFRONT' };
     return {

package/src/foundation/provision-database-bindings.d.ts

@@ -32,7 +32,12 @@ export type ProvisionedDatabaseBindings<TBindings extends DatabaseBindingDeclara
 export declare function createDatabaseBindingPlan(bindings: DatabaseBindingDeclaration, context: {
     slice: string;
     stage: string;
+    localDev?: boolean;
 }): DatabaseBindingPlan;
+/** Validate declaration shape/collisions without planning deployment or connection coordinates. */
+export declare function validateDatabaseBindings(bindings: DatabaseBindingDeclaration, context: {
+    slice: string;
+}): Pick<DatabaseBindingPlan, 'active' | 'provisioned'>;
 export declare function provisionDatabaseBindings<TBindings extends DatabaseBindingDeclaration>(foundation: FoundationInfrastructure, options: ProvisionDatabaseBindingsOptions & {
     bindings: TBindings;
 }): ProvisionedDatabaseBindings<TBindings>;

package/src/foundation/provision-database-bindings.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.selectDatabaseTarget = selectDatabaseTarget;
 exports.createDatabaseBindingPlan = createDatabaseBindingPlan;
+exports.validateDatabaseBindings = validateDatabaseBindings;
 exports.provisionDatabaseBindings = provisionDatabaseBindings;
 const local_database_contract_js_1 = require("./local-database-contract.js");
 const provision_logical_database_js_1 = require("./provision-logical-database.js");
@@ -25,6 +26,40 @@ function collisionKey(value) {
     return (0, local_database_contract_js_1.normalizePostgresIdentifier)(value).normalize('NFKC').toLowerCase();
 }
 function createDatabaseBindingPlan(bindings, context) {
+    return inspectDatabaseBindings(bindings, context.slice, (identifier) => {
+        if (!context.localDev)
+            return (0, local_database_contract_js_1.resolveLogicalDatabaseIdentifiers)({
+                database: identifier,
+                slice: context.slice,
+                stage: context.stage,
+            });
+        const local = (0, local_database_contract_js_1.resolveLocalDatabaseContract)({
+            database: identifier,
+            slice: context.slice,
+            stage: context.stage,
+        });
+        const resolved = {
+            database: local.database,
+            localDatabase: local.database,
+            localReadwriteRole: local.username,
+            readwriteRole: local.username,
+            readonlyRole: `${local.database}_readonly`,
+            migratorRole: `${local.database}_migrator`,
+        };
+        for (const [role, value] of Object.entries(resolved))
+            (0, local_database_contract_js_1.assertPostgresIdentifierLength)(value, `Local ${role} identifier`);
+        return resolved;
+    });
+}
+/** Validate declaration shape/collisions without planning deployment or connection coordinates. */
+function validateDatabaseBindings(bindings, context) {
+    const { active, provisioned } = inspectDatabaseBindings(bindings, context.slice);
+    return { active, provisioned };
+}
+function inspectDatabaseBindings(bindings, slice, resolveIdentifiers) {
+    if (typeof slice !== 'string' || slice.trim() === '') {
+        throw new Error('Product Slice name must be a non-empty string.');
+    }
     if (typeof bindings !== 'object' ||
         bindings === null ||
         Array.isArray(bindings)) {
@@ -73,17 +108,13 @@ function createDatabaseBindingPlan(bindings, context) {
             if (declared.has(identifier)) {
                 throw new Error(`Database identifier "${identifier}" is declared more than once. Each provisioned identifier must be unique across the binding set.`);
             }
-            const resolved = (0, local_database_contract_js_1.resolveLogicalDatabaseIdentifiers)({
-                database: identifier,
-                slice: context.slice,
-                stage: context.stage,
-            });
-            const key = collisionKey(resolved.database);
+            const resolved = resolveIdentifiers?.(identifier);
+            const key = collisionKey(resolved?.database ?? identifier);
             const previous = normalized.get(key);
             if (previous !== undefined) {
                 throw new Error(`Database identifiers "${previous}" and "${identifier}" collide after PostgreSQL normalization. Rename one identifier; EBK never truncates or aliases database bindings.`);
             }
-            const componentName = (0, provision_logical_database_js_1.defaultDatabaseLinkableName)(context.slice, identifier);
+            const componentName = (0, provision_logical_database_js_1.defaultDatabaseLinkableName)(slice, identifier);
             const previousComponent = componentNames.get(componentName);
             if (previousComponent !== undefined) {
                 throw new Error(`Database identifiers "${previousComponent}" and "${identifier}" collide after SST logical-name normalization as "${componentName}". Rename one identifier so every resource name is unique before deployment.`);
@@ -91,7 +122,8 @@ function createDatabaseBindingPlan(bindings, context) {
             declared.add(identifier);
             normalized.set(key, identifier);
             componentNames.set(componentName, identifier);
-            identifiers[identifier] = resolved;
+            if (resolved)
+                identifiers[identifier] = resolved;
         }
     }
     return {
@@ -107,6 +139,7 @@ function provisionDatabaseBindings(foundation, options) {
     const plan = createDatabaseBindingPlan(options.bindings, {
         slice: options.slice,
         stage: $app.stage,
+        localDev: $dev && options.localDev !== false,
     });
     const provisioned = new Map();
     for (const database of plan.provisioned) {

package/src/foundation/provision-logical-database.js

@@ -27,11 +27,6 @@ function provisionLogicalDatabase(foundation, options) {
         options.rotationToken.trim() === '') {
         throw new Error('Logical database rotationToken must be a non-empty string when supplied.');
     }
-    const identifiers = (0, local_database_contract_js_1.resolveLogicalDatabaseIdentifiers)({
-        database: options.database,
-        slice: options.slice,
-        stage: consumerStage,
-    });
     const resourceName = options.linkableName ??
         defaultDatabaseLinkableName(options.slice, options.database);
     if ($dev && (options.localDev ?? true)) {
@@ -40,7 +35,12 @@ function provisionLogicalDatabase(foundation, options) {
             password: options.localDevPassword,
             port: options.localDevPort,
             slice: options.slice,
+            stage: consumerStage,
         });
+        const readonlyRole = `${localDatabase.database}_readonly`;
+        const migratorRole = `${localDatabase.database}_migrator`;
+        (0, local_database_contract_js_1.assertPostgresIdentifierLength)(readonlyRole, 'Local read-only role identifier');
+        (0, local_database_contract_js_1.assertPostgresIdentifierLength)(migratorRole, 'Local migrator role identifier');
         return {
             db: new sst.Linkable(resourceName, {
                 properties: {
@@ -49,12 +49,17 @@ function provisionLogicalDatabase(foundation, options) {
                 },
             }),
             databaseName: localDatabase.database,
-            migratorRole: identifiers.migratorRole,
-            readonlyRole: identifiers.readonlyRole,
-            readwriteRole: identifiers.readwriteRole,
+            migratorRole,
+            readonlyRole,
+            readwriteRole: localDatabase.username,
             resourceName,
         };
     }
+    const identifiers = (0, local_database_contract_js_1.resolveLogicalDatabaseIdentifiers)({
+        database: options.database,
+        slice: options.slice,
+        stage: consumerStage,
+    });
     if (options.removalPolicy === 'destroy') {
         throw new Error('Logical database removalPolicy "destroy" requires a reviewed AWS-internal retirement workflow and is not supported by the v1 protected bootstrap.');
     }

package/src/foundation/requirements.d.ts

@@ -1,6 +1,6 @@
 import { type ValidationResult } from '../validation.js';
-export declare const STANDARD_FOUNDATION_CONTRACT_VERSION: 1;
-export declare const STANDARD_FOUNDATION_CAPABILITIES: readonly ["network", "routing", "container-compute", "postgres", "identity", "events", "observability", "configuration", "deployment"];
+export declare const STANDARD_FOUNDATION_CONTRACT_VERSION: 2;
+export declare const STANDARD_FOUNDATION_CAPABILITIES: readonly ["key-value", "routing", "identity", "events", "observability", "configuration", "deployment", "network", "container-compute", "postgres"];
 export type StandardFoundationCapability = (typeof STANDARD_FOUNDATION_CAPABILITIES)[number];
 export interface FoundationRequirement {
     capabilities: StandardFoundationCapability[];
@@ -20,7 +20,7 @@ export declare const foundationRequirementSchema: {
     readonly properties: {
         readonly capabilities: {
             readonly items: {
-                readonly enum: readonly ["network", "routing", "container-compute", "postgres", "identity", "events", "observability", "configuration", "deployment"];
+                readonly enum: readonly ["key-value", "routing", "identity", "events", "observability", "configuration", "deployment", "network", "container-compute", "postgres"];
                 readonly type: "string";
             };
             readonly type: "array";

package/src/foundation/requirements.js

@@ -6,18 +6,9 @@ exports.validateFoundationRequirement = validateFoundationRequirement;
 exports.validateFoundationCompatibility = validateFoundationCompatibility;
 const validation_js_1 = require("../validation.js");
 const semver_1 = require("semver");
-exports.STANDARD_FOUNDATION_CONTRACT_VERSION = 1;
-exports.STANDARD_FOUNDATION_CAPABILITIES = [
-    'network',
-    'routing',
-    'container-compute',
-    'postgres',
-    'identity',
-    'events',
-    'observability',
-    'configuration',
-    'deployment',
-];
+const capability_plan_js_1 = require("./capability-plan.js");
+exports.STANDARD_FOUNDATION_CONTRACT_VERSION = 2;
+exports.STANDARD_FOUNDATION_CAPABILITIES = capability_plan_js_1.FOUNDATION_CAPABILITY_VOCABULARY;
 const capabilitySet = new Set(exports.STANDARD_FOUNDATION_CAPABILITIES);
 function isStandardFoundationCapability(value) {
     return typeof value === 'string' && capabilitySet.has(value);
@@ -91,6 +82,7 @@ function validateFoundationCompatibility(requirement, foundation) {
         });
     }
     else {
+        const seen = new Set();
         foundation.capabilities.forEach((capability, index) => {
             if (!isStandardFoundationCapability(capability)) {
                 issues.push({
@@ -98,7 +90,27 @@ function validateFoundationCompatibility(requirement, foundation) {
                     path: `foundationDescriptor.capabilities[${index}]`,
                 });
             }
+            if (seen.has(capability)) {
+                issues.push({
+                    message: 'must not contain duplicate capabilities',
+                    path: `foundationDescriptor.capabilities[${index}]`,
+                });
+            }
+            seen.add(capability);
         });
+        if (foundation.contractVersion === '2.0.0') {
+            for (const [capability, dependency] of [
+                ['postgres', 'container-compute'],
+                ['container-compute', 'network'],
+            ]) {
+                if (seen.has(capability) && !seen.has(dependency)) {
+                    issues.push({
+                        message: `capability ${capability} requires ${dependency}`,
+                        path: 'foundationDescriptor.capabilities',
+                    });
+                }
+            }
+        }
     }
     if (requirementResult.valid &&
         typeof foundation.contractVersion === 'string' &&

package/src/foundation/router-waf.d.ts

@@ -143,6 +143,7 @@ export declare function createRouterWafStagePlan(input: {
 export declare function createRouterWafRules(plan: RouterWafStagePlan, ipSets: {
     ipv4Arn?: unknown;
     ipv6Arn?: unknown;
+    smokeArn?: unknown;
 }): WafRule[];
 export declare function routerWafContractDigest(policy: RouterWafPolicy): `sha256:${string}`;
 export {};

package/src/foundation/router-waf.js

@@ -652,7 +652,10 @@ function createRouterWafRules(plan, ipSets) {
     const rules = [];
     let priority = 0;
     if (plan.access === 'allowlist') {
-        const references = [ipSets.ipv4Arn, ipSets.ipv6Arn]
+        if (ipSets.ipv4Arn === undefined && ipSets.ipv6Arn === undefined) {
+            throw new Error('Router WAF allowlist is missing its exact IP set ARN.');
+        }
+        const references = [ipSets.ipv4Arn, ipSets.ipv6Arn, ipSets.smokeArn]
             .filter((value) => value !== undefined)
             .map((arn) => ({ ipSetReferenceStatement: { arn } }));
         if (references.length === 0) {
@@ -749,6 +752,9 @@ function routerWafContractDigest(policy) {
                 ...(plan.ipv6Cidrs.length > 0
                     ? { ipv6Arn: `<ipv6-ip-set:${stage}>` }
                     : {}),
+                ...(plan.access === 'allowlist'
+                    ? { smokeArn: `<smoke-ip-set:${stage}>` }
+                    : {}),
             }),
         };
     });
@@ -785,6 +791,13 @@ function routerWafContractDigest(policy) {
                 'ebk:stage',
                 'ebk:workspace',
             ],
+            smokeIpSetTags: [
+                'ebk:managed-by',
+                'ebk:owner',
+                'ebk:purpose',
+                'ebk:stage',
+                'ebk:workspace',
+            ],
             logging: policy.logging,
             scope: 'CLOUDFRONT',
         },

package/src/generators/blueprint/blueprint.d.ts

@@ -0,0 +1,5 @@
+import { type Tree } from '@nx/devkit';
+import type { BlueprintGeneratorSchema } from './schema.js';
+/** Scaffold source owned by the adopter, without executing it or minting trust. */
+export declare function blueprintGenerator(tree: Tree, options: BlueprintGeneratorSchema): Promise<void>;
+export default blueprintGenerator;

package/src/generators/blueprint/blueprint.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blueprintGenerator = blueprintGenerator;
+const devkit_1 = require("@nx/devkit");
+const prettier_1 = require("prettier");
+const semver_1 = require("semver");
+const validation_js_1 = require("../../validation.js");
+const manifest_js_1 = require("../../blueprints/manifest.js");
+const post_generation_install_js_1 = require("../post-generation-install.js");
+const files_js_1 = require("./files.js");
+/** Scaffold source owned by the adopter, without executing it or minting trust. */
+async function blueprintGenerator(tree, options) {
+    const name = options.name;
+    if (typeof name !== 'string' ||
+        name.length > 63 ||
+        !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(name) ||
+        /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/.test(name)) {
+        throw new Error('Blueprint name must be a lowercase hyphenated name of at most 63 characters.');
+    }
+    (0, post_generation_install_js_1.assertPostGenerationInstallWorkspaceAvailable)(tree, `generator:blueprint:${name}`);
+    const workspace = (0, devkit_1.readJson)(tree, 'package.json');
+    if (!(0, validation_js_1.isRecord)(workspace) ||
+        typeof workspace.name !== 'string' ||
+        !/^[a-z0-9][a-z0-9-]*$/.test(workspace.name) ||
+        !(0, validation_js_1.isRecord)(workspace.devDependencies) ||
+        typeof workspace.devDependencies['@empire-builder-kit/nx'] !== 'string' ||
+        !(0, semver_1.valid)(workspace.devDependencies['@empire-builder-kit/nx'])) {
+        throw new Error('Blueprint authoring requires an EBK workspace with an unscoped name and exact @empire-builder-kit/nx version.');
+    }
+    if (workspace.ebk !== undefined && !(0, validation_js_1.isRecord)(workspace.ebk)) {
+        throw new Error('Workspace ebk configuration must be an object.');
+    }
+    const ebk = (0, validation_js_1.isRecord)(workspace.ebk) ? workspace.ebk : {};
+    if (ebk.blueprints !== undefined && !(0, validation_js_1.isRecord)(ebk.blueprints)) {
+        throw new Error('Workspace ebk.blueprints configuration must be an object.');
+    }
+    const blueprints = (0, validation_js_1.isRecord)(ebk.blueprints) ? ebk.blueprints : {};
+    if ((blueprints.localPackages !== undefined &&
+        (!(0, validation_js_1.isRecord)(blueprints.localPackages) ||
+            Object.values(blueprints.localPackages).some((path) => typeof path !== 'string'))) ||
+        (blueprints.localAuthoringPackages !== undefined &&
+            (!Array.isArray(blueprints.localAuthoringPackages) ||
+                blueprints.localAuthoringPackages.some((entry) => typeof entry !== 'string')))) {
+        throw new Error('Existing Blueprint local authoring mappings must be valid before scaffolding.');
+    }
+    const root = `blueprints/${name}`;
+    const project = `blueprint-${name}`;
+    const packageName = `@${workspace.name}/blueprint-${name}`;
+    const localPackages = (blueprints.localPackages ?? {});
+    const localAuthoringPackages = (blueprints.localAuthoringPackages ??
+        []);
+    if (tree.isFile('blueprints') ||
+        tree.exists(root) ||
+        tree.children(root).length > 0 ||
+        tree.children('blueprints').some((entry) => entry.toLowerCase() === name) ||
+        (0, devkit_1.getProjects)(tree).has(project) ||
+        Object.prototype.hasOwnProperty.call(localPackages, packageName) ||
+        Object.values(localPackages).includes(root)) {
+        throw new Error(`Blueprint ${name} already has files, a project, or a local mapping. Choose a new name; existing authoring source is never overwritten.`);
+    }
+    const files = (0, files_js_1.createBlueprintAuthoringFiles)({
+        engine: workspace.devDependencies['@empire-builder-kit/nx'],
+        name,
+        packageName,
+        root,
+    });
+    const manifest = (0, manifest_js_1.validateBlueprintManifest)(JSON.parse(files['ebk-blueprint.json']));
+    if (!manifest.valid)
+        throw new Error('Generated Blueprint authoring manifest is invalid.');
+    const nextWorkspace = {
+        ...workspace,
+        ebk: {
+            ...ebk,
+            blueprints: {
+                ...blueprints,
+                localPackages: { ...localPackages, [packageName]: root },
+                localAuthoringPackages: [
+                    ...new Set([...localAuthoringPackages, packageName]),
+                ],
+            },
+        },
+    };
+    const planned = {
+        ...Object.fromEntries(Object.entries(files).map(([path, contents]) => [
+            `${root}/${path}`,
+            contents,
+        ])),
+        'package.json': JSON.stringify(nextWorkspace, null, 2) + '\n',
+    };
+    // Complete validation and formatting before the first write. Only this new
+    // package and the supported user-owned root ebk mapping are in scope.
+    const formatted = await Promise.all(Object.entries(planned).map(async ([path, contents]) => [
+        path,
+        options.skipFormat
+            ? contents
+            : await (0, prettier_1.format)(contents, { filepath: path, singleQuote: true }),
+    ]));
+    for (const [path, contents] of formatted)
+        tree.write(path, contents);
+}
+exports.default = blueprintGenerator;
+//# sourceMappingURL=blueprint.js.map

package/src/generators/blueprint/files.d.ts

@@ -0,0 +1,6 @@
+export declare function createBlueprintAuthoringFiles(options: {
+    engine: string;
+    name: string;
+    packageName: string;
+    root: string;
+}): Record<string, string>;