@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.41

package/src/foundation/capability-plan.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOUNDATION_CAPABILITY_VOCABULARY = exports.FOUNDATION_BASE_CAPABILITIES = exports.LEGACY_STANDARD_FOUNDATION_CAPABILITIES = exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION = void 0;
+exports.readStandardSqlDeclaration = readStandardSqlDeclaration;
+exports.standardPersistenceRequirement = standardPersistenceRequirement;
+exports.planFoundationCapabilities = planFoundationCapabilities;
+const semver_1 = require("semver");
+const validation_js_1 = require("../validation.js");
+/** Resource capability version, independent of the requirement-document schema. */
+exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION = '2.0.0';
+/** Known generated-source migration only; never accepted as a live v2 contract. */
+exports.LEGACY_STANDARD_FOUNDATION_CAPABILITIES = [
+    'network',
+    'routing',
+    'container-compute',
+    'postgres',
+    'identity',
+    'events',
+    'observability',
+    'configuration',
+    'deployment',
+];
+exports.FOUNDATION_BASE_CAPABILITIES = [
+    'key-value',
+    'routing',
+    'identity',
+    'events',
+    'observability',
+    'configuration',
+    'deployment',
+];
+exports.FOUNDATION_CAPABILITY_VOCABULARY = [
+    ...exports.FOUNDATION_BASE_CAPABILITIES,
+    'network',
+    'container-compute',
+    'postgres',
+];
+function requireCapabilities(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array.`);
+    const seen = new Set();
+    for (const capability of value) {
+        if (typeof capability !== 'string' ||
+            !exports.FOUNDATION_CAPABILITY_VOCABULARY.some((known) => known === capability) ||
+            seen.has(capability)) {
+            throw new Error(`${label} contains an unknown or duplicate capability.`);
+        }
+        seen.add(capability);
+    }
+    return [...value];
+}
+function requireExactKeys(value, keys, label) {
+    if (Object.keys(value).some((key) => !keys.includes(key))) {
+        throw new Error(`${label} contains unsupported properties.`);
+    }
+}
+/** Absence means DynamoDB-first; false/null is never a database retirement instruction. */
+function readStandardSqlDeclaration(inputs) {
+    if (!(0, validation_js_1.isRecord)(inputs))
+        throw new Error('Standard Blueprint inputs must be an object.');
+    if (!Object.prototype.hasOwnProperty.call(inputs, 'sql'))
+        return null;
+    const sql = inputs.sql;
+    if (!(0, validation_js_1.isRecord)(sql))
+        throw new Error('Standard Blueprint inputs.sql must declare a relational reason.');
+    requireExactKeys(sql, ['reason'], 'Standard Blueprint inputs.sql');
+    if (typeof sql.reason !== 'string' ||
+        sql.reason.trim().length === 0 ||
+        sql.reason.length > 512 ||
+        [...sql.reason].some((character) => {
+            const code = character.charCodeAt(0);
+            return code < 0x20 || code === 0x7f;
+        })) {
+        throw new Error('Standard Blueprint inputs.sql.reason must be a non-empty single-line rationale of at most 512 characters.');
+    }
+    return { reason: sql.reason.trim() };
+}
+function standardPersistenceRequirement(inputs, compositions = []) {
+    const sql = readStandardSqlDeclaration(inputs);
+    const containers = sql !== null ||
+        compositions.some(({ kind }) => kind === 'service' || kind === 'job');
+    return {
+        contract: '^2.0.0',
+        capabilities: [
+            ...exports.FOUNDATION_BASE_CAPABILITIES,
+            ...(containers ? ['network', 'container-compute'] : []),
+            ...(sql ? ['postgres'] : []),
+        ],
+    };
+}
+function readCurrentDescriptor(value) {
+    if (!(0, validation_js_1.isRecord)(value))
+        throw new Error('Existing Foundation descriptor must be an object.');
+    requireExactKeys(value, ['contractVersion', 'capabilities'], 'Existing Foundation descriptor');
+    const capabilities = requireCapabilities(value.capabilities, 'Existing Foundation capabilities');
+    const available = new Set(capabilities);
+    if (value.contractVersion === '1.0.0') {
+        // This is an explicit generated-source upgrade, not a live discovery fallback.
+        // The old Standard Foundation always provisioned all nine capabilities.
+        if (capabilities.length !== exports.LEGACY_STANDARD_FOUNDATION_CAPABILITIES.length ||
+            exports.LEGACY_STANDARD_FOUNDATION_CAPABILITIES.some((capability) => !available.has(capability))) {
+            throw new Error('Existing v1 Standard Foundation must retain its complete capability declaration before upgrade.');
+        }
+        return { capabilities, migratedFromContract: '1.0.0' };
+    }
+    if (value.contractVersion !== exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION ||
+        exports.FOUNDATION_BASE_CAPABILITIES.some((capability) => !available.has(capability)) ||
+        (available.has('postgres') &&
+            (!available.has('network') || !available.has('container-compute'))) ||
+        (available.has('container-compute') && !available.has('network'))) {
+        throw new Error('Existing Foundation descriptor must use contract 2.0.0 with complete capability dependencies.');
+    }
+    return { capabilities, migratedFromContract: null };
+}
+/**
+ * Pure generation plan. Existing declarations are monotonic: removing a Slice
+ * cannot remove a database, network, or cluster. Retirement is a separate operation.
+ * This function never reads AWS and does not attest that resources are deployed.
+ */
+function planFoundationCapabilities(options) {
+    const current = options.current === undefined
+        ? {
+            capabilities: [],
+            migratedFromContract: null,
+        }
+        : readCurrentDescriptor(options.current);
+    const selected = new Set([
+        ...exports.FOUNDATION_BASE_CAPABILITIES,
+        ...current.capabilities,
+    ]);
+    for (const requirement of options.requirements) {
+        if (!(0, validation_js_1.isRecord)(requirement))
+            throw new Error('Foundation requirement must be an object.');
+        requireExactKeys(requirement, ['contract', 'capabilities'], 'Foundation requirement');
+        if (typeof requirement.contract !== 'string' ||
+            !requirement.contract.trim() ||
+            (0, semver_1.validRange)(requirement.contract) === null ||
+            !(0, semver_1.satisfies)(exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION, requirement.contract)) {
+            throw new Error('Foundation requirement must admit contract 2.0.0; regenerate older Blueprint requirements explicitly.');
+        }
+        for (const capability of requireCapabilities(requirement.capabilities, 'Foundation requirement capabilities')) {
+            selected.add(capability);
+        }
+    }
+    // The current SQL migration implementation uses private container compute.
+    // Keep its resource dependency explicit rather than allocating NAT for every Slice.
+    if (selected.has('postgres'))
+        selected.add('container-compute');
+    if (selected.has('container-compute'))
+        selected.add('network');
+    const capabilities = exports.FOUNDATION_CAPABILITY_VOCABULARY.filter((capability) => selected.has(capability));
+    const retained = new Set(current.capabilities);
+    return {
+        descriptor: {
+            contractVersion: exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION,
+            capabilities,
+        },
+        added: capabilities.filter((capability) => !retained.has(capability)),
+        retained: capabilities.filter((capability) => retained.has(capability)),
+        migratedFromContract: current.migratedFromContract,
+        resources: {
+            containerCompute: selected.has('container-compute'),
+            network: selected.has('network'),
+            postgres: selected.has('postgres'),
+        },
+    };
+}
+//# sourceMappingURL=capability-plan.js.map

package/src/foundation/cost-estimate.d.ts

@@ -0,0 +1,170 @@
+import { type DeploymentProfile } from '../repository-policy/index.js';
+/**
+ * Dated AWS list-price snapshot for the generated cost estimate.
+ *
+ * Every price is copied from the public AWS Price List bulk API
+ * (https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/index.json),
+ * OnDemand terms, without rounding. `usd` is the published price per AWS
+ * `unit`; `per` only scales the displayed unit (for example per million
+ * requests). Refresh the whole snapshot together, change `capturedOn`, and
+ * re-render docs/foundation.md; never compute a date at generation time.
+ */
+export interface ListPriceSource {
+    /** Price List offer code. */
+    offer: string;
+    /** Version segment of the offer file URL. */
+    version: string;
+    /** Offer file region segment: us-east-1, or aws-other for global rates. */
+    file: 'aws-other' | 'us-east-1';
+    sku: string;
+    rateCode: string;
+    usageType: string;
+}
+export interface ListUnitPrice {
+    /** Exact published USD price per AWS unit. */
+    usd: string;
+    /** Display multiplier (a power of ten) applied to `usd`. */
+    per: number;
+    /** Display unit for `per` AWS units, e.g. "million requests". */
+    unit: string;
+    source: ListPriceSource;
+}
+export declare const FOUNDATION_LIST_PRICE_SNAPSHOT: {
+    readonly capturedOn: "2026-10-02";
+    readonly currency: "USD";
+    readonly hoursPerMonth: 730;
+    readonly offerFileUrlTemplate: "https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/<offer>/<version>/<file>/index.json";
+    readonly region: {
+        readonly code: "us-east-1";
+        readonly name: "US East (N. Virginia)";
+    };
+    readonly prices: {
+        readonly apiGatewayHttpRequests: ListUnitPrice;
+        readonly appConfigConfigurationRequests: ListUnitPrice;
+        readonly appConfigConfigurationsReceived: ListUnitPrice;
+        readonly auroraPostgresBackup: ListUnitPrice;
+        readonly auroraPostgresIo: ListUnitPrice;
+        readonly auroraPostgresServerlessV2Acu: ListUnitPrice;
+        readonly auroraPostgresStorage: ListUnitPrice;
+        readonly cloudFrontDataTransferOut: ListUnitPrice;
+        readonly cloudFrontHttpsRequests: ListUnitPrice;
+        readonly cloudWatchAlarmMetric: ListUnitPrice;
+        readonly cloudWatchCustomMetric: ListUnitPrice;
+        readonly cloudWatchDashboard: ListUnitPrice;
+        readonly cloudWatchLogsDataProtection: ListUnitPrice;
+        readonly cloudWatchLogsIngest: ListUnitPrice;
+        readonly cloudWatchLogsStorage: ListUnitPrice;
+        readonly cognitoEssentialsMau: ListUnitPrice;
+        readonly cognitoLiteMau: ListUnitPrice;
+        readonly cognitoMachineAppClient: ListUnitPrice;
+        readonly cognitoMachineTokenRequest: ListUnitPrice;
+        readonly dynamoDbPitrStorage: ListUnitPrice;
+        readonly dynamoDbReadRequestUnits: ListUnitPrice;
+        readonly dynamoDbStorage: ListUnitPrice;
+        readonly dynamoDbWriteRequestUnits: ListUnitPrice;
+        readonly ec2T4gNano: ListUnitPrice;
+        readonly eventBridgeArchiveProcessed: ListUnitPrice;
+        readonly eventBridgeArchiveStorage: ListUnitPrice;
+        readonly eventBridgeCustomEvents: ListUnitPrice;
+        readonly fargateMemoryGbHour: ListUnitPrice;
+        readonly fargateVcpuHour: ListUnitPrice;
+        readonly kmsKey: ListUnitPrice;
+        readonly kmsRequests: ListUnitPrice;
+        readonly lambdaComputeX86: ListUnitPrice;
+        readonly lambdaRequests: ListUnitPrice;
+        readonly natGatewayData: ListUnitPrice;
+        readonly natGatewayHour: ListUnitPrice;
+        readonly publicIpv4InUse: ListUnitPrice;
+        readonly route53HostedZone: ListUnitPrice;
+        readonly s3StandardStorage: ListUnitPrice;
+        readonly secretsManagerApi: ListUnitPrice;
+        readonly secretsManagerSecret: ListUnitPrice;
+        readonly snsRequests: ListUnitPrice;
+        readonly sqsFifoRequests: ListUnitPrice;
+        readonly sqsStandardRequests: ListUnitPrice;
+        readonly stepFunctionsStandardTransitions: ListUnitPrice;
+        readonly wafRequests: ListUnitPrice;
+        readonly wafRule: ListUnitPrice;
+        readonly wafWebAcl: ListUnitPrice;
+    };
+};
+export type ListPriceKey = keyof typeof FOUNDATION_LIST_PRICE_SNAPSHOT.prices;
+/**
+ * Generated Foundation quantities that are literals in the Foundation template
+ * or inside SST 4.17.1 components rather than in a framework contract. The
+ * cost-estimate count-drift spec executes the generated Foundation and fails
+ * when any of these differ from what the generator constructs.
+ */
+export declare const FOUNDATION_COST_INVENTORY: {
+    /** One CloudFront Router Web ACL per stage. */
+    readonly wafWebAcls: 1;
+    /** One Foundation CloudWatch dashboard per stage. */
+    readonly dashboards: 1;
+    /** Declared network: `az: 2`, one Elastic IP and one NAT unit per public subnet. */
+    readonly availabilityZones: 2;
+    /** SST Vpc Cloud Map private DNS namespace (a Route 53 private hosted zone). */
+    readonly privateHostedZones: 1;
+    /** Declared nonproduction NAT mode; production uses its capacity contract. */
+    readonly nonproductionNat: "ec2";
+    /** SST Aurora master credential secret. */
+    readonly auroraMasterSecrets: 1;
+    /** Declared SQL Foundation alarm metrics (Aurora capacity alarm). */
+    readonly sqlAlarmMetrics: 1;
+    /** Declared nonproduction Aurora scaling. */
+    readonly nonproductionAurora: {
+        readonly development: {
+            readonly max: "2 ACU";
+            readonly min: "0 ACU";
+            readonly pauseAfter: "5 minutes";
+        };
+        readonly staging: {
+            readonly max: "4 ACU";
+            readonly min: "0 ACU";
+            readonly pauseAfter: "5 minutes";
+        };
+    };
+    /** Seeded Router WAF access: nonproduction allowlist, production public. */
+    readonly routerWafAccess: {
+        readonly development: "allowlist";
+        readonly staging: "allowlist";
+        readonly production: "public";
+    };
+};
+export interface StandardSliceCostInventory {
+    alarms: number;
+    alarmMetrics: number;
+    dataProtectedLogGroups: number;
+    kmsKeys: number;
+    /** Secrets Manager secrets created by Slice infrastructure. */
+    secrets: number;
+    machineClients: number;
+    dashboards: number;
+}
+/**
+ * Per-stage fixed inventory of one default Standard Slice (no async adapters,
+ * performance load off). The count-drift spec renders and executes the
+ * generated Slice infrastructure and fails when these differ.
+ */
+export declare const STANDARD_SLICE_COST_INVENTORY: Readonly<{
+    sqlFree: StandardSliceCostInventory;
+    sqlDeclared: StandardSliceCostInventory;
+    personalStage: StandardSliceCostInventory;
+}>;
+export declare const FOUNDATION_COST_ESTIMATE_BEGIN_MARKER = "<!-- ebk:foundation-cost-estimate:begin -->";
+export declare const FOUNDATION_COST_ESTIMATE_END_MARKER = "<!-- ebk:foundation-cost-estimate:end -->";
+/** The exact label every rendered estimate carries. */
+export declare function foundationCostEstimateLabel(): string;
+/** Nonproduction Aurora scaling as costs.md prose, e.g. "0–4 ACUs, pause after 5 idle minutes". */
+export declare function nonproductionAuroraScalingLabel(stage: 'development' | 'staging'): string;
+export interface FoundationCostEstimateOptions {
+    deploymentProfile: DeploymentProfile;
+    /** Markdown level of the estimate's top heading (2 for costs.md, 3 for docs). */
+    headingLevel: 2 | 3;
+}
+/**
+ * Pure, deterministic Markdown renderer for the dated list-price estimate.
+ * Quantities derive from the Foundation capability plan, the deployment
+ * profile's active stages, the production capacity contracts and the
+ * drift-checked inventories above. No clock, network or environment input.
+ */
+export declare function renderFoundationCostEstimate(options: FoundationCostEstimateOptions): string;