@fjall/components-infrastructure 7.3.0 → 9.0.0

package/dist/lib/utils/exportNaming.d.ts

@@ -0,0 +1,50 @@
+import type { Construct } from "constructs";
+/**
+ * Qualify a CloudFormation export name with the stack that emits it.
+ *
+ * Export names are unique per account per region, so a name built only from a
+ * construct id or a cluster name is shared by every app that happens to use
+ * the same id — and the ids inside a pattern are literals the app author never
+ * chooses. Two apps then collide, and the second one fails at CloudFormation
+ * execution ("Export with name X is already exported by stack Y") after its
+ * first resources exist, so it rolls back rather than refusing up front.
+ *
+ * Stack names are already unique per account+region (CloudFormation enforces
+ * it) and Fjall derives them from the app name, so prefixing with the stack
+ * name makes the export globally unique AND puts the app name in it.
+ *
+ * The suffix must stay last. Consumers match these by suffix and by app-name
+ * token, never by whole string — `EcsServiceResolver` filters on
+ * `endsWith("deployableservice")` (deploy-core
+ * services/infrastructure/EcsServiceResolver.ts) and the webapp finds a linked
+ * app's CIDR by `ListExports` + a `-vpc-cidr` suffix filter
+ * (webapp app/.server/services/infrastructure/captureVpcCidr.ts). Prefixing is
+ * transparent to both; changing the tail is not.
+ *
+ * NOT for exports a consumer reconstructs by whole name. Those are contracts
+ * with their own vocabulary module and must keep their exact spelling:
+ * `getDomainExportNames` (@fjall/util), `EXPORT_NAMES`
+ * (patterns/aws/targets/targetResolution.ts), `SHARED_ALARM_TOPIC_EXPORT_NAME`,
+ * the CloudTrail output keys, and `${toPascalCase(appName)}EcrRepositoryName`
+ * (read by `resolveEcrRepositoryName` in the CLI). Account-level singletons
+ * (`AccountId`, `Environment`, `OrganisationId`, `FjallAuditRoleArn`, …) also
+ * keep their bare names: exactly one is meant to exist, so a collision there
+ * correctly reports a duplicate deployment.
+ */
+export declare function stackScopedExportName(scope: Construct, suffix: string): string;
+/**
+ * Export name for the account's IPAM private default scope.
+ *
+ * Deliberately unqualified: exactly one IPAM exists per account, so a
+ * collision here correctly reports a duplicate deployment rather than an
+ * accidental clash between two apps.
+ *
+ * It lives here rather than beside the construct that emits it because the
+ * producer is in `config/` and the consumer (`IpamPool`) is in `resources/`,
+ * which may not import from `config/`. Both sides must read the same
+ * constant: CloudFormation export names are case-sensitive, and the two sites
+ * previously disagreed on the leading capital — so the import could never
+ * resolve, and the only reason nothing broke is that every caller passed
+ * `ipamScope` explicitly and never reached the fallback.
+ */
+export declare const IPAM_PRIVATE_DEFAULT_SCOPE_EXPORT_NAME = "IpamPrivateDefaultScopeId";

package/dist/lib/utils/exportNaming.js

@@ -0,0 +1,52 @@
+import { Stack } from "aws-cdk-lib";
+/**
+ * Qualify a CloudFormation export name with the stack that emits it.
+ *
+ * Export names are unique per account per region, so a name built only from a
+ * construct id or a cluster name is shared by every app that happens to use
+ * the same id — and the ids inside a pattern are literals the app author never
+ * chooses. Two apps then collide, and the second one fails at CloudFormation
+ * execution ("Export with name X is already exported by stack Y") after its
+ * first resources exist, so it rolls back rather than refusing up front.
+ *
+ * Stack names are already unique per account+region (CloudFormation enforces
+ * it) and Fjall derives them from the app name, so prefixing with the stack
+ * name makes the export globally unique AND puts the app name in it.
+ *
+ * The suffix must stay last. Consumers match these by suffix and by app-name
+ * token, never by whole string — `EcsServiceResolver` filters on
+ * `endsWith("deployableservice")` (deploy-core
+ * services/infrastructure/EcsServiceResolver.ts) and the webapp finds a linked
+ * app's CIDR by `ListExports` + a `-vpc-cidr` suffix filter
+ * (webapp app/.server/services/infrastructure/captureVpcCidr.ts). Prefixing is
+ * transparent to both; changing the tail is not.
+ *
+ * NOT for exports a consumer reconstructs by whole name. Those are contracts
+ * with their own vocabulary module and must keep their exact spelling:
+ * `getDomainExportNames` (@fjall/util), `EXPORT_NAMES`
+ * (patterns/aws/targets/targetResolution.ts), `SHARED_ALARM_TOPIC_EXPORT_NAME`,
+ * the CloudTrail output keys, and `${toPascalCase(appName)}EcrRepositoryName`
+ * (read by `resolveEcrRepositoryName` in the CLI). Account-level singletons
+ * (`AccountId`, `Environment`, `OrganisationId`, `FjallAuditRoleArn`, …) also
+ * keep their bare names: exactly one is meant to exist, so a collision there
+ * correctly reports a duplicate deployment.
+ */
+export function stackScopedExportName(scope, suffix) {
+    return `${Stack.of(scope).stackName}${suffix}`;
+}
+/**
+ * Export name for the account's IPAM private default scope.
+ *
+ * Deliberately unqualified: exactly one IPAM exists per account, so a
+ * collision here correctly reports a duplicate deployment rather than an
+ * accidental clash between two apps.
+ *
+ * It lives here rather than beside the construct that emits it because the
+ * producer is in `config/` and the consumer (`IpamPool`) is in `resources/`,
+ * which may not import from `config/`. Both sides must read the same
+ * constant: CloudFormation export names are case-sensitive, and the two sites
+ * previously disagreed on the leading capital — so the import could never
+ * resolve, and the only reason nothing broke is that every caller passed
+ * `ipamScope` explicitly and never reached the fallback.
+ */
+export const IPAM_PRIVATE_DEFAULT_SCOPE_EXPORT_NAME = "IpamPrivateDefaultScopeId";

package/dist/lib/utils/orgConfigParser.d.ts

@@ -6,15 +6,10 @@ export interface ParsedOrgConfig {
     disasterRecoveryRegion?: string;
 }
 /**
- * Resolve a provider account's synth-time environment. The tier/stage
- * separation (decisions/2026-06-07-account-tier-vs-stage-separation.md) nulls
- * the wire `environment` for organisation-tier accounts, but scaffolded org
- * entry points gate on `config.environment === "root"` — decode the tier back
- * to the historical "root" marker via the sanctioned `accountTier()` decoder.
- * Workload stages pass through verbatim; a null stage on any other tier stays
- * unresolved (callers fall back to "unknown").
+ * Re-exported from `@fjall/util` so the synth-time reader and deploy-core's
+ * pre-synth resolver cannot drift. Do not redeclare it here.
  */
-export declare function resolveSynthEnvironment(account: Pick<ProviderAccount, "environment" | "tier">): string | undefined;
+export { resolveSynthEnvironment } from "@fjall/util";
 /**
  * Parse orgConfig JSON from CDK context into a validated structure.
  *

package/dist/lib/utils/orgConfigParser.js

@@ -1,5 +1,5 @@
 import { VAULT_LOCK_MODES, S3_BPA_MODES } from "@fjall/util/config";
-import { ACCOUNT_TIERS, STRUCTURAL_ENVIRONMENTS, accountTier, maskSensitiveOutput } from "@fjall/util";
+import { ACCOUNT_TIERS, maskSensitiveOutput } from "@fjall/util";
 import { FjallLogger } from "./validationLogger.js";
 function isProviderAccount(item) {
     if (typeof item !== "object" || item === null)
@@ -20,20 +20,10 @@ function isProviderAccount(item) {
             typeof rec.acknowledgeImmutableVaultLock === "boolean"));
 }
 /**
- * Resolve a provider account's synth-time environment. The tier/stage
- * separation (decisions/2026-06-07-account-tier-vs-stage-separation.md) nulls
- * the wire `environment` for organisation-tier accounts, but scaffolded org
- * entry points gate on `config.environment === "root"` — decode the tier back
- * to the historical "root" marker via the sanctioned `accountTier()` decoder.
- * Workload stages pass through verbatim; a null stage on any other tier stays
- * unresolved (callers fall back to "unknown").
+ * Re-exported from `@fjall/util` so the synth-time reader and deploy-core's
+ * pre-synth resolver cannot drift. Do not redeclare it here.
  */
-export function resolveSynthEnvironment(account) {
-    if (accountTier(account) === "organisation") {
-        return STRUCTURAL_ENVIRONMENTS.ROOT;
-    }
-    return account.environment ?? undefined;
-}
+export { resolveSynthEnvironment } from "@fjall/util";
 function describeRejectedAccount(item) {
     if (typeof item !== "object" || item === null)
         return "<unidentifiable>";

package/dist/lib/utils/removalPolicy.d.ts

@@ -8,10 +8,18 @@ export declare function toRemovalPolicy(value?: "DESTROY" | "RETAIN" | "SNAPSHOT
  * benign), an unrecognised value here throws at synth: silently landing a
  * typo like `ENVIRONMENT=prod` on DESTROY deletes data when the stack is
  * deleted. The accept-set derives from `ACCOUNT_STAGES_WITH_ROOT` so a new
- * stage added in `@fjall/util` widens it automatically. The no-signal
- * sentinel keeps the historical warn-and-DESTROY behaviour — raw `cdk synth`
- * without context and null-stage cascade synths rely on it. An explicitly
+ * stage added in `@fjall/util` widens it automatically. An explicitly
  * supplied `ENVIRONMENT=unknown` collides with the sentinel string and would
  * otherwise ride the silent-DESTROY path, so it is treated as unrecognised.
+ *
+ * The no-signal sentinel keeps warn-and-DESTROY for a BARE `cdk synth`: a
+ * developer inspecting a template deploys nothing, so the policy it prints
+ * costs nothing. It is not a safe default for a synth that is about to
+ * deploy, so a Fjall-driven one (`isFjallDrivenSynth`) throws instead — there,
+ * "no signal" means the account resolved to no environment, and reading that
+ * as DESTROY is how a production stack ends up with `Delete` on every bucket.
+ * deploy-core resolves the environment before synth and passes it explicitly
+ * (deploy-core orchestration/deployEnvironment.ts), so a conforming deploy
+ * reaches neither branch; this is the backstop for one that does.
  */
 export declare function envAwareRemovalPolicyDefault(): "DESTROY" | "RETAIN";

package/dist/lib/utils/removalPolicy.js

@@ -1,6 +1,6 @@
 import { ACCOUNT_STAGES_WITH_ROOT } from "@fjall/util";
 import { RemovalPolicy } from "aws-cdk-lib";
-import { getEnvironment, hasExplicitEnvironmentSignal, UNKNOWN_ENVIRONMENT } from "./env.js";
+import { getEnvironment, hasExplicitEnvironmentSignal, isFjallDrivenSynth, UNKNOWN_ENVIRONMENT } from "./env.js";
 export function toRemovalPolicy(value) {
     switch (value) {
         case "DESTROY":
@@ -21,16 +21,31 @@ const REMOVAL_DEFAULT_ENVIRONMENTS = new Set(ACCOUNT_STAGES_WITH_ROOT);
  * benign), an unrecognised value here throws at synth: silently landing a
  * typo like `ENVIRONMENT=prod` on DESTROY deletes data when the stack is
  * deleted. The accept-set derives from `ACCOUNT_STAGES_WITH_ROOT` so a new
- * stage added in `@fjall/util` widens it automatically. The no-signal
- * sentinel keeps the historical warn-and-DESTROY behaviour — raw `cdk synth`
- * without context and null-stage cascade synths rely on it. An explicitly
+ * stage added in `@fjall/util` widens it automatically. An explicitly
  * supplied `ENVIRONMENT=unknown` collides with the sentinel string and would
  * otherwise ride the silent-DESTROY path, so it is treated as unrecognised.
+ *
+ * The no-signal sentinel keeps warn-and-DESTROY for a BARE `cdk synth`: a
+ * developer inspecting a template deploys nothing, so the policy it prints
+ * costs nothing. It is not a safe default for a synth that is about to
+ * deploy, so a Fjall-driven one (`isFjallDrivenSynth`) throws instead — there,
+ * "no signal" means the account resolved to no environment, and reading that
+ * as DESTROY is how a production stack ends up with `Delete` on every bucket.
+ * deploy-core resolves the environment before synth and passes it explicitly
+ * (deploy-core orchestration/deployEnvironment.ts), so a conforming deploy
+ * reaches neither branch; this is the backstop for one that does.
  */
 export function envAwareRemovalPolicyDefault() {
     const environment = getEnvironment();
     if (environment === UNKNOWN_ENVIRONMENT && !hasExplicitEnvironmentSignal()) {
-        return "DESTROY";
+        if (!isFjallDrivenSynth())
+            return "DESTROY";
+        throw new Error(`Refusing to resolve the env-aware removal-policy default: this deploy ` +
+            `carries an organisation config, but the account it targets resolved ` +
+            `to no environment. Defaulting to DESTROY here would delete data when ` +
+            `the stack is deleted. Set the target account's environment in the ` +
+            `organisation config, or pass -c environment=<value> explicitly. ` +
+            `Valid values: ${ACCOUNT_STAGES_WITH_ROOT.join(", ")}.`);
     }
     if (!REMOVAL_DEFAULT_ENVIRONMENTS.has(environment)) {
         throw new Error(`Unrecognised environment "${environment}" — refusing to resolve the ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "7.3.0",
+  "version": "9.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -47,8 +47,9 @@
     "test:watch": "vitest",
     "contract:manifest": "FJALL_WRITE_CONTRACT_MANIFEST=1 vitest run lib/__tests__/_contract/contract.test.ts",
     "cdk": "cdk",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json && tsc --noEmit -p tsconfig.deploy-tests.json",
     "typecheck:tests": "tsc --noEmit -p tsconfig.test.json",
+    "typecheck:deploy-tests": "tsc --noEmit -p tsconfig.deploy-tests.json",
     "check:scripts": "tsc --project tsconfig.scripts.json",
     "deploy-test": "tsx deploy-tests/run.mts",
     "deploy-test:ops": "tsx deploy-tests/ops.mts",
@@ -78,8 +79,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^7.3.0",
-    "@fjall/util": "^7.3.0",
+    "@fjall/generator": "^9.0.0",
+    "@fjall/util": "^9.0.0",
     "constructs": "^10.7.2"
   },
   "overrides": {