@fjall/deploy-core 2.12.0 → 2.14.0

package/dist/src/orchestration/organisationDeploy/infraSteps.d.ts

@@ -0,0 +1,40 @@
+import { type Result } from "@fjall/generator";
+import type { DeployCallbacks } from "../../types/callbacks.js";
+import type { DeployServices } from "../serviceFactory.js";
+export declare const INFRA_STEPS: {
+    readonly CONNECT: {
+        readonly id: "connect";
+        readonly name: "Connect securely";
+    };
+    readonly PREPARE: {
+        readonly id: "prepare-environment";
+        readonly name: "Prepare environment";
+    };
+    readonly DEPLOY: {
+        readonly id: "deploy";
+        readonly name: "Deploy infrastructure";
+    };
+    readonly MONITORING: {
+        readonly id: "monitoring";
+        readonly name: "Enable monitoring";
+    };
+    readonly ORG_DEPLOY: {
+        readonly id: "organisation-deploy";
+        readonly name: "Deploying organisation";
+    };
+    readonly CASCADE_PLATFORM: {
+        readonly id: "cascade-platform";
+        readonly name: "Deploying platform";
+    };
+    readonly CASCADE_ACCOUNTS: {
+        readonly id: "cascade-accounts";
+        readonly name: "Deploying accounts";
+    };
+};
+export declare const INFRA_STEP_TOTAL = 4;
+/** Complete the single-component PREPARE step as errored. */
+export declare function failPrepareStep(callbacks: DeployCallbacks): void;
+/** Mask a failure message, surface it via onError, and return the failure. */
+export declare function maskAndFail(callbacks: DeployCallbacks, message: string): Result<never>;
+/** Best-effort stack-output read: log at debug on failure, never fail. */
+export declare function readStackOutputsBestEffort(services: DeployServices, callbacks: DeployCallbacks, stackName: string, failureLogMessage: string): Promise<Record<string, string> | undefined>;

package/dist/src/orchestration/organisationDeploy/infraSteps.js

@@ -0,0 +1 @@
+import{failure as P}from"@fjall/generator";import{collectStackOutputs as R}from"../contextHelpers.js";import{maskSensitiveOutput as S}from"@fjall/util";import{INFRA_STEP_NAME as r,STEP_IDS as t,STEP_NAMES as A}from"../../types/stepDefinitions.js";const n={CONNECT:{id:t.CONNECT,name:r.CONNECT},PREPARE:{id:t.PREPARE_ENVIRONMENT,name:r.PREPARE},DEPLOY:{id:t.DEPLOY,name:r.DEPLOY},MONITORING:{id:t.MONITORING,name:r.MONITORING},ORG_DEPLOY:{id:t.ORG_DEPLOY,name:A.ORG_DEPLOY},CASCADE_PLATFORM:{id:t.CASCADE_PLATFORM,name:A.CASCADE_PLATFORM},CASCADE_ACCOUNTS:{id:t.CASCADE_ACCOUNTS,name:A.CASCADE_ACCOUNTS}},i=4;function u(E){E.onStepComplete?.(n.PREPARE.id,n.PREPARE.name,"error",1,i)}function p(E,o){const e=new Error(S(o));return E.onError?.(e),P(e)}async function c(E,o,e,C){const O=await E.cfnService.getStackOutputs(e);return O.success||o.onLog?.(C,"debug"),R(O)}export{n as INFRA_STEPS,i as INFRA_STEP_TOTAL,u as failPrepareStep,p as maskAndFail,c as readStackOutputsBestEffort};

package/dist/src/orchestration/organisationDeploy/orgCascadeDeploy.d.ts

@@ -0,0 +1,8 @@
+import { type Result } from "@fjall/generator";
+import type { DeployParams, DeployResult } from "../../types/params.js";
+import type { OrganisationOperation } from "../../types/operations.js";
+import type { DeployServices } from "../serviceFactory.js";
+/**
+ * Full organisation deployment with cascade to platform + member accounts.
+ */
+export declare function deployOrgWithCascade(params: DeployParams, services: DeployServices, operation: OrganisationOperation, startTime: number): Promise<Result<DeployResult>>;

package/dist/src/orchestration/organisationDeploy/orgCascadeDeploy.js

@@ -0,0 +1,5 @@
+import{join as W}from"node:path";import{success as _,failure as Y}from"@fjall/generator";import{ORGANISATION_TYPES as B,getOrganisationStackName as K}from"../../types/operations.js";import{synthOrFail as q,bootstrapOrFail as z,forwardOutput as J,forwardResourceProgress as Q}from"../contextHelpers.js";import{partitionAccounts as U,probeCascadeRoles as V}from"../cascadeHelpers.js";import{accountTier as X,maskSensitiveOutput as l}from"@fjall/util";import{buildOrgContext as Z,resolveOrgDetails as v}from"./orgContext.js";import{INFRA_STEPS as L,maskAndFail as R,readStackOutputsBestEffort as x}from"./infraSteps.js";import{resolveCascadeAccounts as ee}from"./resolveCascadeAccounts.js";import{executeCascade as te}from"./cascadeExecution.js";import{reconcileOrgTrailOutputs as oe}from"./trailReconciliation.js";async function ge(i,t,O,H){const{callbacks:e,options:$}=i,{providerAccounts:u,effectiveOrgConfig:M,defaultRegion:j}=await ee(i,t),g=await v(t);if(!g.success)return R(e,g.error.message);const G=u.find(o=>X(o)==="organisation"),d=Z(i,t,O,"organisation",g.data,void 0,G?.trailLifecycle),m=$?.cascade!==!1,{platformAccount:p,memberAccounts:k}=U(u),P=m&&p!==void 0?1:0,D=m&&k.length>0?1:0,n=2+P+D,I=m?[...p!==void 0?[p]:[],...k]:[];if(I.length>0){const o=await V(t,I,e,i.abortSignal),r=p!==void 0?o.find(a=>a.accountId===p.id):void 0;if(r!==void 0)return R(e,`Pre-flight cascade role check failed for the platform account ${r.accountName} (${r.accountId}): ${r.error}`);for(const a of o)e.onProgress?.({type:"warning",message:l(`Pre-flight cascade role check failed for ${a.accountName} (${a.accountId}) \u2014 its cascade deploy is expected to fail: ${a.error}`)})}e.onCascadeAccountsReconciled?.({hasPlatformAccount:P>0,hasMemberAccounts:D>0});const{id:h,name:S}=L.PREPARE;e.onStepStart?.(h,S,0,n),e.onLog?.("Synthesising organisation infrastructure\u2026","info");const E=await q(t,d,e,"CDK synthesis failed");if(!E.success)return e.onStepComplete?.(h,S,"error",0,n),E;const N=await z(t,d,e);if(!N.success)return e.onStepComplete?.(h,S,"error",0,n),N;e.onStepComplete?.(h,S,"completed",0,n);const{id:C,name:A}=L.ORG_DEPLOY,s=K(B.ORGANISATION);let F=!0;const f=await t.hashService.getTemplateHashes(W(d.path,"cdk.out"));if(f.success){const o=await t.hashService.compareWithState(f.data,d.path);o.success?F=o.data.stackChanges.get(s)??!0:e.onLog?.(l(`Org root change detection failed \u2014 deploying to be safe: ${o.error.message}`),"warn")}else e.onLog?.(l(`Org root template hashing failed \u2014 deploying to be safe: ${f.error.message}`),"warn");const b=F||$?.force===!0||!await t.cfnService.stackExists(s);e.onOrgChangesDetected?.({hasOrgChanges:b});let w;if(b){e.onStepStart?.(C,A,1,n);const o=await t.cdkService.runCdkDeploy(d,s,J(e),Q(e),t.awsProvider);if(!o.success)return e.onStepComplete?.(C,A,"error",1,n),R(e,o.error);w=await x(t,e,s,"Failed to read org stack outputs (non-critical)");const r=f.success?f.data.get(s):void 0;if(r!==void 0){const a=await t.hashService.updateStateAfterDeploy(d.path,new Map([[s,r]]));a.success||e.onLog?.(`Warning: failed to update state file \u2014 next deploy may re-deploy the org root: ${l(a.error.message)}`,"warn")}e.onStepComplete?.(C,A,"completed",1,n)}else e.onLog?.("Organisation root: no infrastructure changes \u2014 skipping deploy","info"),w=await x(t,e,s,"Failed to read org stack outputs (non-critical)");const c=[],y=[];let T=b;if(m&&u.length>0){const{anyCascadeDeployHappened:o}=await te(i,t,O,{providerAccounts:u,effectiveOrgConfig:M,totalSteps:n,cascadeErrors:c,allCascadeOutputs:y});if(o&&(T=!0),await oe(i,t,{orgOutputs:w,allCascadeOutputs:y,orgDetails:g.data,providerAccounts:u,defaultRegion:j}),c.length>0){const r=c.map(a=>`  ${a.accountId}: ${a.error}`).join(`
+`);e.onLog?.(l(`Cascade failed for ${c.length} target(s):
+${r}`),"warn")}}if(c.length>0){const o=c.map(a=>l(`${a.accountId}: ${a.error}`)).join(`
+`),r=new Error(`Organisation root deployed, but the cascade failed for ${c.length} target(s):
+${o}`);return e.onError?.(r),Y(r)}return _({target:O.target,deploymentType:"organisation",outputs:w,...y.length>0?{cascadeOutputs:y}:{},...T?{}:{noChanges:!0},durationMs:Date.now()-H})}export{ge as deployOrgWithCascade};

package/dist/src/orchestration/organisationDeploy/orgContext.d.ts

@@ -0,0 +1,12 @@
+import { type Result } from "@fjall/generator";
+import type { ProviderAccount } from "@fjall/util/config";
+import type { DeployParams } from "../../types/params.js";
+import type { OrganisationOperation } from "../../types/operations.js";
+import type { DeployServices } from "../serviceFactory.js";
+export interface OrgDetailsForSynth {
+    orgId: string;
+    rootId: string;
+    managementAccountId: string;
+}
+export declare function buildOrgContext(params: DeployParams, services: DeployServices, operation: OrganisationOperation, deployType: "organisation" | "platform" | "account", orgDetails: OrgDetailsForSynth, accountName?: string, trailLifecycle?: ProviderAccount["trailLifecycle"]): import("../../types/deployment/DeploymentTypes.js").DeploymentContext;
+export declare function resolveOrgDetails(services: DeployServices): Promise<Result<OrgDetailsForSynth>>;

package/dist/src/orchestration/organisationDeploy/orgContext.js

@@ -0,0 +1 @@
+import{success as a,failure as c}from"@fjall/generator";import{OrganizationsClient as s}from"@aws-sdk/client-organizations";import{CdkContextBuilder as u}from"../../services/supporting/CdkContextBuilder.js";import{stubCallerIdentity as m}from"../../types/deployment/index.js";import{ensureOrganisationExists as f}from"../../aws/organisations/organisation.js";import{buildParamsContext as l}from"../contextHelpers.js";function b(t,n,o,i,r,d,g){const e=n.awsProvider.getRegion();return u.buildDeploymentContext({deployType:i,target:o.target,path:o.path,region:e,accountName:d,callerIdentity:m(n.awsProvider.getAccountId()),orgId:r.orgId,rootId:r.rootId,managementAccountId:r.managementAccountId,...l({orgConfig:t.orgConfig,identity:t.identity,skipOidc:t.options?.skipOidc,...i!=="organisation"?{region:e,primaryRegion:t.orgConfig?.primaryRegion}:{},trailLifecycle:g})},{verbose:t.options?.verbose,infraOnly:t.options?.infraOnly},t.orgConfig)}async function v(t){const n=t.awsProvider.getClient(s),o=await f(n);return o.success?a({orgId:o.data.orgId,rootId:o.data.rootId,managementAccountId:o.data.managementAccountId}):c(o.error)}export{b as buildOrgContext,v as resolveOrgDetails};

package/dist/src/orchestration/organisationDeploy/resolveCascadeAccounts.d.ts

@@ -0,0 +1,15 @@
+import type { ProviderAccount } from "@fjall/util/config";
+import type { DeployParams } from "../../types/params.js";
+import type { OrgConfig } from "../../types/orgConfig.js";
+import type { DeployServices } from "../serviceFactory.js";
+/**
+ * Resolve the deployable provider-account set for an organisation cascade:
+ * reconcile from AWS Organizations when the orgConfig carries no deployable
+ * accounts, stamp a home region onto every account, and compose the
+ * effective orgConfig the cascade synth context needs.
+ */
+export declare function resolveCascadeAccounts(params: DeployParams, services: DeployServices): Promise<{
+    providerAccounts: ProviderAccount[];
+    effectiveOrgConfig: OrgConfig | undefined;
+    defaultRegion: string;
+}>;

package/dist/src/orchestration/organisationDeploy/resolveCascadeAccounts.js

@@ -0,0 +1 @@
+import{cascadeHomeRegion as u}from"../cascadeHelpers.js";import{reconcileProviderAccounts as l,mergeReconciledProviderAccounts as d}from"../reconcileProviderAccounts.js";import{accountTier as f,maskSensitiveOutput as s}from"@fjall/util";async function v(e,g){const{callbacks:c}=e;let o=e.orgConfig?.providerAccounts??[];if(o.length===0||o.every(n=>f(n)==="organisation")){const n=await l(g,e.workingDirectory);if(n.success){const{providerAccounts:i,missingAccountNames:t}=n.data;i.length>0&&(o=d(e.orgConfig,i).providerAccounts,c.onLog?.(`Reconciled ${i.length} account(s) from AWS Organizations`,"info")),t.length>0&&(c.onCascadeMissingAccounts?.(t),c.onProgress?.({type:"warning",message:s(`Accounts declared in ACCOUNTS but not yet in AWS Organizations (cascade will skip): ${t.join(", ")}`)}))}else c.onProgress?.({type:"warning",message:s(`Could not reconcile accounts from AWS Organizations \u2014 cascade may skip accounts: ${n.error.message}`)})}const r=u(e.orgConfig);o=o.map(n=>n.region!==void 0?n:{...n,region:r});const a=e.orgConfig!==void 0?{...e.orgConfig,providerAccounts:o}:o.length>0?{providerAccounts:o}:void 0;return{providerAccounts:o,effectiveOrgConfig:a,defaultRegion:r}}export{v as resolveCascadeAccounts};

package/dist/src/orchestration/organisationDeploy/singleComponentDeploy.d.ts

@@ -0,0 +1,11 @@
+import { type Result } from "@fjall/generator";
+import type { DeployParams, DeployResult } from "../../types/params.js";
+import type { OrganisationOperation } from "../../types/operations.js";
+import type { DeployServices } from "../serviceFactory.js";
+/**
+ * Deploy a single organisation component (platform or account).
+ *
+ * Emits 4 named steps from INFRASTRUCTURE_STEP_NAMES: Connect securely →
+ * Prepare environment → Deploy infrastructure → Enable monitoring.
+ */
+export declare function deploySingleComponent(params: DeployParams, services: DeployServices, operation: OrganisationOperation, deployType: "platform" | "account", startTime: number): Promise<Result<DeployResult>>;

package/dist/src/orchestration/organisationDeploy/singleComponentDeploy.js

@@ -0,0 +1 @@
+import{success as A}from"@fjall/generator";import{BackupClient as N}from"@aws-sdk/client-backup";import{IAMClient as b}from"@aws-sdk/client-iam";import{getOrganisationStackName as w}from"../../types/operations.js";import{accountHasDisasterRecovery as D,describeBackupVaultExists as k}from"../../aws/organisations/backup.js";import{describeAccountGlobalsExist as y,buildMissingAccountGlobalsAdvisory as I}from"../../aws/organisations/accountGlobals.js";import{targetsNonPrimaryRegion as L,synthOrFail as T,bootstrapOrFail as h,forwardOutput as M,forwardResourceProgress as v}from"../contextHelpers.js";import{accountTier as F}from"@fjall/util";import{buildOrgContext as G,resolveOrgDetails as Y}from"./orgContext.js";import{INFRA_STEPS as o,INFRA_STEP_TOTAL as i,failPrepareStep as s,maskAndFail as u,readStackOutputsBestEffort as x}from"./infraSteps.js";async function W(n,r,a,c,E){const{callbacks:t}=n;t.onStepComplete?.(o.CONNECT.id,o.CONNECT.name,"completed",0,i),t.onStepStart?.(o.PREPARE.id,o.PREPARE.name,1,i);const p=r.awsProvider.getRegion(),l=n.orgConfig?.primaryRegion;if(l!==void 0&&L(p,l)){const e=await y(r.awsProvider.getClient(b),n.abortSignal);if(!e.success)return s(t),u(t,e.error.message);if(!e.data)return s(t),u(t,I({target:a.target,deployRegion:p,primaryRegion:l,...n.orgConfig!==void 0?{providerAccounts:n.orgConfig.providerAccounts}:{}}))}const g=await Y(r);if(!g.success)return s(t),u(t,g.error.message);const f=c==="account"?n.orgConfig?.providerAccounts.find(e=>e.name===a.target):n.orgConfig?.providerAccounts.find(e=>F(e)==="platform"),d=G(n,r,a,c,g.data,c==="account"?a.target:void 0,f?.trailLifecycle),m=n.orgConfig?.disasterRecoveryRegion;if(c==="account"&&(m!==void 0&&m!=="")&&(f===void 0||D(f.environment,m))){const e=await k(r.awsProvider.getClient(N));if(!e.success)return s(t),u(t,e.error.message);d.fjallAdoptBackupVault=e.data}t.onLog?.(`Synthesising ${c} infrastructure\u2026`,"info");const R=await T(r,d,t,"CDK synthesis failed");if(!R.success)return s(t),R;const P=await h(r,d,t);if(!P.success)return s(t),P;t.onStepComplete?.(o.PREPARE.id,o.PREPARE.name,"completed",1,i);const C=w(a.type);t.onStepStart?.(o.DEPLOY.id,o.DEPLOY.name,2,i);const O=await r.cdkService.runCdkDeploy(d,C,M(t),v(t),r.awsProvider);if(!O.success)return t.onStepComplete?.(o.DEPLOY.id,o.DEPLOY.name,"error",2,i),u(t,O.error);t.onStepComplete?.(o.DEPLOY.id,o.DEPLOY.name,"completed",2,i);const S=await x(r,t,C,"Failed to read stack outputs (non-critical)");return t.onStepStart?.(o.MONITORING.id,o.MONITORING.name,3,i),t.onStepComplete?.(o.MONITORING.id,o.MONITORING.name,"completed",3,i),A({target:a.target,deploymentType:"organisation",outputs:S,durationMs:Date.now()-E})}export{W as deploySingleComponent};

package/dist/src/orchestration/organisationDeploy/trailReconciliation.d.ts

@@ -0,0 +1,21 @@
+import type { ProviderAccount } from "@fjall/util/config";
+import type { DeployParams } from "../../types/params.js";
+import type { DeployServices } from "../serviceFactory.js";
+import type { OrgDetailsForSynth } from "./orgContext.js";
+/**
+ * Org-trail migration reconciliation: two-invocation convergence — this
+ * run's cheap probes advance lifecycle states (persisted by the consumer
+ * via onTrailLifecycleChanged); the NEXT deploy applies them. Gated on the
+ * org root actually owning an organisation trail; failures warn and never
+ * fail the deploy.
+ */
+export declare function reconcileOrgTrailOutputs(params: DeployParams, services: DeployServices, args: {
+    orgOutputs: Record<string, string> | undefined;
+    allCascadeOutputs: Array<{
+        accountId: string;
+        outputs: Record<string, string>;
+    }>;
+    orgDetails: OrgDetailsForSynth;
+    providerAccounts: ProviderAccount[];
+    defaultRegion: string;
+}): Promise<void>;

package/dist/src/orchestration/organisationDeploy/trailReconciliation.js

@@ -0,0 +1 @@
+import{success as g,failure as O}from"@fjall/generator";import{S3Client as c}from"@aws-sdk/client-s3";import{CloudTrailClient as m}from"@aws-sdk/client-cloudtrail";import{KMSClient as f}from"@aws-sdk/client-kms";import{assumeCascadeRole as w}from"../contextHelpers.js";import{reconcileTrailMigration as I,ORG_TRAIL_BUCKET_OUTPUT_KEY as S,TRAIL_BUCKET_OUTPUT_KEY as P}from"../trailMigration/trailMigration.js";import{getErrorMessage as R,maskSensitiveOutput as _}from"@fjall/util";async function K(n,e,s){const{callbacks:u}=n,{orgOutputs:o,allCascadeOutputs:C,orgDetails:a,providerAccounts:p}=s,l=o?.[S];if(l!==void 0&&l!==""){const r=new Map;for(const t of C)(r.get(t.accountId)===void 0||P in t.outputs)&&r.set(t.accountId,t.outputs);o!==void 0&&r.set(a.managementAccountId,o);const T=async(t,d)=>{if(t.id===a.managementAccountId)return g({cloudTrailClient:e.awsProvider.getClient(m),s3Client:e.awsProvider.getClient(c),kmsClient:e.awsProvider.getClient(f)});const i=await w(e.awsProvider,t.id,d,`fjall-trail-migration-${t.name}`,n.abortSignal);return i.success?g({cloudTrailClient:i.data.provider.getClient(m),s3Client:i.data.provider.getClient(c),kmsClient:i.data.provider.getClient(f)}):O(i.error)};try{await I({managementS3Client:e.awsProvider.getClient(c),getMemberClients:T},{orgId:a.orgId,orgTrailBucketName:l,accounts:p,cascadeOutputs:r,defaultRegion:s.defaultRegion,...n.abortSignal!==void 0?{abortSignal:n.abortSignal}:{}},u)}catch(t){u.onLog?.(_(`Org-trail migration reconciliation failed (non-fatal): ${R(t)}`),"warn")}}}export{K as reconcileOrgTrailOutputs};

package/dist/src/orchestration/organisationDeploy.d.ts

@@ -2,6 +2,7 @@ import { type Result } from "@fjall/generator";
 import type { DeployParams, DeployResult } from "../types/params.js";
 import type { OrganisationOperation } from "../types/operations.js";
 import type { DeployServices } from "./serviceFactory.js";
+export type { OrgDetailsForSynth } from "./organisationDeploy/orgContext.js";
 /**
  * Organisation deployment orchestration.
  *
@@ -14,8 +15,3 @@ import type { DeployServices } from "./serviceFactory.js";
  * responsibility. deploy-core receives credentials and deploys.
  */
 export declare function deployOrganisation(params: DeployParams, services: DeployServices, operation: OrganisationOperation): Promise<Result<DeployResult>>;
-export interface OrgDetailsForSynth {
-    orgId: string;
-    rootId: string;
-    managementAccountId: string;
-}

package/dist/src/orchestration/organisationDeploy.js

@@ -1,5 +1 @@
-import{join as we}from"node:path";import{success as re,failure as h}from"@fjall/generator";import{OrganizationsClient as Ie}from"@aws-sdk/client-organizations";import{BackupClient as ye}from"@aws-sdk/client-backup";import{ORGANISATION_TYPES as K,getOrganisationStackName as me}from"../types/operations.js";import{CdkContextBuilder as Ne}from"../services/supporting/CdkContextBuilder.js";import{stubCallerIdentity as De}from"../types/deployment/index.js";import{ensureOrganisationExists as ke}from"../aws/organisations/organisation.js";import{accountHasDisasterRecovery as be,describeBackupVaultExists as Te}from"../aws/organisations/backup.js";import{buildParamsContext as Le,collectStackOutputs as ae,synthOrFail as ge,bootstrapOrFail as fe,forwardOutput as Ce,forwardResourceProgress as Se}from"./contextHelpers.js";import{partitionAccounts as Ae,deployCascadeAccount as Ee,readPlatformIpamPoolIds as Me,deployDomains as _e,buildRegionList as $e,buildAccountRegionPairs as Fe,CASCADE_MAX_CONCURRENCY as Ge}from"./cascadeHelpers.js";import{projectScalarSummary as Oe}from"./cascadeSummary.js";import{reconcileProviderAccounts as Ye,mergeReconciledProviderAccounts as xe}from"./reconcileProviderAccounts.js";import{accountTier as ve,maskSensitiveOutput as i,mapSettledWithConcurrency as Ue}from"@fjall/util";import{INFRA_STEP_NAME as X,STEP_IDS as T,STEP_NAMES as se}from"../types/stepDefinitions.js";async function at(o,t,s){const g=Date.now();switch(s.type){case K.ORGANISATION:return We(o,t,s,g);case K.PLATFORM:return he(o,t,s,"platform",g);case K.ACCOUNT:return he(o,t,s,"account",g);default:{const e=s.type;return h(new Error(`Unsupported organisation type: ${String(e)}`))}}}function Re(o,t,s,g,e,r){return Ne.buildDeploymentContext({deployType:g,target:s.target,path:s.path,region:t.awsProvider.getRegion(),accountName:r,callerIdentity:De(t.awsProvider.getAccountId()),orgId:e.orgId,rootId:e.rootId,managementAccountId:e.managementAccountId,...Le({orgConfig:o.orgConfig,identity:o.identity,skipOidc:o.options?.skipOidc})},{verbose:o.options?.verbose,infraOnly:o.options?.infraOnly},o.orgConfig)}async function Pe(o){const t=o.awsProvider.getClient(Ie),s=await ke(t);return s.success?re({orgId:s.data.orgId,rootId:s.data.rootId,managementAccountId:s.data.managementAccountId}):h(s.error)}const n={CONNECT:{id:T.CONNECT,name:X.CONNECT},PREPARE:{id:T.PREPARE_ENVIRONMENT,name:X.PREPARE},DEPLOY:{id:T.DEPLOY,name:X.DEPLOY},MONITORING:{id:T.MONITORING,name:X.MONITORING},ORG_DEPLOY:{id:T.ORG_DEPLOY,name:se.ORG_DEPLOY},CASCADE_PLATFORM:{id:T.CASCADE_PLATFORM,name:se.CASCADE_PLATFORM},CASCADE_ACCOUNTS:{id:T.CASCADE_ACCOUNTS,name:se.CASCADE_ACCOUNTS}},S=4;async function he(o,t,s,g,e){const{callbacks:r}=o;r.onStepComplete?.(n.CONNECT.id,n.CONNECT.name,"completed",0,S),r.onStepStart?.(n.PREPARE.id,n.PREPARE.name,1,S);const p=await Pe(t);if(!p.success){r.onStepComplete?.(n.PREPARE.id,n.PREPARE.name,"error",1,S);const l=new Error(i(p.error.message));return r.onError?.(l),h(l)}const $=Re(o,t,s,g,p.data,g==="account"?s.target:void 0),L=o.orgConfig?.disasterRecoveryRegion,W=L!==void 0&&L!=="",M=g==="account"?o.orgConfig?.providerAccounts.find(l=>l.name===s.target):void 0;if(g==="account"&&W&&(M===void 0||be(M.environment,L))){const l=await Te(t.awsProvider.getClient(ye));if(!l.success){r.onStepComplete?.(n.PREPARE.id,n.PREPARE.name,"error",1,S);const N=new Error(i(l.error.message));return r.onError?.(N),h(N)}$.fjallAdoptBackupVault=l.data}r.onLog?.(`Synthesising ${g} infrastructure\u2026`,"info");const _=await ge(t,$,r,"CDK synthesis failed");if(!_.success)return r.onStepComplete?.(n.PREPARE.id,n.PREPARE.name,"error",1,S),_;const j=await fe(t,$,r);if(!j.success)return r.onStepComplete?.(n.PREPARE.id,n.PREPARE.name,"error",1,S),j;r.onStepComplete?.(n.PREPARE.id,n.PREPARE.name,"completed",1,S);const H=me(s.type);r.onStepStart?.(n.DEPLOY.id,n.DEPLOY.name,2,S);const F=await t.cdkService.runCdkDeploy($,H,Ce(r),Se(r),t.awsProvider);if(!F.success){r.onStepComplete?.(n.DEPLOY.id,n.DEPLOY.name,"error",2,S);const l=new Error(i(F.error));return r.onError?.(l),h(l)}r.onStepComplete?.(n.DEPLOY.id,n.DEPLOY.name,"completed",2,S);const G=await t.cfnService.getStackOutputs(H);G.success||r.onLog?.("Failed to read stack outputs (non-critical)","debug");const d=ae(G);return r.onStepStart?.(n.MONITORING.id,n.MONITORING.name,3,S),r.onStepComplete?.(n.MONITORING.id,n.MONITORING.name,"completed",3,S),re({target:s.target,deploymentType:"organisation",outputs:d,durationMs:Date.now()-e})}async function We(o,t,s,g){const{callbacks:e,options:r}=o;let p=o.orgConfig?.providerAccounts??[];if(p.length===0||p.every(a=>ve(a)==="organisation")){const a=await Ye(t,o.workingDirectory);if(a.success){const{providerAccounts:c,missingAccountNames:C}=a.data;c.length>0&&(p=xe(o.orgConfig,c).providerAccounts,e.onLog?.(`Reconciled ${c.length} account(s) from AWS Organizations`,"info")),C.length>0&&(e.onCascadeMissingAccounts?.(C),e.onProgress?.({type:"warning",message:i(`Accounts declared in ACCOUNTS but not yet in AWS Organizations (cascade will skip): ${C.join(", ")}`)}))}else e.onProgress?.({type:"warning",message:i(`Could not reconcile accounts from AWS Organizations \u2014 cascade may skip accounts: ${a.error.message}`)})}const L=o.orgConfig?.primaryRegion??t.awsProvider.getRegion();p=p.map(a=>a.region!==void 0?a:{...a,region:L});const W=o.orgConfig!==void 0?{...o.orgConfig,providerAccounts:p}:p.length>0?{providerAccounts:p}:void 0,M=await Pe(t);if(!M.success){const a=new Error(i(M.error.message));return e.onError?.(a),h(a)}const y=Re(o,t,s,"organisation",M.data),_=r?.cascade!==!1,{platformAccount:j,memberAccounts:H}=Ae(p),F=_&&j!==void 0?1:0,G=_&&H.length>0?1:0,d=2+F+G;e.onCascadeAccountsReconciled?.({hasPlatformAccount:F>0,hasMemberAccounts:G>0});const{id:l,name:N}=n.PREPARE;e.onStepStart?.(l,N,0,d),e.onLog?.("Synthesising organisation infrastructure\u2026","info");const ce=await ge(t,y,e,"CDK synthesis failed");if(!ce.success)return e.onStepComplete?.(l,N,"error",0,d),ce;const ie=await fe(t,y,e);if(!ie.success)return e.onStepComplete?.(l,N,"error",0,d),ie;e.onStepComplete?.(l,N,"completed",0,d);const{id:J,name:Q}=n.ORG_DEPLOY,D=me(K.ORGANISATION);let de=!0;const Y=await t.hashService.getTemplateHashes(we(y.path,"cdk.out"));if(Y.success){const a=await t.hashService.compareWithState(Y.data,y.path);a.success?de=a.data.stackChanges.get(D)??!0:e.onLog?.(i(`Org root change detection failed \u2014 deploying to be safe: ${a.error.message}`),"warn")}else e.onLog?.(i(`Org root template hashing failed \u2014 deploying to be safe: ${Y.error.message}`),"warn");const Z=de||r?.force===!0||!await t.cfnService.stackExists(D);e.onOrgChangesDetected?.({hasOrgChanges:Z});let ee;if(Z){e.onStepStart?.(J,Q,1,d);const a=await t.cdkService.runCdkDeploy(y,D,Ce(e),Se(e),t.awsProvider);if(!a.success){e.onStepComplete?.(J,Q,"error",1,d);const R=new Error(i(a.error));return e.onError?.(R),h(R)}const c=await t.cfnService.getStackOutputs(D);c.success||e.onLog?.("Failed to read org stack outputs (non-critical)","debug"),ee=ae(c);const C=Y.success?Y.data.get(D):void 0;if(C!==void 0){const R=await t.hashService.updateStateAfterDeploy(y.path,new Map([[D,C]]));R.success||e.onLog?.(`Warning: failed to update state file \u2014 next deploy may re-deploy the org root: ${i(R.error.message)}`,"warn")}e.onStepComplete?.(J,Q,"completed",1,d)}else{e.onLog?.("Organisation root: no infrastructure changes \u2014 skipping deploy","info");const a=await t.cfnService.getStackOutputs(D);a.success||e.onLog?.("Failed to read org stack outputs (non-critical)","debug"),ee=ae(a)}const f=[],V=[];let z=Z;if(_&&p.length>0){e.onCascadeStart?.();const a=Date.now();let c=2,C=!1,R,te=!1;const B=[],ue=u=>({members:B,...R!==void 0?{platform:R}:{},domainsDeployed:te,errors:f,totalDurationMs:u}),{platformAccount:A,memberAccounts:q}=Ae(p);if(A){const{id:u,name:m}=n.CASCADE_PLATFORM;e.onStepStart?.(u,m,c,d),e.onCascadePhaseStart?.("platform");let E;const oe=Date.now();try{E=await Ee(o,t,s,A,"platform",e,{orgConfig:W})}catch(P){const v=i(P instanceof Error?P.message:String(P));f.push({accountId:A.id,error:v}),e.onCascadePhaseComplete?.("platform"),e.onStepComplete?.(u,m,"error",c,d),E=h(new Error(v))}const x=Date.now()-oe;if(E.success){C=!0;const P=E.data.skipped===!0;P||(z=!0),E.data.outputs&&V.push({accountId:A.id,outputs:E.data.outputs}),e.onCascadePhaseComplete?.("platform"),e.onStepComplete?.(u,m,P?"skipped":"completed",c,d),R={accountId:A.id,result:P?"skipped":"succeeded",durationMs:x}}else f.some(P=>P.accountId===A.id)||(f.push({accountId:A.id,error:i(E.error.message)}),e.onCascadePhaseComplete?.("platform"),e.onStepComplete?.(u,m,"error",c,d)),R={accountId:A.id,result:"failed",durationMs:x,error:i(E.error.message)};c++}let le=new Map;if(C&&A&&(le=await Me(t,A,e)),o.domainProvider){const u=await _e(o.domainProvider,e);te=u.domainsDeployed>0,te&&(z=!0);for(const m of u.errors)f.push({accountId:"domains",error:i(m)})}if(A!==void 0&&!C&&q.length>0){const{id:u,name:m}=n.CASCADE_ACCOUNTS;e.onStepStart?.(u,m,c,d),e.onStepComplete?.(u,m,"skipped",c,d),e.onLog?.("Skipping account cascade \u2014 platform deployment failed; platform is a prerequisite for member accounts.","warn")}else if(q.length>0){const{id:u,name:m}=n.CASCADE_ACCOUNTS;e.onStepStart?.(u,m,c,d),e.onCascadePhaseStart?.("accounts");const E=$e(o.orgConfig),oe=E[0]??L,x=Fe(q,E);(await Ue(x,Ge,async({account:w,region:U})=>{const k=U.replace(/-/g,""),O=le.get(`${w.id}-${k}`),b=Date.now();return{result:await Ee(o,t,s,w,"account",e,{ipamPoolId:O,orgConfig:W,region:U,skipAccountGlobals:U!==oe}),durationMs:Date.now()-b}})).forEach((w,U)=>{const k=x[U];if(!k)return;const O=k.account;if(w.status==="rejected"){const I=i(w.reason instanceof Error?w.reason.message:String(w.reason));B.push({accountId:O.id,accountName:O.name,region:k.region,result:"failed",durationMs:0,error:I}),f.push({accountId:O.id,error:I});return}const{result:b,durationMs:ne}=w.value;if(b.success){const I=b.data.skipped===!0;I||(z=!0),b.data.outputs&&V.push({accountId:O.id,outputs:b.data.outputs}),B.push({accountId:O.id,accountName:O.name,region:k.region,result:I?"skipped":"succeeded",durationMs:ne})}else{const I=i(b.error.message);B.push({accountId:O.id,accountName:O.name,region:k.region,result:"failed",durationMs:ne,error:I}),f.push({accountId:O.id,error:I})}});const v=Oe(ue(0));e.onCascadePhaseComplete?.("accounts"),e.onStepComplete?.(u,m,v.accountsFailed>0?"error":v.accountsSkipped===q.length?"skipped":"completed",c,d)}const pe=ue(Date.now()-a);if(e.onCascadeComplete?.(Oe(pe)),e.onCascadeLedger?.(pe),f.length>0){const u=f.map(m=>`  ${m.accountId}: ${m.error}`).join(`
-`);e.onLog?.(i(`Cascade failed for ${f.length} target(s):
-${u}`),"warn")}}if(f.length>0){const a=f.map(C=>i(`${C.accountId}: ${C.error}`)).join(`
-`),c=new Error(`Organisation root deployed, but the cascade failed for ${f.length} target(s):
-${a}`);return e.onError?.(c),h(c)}return re({target:s.target,deploymentType:"organisation",outputs:ee,...V.length>0?{cascadeOutputs:V}:{},...z?{}:{noChanges:!0},durationMs:Date.now()-g})}export{at as deployOrganisation};
+import{failure as a}from"@fjall/generator";import{ORGANISATION_TYPES as o}from"../types/operations.js";import{deploySingleComponent as i}from"./organisationDeploy/singleComponentDeploy.js";import{deployOrgWithCascade as c}from"./organisationDeploy/orgCascadeDeploy.js";async function l(r,e,t){const n=Date.now();switch(t.type){case o.ORGANISATION:return c(r,e,t,n);case o.PLATFORM:return i(r,e,t,"platform",n);case o.ACCOUNT:return i(r,e,t,"account",n);default:{const u=t.type;return a(new Error(`Unsupported organisation type: ${String(u)}`))}}}export{l as deployOrganisation};

package/dist/src/orchestration/organisationDestroy.d.ts

@@ -4,7 +4,7 @@
  * Receives pre-authenticated credentials and destroys all organisation
  * infrastructure in cascade order:
  * 1. Member accounts across ALL regions in parallel
- * 2. Platform account in primary region
+ * 2. Platform account in its home region
  * 3. Organisation root stack
  *
  * Auth, verification, and interactive prompts are the caller's job

package/dist/src/orchestration/organisationDestroy.js

@@ -1,3 +1,3 @@
-import{success as O,failure as P}from"@fjall/generator";import{maskSensitiveOutput as g,getErrorMessage as $,mapSettledWithConcurrency as M}from"@fjall/util";import{stubCallerIdentity as _}from"../types/deployment/index.js";import{ORGANISATION_TYPES as k,getOrganisationStackName as b}from"../types/operations.js";import{CdkContextBuilder as v}from"../services/supporting/CdkContextBuilder.js";import{buildParamsContext as L,synthOrFail as x,forwardOutput as G,forwardResourceProgress as Y}from"./contextHelpers.js";import{destroyCascadeAccount as T}from"./cascadeDestroyHelpers.js";import{partitionAccounts as j,buildRegionList as U,buildAccountRegionPairs as B,CASCADE_MAX_CONCURRENCY as F}from"./cascadeHelpers.js";import{projectScalarSummary as W}from"./cascadeSummary.js";import{STEP_IDS as X}from"../types/stepDefinitions.js";const D=X.ORG_DESTROY,I="Destroying organisation infrastructure";async function et(r,e,i){const h=Date.now(),{callbacks:t}=r,l=r.orgConfig?.providerAccounts??[],f=r.orgConfig?.primaryRegion??e.awsProvider.getRegion(),m=U(r.orgConfig),{platformAccount:u,memberAccounts:p}=j(l),N=r.options?.cascade!==!1;t.onLog?.(`Destroying organisation infrastructure (${l.length} accounts, ${m.length} region(s))`,"info");const n=[],y=[],R=[];let w;if(N){t.onCascadeStart?.();const E=Date.now();if(p.length>0){t.onCascadePhaseStart?.("accounts");const a=B(p,m),d=await M(a,F,({account:s,region:c})=>T(r,e,i,s,"account",c,t));for(let s=0;s<d.length;s++){const c=d[s],o=a[s];if(!(!c||!o))if(c.status==="fulfilled")if(c.value.success)y.push(`Account-${o.account.name}-${o.region}`),R.push({accountId:o.account.id,accountName:o.account.name,region:o.region,result:"succeeded",durationMs:c.value.duration});else{const C=g(c.value.error??"Unknown error");R.push({accountId:o.account.id,accountName:o.account.name,region:o.region,result:"failed",durationMs:c.value.duration,error:C}),n.push({accountId:o.account.id,error:C})}else{const C=g($(c.reason));R.push({accountId:o.account.id,accountName:o.account.name,region:o.region,result:"failed",durationMs:0,error:C}),n.push({accountId:o.account.id,error:C})}}}if(u){t.onCascadePhaseStart?.("platform");const a=await T(r,e,i,u,"platform",f,t);if(a.success)y.push("Platform"),w={accountId:u.id,result:"succeeded",durationMs:a.duration};else{const d=g(a.error??"Platform destroy failed");n.push({accountId:u.id,error:d}),w={accountId:u.id,result:"failed",durationMs:a.duration,error:d}}}const S={members:R,...w!==void 0?{platform:w}:{},domainsDeployed:!1,errors:n,totalDurationMs:Date.now()-E};if(t.onCascadeComplete?.(W(S)),t.onCascadeLedger?.(S),n.length>0){const a=n.map(s=>`  ${s.accountId}: ${s.error}`).join(`
+import{CloudFormationClient as k}from"@aws-sdk/client-cloudformation";import{S3Client as T}from"@aws-sdk/client-s3";import{success as D,failure as N}from"@fjall/generator";import{maskSensitiveOutput as O,getErrorMessage as M,mapSettledWithConcurrency as _}from"@fjall/util";import{stubCallerIdentity as b}from"../types/deployment/index.js";import{ORGANISATION_TYPES as v,getOrganisationStackName as L}from"../types/operations.js";import{CdkContextBuilder as x}from"../services/supporting/CdkContextBuilder.js";import{buildParamsContext as B,synthOrFail as G,forwardOutput as Y,forwardResourceProgress as j}from"./contextHelpers.js";import{destroyCascadeAccount as $}from"./cascadeDestroyHelpers.js";import{capturedSweepBuckets as F,preEmptyStackBuckets as U,sweepOrphanedDestroyBuckets as H}from"./stackCleanup.js";import{partitionAccounts as W,buildRegionList as X,buildAccountRegionPairs as q,cascadeHomeRegion as z,CASCADE_MAX_CONCURRENCY as J}from"./cascadeHelpers.js";import{projectScalarSummary as K}from"./cascadeSummary.js";import{STEP_IDS as Q}from"../types/stepDefinitions.js";const E=Q.ORG_DESTROY,I="Destroying organisation infrastructure";async function lt(o,r,c){const S=Date.now(),{callbacks:t}=o,l=o.orgConfig?.providerAccounts??[],g=z(o.orgConfig),m=X(o.orgConfig),{platformAccount:u,memberAccounts:f}=W(l),h=o.options?.cascade!==!1;t.onLog?.(`Destroying organisation infrastructure (${l.length} accounts, ${m.length} region(s))`,"info");const n=[],p=[],w=[];let R;if(h){t.onCascadeStart?.();const A=Date.now();if(f.length>0){t.onCascadePhaseStart?.("accounts");const a=q(f,m),d=await _(a,J,({account:s,region:i})=>$(o,r,c,s,"account",i,t,{primaryRegion:g}));for(let s=0;s<d.length;s++){const i=d[s],e=a[s];if(!(!i||!e))if(i.status==="fulfilled")if(i.value.success)p.push(`Account-${e.account.name}-${e.region}`),w.push({accountId:e.account.id,accountName:e.account.name,region:e.region,result:"succeeded",durationMs:i.value.duration});else{const C=O(i.value.error??"Unknown error");w.push({accountId:e.account.id,accountName:e.account.name,region:e.region,result:"failed",durationMs:i.value.duration,error:C}),n.push({accountId:e.account.id,error:C})}else{const C=O(M(i.reason));w.push({accountId:e.account.id,accountName:e.account.name,region:e.region,result:"failed",durationMs:0,error:C}),n.push({accountId:e.account.id,error:C})}}t.onCascadePhaseComplete?.("accounts")}if(u){t.onCascadePhaseStart?.("platform");const a=await $(o,r,c,u,"platform",u.region??g,t);if(a.success)p.push("Platform"),R={accountId:u.id,result:"succeeded",durationMs:a.duration};else{const d=O(a.error??"Platform destroy failed");n.push({accountId:u.id,error:d}),R={accountId:u.id,result:"failed",durationMs:a.duration,error:d}}t.onCascadePhaseComplete?.("platform")}const y={members:w,...R!==void 0?{platform:R}:{},domainsDeployed:!1,errors:n,totalDurationMs:Date.now()-A};if(t.onCascadeComplete?.(K(y)),t.onCascadeLedger?.(y),n.length>0){const a=n.map(s=>`  ${s.accountId}: ${s.error}`).join(`
 `),d=new Error(`Cascade destroy completed with ${n.length} failure(s):
-${a}`);t.onError?.(d),t.onLog?.(g(d.message),"warn")}}if(n.length>0)return t.onLog?.("Skipping organisation root stack destroy due to cascade failures","warn"),O({target:i.target,deploymentType:"organisation",stacksDestroyed:y,durationMs:Date.now()-h,warnings:n.map(S=>g(`${S.accountId}: ${S.error}`))});t.onStepStart?.(D,I,0,1);const A=await q(r,e,i,f,t);if(A.success)y.push("Organisation"),t.onStepComplete?.(D,I,"completed",0,1);else return t.onStepComplete?.(D,I,"error",0,1),P(A.error);return O({target:i.target,deploymentType:"organisation",stacksDestroyed:y,durationMs:Date.now()-h})}async function q(r,e,i,h,t){const l=v.buildDeploymentContext({deployType:"organisation",target:i.target,path:i.path,region:h,callerIdentity:_(e.awsProvider.getAccountId()),...L({orgConfig:r.orgConfig,identity:r.identity})},{verbose:r.options?.verbose},r.orgConfig),f=b(k.ORGANISATION);t.onLog?.("Synthesising organisation infrastructure\u2026","info");const m=await x(e,l,t,"Organisation synth failed");if(!m.success)return m;t.onLog?.(`Destroying ${f} stack\u2026`,"info");const u=await e.cdkService.runCdkDestroy(l,f,G(t),Y(t),e.awsProvider,!0);if(!u.success){const p=new Error(g(`Organisation destroy failed: ${u.error}`));return t.onError?.(p),P(p)}return O(void 0)}export{et as destroyOrganisation};
+${a}`);t.onError?.(d),t.onLog?.(d.message,"warn")}}if(n.length>0)return t.onLog?.("Skipping organisation root stack destroy due to cascade failures","warn"),D({target:c.target,deploymentType:"organisation",stacksDestroyed:p,durationMs:Date.now()-S,warnings:n.map(y=>`${y.accountId}: ${y.error}`)});t.onStepStart?.(E,I,0,1);const P=await V(o,r,c,r.awsProvider.getRegion(),t);if(P.success)p.push("Organisation"),t.onStepComplete?.(E,I,"completed",0,1);else return t.onStepComplete?.(E,I,"error",0,1),N(P.error);return D({target:c.target,deploymentType:"organisation",stacksDestroyed:p,durationMs:Date.now()-S})}async function V(o,r,c,S,t){const l=x.buildDeploymentContext({deployType:"organisation",target:c.target,path:c.path,region:S,callerIdentity:b(r.awsProvider.getAccountId()),...B({orgConfig:o.orgConfig,identity:o.identity})},{verbose:o.options?.verbose},o.orgConfig),g=L(v.ORGANISATION);t.onLog?.("Synthesising organisation infrastructure\u2026","info");const m=await G(r,l,t,"Organisation synth failed");if(!m.success)return m;const u=await U(r.awsProvider.getClient(k),r.awsProvider.getClient(T),g,t,o.abortSignal),f=F(u);t.onLog?.(`Destroying ${g} stack\u2026`,"info");const h=await r.cdkService.runCdkDestroy(l,g,Y(t),j(t),r.awsProvider,!0);if(!h.success){const n=new Error(O(`Organisation destroy failed: ${h.error}`));return t.onError?.(n),N(n)}return f.length>0&&await H(r.awsProvider.getClient(T),f,t,o.abortSignal),D(void 0)}export{lt as destroyOrganisation};

package/dist/src/orchestration/organisationSetup.d.ts

@@ -1,11 +1,26 @@
 import { type Result } from "@fjall/generator";
 import type { AwsProvider } from "../aws/AwsProvider.js";
 import type { OUTree, AccountInfo } from "../aws/organisations/types.js";
-export type OrgSetupPhase = "create-organisation" | "enable-policies" | "enable-service-access" | "enable-ram-sharing" | "activate-trusted-access" | "enable-ipam" | "configure-backup" | "create-accounts" | "create-organisational-units" | "place-accounts" | "activate-cost-tags" | "check-identity-centre" | "register-security-delegates";
+/**
+ * Execution-order tuple of org-setup phases — single source of truth for the
+ * OrgSetupPhase union. The engine's hand-written phase blocks are tethered to
+ * this tuple by the "starts every declared phase" test in
+ * organisationSetup.test.ts: a variant added here without an engine block
+ * fails that test; an engine literal not listed here fails typecheck
+ * (executePhase/skipPhase take OrgSetupPhase).
+ */
+export declare const ORG_SETUP_PHASES: readonly ["create-organisation", "enable-policies", "enable-service-access", "enable-root-access", "enable-ram-sharing", "activate-trusted-access", "enable-ipam", "configure-backup", "create-accounts", "create-organisational-units", "place-accounts", "activate-cost-tags", "check-identity-centre", "register-security-delegates"];
+export type OrgSetupPhase = (typeof ORG_SETUP_PHASES)[number];
 export interface OrgSetupCallbacks {
     onPhaseStart?(phase: OrgSetupPhase): void;
     onPhaseComplete?(phase: OrgSetupPhase, result: "completed" | "skipped" | "error"): void;
     onProgress?(message: string): void;
+    /**
+     * Posture-change warnings that must be visible but never block the phase
+     * (e.g. the AC2.8 imported-account warning). Adapters that do not handle
+     * this receive the same message through onProgress instead.
+     */
+    onWarning?(phase: OrgSetupPhase, message: string): void;
     onError?(phase: OrgSetupPhase, error: Error): void;
 }
 export interface OrgSetupConfig {
@@ -18,6 +33,7 @@ export interface OrgSetupConfig {
     accountPlacements?: AccountInfo[];
     costAllocationTags?: string[];
     skipIdentityCentre?: boolean;
+    skipRootAccessManagement?: boolean;
     securityDelegateAccountId?: string;
 }
 export interface OrgSetupResult {
@@ -37,8 +53,12 @@ export interface OrgSetupResult {
 /**
  * Orchestrate the full AWS Organisation setup sequence.
  *
- * Runs up to 13 phases sequentially. Non-fatal phase failures are recorded
+ * Runs up to 14 phases sequentially. Non-fatal phase failures are recorded
  * and execution continues. The only fatal failure is phase 1
  * (create-organisation) since all subsequent phases depend on the org ID.
+ *
+ * @param abortSignal Optional shutdown signal — short-circuits the long
+ *   account-creation and policy-enable polls so a SIGTERM-driven worker
+ *   shutdown is not stalled by in-flight sleeps
  */
-export declare function runOrganisationSetup(awsProvider: AwsProvider, config: OrgSetupConfig, callbacks?: OrgSetupCallbacks): Promise<Result<OrgSetupResult>>;
+export declare function runOrganisationSetup(awsProvider: AwsProvider, config: OrgSetupConfig, callbacks?: OrgSetupCallbacks, abortSignal?: AbortSignal): Promise<Result<OrgSetupResult>>;

package/dist/src/orchestration/organisationSetup.js

@@ -1 +1 @@
-import{success as C,failure as f}from"@fjall/generator";import{OrganizationsClient as L}from"@aws-sdk/client-organizations";import{RAMClient as F}from"@aws-sdk/client-ram";import{CloudFormationClient as j}from"@aws-sdk/client-cloudformation";import{EC2Client as D}from"@aws-sdk/client-ec2";import{BackupClient as W}from"@aws-sdk/client-backup";import{CostExplorerClient as B}from"@aws-sdk/client-cost-explorer";import{SSOAdminClient as $}from"@aws-sdk/client-sso-admin";import{ensureOrganisationExists as z}from"../aws/organisations/organisation.js";import{enablePolicyTypes as G}from"../aws/organisations/policies.js";import{enableServiceAccess as K}from"../aws/organisations/serviceAccess.js";import{enableRamSharing as q}from"../aws/organisations/ram.js";import{activateTrustedAccess as H}from"../aws/organisations/trustedAccess.js";import{enableIpamDelegatedAdmin as J}from"../aws/organisations/ipam.js";import{updateBackupGlobalSettings as Q}from"../aws/organisations/backup.js";import{listAccounts as E,createAccount as V}from"../aws/organisations/accounts.js";import{ensureOrganisationalUnitsExist as X,placeAccountsInOUs as Y,buildAccountToOUMap as Z}from"../aws/organisations/organisationalUnits.js";import{activateCostAllocationTags as _}from"../aws/organisations/costAllocation.js";import{checkIdentityCentreStatus as b}from"../aws/organisations/identityCentre.js";import{registerSecurityDelegates as k}from"../aws/organisations/delegatedAdmin.js";import{isOULeaf as ee}from"../aws/organisations/types.js";async function Ee(n,o,e){const r=[],s=[],t=[],a=[];let c;const u=n.getClient(L),O=n.getClient(F),U=n.getClient(j),R=n.getClient(D),x=n.getClient(W),N=n.getClient(B),T=n.getClient($);e?.onPhaseStart?.("create-organisation"),e?.onProgress?.("Ensuring AWS Organisation exists");const g=await z(u);if(!g.success)return e?.onError?.("create-organisation",g.error),e?.onPhaseComplete?.("create-organisation","error"),f(g.error);const{orgId:M,rootId:P}=g.data;if(e?.onPhaseComplete?.("create-organisation","completed"),r.push("create-organisation"),await p("enable-policies",()=>(e?.onProgress?.("Enabling organisation policy types"),G(u,P)),r,t,e),await p("enable-service-access",()=>(e?.onProgress?.("Enabling AWS service access"),K(u)),r,t,e),await p("enable-ram-sharing",()=>(e?.onProgress?.("Enabling RAM sharing"),q(O)),r,t,e),await p("activate-trusted-access",()=>(e?.onProgress?.("Activating CloudFormation trusted access"),H(U)),r,t,e),o.platformAccountId){const i=o.platformAccountId;await p("enable-ipam",()=>(e?.onProgress?.("Enabling IPAM delegated administrator"),J(R,i)),r,t,e)}await p("configure-backup",()=>(e?.onProgress?.("Updating backup global settings"),Q(x)),r,t,e),e?.onPhaseStart?.("create-accounts"),e?.onProgress?.("Checking for missing accounts");const d=await te(u,o.accounts,a,e);let y=[];d.success?(y=d.data,r.push("create-accounts"),e?.onPhaseComplete?.("create-accounts","completed")):(t.push({phase:"create-accounts",error:d.error.message}),e?.onError?.("create-accounts",d.error),e?.onPhaseComplete?.("create-accounts","error"));let h={};e?.onPhaseStart?.("create-organisational-units"),e?.onProgress?.("Ensuring organisational units exist");const l=await X(u,P,o.organisationalUnits);l.success?(h=l.data,r.push("create-organisational-units"),e?.onPhaseComplete?.("create-organisational-units","completed")):(t.push({phase:"create-organisational-units",error:l.error.message}),e?.onError?.("create-organisational-units",l.error),e?.onPhaseComplete?.("create-organisational-units","error"));const m=Array.isArray(o.organisationalUnits)?void 0:o.organisationalUnits,A=o.accountPlacements??[],w=A.length===0&&m!==void 0?ne(m,y):A;if(Object.keys(h).length===0)s.push("place-accounts"),e?.onPhaseStart?.("place-accounts"),e?.onPhaseComplete?.("place-accounts","skipped");else if(o.accountPlacements===void 0&&m===void 0){const i=new Error("Account placements not provided despite OUs being created. Caller must populate accountPlacements (flat-list mode cannot derive placements internally).");t.push({phase:"place-accounts",error:i.message}),e?.onPhaseStart?.("place-accounts"),e?.onError?.("place-accounts",i),e?.onPhaseComplete?.("place-accounts","error")}else if(w.length===0)s.push("place-accounts"),e?.onPhaseStart?.("place-accounts"),e?.onPhaseComplete?.("place-accounts","skipped");else{const i=m?Z(m,h):void 0;await p("place-accounts",()=>(e?.onProgress?.("Placing accounts in organisational units"),Y(u,h,w,i)),r,t,e)}const S=o.costAllocationTags??[];if(S.length>0?await p("activate-cost-tags",()=>(e?.onProgress?.("Activating cost allocation tags"),_(N,S.map(i=>({TagKey:i})))),r,t,e):(s.push("activate-cost-tags"),e?.onPhaseStart?.("activate-cost-tags"),e?.onPhaseComplete?.("activate-cost-tags","skipped")),o.skipIdentityCentre)s.push("check-identity-centre"),e?.onPhaseStart?.("check-identity-centre"),e?.onPhaseComplete?.("check-identity-centre","skipped");else{e?.onPhaseStart?.("check-identity-centre"),e?.onProgress?.("Checking Identity Centre status");const i=await b(T);i.success?(c=i.data.enabled?"enabled":"not-enabled",r.push("check-identity-centre"),e?.onPhaseComplete?.("check-identity-centre","completed")):(t.push({phase:"check-identity-centre",error:i.error.message}),e?.onError?.("check-identity-centre",i.error),e?.onPhaseComplete?.("check-identity-centre","error"))}const I=o.securityDelegateAccountId;return I?await p("register-security-delegates",()=>(e?.onProgress?.("Registering security service delegated administrators"),k(u,I)),r,t,e):(s.push("register-security-delegates"),e?.onPhaseStart?.("register-security-delegates"),e?.onPhaseComplete?.("register-security-delegates","skipped")),C({organisationId:M,createdAccounts:a,identityCentreStatus:c,phasesCompleted:r,phasesSkipped:s,errors:t})}async function p(n,o,e,r,s){s?.onPhaseStart?.(n);const t=await o();t.success?(e.push(n),s?.onPhaseComplete?.(n,"completed")):(r.push({phase:n,error:t.error.message}),s?.onError?.(n,t.error),s?.onPhaseComplete?.(n,"error"))}async function te(n,o,e,r){const s=await E(n);if(!s.success)return f(s.error);const t=new Set(s.data.map(c=>c.Name?.toLowerCase()).filter(c=>c!==void 0));for(const c of o){if(t.has(c.name.toLowerCase()))continue;r?.onProgress?.(`Account "${c.name}" is not yet a member of this AWS Organisation. Fjall will create a new account (with a new account ID). If "${c.name}" already exists as a standalone Fjall-connected account, abort now and import it into the organisation instead, because creating here produces a duplicate account. See the account-import runbook.`);const u=await V(n,c.name,c.email);if(!u.success)return f(u.error);e.push({name:u.data.accountName,accountId:u.data.accountId})}if(e.length===0)return C(s.data);const a=await E(n);return a.success?C(a.data):f(a.error)}function v(n){const o=[];for(const e of Object.values(n))ee(e)?o.push(...e):o.push(...v(e));return o}function ne(n,o){const e=v(n),r=new Map;for(const t of o){const a=t.Name?.toLowerCase();a&&t.Id&&r.set(a,t)}const s=[];for(const t of e){const a=r.get(t.toLowerCase());a?.Id&&a.Name&&s.push({id:a.Id,name:a.Name,environment:t})}return s}export{Ee as runOrganisationSetup};
+import{success as y,failure as h}from"@fjall/generator";import{OrganizationsClient as K}from"@aws-sdk/client-organizations";import{RAMClient as $}from"@aws-sdk/client-ram";import{CloudFormationClient as B}from"@aws-sdk/client-cloudformation";import{EC2Client as G}from"@aws-sdk/client-ec2";import{IAMClient as _}from"@aws-sdk/client-iam";import{BackupClient as z}from"@aws-sdk/client-backup";import{CostExplorerClient as H}from"@aws-sdk/client-cost-explorer";import{SSOAdminClient as q}from"@aws-sdk/client-sso-admin";import{ensureOrganisationExists as J}from"../aws/organisations/organisation.js";import{enablePolicyTypes as Q}from"../aws/organisations/policies.js";import{enableServiceAccess as V}from"../aws/organisations/serviceAccess.js";import{enableRamSharing as X}from"../aws/organisations/ram.js";import{activateTrustedAccess as Y}from"../aws/organisations/trustedAccess.js";import{enableIpamDelegatedAdmin as Z}from"../aws/organisations/ipam.js";import{updateBackupGlobalSettings as b}from"../aws/organisations/backup.js";import{listAccounts as w,createAccount as k}from"../aws/organisations/accounts.js";import{ensureOrganisationalUnitsExist as ee,placeAccountsInOUs as te,buildAccountToOUMap as ne}from"../aws/organisations/organisationalUnits.js";import{activateCostAllocationTags as oe}from"../aws/organisations/costAllocation.js";import{checkIdentityCentreStatus as re}from"../aws/organisations/identityCentre.js";import{registerSecurityDelegates as se}from"../aws/organisations/delegatedAdmin.js";import{enableCentralisedRootAccess as ae}from"../aws/organisations/rootAccess.js";import{selectImportedMemberAccounts as ie,formatImportedAccountsWarning as ce}from"../aws/organisations/importedAccounts.js";import{isOULeaf as ue}from"../aws/organisations/types.js";const Ke=["create-organisation","enable-policies","enable-service-access","enable-root-access","enable-ram-sharing","activate-trusted-access","enable-ipam","configure-backup","create-accounts","create-organisational-units","place-accounts","activate-cost-tags","check-identity-centre","register-security-delegates"];async function $e(t,n,e,a){const o=[],s=[],r=[],m=[];let i;const u=t.getClient(K),M=t.getClient(_),x=t.getClient($),N=t.getClient(B),L=t.getClient(G),W=t.getClient(z),F=t.getClient(H),j=t.getClient(q);e?.onPhaseStart?.("create-organisation"),e?.onProgress?.("Ensuring AWS Organisation exists");const l=await J(u);if(!l.success)return e?.onError?.("create-organisation",l.error),e?.onPhaseComplete?.("create-organisation","error"),h(l.error);const{orgId:D,rootId:I,managementAccountId:S}=l.data;if(e?.onPhaseComplete?.("create-organisation","completed"),o.push("create-organisation"),await p("enable-policies",()=>(e?.onProgress?.("Enabling organisation policy types"),Q(u,I,{abortSignal:a})),o,r,e),await p("enable-service-access",()=>(e?.onProgress?.("Enabling AWS service access"),V(u)),o,r,e),n.skipRootAccessManagement?d("enable-root-access",s,e):await p("enable-root-access",async()=>{e?.onProgress?.("Enabling centralised root access management");const c=await ae(M,a);return(c.success?c.data.enabled:c.error.partialSummary.enabled).length>0&&await me(u,S,e),c},o,r,e),await p("enable-ram-sharing",()=>(e?.onProgress?.("Enabling RAM sharing"),X(x)),o,r,e),await p("activate-trusted-access",()=>(e?.onProgress?.("Activating CloudFormation trusted access"),Y(N)),o,r,e),n.platformAccountId){const c=n.platformAccountId;await p("enable-ipam",()=>(e?.onProgress?.("Enabling IPAM delegated administrator"),Z(L,c)),o,r,e)}else d("enable-ipam",s,e);await p("configure-backup",()=>(e?.onProgress?.("Updating backup global settings"),b(W)),o,r,e),e?.onPhaseStart?.("create-accounts"),e?.onProgress?.("Checking for missing accounts");const P=await pe(u,n.accounts,m,e,a);let E=[];P.success?(E=P.data,o.push("create-accounts"),e?.onPhaseComplete?.("create-accounts","completed")):C("create-accounts",P.error,r,e);let f={};e?.onPhaseStart?.("create-organisational-units"),e?.onProgress?.("Ensuring organisational units exist");const A=await ee(u,I,n.organisationalUnits);A.success?(f=A.data,o.push("create-organisational-units"),e?.onPhaseComplete?.("create-organisational-units","completed")):C("create-organisational-units",A.error,r,e);const g=Array.isArray(n.organisationalUnits)?void 0:n.organisationalUnits,R=n.accountPlacements??[],O=R.length===0&&g!==void 0?de(g,E,S):R;if(Object.keys(f).length===0)d("place-accounts",s,e);else if(n.accountPlacements===void 0&&g===void 0){const c=new Error("Account placements not provided despite OUs being created. Caller must populate accountPlacements (flat-list mode cannot derive placements internally).");r.push({phase:"place-accounts",error:c.message}),e?.onPhaseStart?.("place-accounts"),e?.onError?.("place-accounts",c),e?.onPhaseComplete?.("place-accounts","error")}else if(O.length===0)d("place-accounts",s,e);else{const c=g?ne(g,f):void 0;await p("place-accounts",()=>(e?.onProgress?.("Placing accounts in organisational units"),te(u,f,O,c)),o,r,e)}const v=n.costAllocationTags??[];if(v.length>0?await p("activate-cost-tags",()=>(e?.onProgress?.("Activating cost allocation tags"),oe(F,v.map(c=>({TagKey:c})))),o,r,e):d("activate-cost-tags",s,e),n.skipIdentityCentre)d("check-identity-centre",s,e);else{e?.onPhaseStart?.("check-identity-centre"),e?.onProgress?.("Checking Identity Centre status");const c=await re(j);c.success?(i=c.data.enabled?"enabled":"not-enabled",o.push("check-identity-centre"),e?.onPhaseComplete?.("check-identity-centre","completed")):C("check-identity-centre",c.error,r,e)}const T=n.securityDelegateAccountId;return T?await p("register-security-delegates",()=>(e?.onProgress?.("Registering security service delegated administrators"),se(u,T)),o,r,e):d("register-security-delegates",s,e),y({organisationId:D,createdAccounts:m,identityCentreStatus:i,phasesCompleted:o,phasesSkipped:s,errors:r})}function C(t,n,e,a){e.push({phase:t,error:n.message}),a?.onError?.(t,n),a?.onPhaseComplete?.(t,"error")}function d(t,n,e){n.push(t),e?.onPhaseStart?.(t),e?.onPhaseComplete?.(t,"skipped")}async function me(t,n,e){const a=await w(t);if(!a.success){e?.onProgress?.(`Could not check for imported member accounts: ${a.error.message}`);return}const o=ie(a.data,n);if(o.length===0)return;const s=ce(o);e?.onWarning?e.onWarning("enable-root-access",s):e?.onProgress?.(s)}async function p(t,n,e,a,o){o?.onPhaseStart?.(t);const s=await n();s.success?(e.push(t),o?.onPhaseComplete?.(t,"completed")):C(t,s.error,a,o)}async function pe(t,n,e,a,o){const s=await w(t);if(!s.success)return h(s.error);const r=new Set(s.data.map(i=>i.Name?.toLowerCase()).filter(i=>i!==void 0));for(const i of n){if(r.has(i.name.toLowerCase()))continue;a?.onProgress?.(`Account "${i.name}" is not yet a member of this AWS Organisation. Fjall will create a new account (with a new account ID). If "${i.name}" already exists as a standalone Fjall-connected account, abort now and import it into the organisation instead, because creating here produces a duplicate account. See the account-import runbook.`);const u=await k(t,i.name,i.email,void 0,void 0,o);if(!u.success)return h(u.error);e.push({name:u.data.accountName,accountId:u.data.accountId})}if(e.length===0)return y(s.data);const m=await w(t);return m.success?y(m.data):h(m.error)}function U(t){const n=[];for(const[e,a]of Object.entries(t))if(ue(a))for(const o of a)n.push({accountName:o,placementKey:e});else n.push(...U(a));return n}function de(t,n,e){const a=U(t),o=new Map;for(const r of n){const m=r.Name?.toLowerCase();m&&r.Id&&o.set(m,r)}const s=[];for(const{accountName:r,placementKey:m}of a){const i=o.get(r.toLowerCase());!i?.Id||!i.Name||e!==void 0&&i.Id===e||s.push({id:i.Id,name:i.Name,environment:m})}return s}export{Ke as ORG_SETUP_PHASES,$e as runOrganisationSetup};

package/dist/src/orchestration/reconcileProviderAccounts.js

@@ -1 +1 @@
-import{z as m}from"zod";import{success as A,failure as c}from"@fjall/generator";import{environmentToTier as v,stageFromWireEnvironment as w}from"@fjall/util";import{OrganizationsClient as N}from"@aws-sdk/client-organizations";import{listAccounts as C}from"../aws/organisations/accounts.js";import{parseAccountsConfiguration as y,flattenAccountsToEnvironments as E}from"./accountsConfig.js";const T=m.object({Id:m.string().min(1),Name:m.string().min(1)});async function O(t,i){const e=await y(i);if(!e.success)return c(new Error(`Failed to parse ACCOUNTS configuration: ${e.error.message}`));if(e.data===null)return c(new Error("ACCOUNTS configuration file not found"));const r=E(e.data),u=new Map;for(const{accountName:o,environment:n}of r)u.set(o.toLowerCase(),{environment:n,displayName:o});let f;try{f=t.awsProvider.getClient(N)}catch(o){return c(o instanceof Error?o:new Error(String(o)))}const s=await C(f);if(!s.success)return c(s.error);const d=new Map;for(const o of s.data){const n=T.safeParse(o);n.success&&d.set(n.data.Name.toLowerCase(),{id:n.data.Id,name:n.data.Name})}const p=[],l=[];for(const[o,{environment:n,displayName:g}]of u){const a=d.get(o);if(!a){l.push(g);continue}v(n)!=="organisation"&&p.push({id:a.id,name:a.name,tier:v(n),environment:w(n)})}return A({providerAccounts:p,missingAccountNames:l})}function R(t,i){const e=new Map;for(const r of t?.providerAccounts??[])e.set(r.id,r);for(const r of i)e.has(r.id)||e.set(r.id,r);return{...t??{},providerAccounts:Array.from(e.values())}}export{R as mergeReconciledProviderAccounts,O as reconcileProviderAccounts};
+import{z as u}from"zod";import{success as T,failure as i}from"@fjall/generator";import{environmentToTier as v,stageFromWireEnvironment as y,normaliseError as g}from"@fjall/util";import{OrganizationsClient as E}from"@aws-sdk/client-organizations";import{listAccounts as P}from"../aws/organisations/accounts.js";import{parseAccountsConfiguration as S,flattenAccountsToEnvironments as h}from"./accountsConfig.js";const w=6e4,O=u.object({Id:u.string().min(1),Name:u.string().min(1)});async function b(s,c){let n;const r=new Promise((o,e)=>{n=setTimeout(()=>e(new Error(`Timed out parsing ACCOUNTS configuration after ${w}ms`)),w)});let t;try{t=await Promise.race([S(c),r])}catch(o){return i(g(o))}finally{n!==void 0&&clearTimeout(n)}if(!t.success)return i(new Error(`Failed to parse ACCOUNTS configuration: ${t.error.message}`));if(t.data===null)return i(new Error("ACCOUNTS configuration file not found"));const C=h(t.data),f=new Map;for(const{accountName:o,environment:e}of C)f.set(o.toLowerCase(),{environment:e,displayName:o});let d;try{d=s.awsProvider.getClient(E)}catch(o){return i(g(o))}const a=await P(d);if(!a.success)return i(a.error);const l=new Map;for(const o of a.data){const e=O.safeParse(o);e.success&&l.set(e.data.Name.toLowerCase(),{id:e.data.Id,name:e.data.Name})}const p=[],A=[];for(const[o,{environment:e,displayName:N}]of f){const m=l.get(o);if(!m){A.push(N);continue}v(e)!=="organisation"&&p.push({id:m.id,name:m.name,tier:v(e),environment:y(e)})}return T({providerAccounts:p,missingAccountNames:A})}function z(s,c){const n=new Map;for(const r of s?.providerAccounts??[])n.set(r.id,r);for(const r of c)n.has(r.id)||n.set(r.id,r);return{...s??{},providerAccounts:Array.from(n.values())}}export{z as mergeReconciledProviderAccounts,b as reconcileProviderAccounts};

package/dist/src/orchestration/stackCleanup/bucketOps.d.ts

@@ -0,0 +1,54 @@
+import { type S3Client } from "@aws-sdk/client-s3";
+import type { DeployCallbacks } from "../../types/callbacks.js";
+/**
+ * Tag keys that opt a stack bucket into SDK-side pre-emptying before CFN
+ * destroy. `aws-cdk:auto-delete-objects` covers stacks deployed while the S3
+ * wrapper still used the CDK custom resource — an external CDK contract, so
+ * it stays a literal here; `SDK_PRE_EMPTY_TAG_KEY` is the marker the Phase 3
+ * wrapper applies after autoDeleteObjects retirement (canonical source:
+ * @fjall/util/aws infraTags, shared with the producing S3 wrapper).
+ * A bucket carrying neither tag (Retain) is never touched — ListStackResources
+ * cannot read removal policy, so this predicate is the Retain-skip mechanism.
+ * A tag only counts when its value is "true", mirroring the CDK auto-delete
+ * handler's own check: flipping the value is the documented opt-out for
+ * preserving data, and this pass must never be looser than the handler.
+ */
+export declare const PRE_EMPTY_TAG_KEYS: readonly ["aws-cdk:auto-delete-objects", "fjall:sdk-pre-empty"];
+/**
+ * Error names meaning the bucket is already gone — convergence, not failure,
+ * for delete-side S3 calls. Shared with the trail-migration decommission
+ * (coupled values: a new gone-shape must be recognised by both sites).
+ */
+export declare const BUCKET_GONE_ERROR_NAMES: ReadonlySet<string>;
+/**
+ * Gone-class predicate for delete-side S3 calls: error name in
+ * BUCKET_GONE_ERROR_NAMES, with a message fallback because wrapped/unmodelled
+ * errors can carry the shape only in the message. NoSuchBucket is the one
+ * safe message probe — "NotFound"/"404" are too generic to match free text.
+ */
+export declare function isBucketGoneError(error: unknown): boolean;
+/**
+ * Outcome of an empty pass. "access-denied" is the quarantine signal
+ * `cleanupFailedStack` classifies; existing callers ignore the value and keep
+ * their warn-only behaviour.
+ */
+export type EmptyBucketOutcome = "emptied" | "missing" | "access-denied" | "failed";
+/**
+ * Empty an S3 bucket by deleting all object versions and delete markers.
+ * Handles NoSuchBucket gracefully (bucket already gone).
+ * Exported for the org-trail migration's member-bucket decommission.
+ */
+export declare function emptyS3Bucket(s3Client: S3Client, bucketName: string, callbacks?: DeployCallbacks, abortSignal?: AbortSignal): Promise<EmptyBucketOutcome>;
+export type PreEmptyVerdict = "matched" | "retained" | "gone" | "unreadable";
+/**
+ * Classify a bucket for a destroy-intent pass via GetBucketTagging.
+ * - "matched": carries a pre-empty tag — the bucket may be emptied/deleted.
+ * - "retained": untagged (NoSuchTagSet / no matching tag) — never touched.
+ * - "gone": NoSuchBucket — already deleted; excluded from the retained
+ *   report because nothing survives the destroy.
+ * - "unreadable": tags could not be read (throttle, denial) — never touched,
+ *   already warned here; callers decide how to account for it (the pre-empty
+ *   pass folds it into the conservative retained report, the orphan sweep
+ *   counts it as a failure).
+ */
+export declare function classifyBucketForPreEmpty(s3Client: S3Client, bucketName: string, callbacks?: DeployCallbacks, abortSignal?: AbortSignal): Promise<PreEmptyVerdict>;

package/dist/src/orchestration/stackCleanup/bucketOps.js

@@ -0,0 +1 @@
+import{ListObjectVersionsCommand as w,DeleteObjectsCommand as K,GetBucketTaggingCommand as x}from"@aws-sdk/client-s3";import{logger as f}from"@fjall/util/logger";import{getErrorMessage as y,maskSensitiveOutput as p}from"@fjall/util";import{SDK_PRE_EMPTY_TAG_KEY as C}from"@fjall/util/aws";import{composeSdkAbortSignal as B,extractErrorName as T,isAborted as b,isAccessDenied as D}from"../../aws/organisations/types.js";import{STACK_CLEANUP_LOG as E,warnViaCallbacks as g}from"./logging.js";const _=1e3,P=["aws-cdk:auto-delete-objects",C],V=new Set(["NoSuchBucket","NotFound","404"]);function $(t){return V.has(T(t))?!0:(t instanceof Error?t.message??"":"").includes("NoSuchBucket")}function A(t){const e=t instanceof Error?t.message??"":"";return D(T(t))||e.includes("AccessDenied")}async function L(t,e,i,u){let s,a,d=!1;i?.onStackCleanupProgress?.(e,"emptying-bucket");const r=1e3;let l=0;for(;l++<r;){if(b(u))return f.debug(E,`Aborted while emptying bucket ${e}`),"failed";let n;try{n=await t.send(new w({Bucket:e,KeyMarker:s,VersionIdMarker:a}),{abortSignal:B(u)})}catch(o){if($(o))return f.debug(E,`Bucket ${e} no longer exists, skipping`),"missing";const h=`Unexpected error emptying bucket ${e}: ${p(y(o))}`;return g(h,i),A(o)?"access-denied":"failed"}const S=[...n.Versions??[],...n.DeleteMarkers??[]];if(S.length===0)break;for(let o=0;o<S.length;o+=_){const h=S.slice(o,o+_);try{const c=(await t.send(new K({Bucket:e,Delete:{Objects:h.map(m=>({Key:m.Key,VersionId:m.VersionId})),Quiet:!0}}),{abortSignal:B(u)})).Errors??[];if(c.length>0){const m=`Failed to delete ${c.length} object(s) from ${e}: ${p(c[0]?.Message??c[0]?.Code??"unknown error")}`;if(g(m,i),c.some(M=>M.Code?.includes("AccessDenied")))return"access-denied";d=!0}}catch(k){const c=`Failed to delete batch from ${e}: ${p(y(k))}`;if(g(c,i),A(k))return"access-denied";d=!0}}if(!n.IsTruncated)break;s=n.NextKeyMarker,a=n.NextVersionIdMarker}if(l>r){const n=`Bucket ${e} reached ${r} page limit \u2014 some objects may remain`;return g(n,i),"failed"}return f.debug(E,`Emptied bucket ${e}`),d?"failed":"emptied"}async function Y(t,e,i,u){try{const s=await t.send(new x({Bucket:e}),{abortSignal:B(u)}),a=P;return(s.TagSet??[]).some(r=>r.Key!==void 0&&a.includes(r.Key)&&r.Value==="true")?"matched":"retained"}catch(s){const a=T(s),d=s instanceof Error?s.message??"":"",r=$(s),l=a==="NoSuchTagSet"||d.includes("NoSuchTagSet");if(r||l)return f.debug(E,`Bucket ${e} ${r?"no longer exists":"has no tags"} \u2014 skipping`),r?"gone":"retained";const n=`Could not read tags for bucket ${e}, leaving it untouched: ${p(y(s))}`;return g(n,i),"unreadable"}}export{V as BUCKET_GONE_ERROR_NAMES,P as PRE_EMPTY_TAG_KEYS,Y as classifyBucketForPreEmpty,L as emptyS3Bucket,$ as isBucketGoneError};

package/dist/src/orchestration/stackCleanup/failedStack.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cleanup for CloudFormation stacks stuck in failed states.
+ *
+ * Only operates on stacks that never successfully deployed:
+ * - ROLLBACK_FAILED -- creation failed, rollback failed
+ * - ROLLBACK_COMPLETE -- creation failed, rollback succeeded
+ * - DELETE_FAILED -- deletion already started
+ *
+ * Never touches UPDATE_ROLLBACK_FAILED (has live resources from previous deploy).
+ */
+import type { DeployCallbacks } from "../../types/callbacks.js";
+interface StackCleanupCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/**
+ * Clean up a CloudFormation stack stuck in a failed state.
+ * Best-effort: all errors are caught and logged, never throws.
+ *
+ * Flow:
+ * 1. Check stack status -- skip if not in SAFE_CLEANUP_STATES
+ * 2. Find and empty S3 buckets blocking deletion
+ * 3. Delete the stack
+ * 4. Poll for DELETE_COMPLETE (5min timeout, 5s interval)
+ * 5. If DELETE_FAILED again, retry once with RetainResources for non-S3 failures
+ */
+export declare function cleanupFailedStack(stackName: string, region: string, credentials: StackCleanupCredentials, options?: {
+    timeoutMs?: number;
+    pollMs?: number;
+    accountId?: string;
+    abortSignal?: AbortSignal;
+}, callbacks?: DeployCallbacks): Promise<void>;
+export {};

package/dist/src/orchestration/stackCleanup/failedStack.js

@@ -0,0 +1 @@
+import{CloudFormationClient as A,DescribeStacksCommand as m,DeleteStackCommand as C}from"@aws-sdk/client-cloudformation";import{S3Client as P}from"@aws-sdk/client-s3";import{NodeHttpHandler as D}from"@smithy/node-http-handler";import{logger as u}from"@fjall/util/logger";import{getErrorMessage as f,maskSensitiveOutput as p,sleep as R}from"@fjall/util";import{composeSdkAbortSignal as w,isAborted as _}from"../../aws/organisations/types.js";import{STACK_NOT_FOUND_PATTERN as g,isCleanableState as F}from"../../types/constants.js";import{emptyS3Bucket as I}from"./bucketOps.js";import{STACK_CLEANUP_LOG as s,warnViaCallbacks as M}from"./logging.js";import{formatQuarantineSuspectedMessage as k}from"./messages.js";import{collectStackResources as y}from"./stackResources.js";async function O(e,t,a){return y(e,t,r=>r.ResourceType==="AWS::S3::Bucket"&&r.ResourceStatus==="DELETE_FAILED",r=>r.PhysicalResourceId,a)}function h(e,t){return t===void 0?R(e):t.aborted?Promise.resolve():new Promise(a=>{const r=()=>{clearTimeout(n),a()},n=setTimeout(()=>{t.removeEventListener("abort",r),a()},e);t.addEventListener("abort",r,{once:!0})})}async function J(e,t,a,r,n){const S=r?.timeoutMs??3e5,E=r?.pollMs??5e3,o=r?.abortSignal;try{const c=new A({region:t,credentials:a,requestHandler:new D({requestTimeout:15e3})});let d;try{d=(await c.send(new m({StackName:e}),{abortSignal:w(o)})).Stacks?.[0]?.StackStatus}catch(i){if(i instanceof Error&&i.message?.includes(g)){u.debug(s,`Stack ${e} does not exist, no cleanup needed`);return}u.warn(s,`Failed to check stack status: ${p(f(i))}`,{stackName:e,region:t});return}if(!d||!F(d)){u.debug(s,`Stack ${e} status ${d??"unknown"} is not cleanable, skipping`);return}u.warn(s,`Cleaning up ${e} stack in ${d} state`,{region:t}),n?.onStackCleanupProgress?.(e,"deleting-stack");const b=new P({region:t,credentials:a,requestHandler:new D({requestTimeout:15e3})});try{const i=await O(c,e,o);for(const l of i){if(_(o))break;if(u.warn(s,`Emptying bucket ${l}`,{region:t}),await I(b,l,n,o)==="access-denied"){const L={bucketName:l,...r?.accountId!==void 0?{accountId:r.accountId}:{}};u.warn(s,k(e,L),{region:t}),n?.onStackCleanupProgress?.(e,"quarantine-suspected",L)}}}catch(i){const l=`Failed to empty S3 buckets: ${p(f(i))}`;M(l,n,{stackName:e,region:t})}await c.send(new C({StackName:e}),{abortSignal:w(o)}),n?.onStackCleanupProgress?.(e,"waiting");const T=await $(c,e,S,E,o);if(T==="DELETE_COMPLETE"){u.warn(s,`${e} stack deleted successfully`,{region:t}),n?.onStackCleanupProgress?.(e,"complete");return}if(T==="DELETE_FAILED"){u.warn(s,`${e} still in DELETE_FAILED, retrying with RetainResources`,{region:t});const i=await B(c,e,o);if(i.length===0)u.warn(s,`${e} in DELETE_FAILED but no non-bucket resources to retain \u2014 cannot retry`,{region:t}),n?.onStackCleanupProgress?.(e,"error");else{await c.send(new C({StackName:e,RetainResources:i}),{abortSignal:w(o)});const l=await $(c,e,S,E,o);l==="DELETE_COMPLETE"?(u.warn(s,`${e} stack deleted on retry (retained: ${i.join(", ")})`,{region:t}),n?.onStackCleanupProgress?.(e,"complete")):(u.warn(s,`${e} stack still not deleted after retry: ${l}`,{region:t}),n?.onStackCleanupProgress?.(e,"error"))}}}catch(c){u.warn(s,`Stack cleanup failed: ${p(f(c))}`,{stackName:e,region:t}),n?.onStackCleanupProgress?.(e,"error")}}async function $(e,t,a,r,n){const S=Date.now();for(;Date.now()-S<a;){if(await h(r,n),_(n))return"ABORTED";try{const o=(await e.send(new m({StackName:t}),{abortSignal:w(n)})).Stacks?.[0]?.StackStatus;if(!o||o==="DELETE_COMPLETE")return"DELETE_COMPLETE";if(o==="DELETE_FAILED")return"DELETE_FAILED";u.debug(s,`Waiting for ${t}: ${o}`)}catch(E){if(E instanceof Error&&E.message?.includes(g))return"DELETE_COMPLETE";throw u.debug(s,`Unexpected error polling ${t}: ${p(f(E))}`),E}}return"TIMEOUT"}async function B(e,t,a){return y(e,t,r=>r.ResourceStatus==="DELETE_FAILED"&&r.ResourceType!=="AWS::S3::Bucket",r=>r.LogicalResourceId,a)}export{J as cleanupFailedStack};

package/dist/src/orchestration/stackCleanup/logging.d.ts

@@ -0,0 +1,9 @@
+import type { DeployCallbacks } from "../../types/callbacks.js";
+/** Logger category shared by every stackCleanup sub-module. */
+export declare const STACK_CLEANUP_LOG = "stackCleanup";
+/**
+ * Dual-sink warn: the file-persisted logger plus the caller's onLog callback.
+ * Callers mask error-derived content before calling — messages pass through
+ * unmodified.
+ */
+export declare function warnViaCallbacks(message: string, callbacks: DeployCallbacks | undefined, meta?: Record<string, unknown>): void;

package/dist/src/orchestration/stackCleanup/logging.js

@@ -0,0 +1 @@
+import{logger as a}from"@fjall/util/logger";const t="stackCleanup";function l(o,n,r){a.warn(t,o,r),n?.onLog?.(o,"warn")}export{t as STACK_CLEANUP_LOG,l as warnViaCallbacks};

package/dist/src/orchestration/stackCleanup/messages.d.ts

@@ -0,0 +1,16 @@
+import type { StackCleanupQuarantineDetail } from "../../types/callbacks.js";
+/**
+ * Render the quarantine-suspected remediation copy. Shared by the CLI
+ * adapters (and the webapp worker adapter) so consumers do not fork the
+ * wording.
+ */
+export declare function formatQuarantineSuspectedMessage(stackName: string, detail?: StackCleanupQuarantineDetail): string;
+/**
+ * Render the retained-bucket report (AC3.5). The copy travels pre-formatted
+ * inside StackCleanupRetainedBucketsDetail.message so adapters render it
+ * verbatim without importing this function — the single travelling string
+ * keeps the remediation wording from forking across consumers.
+ * Bucket and stack names are resource identifiers, not credential values, so
+ * the message needs no masking.
+ */
+export declare function formatRetainedBucketsMessage(stackName: string, retainedBuckets: readonly string[]): string;

package/dist/src/orchestration/stackCleanup/messages.js

@@ -0,0 +1 @@
+function u(n,e){const t=e?.bucketName??"unknown bucket",o=e?.accountId!==void 0?` (account ${e.accountId})`:"",c=e?.bucketName!==void 0&&e?.accountId!==void 0?` \u2014 run \`fjall unlock bucket ${e.bucketName} --account ${e.accountId} --acknowledge-root-session\` to remove it`:" \u2014 a root session is required to remove it (fjall unlock bucket)";return`Bucket ${t} in stack ${n}${o} appears quarantined by a stranded deny policy${c}`}function a(n,e){return`Stack ${n}: bucket(s) retained, not deleted: ${e.join(", ")} \u2014 production buckets survive destroy by design (RemovalPolicy.RETAIN). Delete deliberately when the data is no longer needed, or redeploy with an explicit DESTROY removal policy before destroying.`}export{u as formatQuarantineSuspectedMessage,a as formatRetainedBucketsMessage};

package/dist/src/orchestration/stackCleanup/orphanSweep.d.ts

@@ -0,0 +1,25 @@
+import { type S3Client } from "@aws-sdk/client-s3";
+import type { DeployCallbacks } from "../../types/callbacks.js";
+export interface OrphanSweepSummary {
+    /** Marked buckets that survived the CFN destroy and were emptied + deleted SDK-side. */
+    swept: string[];
+    /** Marked buckets that still exist but could not be removed — warned, never fails the destroy. */
+    failed: string[];
+}
+/**
+ * Convergent post-CFN orphan sweep (AC3.3). After CFN reports the stack gone,
+ * any bucket captured pre-destroy that still exists AND still carries a
+ * DESTROY-intent marker is emptied and deleted SDK-side, so re-running an
+ * interrupted destroy converges instead of stranding marked buckets.
+ *
+ * Convergence is bounded by capture-before-destroy: the captured list dies
+ * with the process, so a crash after CFN reports the stack gone but before
+ * this sweep completes leaves survivors a re-run cannot see — the deleted
+ * stack no longer lists its resources, and the re-run captures nothing.
+ *
+ * The tag re-probe is the name-reuse guard: a bucket recreated by another
+ * owner after CFN deleted the original classifies "retained" and is never
+ * touched. Already-gone buckets are convergence, not failures. The sweep
+ * never fails the destroy — per-bucket problems warn and continue.
+ */
+export declare function sweepOrphanedDestroyBuckets(s3Client: S3Client, bucketNames: readonly string[], callbacks?: DeployCallbacks, abortSignal?: AbortSignal): Promise<OrphanSweepSummary>;

package/dist/src/orchestration/stackCleanup/orphanSweep.js

@@ -0,0 +1 @@
+import{DeleteBucketCommand as p}from"@aws-sdk/client-s3";import{logger as a}from"@fjall/util/logger";import{getErrorMessage as d,maskSensitiveOutput as k}from"@fjall/util";import{composeSdkAbortSignal as h,isAborted as w}from"../../aws/organisations/types.js";import{classifyBucketForPreEmpty as y,emptyS3Bucket as g,isBucketGoneError as l}from"./bucketOps.js";import{STACK_CLEANUP_LOG as B,warnViaCallbacks as b}from"./logging.js";async function $(i,m,o,r){const t={swept:[],failed:[]};for(const e of m){if(w(r))break;const n=await y(i,e,o,r);if(n==="unreadable"){t.failed.push(e);continue}if(n!=="matched")continue;const s=await g(i,e,o,r);if(s==="missing")continue;if(s!=="emptied"){t.failed.push(e);continue}try{await i.send(new p({Bucket:e}),{abortSignal:h(r)})}catch(u){if(l(u))continue;const f=`Could not delete orphaned bucket ${e} after stack delete: ${k(d(u))}`;b(f,o),t.failed.push(e);continue}t.swept.push(e);const c=`Swept orphaned bucket ${e} left behind by the stack delete`;a.info(B,c),o?.onLog?.(c,"info")}return t}export{$ as sweepOrphanedDestroyBuckets};

package/dist/src/orchestration/stackCleanup/preEmpty.d.ts

@@ -0,0 +1,35 @@
+import type { CloudFormationClient } from "@aws-sdk/client-cloudformation";
+import type { S3Client } from "@aws-sdk/client-s3";
+import { type Result } from "@fjall/generator";
+import type { DeployCallbacks } from "../../types/callbacks.js";
+export interface PreEmptyBucketsSummary {
+    /** Buckets carrying a pre-empty tag; the empty pass ran over them (warn-only inside). */
+    matched: string[];
+    /**
+     * Buckets evaluated and left untouched (no pre-empty tag, or tags
+     * unreadable). Already-deleted buckets appear in neither list — nothing
+     * survives the destroy, so reporting them as retained would mislead.
+     */
+    skipped: string[];
+}
+/**
+ * SDK-empty a live stack's pre-empty-tagged S3 buckets before CFN destroy, so
+ * the auto-delete custom resource (where present) is a fast no-op and never
+ * hits its Lambda timeout — the S3 quarantine trigger.
+ *
+ * Per-bucket failures (throttle, AccessDenied, anything) warn via callback and
+ * continue; they never produce a Result failure. Failure is reserved for
+ * "could not even list stack resources" — callers proceed to destroy on
+ * failure too, degrading to today's behaviour.
+ */
+export declare function preEmptyStackBuckets(cfnClient: CloudFormationClient, s3Client: S3Client, stackName: string, callbacks?: DeployCallbacks, abortSignal?: AbortSignal): Promise<Result<PreEmptyBucketsSummary>>;
+/**
+ * Extract the marker-tagged buckets a pre-empty pass captured, or [] when the
+ * pass failed (the failure already warned via callbacks; destroy proceeds
+ * regardless).
+ *
+ * Call BEFORE the destroy — once CFN reports the stack gone the resource list
+ * is unreadable, so the captured list is the only record of which marked
+ * buckets the orphan sweep (AC3.3) may touch.
+ */
+export declare function capturedSweepBuckets(preEmptyResult: Result<PreEmptyBucketsSummary>): readonly string[];