@fjall/deploy-core 7.1.0 → 7.2.0

package/dist/.build-source-hash

@@ -9,7 +9,7 @@
     "package.json",
     "tsconfig.json"
   ],
-  "hash": "3ac67fa1123461c35ead0b130bd78ff3854de09e21665058101ab80eb6b8f76a",
+  "hash": "d471f35f40c7c92d371201481e61e9fd32faf7b081dc9f87779382598575b4f5",
   "files": {
     "src/__test-utils__/awsMockHelpers.ts": "fea371c1b1869678",
     "src/__test-utils__/index.ts": "e03cf35821157dc4",
@@ -52,7 +52,7 @@
     "src/aws/utils/regions.ts": "3a5191f4d2242a60",
     "src/aws/utils/stackStatus.ts": "55fb23ba5514bc13",
     "src/events/index.ts": "e55c022f0d9013e6",
-    "src/index.ts": "246666b0fa119a1c",
+    "src/index.ts": "138bc00a3dedc54f",
     "src/orchestration/activeDeploymentGuard.ts": "e8dde742c00ea728",
     "src/orchestration/application/applicationDeploy.ts": "2da75f7e60474a5a",
     "src/orchestration/application/applicationDeployHelpers.ts": "a8023472f95d3f05",
@@ -177,16 +177,16 @@
     "src/services/application/ApplicationStackService.ts": "45824be79c1b82aa",
     "src/services/application/applicationStackHelpers.ts": "04e1758b97ffc5fc",
     "src/services/application/index.ts": "ee810be803dfda9c",
-    "src/services/index.ts": "cc84cbd35873b20d",
+    "src/services/index.ts": "8c441c1b37540650",
     "src/services/infrastructure/CdkArgumentBuilder.ts": "e1b866b72e619bf5",
-    "src/services/infrastructure/CdkCommandRunner.ts": "e33d4e529298f518",
+    "src/services/infrastructure/CdkCommandRunner.ts": "427a9c1171902e42",
     "src/services/infrastructure/CdkErrorFormatter.ts": "e2e017136108a5d1",
     "src/services/infrastructure/CdkEventMonitoring.ts": "2b0ecd84f76c54c1",
     "src/services/infrastructure/CdkOutputAnalyser.ts": "37114ecae45d7017",
     "src/services/infrastructure/CdkOutputParser.ts": "eed9f3475324118e",
     "src/services/infrastructure/CdkProcessManager.ts": "f68ae4e44adee2fa",
-    "src/services/infrastructure/CdkService.ts": "1ec1718dfc3cb587",
-    "src/services/infrastructure/CdkServiceTypes.ts": "6dc7429857b2efee",
+    "src/services/infrastructure/CdkService.ts": "9b5883d5362be9b0",
+    "src/services/infrastructure/CdkServiceTypes.ts": "c4f3075238952728",
     "src/services/infrastructure/CfnRegistryService.ts": "bd4f57d97982cdda",
     "src/services/infrastructure/CloudFormationService.ts": "82ce03614feae2db",
     "src/services/infrastructure/EcrImageInspectorService.ts": "e784440b5680df74",
@@ -195,13 +195,14 @@
     "src/services/infrastructure/ICdkProcessManager.ts": "7e7bfe7dacc999f6",
     "src/services/infrastructure/LambdaService.ts": "5b21e34185e77a4c",
     "src/services/infrastructure/SsmParameterMetadataService.ts": "3ff0bb42219cec3d",
+    "src/services/infrastructure/bootstrapConvergence.ts": "ca11f0bf9552ba8c",
     "src/services/infrastructure/cancelInFlightStack.ts": "8388a16a23db725a",
     "src/services/infrastructure/cdkServiceHelpers.ts": "2db30686382e568a",
     "src/services/infrastructure/cfnRegistrySeed.ts": "b1232b66883d6f90",
     "src/services/infrastructure/changeSetProbe.ts": "5f3e100db396cf9b",
     "src/services/infrastructure/constructMapEnrichment.ts": "7400af9bcfaa0da3",
     "src/services/infrastructure/dependencyIntegrityGate.ts": "c984bb1620f73f38",
-    "src/services/infrastructure/index.ts": "1241c6dc24d925fe",
+    "src/services/infrastructure/index.ts": "c45e43711bf64fa9",
     "src/services/infrastructure/infraTypecheckPreflight.ts": "09e423a8283e3b8b",
     "src/services/infrastructure/transientNetworkRecovery.ts": "44a9333ce963bf50",
     "src/services/supporting/CdkContextBuilder.ts": "dee16f4302f7312a",
@@ -255,9 +256,9 @@
     "src/util/sleepAbortable.ts": "f9cac3bf8a79a476",
     "src/version.ts": "1811a4475823b27e",
     "../scripts/minify-dist.mjs": "6b2e4b0df8aec601",
-    "package.json": "4a2daca4713da152",
+    "package.json": "05b055cd30867fc1",
     "tsconfig.json": "1929cf3f99fe9b1e"
   },
-  "outputHash": "c2b4d1981a0a0e4b3f626776d932d77f5525dc0457909bb0390ec0620974c394",
-  "outputFileCount": 479
+  "outputHash": "de61f3e9e5353ea996e61e068fb1054c7460b0e48216a23ea707c046bf775001",
+  "outputFileCount": 481
 }

package/dist/.minified

@@ -1 +1 @@
-239 files minified at 2026-08-05T08:58:52.836Z
+240 files minified at 2026-08-06T02:34:18.572Z

package/dist/src/index.d.ts

@@ -40,7 +40,7 @@ export { readDomainState, writeDomainState, recordDomainDeployState, deleteDomai
 export { CloudFormationEventMonitor } from "./aws/index.js";
 export type { AwsClientLike, EventLogWriter, EventFailureAnalyser, EventLogWriterFactory, EventMonitorDeps } from "./aws/index.js";
 export { CdkService, CdkArgumentBuilder, CdkProcessManager, ensureDependencyIntegrity, clearDependencyIntegrityCache, DEPENDENCY_SYNC_TIMEOUT_MS, CdkEventMonitor, startStackMonitoring, DEFAULT_DEPLOY_TIMEOUT_MS, isCdkError, formatInfrastructureError, getStructuralHint, getSourceContext, hasCdkDifferences, parseDiffOutput, CloudFormationService, CloudFormationError, EcsService, EcsError, EcsServiceResolver, type CfnExportsClient, TemplateHashService, TemplateHashError, type TemplateComparisonResult, CdkContextBuilder, emitProgress, PROGRESS_MESSAGES, parseBuildPhase, buildStepContextBuildConfig, convertCloudFormationOutputsToRecord, type CloudFormationOutput, ApplicationStackService } from "./services/index.js";
-export type { CdkContext, CdkOptions, CdkOutput, CheckDifferencesResult, CdkServiceOptions, ICdkProcessManager, DependencyIntegrityOutcome, DependencyIntegrityStatus, EnsureDependencyIntegrityOptions, DiffDetails, CloudFormationCallbacks, ECSServiceInfo, ECSClusterInfo, DeploymentStatus, ECSDeploymentOptions } from "./services/index.js";
+export type { BootstrapRunFailure, CdkContext, CdkOptions, CdkOutput, CheckDifferencesResult, CdkServiceOptions, ICdkProcessManager, DependencyIntegrityOutcome, DependencyIntegrityStatus, EnsureDependencyIntegrityOptions, DiffDetails, CloudFormationCallbacks, ECSServiceInfo, ECSClusterInfo, DeploymentStatus, ECSDeploymentOptions } from "./services/index.js";
 export { CdkError } from "./types/errors/index.js";
 export { type ServiceErrorDetails, type ServiceError, BaseServiceError, ValidationError, AuthError, AwsError, DeploymentError, NetworkError, FileSystemError, ConfigError, toServiceError } from "./types/errors/index.js";
 export { filterDangerousEnvVars, maskSensitiveOutput, parseShellArgs, sleep } from "@fjall/util";

package/dist/src/services/index.d.ts

@@ -1,5 +1,5 @@
 export { CdkService, CdkArgumentBuilder, CdkProcessManager, ensureDependencyIntegrity, clearDependencyIntegrityCache, DEPENDENCY_SYNC_TIMEOUT_MS, CdkEventMonitor, startStackMonitoring, DEFAULT_DEPLOY_TIMEOUT_MS, isCdkError, formatInfrastructureError, getStructuralHint, getSourceContext, hasCdkDifferences, parseDiffOutput, CloudFormationService, CloudFormationError, CfnRegistryService, CFN_REGISTRY_SEED, EcsService, EcsError, EcsServiceResolver, type CfnExportsClient } from "./infrastructure/index.js";
-export type { CdkContext, CdkOptions, CdkOutput, CheckDifferencesResult, CdkServiceOptions, ICdkProcessManager, DependencyIntegrityOutcome, DependencyIntegrityStatus, EnsureDependencyIntegrityOptions, DiffDetails, CloudFormationCallbacks, CfnRegistrySchemaSummary, CfnRegistryServiceOptions, CfnRegistrySummaryReader, ECSServiceInfo, ECSClusterInfo, DeploymentStatus, ECSDeploymentOptions } from "./infrastructure/index.js";
+export type { BootstrapRunFailure, CdkContext, CdkOptions, CdkOutput, CheckDifferencesResult, CdkServiceOptions, ICdkProcessManager, DependencyIntegrityOutcome, DependencyIntegrityStatus, EnsureDependencyIntegrityOptions, DiffDetails, CloudFormationCallbacks, CfnRegistrySchemaSummary, CfnRegistryServiceOptions, CfnRegistrySummaryReader, ECSServiceInfo, ECSClusterInfo, DeploymentStatus, ECSDeploymentOptions } from "./infrastructure/index.js";
 export { TemplateHashService, TemplateHashError, type TemplateComparisonResult } from "./supporting/index.js";
 export { CdkContextBuilder } from "./supporting/index.js";
 export { emitProgress, PROGRESS_MESSAGES, parseBuildPhase, buildStepContextBuildConfig, convertCloudFormationOutputsToRecord, type CloudFormationOutput } from "./supporting/index.js";

package/dist/src/services/infrastructure/CdkCommandRunner.d.ts

@@ -2,6 +2,7 @@ import type { Result } from "@fjall/generator";
 import { CdkError } from "../../types/errors/CdkError.js";
 import { type DiffDetails } from "./CdkOutputParser.js";
 import type { ICdkProcessManager } from "./ICdkProcessManager.js";
+import { type BootstrapRunFailure } from "./bootstrapConvergence.js";
 import type { CdkOptions, CdkOutput } from "./CdkService.js";
 /** Synth is CPU-bound template generation — 5 minutes is generous */
 export declare const SYNTH_TIMEOUT_MS = 300000;
@@ -35,5 +36,5 @@ export declare class CdkCommandRunner {
      */
     runImport(path: string, resourceMappingFile?: string, options?: CdkOptions): Promise<Result<CdkOutput, string>>;
     synth(path: string, options?: CdkOptions): Promise<Result<CdkOutput, string>>;
-    bootstrap(accountId: string, region: string, options?: CdkOptions): Promise<Result<CdkOutput, string>>;
+    bootstrap(accountId: string, region: string, options?: CdkOptions): Promise<Result<CdkOutput, BootstrapRunFailure>>;
 }

package/dist/src/services/infrastructure/CdkCommandRunner.js

@@ -1,2 +1,2 @@
-var E=Object.defineProperty;var f=(m,s)=>E(m,"name",{value:s,configurable:!0});import{tmpdir as O}from"os";import{resolve as A}from"path";import{logger as l}from"@fjall/util/logger";import{success as p,failure as i}from"@fjall/generator";import{CdkError as h}from"../../types/errors/CdkError.js";import{DEFAULT_REGION as P}from"../../aws/utils/regions.js";import{CdkArgumentBuilder as g}from"./CdkArgumentBuilder.js";import{isCdkError as _,formatInfrastructureError as c}from"./CdkErrorFormatter.js";import{hasCdkDifferences as L,parseDiffOutput as R}from"./CdkOutputParser.js";import{DEFAULT_DEPLOY_TIMEOUT_MS as C}from"./CdkEventMonitoring.js";import{analyseBootstrapError as y}from"./CdkOutputAnalyser.js";const k=3e5,S=18e4,D=12e5,b="cdk.out",o=Object.freeze({APP:"--app",CI:"--ci",REQUIRE_APPROVAL:"--require-approval",APPROVAL_NEVER:"never",VERBOSE:"--verbose",NO_LOOKUPS:"--no-lookups",ALL:"--all",EXCLUSIVELY:"--exclusively"});class F{static{f(this,"CdkCommandRunner")}processManager;argumentBuilder=new g;constructor(s){this.processManager=s}dispose(){this.processManager.dispose()}async checkDifferences(s,t,r){const e=["diff"];t?e.push(t):e.push(o.ALL),e.push("--no-color"),r?.noLookups&&e.push(o.NO_LOOKUPS);const u=await this.processManager.runCdkCommand(s,e,{...r,ignoreExitCode:!0,combineOutput:!0});if(!u.success)return i(new h(c(u.error,s),"diff_failed",void 0,void 0,u.error,void 0,!1));const a=u.data.output||"";if(_(a))return i(new h(c(a,s),"diff_failed",void 0,void 0,a,void 0,!1));const n=L(a),d=R(a);return p({hasDifferences:n,output:a,details:d})}async deploy(s,t,r){const e=["deploy"];r?.appDir?e.push(o.APP,r.appDir):r?.useCdkOut&&e.push(o.APP,"cdk.out"),t?(e.push(t),r?.exclusively&&e.push(o.EXCLUSIVELY)):e.push(o.ALL),e.push(o.REQUIRE_APPROVAL,o.APPROVAL_NEVER),e.push(o.CI),e.push("--no-version-reporting"),e.push("--no-path-metadata"),e.push("--no-asset-metadata"),r?.verbose?e.push(o.VERBOSE):e.push("--progress","events"),e.push(...this.argumentBuilder.buildParameterArgs(r?.parameters,t));const u={...r,timeout:r?.timeout||C};return r?.passThroughCDK?this.processManager.runCdkCommandPassthrough(s,e,u):this.processManager.runCdkCommand(s,e,u)}async destroy(s,t,r){const e=["destroy"];r?.appDir?e.push(o.APP,r.appDir):r?.useCdkOut&&e.push(o.APP,"cdk.out"),t?e.push(t):e.push(o.ALL),e.push("--force"),r?.verbose&&e.push(o.VERBOSE);const u={...r,timeout:r?.timeout||C};return this.processManager.runCdkCommand(s,e,u)}async runImport(s,t,r){const e=["import"];r?.stacks&&r.stacks.length>0&&e.push(...r.stacks),t&&e.push("--resource-mapping",t),e.push(o.REQUIRE_APPROVAL,o.APPROVAL_NEVER),e.push(o.CI),r?.noLookups&&e.push(o.NO_LOOKUPS),r?.verbose&&(e.push(o.VERBOSE),e.push("--trace"),e.push("--debug"));const u={...r,timeout:r?.timeout||D};return r?.passThroughCDK?this.processManager.runCdkCommandPassthrough(s,e,u):this.processManager.runCdkCommand(s,e,u)}async synth(s,t){t?.outputCallback?.(`Synthesising CloudFormation template...
-`);const r=t?.noLookups?[o.NO_LOOKUPS]:[],u=["--output",A(s,t?.outputDir??b)],a=t?.context?.region||P,n=await this.processManager.runCdkCommand(s,["synth",...r,...u,o.CI,"--quiet"],{...t,context:{...t?.context,region:a},timeout:t?.timeout||k});if(!n.success){const d=n.error?c(n.error,s):"Failed to synthesise CloudFormation template";return i(d)}return n}async bootstrap(s,t,r){const e=O();l.debug("CdkService","Starting CDK bootstrap",{accountId:s,region:t,bootstrapPath:e,target:`aws://${s}/${t}`});const u=await this.processManager.runCdkCommand(e,["bootstrap",`aws://${s}/${t}`,"--cloudformation-execution-policies","arn:aws:iam::aws:policy/AdministratorAccess",...r?.permissionsBoundary!==void 0&&r.permissionsBoundary!==""?["--custom-permissions-boundary",r.permissionsBoundary]:[],...Object.entries(r?.bootstrapTags??{}).filter(([a,n])=>a!==""&&n!=="").flatMap(([a,n])=>["--tags",`${a}=${n}`]),"-c",`accountId=${s}`,o.REQUIRE_APPROVAL,o.APPROVAL_NEVER,o.CI,"--quiet","--force"],{...r,timeout:r?.timeout||S,context:{region:t,accountId:s},credentials:r?.credentials,skipProjectCheck:!0,extraEnv:{TERM:"dumb",CDK_DISABLE_NOTICES:"true",CDK_DISABLE_PROGRESS_BAR:"true"}});return l.debug("CdkService",u.success?"Bootstrap completed successfully":"Bootstrap exited with non-zero code",{accountId:s,region:t,exitCode:u.success?u.data.exitCode:void 0,output:u.success&&u.data.output?.trim()||"(empty)",error:u.success?"(empty)":u.error.trim()||"(empty)"}),u.success?p({output:"AWS environment bootstrapped",exitCode:0}):u.error.includes("already bootstrapped")?p({output:"Environment is already bootstrapped",exitCode:0}):i(y(u.error))}}export{S as BOOTSTRAP_TIMEOUT_MS,F as CdkCommandRunner,D as IMPORT_TIMEOUT_MS,k as SYNTH_TIMEOUT_MS};
+var E=Object.defineProperty;var f=(m,s)=>E(m,"name",{value:s,configurable:!0});import{tmpdir as O}from"os";import{resolve as g}from"path";import{logger as h}from"@fjall/util/logger";import{maskSensitiveOutput as A}from"@fjall/util";import{success as d,failure as n}from"@fjall/generator";import{CdkError as l}from"../../types/errors/CdkError.js";import{DEFAULT_REGION as P}from"../../aws/utils/regions.js";import{CdkArgumentBuilder as _}from"./CdkArgumentBuilder.js";import{isCdkError as L,formatInfrastructureError as c}from"./CdkErrorFormatter.js";import{hasCdkDifferences as R,parseDiffOutput as y}from"./CdkOutputParser.js";import{DEFAULT_DEPLOY_TIMEOUT_MS as C}from"./CdkEventMonitoring.js";import{analyseBootstrapError as k}from"./CdkOutputAnalyser.js";import{filterBootstrapTagEntries as S,isBootstrapLostRaceError as D}from"./bootstrapConvergence.js";const b=3e5,M=18e4,T=12e5,v="cdk.out",u=Object.freeze({APP:"--app",CI:"--ci",REQUIRE_APPROVAL:"--require-approval",APPROVAL_NEVER:"never",VERBOSE:"--verbose",NO_LOOKUPS:"--no-lookups",ALL:"--all",EXCLUSIVELY:"--exclusively"});class G{static{f(this,"CdkCommandRunner")}processManager;argumentBuilder=new _;constructor(s){this.processManager=s}dispose(){this.processManager.dispose()}async checkDifferences(s,t,r){const e=["diff"];t?e.push(t):e.push(u.ALL),e.push("--no-color"),r?.noLookups&&e.push(u.NO_LOOKUPS);const o=await this.processManager.runCdkCommand(s,e,{...r,ignoreExitCode:!0,combineOutput:!0});if(!o.success)return n(new l(c(o.error,s),"diff_failed",void 0,void 0,o.error,void 0,!1));const a=o.data.output||"";if(L(a))return n(new l(c(a,s),"diff_failed",void 0,void 0,a,void 0,!1));const i=R(a),p=y(a);return d({hasDifferences:i,output:a,details:p})}async deploy(s,t,r){const e=["deploy"];r?.appDir?e.push(u.APP,r.appDir):r?.useCdkOut&&e.push(u.APP,"cdk.out"),t?(e.push(t),r?.exclusively&&e.push(u.EXCLUSIVELY)):e.push(u.ALL),e.push(u.REQUIRE_APPROVAL,u.APPROVAL_NEVER),e.push(u.CI),e.push("--no-version-reporting"),e.push("--no-path-metadata"),e.push("--no-asset-metadata"),r?.verbose?e.push(u.VERBOSE):e.push("--progress","events"),e.push(...this.argumentBuilder.buildParameterArgs(r?.parameters,t));const o={...r,timeout:r?.timeout||C};return r?.passThroughCDK?this.processManager.runCdkCommandPassthrough(s,e,o):this.processManager.runCdkCommand(s,e,o)}async destroy(s,t,r){const e=["destroy"];r?.appDir?e.push(u.APP,r.appDir):r?.useCdkOut&&e.push(u.APP,"cdk.out"),t?e.push(t):e.push(u.ALL),e.push("--force"),r?.verbose&&e.push(u.VERBOSE);const o={...r,timeout:r?.timeout||C};return this.processManager.runCdkCommand(s,e,o)}async runImport(s,t,r){const e=["import"];r?.stacks&&r.stacks.length>0&&e.push(...r.stacks),t&&e.push("--resource-mapping",t),e.push(u.REQUIRE_APPROVAL,u.APPROVAL_NEVER),e.push(u.CI),r?.noLookups&&e.push(u.NO_LOOKUPS),r?.verbose&&(e.push(u.VERBOSE),e.push("--trace"),e.push("--debug"));const o={...r,timeout:r?.timeout||T};return r?.passThroughCDK?this.processManager.runCdkCommandPassthrough(s,e,o):this.processManager.runCdkCommand(s,e,o)}async synth(s,t){t?.outputCallback?.(`Synthesising CloudFormation template...
+`);const r=t?.noLookups?[u.NO_LOOKUPS]:[],o=["--output",g(s,t?.outputDir??v)],a=t?.context?.region||P,i=await this.processManager.runCdkCommand(s,["synth",...r,...o,u.CI,"--quiet"],{...t,context:{...t?.context,region:a},timeout:t?.timeout||b});if(!i.success){const p=i.error?c(i.error,s):"Failed to synthesise CloudFormation template";return n(p)}return i}async bootstrap(s,t,r){const e=O();h.debug("CdkService","Starting CDK bootstrap",{accountId:s,region:t,bootstrapPath:e,target:`aws://${s}/${t}`});const o=await this.processManager.runCdkCommand(e,["bootstrap",`aws://${s}/${t}`,"--cloudformation-execution-policies","arn:aws:iam::aws:policy/AdministratorAccess",...r?.permissionsBoundary!==void 0&&r.permissionsBoundary!==""?["--custom-permissions-boundary",r.permissionsBoundary]:[],...Object.entries(S(r?.bootstrapTags)).flatMap(([a,i])=>["--tags",`${a}=${i}`]),"-c",`accountId=${s}`,u.REQUIRE_APPROVAL,u.APPROVAL_NEVER,u.CI,"--quiet",...r?.bootstrapForce!==!1?["--force"]:[]],{...r,timeout:r?.timeout||M,context:{region:t,accountId:s},credentials:r?.credentials,skipProjectCheck:!0,extraEnv:{TERM:"dumb",CDK_DISABLE_NOTICES:"true",CDK_DISABLE_PROGRESS_BAR:"true"}});return h.debug("CdkService",o.success?"Bootstrap completed successfully":"Bootstrap exited with non-zero code",{accountId:s,region:t,exitCode:o.success?o.data.exitCode:void 0,output:o.success&&o.data.output?.trim()||"(empty)",error:o.success?"(empty)":A(o.error.trim())||"(empty)"}),o.success?d({output:"AWS environment bootstrapped",exitCode:0}):o.error.includes("already bootstrapped")?d({output:"Environment is already bootstrapped",exitCode:0}):D(o.error)?n({kind:"lost-race",message:`Another process is bootstrapping aws://${s}/${t} at the same time. Wait for it to finish, then retry.`}):n({kind:"other",message:k(o.error)})}}export{M as BOOTSTRAP_TIMEOUT_MS,G as CdkCommandRunner,T as IMPORT_TIMEOUT_MS,b as SYNTH_TIMEOUT_MS};

package/dist/src/services/infrastructure/CdkService.d.ts

@@ -4,6 +4,7 @@ import type { AwsProvider } from "../../aws/AwsProvider.js";
 import type { Result } from "@fjall/generator";
 import type { CdkError } from "../../types/errors/CdkError.js";
 import { type CheckDifferencesResult } from "./CdkCommandRunner.js";
+import { type BootstrapRunFailure } from "./bootstrapConvergence.js";
 import type { CdkOptions, CdkOutput, CdkServiceOptions } from "./CdkServiceTypes.js";
 export type { CdkContext, CdkOptions, CdkOutput, CdkServiceOptions } from "./CdkServiceTypes.js";
 export { type CheckDifferencesResult } from "./CdkCommandRunner.js";
@@ -18,8 +19,17 @@ export declare class CdkService {
     destroy(path: string, stackName?: string, options?: CdkOptions): Promise<Result<CdkOutput, string>>;
     runImport(path: string, resourceMappingFile?: string, options?: CdkOptions): Promise<Result<CdkOutput, string>>;
     synth(path: string, options?: CdkOptions): Promise<Result<CdkOutput, string>>;
-    bootstrap(accountId: string, region: string, options?: CdkOptions): Promise<Result<CdkOutput, string>>;
+    bootstrap(accountId: string, region: string, options?: CdkOptions): Promise<Result<CdkOutput, BootstrapRunFailure>>;
     runCdkSynth(context: DeploymentContext, onOutput?: (chunk: string) => void, credentials?: CdkOptions["credentials"]): Promise<Result<StepOutput, string>>;
+    /**
+     * Convergence-first bootstrap protocol: probe the CDKToolkit stack, wait
+     * out any in-flight bootstrap instead of racing its fixed-name changeset,
+     * force only when the desired tag set cannot be confirmed live, and retry
+     * a bounded number of lost races after the winner settles. Retry rather
+     * than declare success on a lost race — the winner may have run a
+     * different CDK version or stamped a different tag set; a no-force retry
+     * short-circuits in seconds when the toolkit already converged.
+     */
     runCdkBootstrap(context: DeploymentContext, onOutput?: (chunk: string) => void, credentials?: CdkOptions["credentials"], permissionsBoundary?: string, bootstrapTags?: CdkOptions["bootstrapTags"]): Promise<Result<StepOutput, string>>;
     runCdkDiff(context: DeploymentContext, onOutput?: (chunk: string) => void): Promise<Result<StepOutput, string>>;
     runCdkDeploy(context: DeploymentContext, stackPattern?: string, onOutput?: (chunk: string) => void, onResourceProgress?: (event: ResourceEvent) => void, aws?: AwsProvider, credentials?: CdkOptions["credentials"], parameters?: Record<string, string>, exclusively?: boolean): Promise<Result<StepOutput, string>>;

package/dist/src/services/infrastructure/CdkService.js

@@ -1,13 +1,15 @@
-var q=Object.defineProperty;var M=(P,t)=>q(P,"name",{value:t,configurable:!0});import{existsSync as H}from"fs";import{join as K}from"path";import{logger as T}from"@fjall/util/logger";import{isSuccessState as L,isTerminalState as W}from"../../aws/utils/cloudformationEventHelpers.js";import{success as y,failure as s}from"@fjall/generator";import{DEFAULT_REGION as k}from"../../aws/utils/regions.js";import{getErrorMessage as b,maskSensitiveOutput as p}from"@fjall/util";import{CdkEventMonitor as X,DEFAULT_DEPLOY_TIMEOUT_MS as z,settleMonitoringAnalysis as j,startStackMonitoring as J}from"./CdkEventMonitoring.js";import{analyseDeployOutput as Q,analyseDestroyResult as V,createEnhancedOutputCallback as Z,formatAnalysedDeployFailure as $}from"./CdkOutputAnalyser.js";import{recordDriftSuspects as x}from"../../orchestration/drift/driftSuspectJournal.js";import{CdkCommandRunner as tt}from"./CdkCommandRunner.js";import{CdkArgumentBuilder as et}from"./CdkArgumentBuilder.js";import{CdkProcessManager as rt}from"./CdkProcessManager.js";import{cancelInFlightStack as U}from"./cancelInFlightStack.js";import{isAborted as A}from"../../aws/organisations/types.js";import{wrapWithConstructMapEnrichment as nt}from"./constructMapEnrichment.js";import{STACK_DETECTION_FALLBACK_MS as at,resolveStackName as G,getFallbackStackName as ot,buildDeploymentCdkContext as N}from"./cdkServiceHelpers.js";import{ensureDependencyIntegrity as it}from"./dependencyIntegrityGate.js";import{runInfraTypecheckPreflight as st}from"./infraTypecheckPreflight.js";import{isTransientNetworkFailure as ct,isReattachableInProgressStatus as ut,MAX_TRANSIENT_NETWORK_RETRIES as E,TRANSIENT_RETRY_BACKOFF_MS as lt}from"./transientNetworkRecovery.js";import{sleepAbortable as dt}from"../../util/sleepAbortable.js";class Pt{static{M(this,"CdkService")}commandRunner;eventMonitor;abortSignal;constructor(t){const e=t?.processManager??new rt(new et,t?.abortSignal);this.commandRunner=new tt(e),this.eventMonitor=new X({eventLogWriterFactory:t?.eventLogWriterFactory,...t?.onFailureAnalysis!==void 0?{onFailureAnalysis:t.onFailureAnalysis}:{}}),this.abortSignal=t?.abortSignal}dispose(){this.commandRunner.dispose()}async checkDifferences(t,e,r){return this.commandRunner.checkDifferences(t,e,r)}async deploy(t,e,r){return this.commandRunner.deploy(t,e,r)}async destroy(t,e,r){return this.commandRunner.destroy(t,e,r)}async runImport(t,e,r){return this.commandRunner.runImport(t,e,r)}async synth(t,e){return this.commandRunner.synth(t,e)}async bootstrap(t,e,r){return this.commandRunner.bootstrap(t,e,r)}async runCdkSynth(t,e,r){const a=t.callerIdentity?.Account;try{const n=await it(t.path,{...e!==void 0?{onOutput:e}:{},...this.abortSignal!==void 0?{abortSignal:this.abortSignal}:{}});if(!n.success)return s(n.error);const o=await st(t.path,{...this.abortSignal!==void 0?{abortSignal:this.abortSignal}:{}});o.status==="failed"&&(e?.(`WARNING: TypeScript errors in ${t.path} \u2014 the synthesised template may be wrong. This check will block deploys in a future release.
+var H=Object.defineProperty;var M=(_,t)=>H(_,"name",{value:t,configurable:!0});import{existsSync as z}from"fs";import{join as K}from"path";import{logger as I}from"@fjall/util/logger";import{isSuccessState as L,isTerminalState as W}from"../../aws/utils/cloudformationEventHelpers.js";import{success as b,failure as a}from"@fjall/generator";import{DEFAULT_REGION as C}from"../../aws/utils/regions.js";import{getErrorMessage as D,maskSensitiveOutput as S}from"@fjall/util";import{CdkEventMonitor as J,DEFAULT_DEPLOY_TIMEOUT_MS as Q,settleMonitoringAnalysis as B,startStackMonitoring as V}from"./CdkEventMonitoring.js";import{analyseDeployOutput as Z,analyseDestroyResult as x,createEnhancedOutputCallback as tt,formatAnalysedDeployFailure as N}from"./CdkOutputAnalyser.js";import{recordDriftSuspects as et}from"../../orchestration/drift/driftSuspectJournal.js";import{CdkCommandRunner as rt}from"./CdkCommandRunner.js";import{CdkArgumentBuilder as nt}from"./CdkArgumentBuilder.js";import{CdkProcessManager as ot}from"./CdkProcessManager.js";import{cancelInFlightStack as j}from"./cancelInFlightStack.js";import{awaitToolkitSettled as U,filterBootstrapTagEntries as at,probeToolkitStack as it,resolveBootstrapForce as st,MAX_BOOTSTRAP_LOST_RACE_RETRIES as G,TOOLKIT_SETTLE_BUDGET_MS as ct}from"./bootstrapConvergence.js";import{isAborted as k}from"../../aws/organisations/types.js";import{wrapWithConstructMapEnrichment as lt}from"./constructMapEnrichment.js";import{STACK_DETECTION_FALLBACK_MS as ut,resolveStackName as X,getFallbackStackName as dt,buildDeploymentCdkContext as $}from"./cdkServiceHelpers.js";import{ensureDependencyIntegrity as ft}from"./dependencyIntegrityGate.js";import{runInfraTypecheckPreflight as mt}from"./infraTypecheckPreflight.js";import{isTransientNetworkFailure as pt,isReattachableInProgressStatus as gt,MAX_TRANSIENT_NETWORK_RETRIES as E,TRANSIENT_RETRY_BACKOFF_MS as ht}from"./transientNetworkRecovery.js";import{sleepAbortable as yt}from"../../util/sleepAbortable.js";class jt{static{M(this,"CdkService")}commandRunner;eventMonitor;abortSignal;constructor(t){const e=t?.processManager??new ot(new nt,t?.abortSignal);this.commandRunner=new rt(e),this.eventMonitor=new J({eventLogWriterFactory:t?.eventLogWriterFactory,...t?.onFailureAnalysis!==void 0?{onFailureAnalysis:t.onFailureAnalysis}:{}}),this.abortSignal=t?.abortSignal}dispose(){this.commandRunner.dispose()}async checkDifferences(t,e,r){return this.commandRunner.checkDifferences(t,e,r)}async deploy(t,e,r){return this.commandRunner.deploy(t,e,r)}async destroy(t,e,r){return this.commandRunner.destroy(t,e,r)}async runImport(t,e,r){return this.commandRunner.runImport(t,e,r)}async synth(t,e){return this.commandRunner.synth(t,e)}async bootstrap(t,e,r){return this.commandRunner.bootstrap(t,e,r)}async runCdkSynth(t,e,r){const i=t.callerIdentity?.Account;try{const s=await ft(t.path,{...e!==void 0?{onOutput:e}:{},...this.abortSignal!==void 0?{abortSignal:this.abortSignal}:{}});if(!s.success)return a(s.error);const o=await mt(t.path,{...this.abortSignal!==void 0?{abortSignal:this.abortSignal}:{}});o.status==="failed"&&(e?.(`WARNING: TypeScript errors in ${t.path} \u2014 the synthesised template may be wrong. This check will block deploys in a future release.
 ${o.details}
-`),T.warn("CdkService","Infrastructure typecheck failed",{path:t.path}));const i=await this.synth(t.path,{outputCallback:e,context:N(t,a,t.region||k),...t.assemblyDir!==void 0?{outputDir:t.assemblyDir}:{},...r!==void 0?{credentials:r}:{}});return i.success?y({message:"CloudFormation template synthesised",details:i.data.output?{synthesisTime:i.data.output}:void 0}):s(i.error||"Failed to synthesise CloudFormation template")}catch(n){return s(`CDK synth failed: ${p(b(n))}`)}}async runCdkBootstrap(t,e,r,a,n){const o=t.callerIdentity?.Account,i=t.region||k;try{if(!o)return s("No AWS account ID available");const l=K(t.path,"node_modules");if(!H(l))return s(`Dependencies not installed. Please run 'npm install' in ${t.path} before deploying.`);const d=await this.bootstrap(o,i,{outputCallback:e,credentials:r,...a!==void 0&&a!==""?{permissionsBoundary:a}:{},...n!==void 0&&Object.keys(n).length>0?{bootstrapTags:n}:{}});return d.success?y({message:"AWS environment bootstrapped"}):s(d.error||"Failed to bootstrap AWS environment")}catch(l){return s(`CDK bootstrap failed: ${p(b(l))}`)}}async runCdkDiff(t,e){const r=t.callerIdentity?.Account;try{const a=await this.checkDifferences(t.path,void 0,{verbose:t.options?.verbose,outputCallback:e,context:N(t,r,t.region||k)});return a.success?y({message:"Diff check complete",details:{hasDifferences:a.data.hasDifferences,details:a.data.details}}):s(`CDK diff failed: ${a.error.message}`)}catch(a){return s(`CDK diff failed: ${p(b(a))}`)}}async runCdkDeploy(t,e,r,a,n,o,i,l){const d=t.callerIdentity?.Account,u=t.region||k;if(!d)return s("AWS account ID not available. Please ensure AWS credentials are properly configured.");if(!n)return s("AwsProvider is required for deployment monitoring.");const g=t.assemblyDir??K(t.path,"cdk.out"),S=nt(g,a);let h=null,D;try{const m=G(e,t)??ot(t),f=await this.eventMonitor.createEventMonitor("deploy",m,u,t,n);h=f,r&&(r(p(`Starting CloudFormation deployment of ${m}...
+`),I.warn("CdkService","Infrastructure typecheck failed",{path:t.path}));const n=await this.synth(t.path,{outputCallback:e,context:$(t,i,t.region||C),...t.assemblyDir!==void 0?{outputDir:t.assemblyDir}:{},...r!==void 0?{credentials:r}:{}});return n.success?b({message:"CloudFormation template synthesised",details:n.data.output?{synthesisTime:n.data.output}:void 0}):a(n.error||"Failed to synthesise CloudFormation template")}catch(s){return a(`CDK synth failed: ${S(D(s))}`)}}async runCdkBootstrap(t,e,r,i,s){const o=t.callerIdentity?.Account,n=t.region||C;try{if(!o)return a("No AWS account ID available");const u=K(t.path,"node_modules");if(!z(u))return a(`Dependencies not installed. Please run 'npm install' in ${t.path} before deploying.`);const d=at(s),c=Object.keys(d).length>0,m={region:n,...r!==void 0?{credentials:r}:{},...this.abortSignal!==void 0?{abortSignal:this.abortSignal}:{}};for(let p=0;p<=G;p++){if(k(this.abortSignal))return a("Bootstrap cancelled before completion");let f=await it(m);if(f.kind==="in-progress"&&(e?.(`Another deployment is updating the CDK toolkit in ${o}/${n} \u2014 waiting for it to finish...
+`),f=await U(m)),k(this.abortSignal))return a("Bootstrap cancelled before completion");if(f.kind==="in-progress")return a(`The CDKToolkit stack in ${o}/${n} has been ${f.status} for over ${Math.round(ct/6e4)} minutes. Another deployment may be stuck bootstrapping this environment \u2014 wait for it to finish (or cancel it in the CloudFormation console), then retry.`);const y=await this.bootstrap(o,n,{outputCallback:e,credentials:r,bootstrapForce:st(f,c?d:void 0),...i!==void 0&&i!==""?{permissionsBoundary:i}:{},...c?{bootstrapTags:d}:{}});if(y.success)return b({message:"AWS environment bootstrapped"});if(k(this.abortSignal))return a("Bootstrap cancelled before completion");if(y.error.kind==="lost-race"&&p<G){I.warn("CdkService","Concurrent bootstrap detected \u2014 waiting for it to settle before retrying",{accountId:o,region:n,attempt:p+1}),e?.(`Another deployment is bootstrapping ${o}/${n} \u2014 waiting for it to finish before retrying...
+`),await U(m);continue}return a(y.error.message||"Failed to bootstrap AWS environment")}return a("Failed to bootstrap AWS environment")}catch(u){return a(`CDK bootstrap failed: ${S(D(u))}`)}}async runCdkDiff(t,e){const r=t.callerIdentity?.Account;try{const i=await this.checkDifferences(t.path,void 0,{verbose:t.options?.verbose,outputCallback:e,context:$(t,r,t.region||C)});return i.success?b({message:"Diff check complete",details:{hasDifferences:i.data.hasDifferences,details:i.data.details}}):a(`CDK diff failed: ${i.error.message}`)}catch(i){return a(`CDK diff failed: ${S(D(i))}`)}}async runCdkDeploy(t,e,r,i,s,o,n,u){const d=t.callerIdentity?.Account,c=t.region||C;if(!d)return a("AWS account ID not available. Please ensure AWS credentials are properly configured.");if(!s)return a("AwsProvider is required for deployment monitoring.");const m=t.assemblyDir??K(t.path,"cdk.out"),p=lt(m,i);let f=null,y;try{const h=X(e,t)??dt(t),g=await this.eventMonitor.createEventMonitor("deploy",h,c,t,s);f=g,r&&(r(S(`Starting CloudFormation deployment of ${h}...
 `)),r(`Monitoring CloudFormation events (CDK process running in background)...
-`));const c={cdkOutput:"",actualStackName:m,stackDetected:!1,monitoringPromise:null},B=Z(c,r,h,S);D=setTimeout(()=>{!c.stackDetected&&!c.monitoringPromise&&(T.debug("CdkService","Fallback monitoring STARTING",{targetStackName:m,stackDetected:c.stackDetected,hasOnResourceProgress:!!a}),c.monitoringPromise=J(f,m,S))},at);for(let C=0;;C++){const R=await this.deploy(t.path,m,{verbose:t.options?.verbose,outputCallback:B,...t.assemblyDir!==void 0?{appDir:t.assemblyDir}:{useCdkOut:!0},cdkOutputLogger:f.getEventLogger()??void 0,context:N(t,d,u),credentials:o,...i!==void 0&&Object.keys(i).length>0&&{parameters:i},...l===!0&&{exclusively:!0}});if(A(this.abortSignal))return await U(m,u,o,r),s("Deployment cancelled");const w=Q(c.cdkOutput,R,c.actualStackName);if(w.success)return await this.reconcileDeploySuccessAgainstStack({successOutput:w.data,stackName:c.actualStackName,monitor:f,monitoringPromise:c.monitoringPromise,accountId:d,region:u,onOutput:r});const Y=[c.cdkOutput,R.success?R.data.output??"":R.error,w.error].join(`
-`);if(ct(Y)){r?.(`Transient network failure while running CDK for ${c.actualStackName} \u2014 probing CloudFormation for an in-flight operation...
-`);const I=await f.getStackStatus(c.actualStackName,this.abortSignal);if(I!==null&&ut(I.status))return clearTimeout(D),await this.reattachToInFlightOperation({stackName:c.actualStackName,currentStatus:I.status,region:u,accountId:d,monitor:f,state:c,credentials:o,onOutput:r,onResourceProgress:S});const v=I?.status,O=v!==void 0&&W(v)&&!L(v);if(!O&&C<E){const _=lt[C]??15e3;if(r?.(`No CloudFormation operation in progress \u2014 nothing was mutated. Retrying the CDK deploy in ${_/1e3}s (retry ${C+1} of ${E})...
-`),await dt(_,this.abortSignal),A(this.abortSignal))return s("Deployment cancelled");c.cdkOutput="";continue}r?.(O?`CloudFormation settled at ${v} for ${c.actualStackName} \u2014 the stack was rolled back, not cleanly interrupted. Not retrying.
+`));const l={cdkOutput:"",actualStackName:h,stackDetected:!1,monitoringPromise:null},Y=tt(l,r,f,p);y=setTimeout(()=>{!l.stackDetected&&!l.monitoringPromise&&(I.debug("CdkService","Fallback monitoring STARTING",{targetStackName:h,stackDetected:l.stackDetected,hasOnResourceProgress:!!i}),l.monitoringPromise=V(g,h,p))},ut);for(let w=0;;w++){const T=await this.deploy(t.path,h,{verbose:t.options?.verbose,outputCallback:Y,...t.assemblyDir!==void 0?{appDir:t.assemblyDir}:{useCdkOut:!0},cdkOutputLogger:g.getEventLogger()??void 0,context:$(t,d,c),credentials:o,...n!==void 0&&Object.keys(n).length>0&&{parameters:n},...u===!0&&{exclusively:!0}});if(k(this.abortSignal))return await j(h,c,o,r),a("Deployment cancelled");const R=Z(l.cdkOutput,T,l.actualStackName);if(R.success)return await this.reconcileDeploySuccessAgainstStack({successOutput:R.data,stackName:l.actualStackName,monitor:g,monitoringPromise:l.monitoringPromise,accountId:d,region:c,onOutput:r});const q=[l.cdkOutput,T.success?T.data.output??"":T.error,R.error].join(`
+`);if(pt(q)){r?.(`Transient network failure while running CDK for ${l.actualStackName} \u2014 probing CloudFormation for an in-flight operation...
+`);const A=await g.getStackStatus(l.actualStackName,this.abortSignal);if(A!==null&&gt(A.status))return clearTimeout(y),await this.reattachToInFlightOperation({stackName:l.actualStackName,currentStatus:A.status,region:c,accountId:d,monitor:g,state:l,credentials:o,onOutput:r,onResourceProgress:p});const v=A?.status,P=v!==void 0&&W(v)&&!L(v);if(!P&&w<E){const O=ht[w]??15e3;if(r?.(`No CloudFormation operation in progress \u2014 nothing was mutated. Retrying the CDK deploy in ${O/1e3}s (retry ${w+1} of ${E})...
+`),await yt(O,this.abortSignal),k(this.abortSignal))return a("Deployment cancelled");l.cdkOutput="";continue}r?.(P?`CloudFormation settled at ${v} for ${l.actualStackName} \u2014 the stack was rolled back, not cleanly interrupted. Not retrying.
 `:`No CloudFormation operation in progress and the retry budget (${E}) is exhausted \u2014 giving up.
-`)}const F=await j(f,c.monitoringPromise);return F===null?w:(await this.journalDriftSuspects(d,u,c.actualStackName,F),s($(F)))}}catch(m){const f=`CDK deploy failed: ${p(b(m))}`;return T.error("CdkService","CDK deployment exception",{error:f}),s(f)}finally{clearTimeout(D),h&&h.stopMonitoring()}}async reattachToInFlightOperation(t){const{stackName:e,monitor:r,state:a,onOutput:n}=t;n?.(`CloudFormation reports ${t.currentStatus} for ${e} \u2014 the operation survived the network failure. Re-attaching and monitoring it to completion...
-`),r.stopMonitoring(),a.monitoringPromise=null;const o=M(()=>{r.stopMonitoring()},"onAbort");this.abortSignal?.addEventListener("abort",o,{once:!0});const i=await r.waitForStackComplete(e,{timeout:z,...t.onResourceProgress!==void 0?{onResourceUpdate:t.onResourceProgress}:{}}).finally(()=>{this.abortSignal?.removeEventListener("abort",o)});if(A(this.abortSignal))return await U(e,t.region,t.credentials,n),s("Deployment cancelled");if(i.success){const u=i.status??"COMPLETE";return n?.(`${e} reached ${u} after re-attach.
-`),y({message:`Re-attached to the in-flight CloudFormation operation after a transient network failure; ${e} reached ${u}`,details:{reattached:!0,status:u}})}const l=r.getFailureAnalysis();if(l!==null)return await this.journalDriftSuspects(t.accountId,t.region,e,l),s($(l));const d=i.failureReason!==void 0&&i.failureReason!==""?p(i.failureReason):"no failure reason reported";return s(`Re-attached to the in-flight CloudFormation operation after a transient network failure; ${e} reached ${i.status??"UNKNOWN"}: ${d}`)}async reconcileDeploySuccessAgainstStack(t){const{successOutput:e,stackName:r,monitor:a,onOutput:n}=t;if(e.status==="NO_CHANGES"||e.status==="SKIPPED"||e.details?.skipped===!0)return y(e);const o=await a.getStackStatus(r,this.abortSignal);if(o===null||!W(o.status)||L(o.status))return y(e);n?.(`CDK reported success but CloudFormation settled at ${o.status} for ${r} \u2014 the deployment did not converge. Reporting failure.
-`);const i=await j(a,t.monitoringPromise);if(i!==null)return await this.journalDriftSuspects(t.accountId,t.region,r,i),s($(i));const l=o.statusReason!==void 0&&o.statusReason!==""?p(o.statusReason):"no failure reason reported";return s(`Deployment of ${r} reported success but CloudFormation settled at ${o.status}: ${l}`)}async journalDriftSuspects(t,e,r,a){a.driftSuspects===void 0||a.driftSuspects.length===0||await x({accountId:t,region:e,stackName:r,recordedAt:new Date().toISOString(),suspects:a.driftSuspects.map(n=>({stackName:r,logicalId:n.logicalId,resourceType:n.resourceType,...n.physicalId!==void 0?{physicalId:n.physicalId}:{},failedStatus:n.failedStatus,statusReason:n.statusReason}))})}async runCdkDestroy(t,e,r,a,n,o,i){const l=t.callerIdentity?.Account,d=t.region||k;let u=null;try{const g=G(e,t);l&&g&&n&&(u=await this.eventMonitor.createEventMonitor("destroy",g,d,t,n),u.startMonitoring(g,h=>{a?.(h)},(h,D)=>{}));const S=await this.destroy(t.path,e,{verbose:t.options?.verbose,outputCallback:r,useCdkOut:o,cdkOutputLogger:u?.getEventLogger()??void 0,context:N(t,l,d),credentials:i});return A(this.abortSignal)?s("Destroy cancelled"):V(S)}catch(g){return s(`CDK destroy failed: ${p(b(g))}`)}finally{u&&u.stopMonitoring()}}}export{Pt as CdkService};
+`)}const F=await B(g,l.monitoringPromise);return F===null?R:(await this.journalDriftSuspects(d,c,l.actualStackName,F),a(N(F)))}}catch(h){const g=`CDK deploy failed: ${S(D(h))}`;return I.error("CdkService","CDK deployment exception",{error:g}),a(g)}finally{clearTimeout(y),f&&f.stopMonitoring()}}async reattachToInFlightOperation(t){const{stackName:e,monitor:r,state:i,onOutput:s}=t;s?.(`CloudFormation reports ${t.currentStatus} for ${e} \u2014 the operation survived the network failure. Re-attaching and monitoring it to completion...
+`),r.stopMonitoring(),i.monitoringPromise=null;const o=M(()=>{r.stopMonitoring()},"onAbort");this.abortSignal?.addEventListener("abort",o,{once:!0});const n=await r.waitForStackComplete(e,{timeout:Q,...t.onResourceProgress!==void 0?{onResourceUpdate:t.onResourceProgress}:{}}).finally(()=>{this.abortSignal?.removeEventListener("abort",o)});if(k(this.abortSignal))return await j(e,t.region,t.credentials,s),a("Deployment cancelled");if(n.success){const c=n.status??"COMPLETE";return s?.(`${e} reached ${c} after re-attach.
+`),b({message:`Re-attached to the in-flight CloudFormation operation after a transient network failure; ${e} reached ${c}`,details:{reattached:!0,status:c}})}const u=r.getFailureAnalysis();if(u!==null)return await this.journalDriftSuspects(t.accountId,t.region,e,u),a(N(u));const d=n.failureReason!==void 0&&n.failureReason!==""?S(n.failureReason):"no failure reason reported";return a(`Re-attached to the in-flight CloudFormation operation after a transient network failure; ${e} reached ${n.status??"UNKNOWN"}: ${d}`)}async reconcileDeploySuccessAgainstStack(t){const{successOutput:e,stackName:r,monitor:i,onOutput:s}=t;if(e.status==="NO_CHANGES"||e.status==="SKIPPED"||e.details?.skipped===!0)return b(e);const o=await i.getStackStatus(r,this.abortSignal);if(o===null||!W(o.status)||L(o.status))return b(e);s?.(`CDK reported success but CloudFormation settled at ${o.status} for ${r} \u2014 the deployment did not converge. Reporting failure.
+`);const n=await B(i,t.monitoringPromise);if(n!==null)return await this.journalDriftSuspects(t.accountId,t.region,r,n),a(N(n));const u=o.statusReason!==void 0&&o.statusReason!==""?S(o.statusReason):"no failure reason reported";return a(`Deployment of ${r} reported success but CloudFormation settled at ${o.status}: ${u}`)}async journalDriftSuspects(t,e,r,i){i.driftSuspects===void 0||i.driftSuspects.length===0||await et({accountId:t,region:e,stackName:r,recordedAt:new Date().toISOString(),suspects:i.driftSuspects.map(s=>({stackName:r,logicalId:s.logicalId,resourceType:s.resourceType,...s.physicalId!==void 0?{physicalId:s.physicalId}:{},failedStatus:s.failedStatus,statusReason:s.statusReason}))})}async runCdkDestroy(t,e,r,i,s,o,n){const u=t.callerIdentity?.Account,d=t.region||C;let c=null;try{const m=X(e,t);u&&m&&s&&(c=await this.eventMonitor.createEventMonitor("destroy",m,d,t,s),c.startMonitoring(m,f=>{i?.(f)},(f,y)=>{}));const p=await this.destroy(t.path,e,{verbose:t.options?.verbose,outputCallback:r,useCdkOut:o,cdkOutputLogger:c?.getEventLogger()??void 0,context:$(t,u,d),credentials:n});return k(this.abortSignal)?a("Destroy cancelled"):x(p)}catch(m){return a(`CDK destroy failed: ${S(D(m))}`)}finally{c&&c.stopMonitoring()}}}export{jt as CdkService};

package/dist/src/services/infrastructure/CdkServiceTypes.d.ts

@@ -108,6 +108,15 @@ export interface CdkOptions {
      * `--tags` args (today's behaviour).
      */
     bootstrapTags?: Record<string, string>;
+    /**
+     * Force decision for `cdk bootstrap`. `--force` defeats CDK's own
+     * "toolkit already at version N" short-circuit and exists ONLY to serve
+     * the bootstrapTags REPLACE contract, so the convergence protocol
+     * (`resolveBootstrapForce`) emits it iff the desired tag set cannot be
+     * confirmed present on the live CDKToolkit stack. `undefined` preserves
+     * the historical always-force behaviour for direct callers.
+     */
+    bootstrapForce?: boolean;
     /**
      * Pass `--exclusively` to `cdk deploy <stack>`: deploy only the named
      * stack, never the dependency stacks cdk would otherwise pull in. Set by

package/dist/src/services/infrastructure/bootstrapConvergence.d.ts

@@ -0,0 +1,95 @@
+import type { CdkOptions } from "./CdkServiceTypes.js";
+/** CDK's fixed toolkit stack name for the default qualifier. */
+export declare const TOOLKIT_STACK_NAME = "CDKToolkit";
+/** Poll cadence while waiting for a concurrent bootstrap to settle. */
+export declare const TOOLKIT_SETTLE_POLL_INTERVAL_MS = 5000;
+/**
+ * Overall budget for waiting on a concurrent bootstrap. The toolkit stack is
+ * a handful of resources — a healthy bootstrap settles well inside this.
+ */
+export declare const TOOLKIT_SETTLE_BUDGET_MS = 240000;
+/**
+ * Lost-race retries after the initial attempt. A no-force retry
+ * short-circuits in seconds when the winner already converged the toolkit,
+ * and a forced retry covers the winner having stamped a different tag set.
+ */
+export declare const MAX_BOOTSTRAP_LOST_RACE_RETRIES = 2;
+export type ToolkitStackState = {
+    kind: "absent";
+} | {
+    kind: "in-progress";
+    status: string;
+} | {
+    kind: "healthy";
+    status: string;
+    tags: Record<string, string>;
+} | {
+    kind: "unhealthy";
+    status: string;
+} | {
+    kind: "unknown";
+};
+export interface ToolkitProbeParams {
+    region: string;
+    credentials?: CdkOptions["credentials"];
+    abortSignal?: AbortSignal;
+}
+/**
+ * Describe the CDKToolkit stack and classify its state. Never throws — a
+ * probe failure (network, permissions) classifies as `unknown`, which the
+ * force decision treats conservatively.
+ */
+export declare function probeToolkitStack(params: ToolkitProbeParams): Promise<ToolkitStackState>;
+export interface ToolkitSettleOptions {
+    pollIntervalMs?: number;
+    budgetMs?: number;
+    /** Injectable clock for budget tests. */
+    now?: () => number;
+}
+/**
+ * Poll the toolkit stack until it reaches a definitively settled state
+ * (absent, healthy, unhealthy), the budget expires, or the abort signal
+ * fires. An `unknown` probe does NOT exit the wait — DescribeStacks
+ * throttling is likeliest under exactly the concurrent load this protocol
+ * targets, and a single throttled poll must not vacate the settle gate.
+ * Returns the final observed state — still `in-progress` (or `unknown`) on
+ * budget exhaustion, so callers decide how to surface that.
+ */
+export declare function awaitToolkitSettled(params: ToolkitProbeParams, options?: ToolkitSettleOptions): Promise<ToolkitStackState>;
+/**
+ * Drop empty-key/empty-value tag entries. The CDK CLI parses degenerate
+ * `--tags =v` / `k=` args fine — it is CloudFormation that rejects them.
+ * Shared by the runner's argv emission AND the service's force decision so
+ * both sites compare the same emitted set (coupled at 2 occurrences).
+ */
+export declare function filterBootstrapTagEntries(tags: Record<string, string> | undefined): Record<string, string>;
+/**
+ * The force decision: `--force` is emitted iff there are tags to stamp AND
+ * the live stack cannot be confirmed to already carry exactly that set.
+ * Parity is exact record equality — an extra live tag forces a restamp,
+ * preserving the REPLACE contract's "complete set or nothing" semantics.
+ *
+ * Without desired tags there is nothing `--force` buys: creation ignores it,
+ * and CDK upgrades an outdated toolkit without it.
+ */
+export declare function resolveBootstrapForce(state: ToolkitStackState, desiredTags: Record<string, string> | undefined): boolean;
+/**
+ * Discriminated failure for CdkCommandRunner.bootstrap: `lost-race` means a
+ * concurrent bootstrap won the fixed-name changeset and the protocol should
+ * wait for it to settle and retry; `other` carries the analysed error.
+ * Messages are pre-masked at construction: the lost-race arm interpolates
+ * identifiers only, and the `other` arm analyses runCdkCommand's failure
+ * string, whose sole stderr-bearing arm masks at source (the close-handler
+ * `maskSensitiveOutput(fullError)` in CdkProcessManager) — every other arm
+ * is identifier-only.
+ */
+export interface BootstrapRunFailure {
+    kind: "lost-race" | "other";
+    message: string;
+}
+/**
+ * Classify RAW bootstrap stderr as a lost concurrent-bootstrap race. Must run
+ * BEFORE analyseBootstrapError, which reformats the output and destroys the
+ * signatures.
+ */
+export declare function isBootstrapLostRaceError(stderr: string): boolean;

package/dist/src/services/infrastructure/bootstrapConvergence.js

@@ -0,0 +1 @@
+var _=Object.defineProperty;var o=(t,e)=>_(t,"name",{value:e,configurable:!0});import{CloudFormationClient as f,DescribeStacksCommand as S}from"@aws-sdk/client-cloudformation";import{NodeHttpHandler as O}from"@smithy/node-http-handler";import{logger as g}from"@fjall/util/logger";import{getErrorMessage as k,maskSensitiveOutput as b}from"@fjall/util";import{composeSdkAbortSignal as p,isAborted as T}from"../../aws/organisations/types.js";import{STACK_NOT_FOUND_PATTERN as L}from"../../types/constants.js";import{sleepAbortable as R}from"../../util/sleepAbortable.js";const A="BootstrapConvergence",C="CDKToolkit",E=15e3,h=5e3,w=24e4,U=2,M=new Set(["CREATE_COMPLETE","UPDATE_COMPLETE","UPDATE_ROLLBACK_COMPLETE","IMPORT_COMPLETE","IMPORT_ROLLBACK_COMPLETE"]);function d(t){return new f({region:t.region,...t.credentials!==void 0?{credentials:t.credentials}:{},requestHandler:new O({requestTimeout:E})})}o(d,"createProbeClient");async function j(t){return l(d(t),t)}o(j,"probeToolkitStack");async function l(t,e){const{region:r,abortSignal:a}=e;try{const c=(await t.send(new S({StackName:C}),{abortSignal:p(a,E)})).Stacks?.[0],n=c?.StackStatus;if(c===void 0||n===void 0)return{kind:"absent"};if(n==="DELETE_COMPLETE")return{kind:"absent"};if(n.endsWith("_IN_PROGRESS")&&n!=="REVIEW_IN_PROGRESS")return{kind:"in-progress",status:n};if(M.has(n)){const s={};for(const u of c.Tags??[])u.Key!==void 0&&u.Value!==void 0&&(s[u.Key]=u.Value);return{kind:"healthy",status:n,tags:s}}return{kind:"unhealthy",status:n}}catch(i){return i instanceof Error&&i.message.includes(L)?{kind:"absent"}:(g.debug(A,"Toolkit probe failed \u2014 treating state as unknown",{region:r,error:b(k(i))}),{kind:"unknown"})}}o(l,"probeWithClient");async function G(t,e){const r=e?.pollIntervalMs??h,a=e?.budgetMs??w,i=e?.now??(()=>Date.now()),c=i(),n=d(t);try{let s=await l(n,t);for(;(s.kind==="in-progress"||s.kind==="unknown")&&!T(t.abortSignal)&&i()-c<a&&(await R(r,t.abortSignal),!T(t.abortSignal));)s=await l(n,t);return s}finally{n.destroy()}}o(G,"awaitToolkitSettled");function H(t){return Object.fromEntries(Object.entries(t??{}).filter(([e,r])=>e!==""&&r!==""))}o(H,"filterBootstrapTagEntries");function P(t,e){const r=Object.keys(t);return r.length===Object.keys(e).length&&r.every(a=>e[a]===t[a])}o(P,"tagRecordsEqual");function F(t,e){if(e===void 0||Object.keys(e).length===0)return!1;switch(t.kind){case"absent":return!1;case"healthy":return!P(t.tags,e);case"in-progress":case"unhealthy":case"unknown":return!0}}o(F,"resolveBootstrapForce");const m=[/ChangeSetNotFoundException/,/mismatch with existing attribute ClientToken/i,/is in [A-Z_]*IN_PROGRESS state and can ?not be updated/i];function V(t){return m.some(e=>e.test(t))}o(V,"isBootstrapLostRaceError");export{U as MAX_BOOTSTRAP_LOST_RACE_RETRIES,w as TOOLKIT_SETTLE_BUDGET_MS,h as TOOLKIT_SETTLE_POLL_INTERVAL_MS,C as TOOLKIT_STACK_NAME,G as awaitToolkitSettled,H as filterBootstrapTagEntries,V as isBootstrapLostRaceError,j as probeToolkitStack,F as resolveBootstrapForce};

package/dist/src/services/infrastructure/index.d.ts

@@ -1,5 +1,6 @@
 export { CdkService } from "./CdkService.js";
 export type { CheckDifferencesResult } from "./CdkCommandRunner.js";
+export { isBootstrapLostRaceError, probeToolkitStack, awaitToolkitSettled, resolveBootstrapForce, TOOLKIT_STACK_NAME, type BootstrapRunFailure, type ToolkitStackState, type ToolkitProbeParams } from "./bootstrapConvergence.js";
 export type { CdkContext, CdkOptions, CdkOutput, CdkServiceOptions } from "./CdkServiceTypes.js";
 export type { ICdkProcessManager } from "./ICdkProcessManager.js";
 export { CdkArgumentBuilder } from "./CdkArgumentBuilder.js";

package/dist/src/services/infrastructure/index.js

@@ -1 +1 @@
-import{CdkService as o}from"./CdkService.js";import{CdkArgumentBuilder as c}from"./CdkArgumentBuilder.js";import{CdkProcessManager as n}from"./CdkProcessManager.js";import{ensureDependencyIntegrity as p,clearDependencyIntegrityCache as E,DEPENDENCY_SYNC_TIMEOUT_MS as m}from"./dependencyIntegrityGate.js";import{CdkEventMonitor as a,startStackMonitoring as x,DEFAULT_DEPLOY_TIMEOUT_MS as C}from"./CdkEventMonitoring.js";import{isCdkError as u,formatInfrastructureError as d,getStructuralHint as g,getSourceContext as D}from"./CdkErrorFormatter.js";import{hasCdkDifferences as I,parseDiffOutput as _}from"./CdkOutputParser.js";import{CloudFormationService as M,CloudFormationError as T}from"./CloudFormationService.js";import{CfnRegistryService as y}from"./CfnRegistryService.js";import{CFN_REGISTRY_SEED as F}from"./cfnRegistrySeed.js";import{EcsService as R,EcsError as Y}from"./EcsService.js";import{EcsServiceResolver as U}from"./EcsServiceResolver.js";import{EcrImageInspectorService as A,stripTagOrDigest as L}from"./EcrImageInspectorService.js";export{F as CFN_REGISTRY_SEED,c as CdkArgumentBuilder,a as CdkEventMonitor,n as CdkProcessManager,o as CdkService,y as CfnRegistryService,T as CloudFormationError,M as CloudFormationService,C as DEFAULT_DEPLOY_TIMEOUT_MS,m as DEPENDENCY_SYNC_TIMEOUT_MS,A as EcrImageInspectorService,Y as EcsError,R as EcsService,U as EcsServiceResolver,E as clearDependencyIntegrityCache,p as ensureDependencyIntegrity,d as formatInfrastructureError,D as getSourceContext,g as getStructuralHint,I as hasCdkDifferences,u as isCdkError,_ as parseDiffOutput,x as startStackMonitoring,L as stripTagOrDigest};
+import{CdkService as o}from"./CdkService.js";import{isBootstrapLostRaceError as i,probeToolkitStack as c,awaitToolkitSettled as p,resolveBootstrapForce as s,TOOLKIT_STACK_NAME as a}from"./bootstrapConvergence.js";import{CdkArgumentBuilder as n}from"./CdkArgumentBuilder.js";import{CdkProcessManager as m}from"./CdkProcessManager.js";import{ensureDependencyIntegrity as x,clearDependencyIntegrityCache as C,DEPENDENCY_SYNC_TIMEOUT_MS as d}from"./dependencyIntegrityGate.js";import{CdkEventMonitor as T,startStackMonitoring as g,DEFAULT_DEPLOY_TIMEOUT_MS as k}from"./CdkEventMonitoring.js";import{isCdkError as D,formatInfrastructureError as _,getStructuralHint as v,getSourceContext as I}from"./CdkErrorFormatter.js";import{hasCdkDifferences as O,parseDiffOutput as y}from"./CdkOutputParser.js";import{CloudFormationService as N,CloudFormationError as R}from"./CloudFormationService.js";import{CfnRegistryService as L}from"./CfnRegistryService.js";import{CFN_REGISTRY_SEED as B}from"./cfnRegistrySeed.js";import{EcsService as U,EcsError as h}from"./EcsService.js";import{EcsServiceResolver as b}from"./EcsServiceResolver.js";import{EcrImageInspectorService as G,stripTagOrDigest as H}from"./EcrImageInspectorService.js";export{B as CFN_REGISTRY_SEED,n as CdkArgumentBuilder,T as CdkEventMonitor,m as CdkProcessManager,o as CdkService,L as CfnRegistryService,R as CloudFormationError,N as CloudFormationService,k as DEFAULT_DEPLOY_TIMEOUT_MS,d as DEPENDENCY_SYNC_TIMEOUT_MS,G as EcrImageInspectorService,h as EcsError,U as EcsService,b as EcsServiceResolver,a as TOOLKIT_STACK_NAME,p as awaitToolkitSettled,C as clearDependencyIntegrityCache,x as ensureDependencyIntegrity,_ as formatInfrastructureError,I as getSourceContext,v as getStructuralHint,O as hasCdkDifferences,i as isBootstrapLostRaceError,D as isCdkError,y as parseDiffOutput,c as probeToolkitStack,s as resolveBootstrapForce,g as startStackMonitoring,H as stripTagOrDigest};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/deploy-core",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -95,8 +95,8 @@
     "@aws-sdk/client-ssm": "^3.1098.0",
     "@aws-sdk/client-sso-admin": "^3.1098.0",
     "@aws-sdk/client-sts": "^3.1098.0",
-    "@fjall/generator": "^7.1.0",
-    "@fjall/util": "^7.1.0",
+    "@fjall/generator": "^7.2.0",
+    "@fjall/util": "^7.2.0",
     "@smithy/node-http-handler": "^4.9.13",
     "aws-cdk": "^2.1134.0",
     "tsx": "^4.23.1",