@fjall/deploy-core 0.89.5 → 0.89.6

package/LICENSE

@@ -1,21 +1,50 @@
-MIT License
-
-Copyright (c) 2026 Fjall
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Fjall Proprietary Software Licence
+
+Copyright (c) 2026 Fjall. All rights reserved.
+
+This software, including all source, object, bundled, and minified forms
+("the Software"), is the proprietary and confidential property of Fjall.
+
+1. Permitted Use. Subject to the terms of this Licence, Fjall grants you
+   a non-exclusive, non-transferable, revocable licence to install the
+   Software via the npm registry and to execute it solely for the purpose
+   of deploying, operating, and managing your own applications and
+   infrastructure on cloud providers.
+
+2. Restrictions. You may NOT, and may not permit any third party to:
+   (a) copy, redistribute, sublicense, sell, rent, lease, or otherwise
+       transfer the Software;
+   (b) modify, adapt, translate, or create derivative works of the Software;
+   (c) reverse engineer, decompile, disassemble, deminify, or otherwise
+       attempt to derive the source code, structure, or organisation of
+       the Software, except to the minimum extent expressly permitted by
+       applicable mandatory law;
+   (d) use the Software, or any portion of it, to develop, train, or
+       improve any product or service that competes with Fjall;
+   (e) remove, alter, or obscure any proprietary notices contained in
+       the Software;
+   (f) publish, share, or otherwise disclose the Software or its contents
+       to any third party.
+
+3. Ownership. All right, title, and interest in and to the Software,
+   including all intellectual property rights, remain with Fjall. No
+   rights are granted except as expressly set out in this Licence.
+
+4. Termination. This Licence terminates automatically if you breach any
+   of its terms. Upon termination you must cease all use of the Software
+   and destroy all copies in your possession.
+
+5. Disclaimer of Warranty. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT
+   WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION
+   THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+   AND NON-INFRINGEMENT.
+
+6. Limitation of Liability. IN NO EVENT SHALL FJALL BE LIABLE FOR ANY
+   INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES
+   ARISING OUT OF OR RELATED TO THE SOFTWARE, EVEN IF ADVISED OF THE
+   POSSIBILITY OF SUCH DAMAGES.
+
+7. Governing Law. This Licence is governed by the laws of England and
+   Wales, without regard to conflict of laws principles.
+
+For commercial licensing enquiries, contact: contact@fjall.io

package/README.md

@@ -0,0 +1,25 @@
+# @fjall/deploy-core
+
+Shared deployment engine for Fjall. Used by both `@fjall/cli` and the Fjall webapp deployment worker to provide a single source of truth for build, synth, and deploy orchestration across CDK stacks.
+
+Provides `AwsProvider`, `FrameworkBuilder`, `StepRegistry`, and the `DeployCallbacks` contract. Pure orchestration — environment-agnostic and free of UI concerns.
+
+## Installation
+
+```bash
+npm install @fjall/deploy-core
+```
+
+## Subpath exports
+
+```typescript
+import { AwsProvider } from "@fjall/deploy-core/aws";
+import { FrameworkBuilder } from "@fjall/deploy-core/builders";
+import { StepRegistry } from "@fjall/deploy-core/steps";
+```
+
+See [docs.fjall.io](https://docs.fjall.io) for full usage.
+
+## Licence
+
+Proprietary — see [LICENSE](./LICENSE).

package/dist/.minified

@@ -0,0 +1 @@
+114 files minified at 2026-04-20T23:47:40.999Z

package/dist/src/__test-utils__/awsMockHelpers.d.ts

@@ -0,0 +1,20 @@
+import { vi } from "vitest";
+/**
+ * Create an AWS error with the correct name property for SDK v3 error matching.
+ * AWS SDK v3 checks error.name for typed error handling (e.g. "AccountAlreadyRegisteredException").
+ * Object.defineProperty is required because Error.name is non-writable by default.
+ */
+export declare function createAwsError(name: string, message: string): Error;
+/**
+ * Create a mock AWS SDK v3 client with a spied `send` method.
+ * The returned object is typed as the specified client type for test convenience.
+ *
+ * Usage:
+ * ```ts
+ * const mockClient = createMockAwsClient<OrganizationsClient>();
+ * vi.mocked(mockClient.send).mockResolvedValue({ ... });
+ * ```
+ */
+export declare function createMockAwsClient<T>(): T & {
+    send: ReturnType<typeof vi.fn>;
+};

package/dist/src/__test-utils__/awsMockHelpers.js

@@ -0,0 +1 @@
+import{vi as n}from"vitest";function c(e,t){const r=new Error(t);return Object.defineProperty(r,"name",{value:e,writable:!0}),r}function i(){return{send:n.fn()}}export{c as createAwsError,i as createMockAwsClient};

package/dist/src/__test-utils__/index.d.ts

@@ -0,0 +1 @@
+export { createAwsError, createMockAwsClient } from "./awsMockHelpers.js";

package/dist/src/__test-utils__/index.js

@@ -0,0 +1 @@
+import{createAwsError as o,createMockAwsClient as t}from"./awsMockHelpers.js";export{o as createAwsError,t as createMockAwsClient};

package/dist/src/aws/AwsProvider.js

@@ -1 +0,0 @@
-export {};

package/dist/src/aws/SimpleAwsProvider.js

@@ -1,70 +1 @@
-import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts";
-/**
- * Minimal AWS provider for pre-assumed credentials.
- *
- * Used by the webapp worker, which assumes an OIDC role before
- * calling deploy-core. No SSO, no credential discovery, no caching.
- */
-export class SimpleAwsProvider {
-    credentials;
-    region;
-    accountId;
-    clientCache = new Map();
-    constructor(awsCredentials) {
-        this.credentials = {
-            accessKeyId: awsCredentials.accessKeyId,
-            secretAccessKey: awsCredentials.secretAccessKey,
-            sessionToken: awsCredentials.sessionToken
-        };
-        this.region = awsCredentials.region;
-        this.accountId = awsCredentials.accountId;
-    }
-    getClient(ClientClass) {
-        const key = ClientClass.name;
-        const cached = this.clientCache.get(key);
-        if (cached !== undefined)
-            return cached;
-        const client = new ClientClass({
-            region: this.region,
-            credentials: this.credentials
-        });
-        this.clientCache.set(key, client);
-        return client;
-    }
-    getRegion() {
-        return this.region;
-    }
-    getAccountId() {
-        return this.accountId;
-    }
-    getCredentials() {
-        return this.credentials;
-    }
-    exportToEnv() {
-        process.env.AWS_ACCESS_KEY_ID = this.credentials.accessKeyId;
-        process.env.AWS_SECRET_ACCESS_KEY = this.credentials.secretAccessKey;
-        process.env.AWS_REGION = this.region;
-        if (this.credentials.sessionToken) {
-            process.env.AWS_SESSION_TOKEN = this.credentials.sessionToken;
-        }
-    }
-    async assumeRole(roleArn, sessionName) {
-        const stsClient = new STSClient({
-            region: this.region,
-            credentials: this.credentials
-        });
-        const response = await stsClient.send(new AssumeRoleCommand({
-            RoleArn: roleArn,
-            RoleSessionName: sessionName
-        }), { abortSignal: AbortSignal.timeout(30_000) });
-        const assumed = response.Credentials;
-        if (!assumed?.AccessKeyId || !assumed?.SecretAccessKey) {
-            throw new Error(`AssumeRole for ${roleArn} returned incomplete credentials`);
-        }
-        return {
-            accessKeyId: assumed.AccessKeyId,
-            secretAccessKey: assumed.SecretAccessKey,
-            sessionToken: assumed.SessionToken
-        };
-    }
-}
+import{STSClient as i,AssumeRoleCommand as r}from"@aws-sdk/client-sts";import{NodeHttpHandler as d}from"@smithy/node-http-handler";const o=3e4;class u{credentials;region;accountId;clientCache=new Map;constructor(e){this.credentials={accessKeyId:e.accessKeyId,secretAccessKey:e.secretAccessKey,sessionToken:e.sessionToken},this.region=e.region,this.accountId=e.accountId}getClient(e){const t=e.name,n=this.clientCache.get(t);if(n!==void 0)return n;const c={region:this.region,credentials:this.credentials,requestHandler:new d({requestTimeout:o})},s=new e(c);return this.clientCache.set(t,s),s}getRegion(){return this.region}getAccountId(){return this.accountId}getCredentials(){return this.credentials}exportToEnv(){process.env.AWS_ACCESS_KEY_ID=this.credentials.accessKeyId,process.env.AWS_SECRET_ACCESS_KEY=this.credentials.secretAccessKey,process.env.AWS_REGION=this.region,this.credentials.sessionToken?process.env.AWS_SESSION_TOKEN=this.credentials.sessionToken:delete process.env.AWS_SESSION_TOKEN}async assumeRole(e,t){const s=(await this.getClient(i).send(new r({RoleArn:e,RoleSessionName:t}),{abortSignal:AbortSignal.timeout(o)})).Credentials;if(!s?.AccessKeyId||!s?.SecretAccessKey)throw new Error(`AssumeRole for ${e} returned incomplete credentials`);return{accessKeyId:s.AccessKeyId,secretAccessKey:s.SecretAccessKey,sessionToken:s.SessionToken}}}export{u as SimpleAwsProvider};

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

@@ -1,4 +1,6 @@
 export type { AwsProvider, AwsProviderCredentials, AwsSdkClientConstructor } from "./AwsProvider.js";
 export { SimpleAwsProvider } from "./SimpleAwsProvider.js";
-export { ensureOrganisationExists, describeOrganisation, enablePolicyTypes, enableServiceAccess, enableRamSharing, activateTrustedAccess, enableIpamDelegatedAdmin, updateBackupGlobalSettings, listAccounts, findAccount, createAccount, ensureOrganisationalUnitsExist, placeAccountsInOUs, activateCostAllocationTags, checkIdentityCentreStatus } from "./organisations/index.js";
-export type { OrgDetails, OUMap, AccountPlacementResult, AccountInfo, IdentityCentreStatus, BackupGlobalSettings, CostAllocationTag, CreateAccountResult } from "./organisations/index.js";
+export { ensureOrganisationExists, describeOrganisation, enablePolicyTypes, enableServiceAccess, enableRamSharing, activateTrustedAccess, enableIpamDelegatedAdmin, updateBackupGlobalSettings, listAccounts, findAccount, createAccount, ensureOrganisationalUnitsExist, placeAccountsInOUs, buildAccountToOUMap, activateCostAllocationTags, checkIdentityCentreStatus, extractErrorName, isOULeaf, registerSecurityDelegates, SECURITY_SERVICE_PRINCIPALS } from "./organisations/index.js";
+export type { OrgDetails, OUMap, OUTree, AccountPlacementResult, AccountInfo, IdentityCentreStatus, BackupGlobalSettings, CostAllocationTag, CreateAccountResult } from "./organisations/index.js";
+export { CloudFormationEventMonitor } from "./utils/cloudformationEvents.js";
+export type { AwsClientLike, EventLogWriter, EventFailureAnalyser, EventLogWriterFactory, EventMonitorDeps } from "./utils/cloudformationEvents.js";

package/dist/src/aws/index.js

@@ -1,3 +1 @@
-export { SimpleAwsProvider } from "./SimpleAwsProvider.js";
-// Organisation setup primitives
-export { ensureOrganisationExists, describeOrganisation, enablePolicyTypes, enableServiceAccess, enableRamSharing, activateTrustedAccess, enableIpamDelegatedAdmin, updateBackupGlobalSettings, listAccounts, findAccount, createAccount, ensureOrganisationalUnitsExist, placeAccountsInOUs, activateCostAllocationTags, checkIdentityCentreStatus } from "./organisations/index.js";
+import{SimpleAwsProvider as a}from"./SimpleAwsProvider.js";import{ensureOrganisationExists as n,describeOrganisation as r,enablePolicyTypes as s,enableServiceAccess as c,enableRamSharing as o,activateTrustedAccess as l,enableIpamDelegatedAdmin as u,updateBackupGlobalSettings as A,listAccounts as d,findAccount as p,createAccount as g,ensureOrganisationalUnitsExist as m,placeAccountsInOUs as S,buildAccountToOUMap as b,activateCostAllocationTags as E,checkIdentityCentreStatus as I,extractErrorName as x,isOULeaf as C,registerSecurityDelegates as O,SECURITY_SERVICE_PRINCIPALS as f}from"./organisations/index.js";import{CloudFormationEventMonitor as T}from"./utils/cloudformationEvents.js";export{T as CloudFormationEventMonitor,f as SECURITY_SERVICE_PRINCIPALS,a as SimpleAwsProvider,E as activateCostAllocationTags,l as activateTrustedAccess,b as buildAccountToOUMap,I as checkIdentityCentreStatus,g as createAccount,r as describeOrganisation,u as enableIpamDelegatedAdmin,s as enablePolicyTypes,o as enableRamSharing,c as enableServiceAccess,n as ensureOrganisationExists,m as ensureOrganisationalUnitsExist,x as extractErrorName,p as findAccount,C as isOULeaf,d as listAccounts,S as placeAccountsInOUs,O as registerSecurityDelegates,A as updateBackupGlobalSettings};

package/dist/src/aws/organisations/accounts.js

@@ -1,20 +1,20 @@
 import { ListAccountsCommand, CreateAccountCommand, CreateAccountState, DescribeCreateAccountStatusCommand } from "@aws-sdk/client-organizations";
 import { success, failure } from "@fjall/generator";
-import { sleep } from "../../util/sleep.js";
-import { extractErrorName } from "./types.js";
+import { sleep, getErrorMessage } from "@fjall/util";
+import { extractErrorName, SDK_TIMEOUT_MS, AWS_ERROR_NAMES } from "./types.js";
 /**
  * List all accounts in the organisation, handling pagination.
  */
 export async function listAccounts(client) {
     try {
-        const response = await client.send(new ListAccountsCommand({ MaxResults: 20 }));
+        const response = await client.send(new ListAccountsCommand({ MaxResults: 20 }), { abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS) });
         let accounts = response.Accounts ?? [];
         let nextToken = response.NextToken;
         while (nextToken) {
             const nextResponse = await client.send(new ListAccountsCommand({
                 MaxResults: 20,
                 NextToken: nextToken
-            }));
+            }), { abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS) });
             accounts = accounts.concat(nextResponse.Accounts ?? []);
             nextToken = nextResponse.NextToken;
         }
@@ -22,10 +22,10 @@ export async function listAccounts(client) {
     }
     catch (error) {
         const errorName = extractErrorName(error);
-        if (errorName === "AWSOrganizationsNotInUseException") {
+        if (errorName === AWS_ERROR_NAMES.ORGS_NOT_IN_USE) {
             return failure(new Error("AWS Organisations is not enabled for this account"));
         }
-        return failure(new Error(`Failed to list accounts: ${error instanceof Error ? error.message : String(error)}`));
+        return failure(new Error(`Failed to list accounts: ${getErrorMessage(error)}`));
     }
 }
 /**
@@ -51,11 +51,11 @@ export async function createAccount(client, accountName, email, maxAttempts = 18
             response = await client.send(new CreateAccountCommand({
                 AccountName: accountName,
                 Email: email
-            }));
+            }), { abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS) });
         }
         catch (error) {
             const errorName = extractErrorName(error);
-            if (errorName === "AccessDeniedException") {
+            if (errorName === AWS_ERROR_NAMES.ACCESS_DENIED) {
                 return failure(new Error(`Access denied when creating account "${accountName}". ` +
                     "Ensure your credentials have organizations:CreateAccount permission."));
             }
@@ -74,7 +74,7 @@ export async function createAccount(client, accountName, email, maxAttempts = 18
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
             const statusResponse = await client.send(new DescribeCreateAccountStatusCommand({
                 CreateAccountRequestId: requestId
-            }));
+            }), { abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS) });
             const status = statusResponse.CreateAccountStatus;
             if (!status) {
                 return failure(new Error(`No status returned for CreateAccount request ${requestId}`));
@@ -94,6 +94,6 @@ export async function createAccount(client, accountName, email, maxAttempts = 18
         return failure(new Error(`Account creation for "${accountName}" timed out after ${(maxAttempts * delayMs) / 1000} seconds`));
     }
     catch (error) {
-        return failure(new Error(`Failed to create account "${accountName}": ${error instanceof Error ? error.message : String(error)}`));
+        return failure(new Error(`Failed to create account "${accountName}": ${getErrorMessage(error)}`));
     }
 }

package/dist/src/aws/organisations/backup.js

@@ -1,5 +1,7 @@
 import { UpdateGlobalSettingsCommand } from "@aws-sdk/client-backup";
 import { success, failure } from "@fjall/generator";
+import { getErrorMessage } from "@fjall/util";
+import { SDK_TIMEOUT_MS } from "./types.js";
 const DEFAULT_BACKUP_SETTINGS = {
     enableCrossAccountBackup: true,
     enableDelegatedAdministrator: true,
@@ -19,10 +21,10 @@ export async function updateBackupGlobalSettings(client, settings) {
         };
         await client.send(new UpdateGlobalSettingsCommand({
             GlobalSettings: globalSettings
-        }));
+        }), { abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS) });
         return success(undefined);
     }
     catch (error) {
-        return failure(new Error(`Failed to update backup global settings: ${error instanceof Error ? error.message : String(error)}`));
+        return failure(new Error(`Failed to update backup global settings: ${getErrorMessage(error)}`));
     }
 }

package/dist/src/aws/organisations/costAllocation.js

@@ -1,5 +1,7 @@
 import { UpdateCostAllocationTagsStatusCommand } from "@aws-sdk/client-cost-explorer";
 import { success, failure } from "@fjall/generator";
+import { getErrorMessage } from "@fjall/util";
+import { SDK_TIMEOUT_MS } from "./types.js";
 /**
  * Activate cost allocation tags for billing tracking.
  * Idempotent — activating already-active tags is a no-op.
@@ -17,10 +19,10 @@ export async function activateCostAllocationTags(client, tags) {
         }));
         await client.send(new UpdateCostAllocationTagsStatusCommand({
             CostAllocationTagsStatus: costAllocationTagsStatus
-        }));
+        }), { abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS) });
         return success(undefined);
     }
     catch (error) {
-        return failure(new Error(`Failed to activate cost allocation tags: ${error instanceof Error ? error.message : String(error)}`));
+        return failure(new Error(`Failed to activate cost allocation tags: ${getErrorMessage(error)}`));
     }
 }

package/dist/src/aws/organisations/delegatedAdmin.d.ts

@@ -0,0 +1,9 @@
+import { type OrganizationsClient } from "@aws-sdk/client-organizations";
+import { type Result } from "@fjall/generator";
+declare const SECURITY_SERVICE_PRINCIPALS: readonly ["guardduty.amazonaws.com", "securityhub.amazonaws.com", "config.amazonaws.com", "inspector2.amazonaws.com", "access-analyzer.amazonaws.com"];
+/**
+ * Register delegated administrators for security services.
+ * Idempotent — already-registered delegates are silently skipped.
+ */
+export declare function registerSecurityDelegates(client: OrganizationsClient, delegateAccountId: string, services?: readonly string[]): Promise<Result<void>>;
+export { SECURITY_SERVICE_PRINCIPALS };

package/dist/src/aws/organisations/delegatedAdmin.js

@@ -0,0 +1,43 @@
+import { RegisterDelegatedAdministratorCommand } from "@aws-sdk/client-organizations";
+import { success, failure } from "@fjall/generator";
+import { extractErrorName, SDK_TIMEOUT_MS, AWS_ERROR_NAMES } from "./types.js";
+import { getErrorMessage } from "@fjall/util";
+const SECURITY_SERVICE_PRINCIPALS = [
+    "guardduty.amazonaws.com",
+    "securityhub.amazonaws.com",
+    "config.amazonaws.com",
+    "inspector2.amazonaws.com",
+    "access-analyzer.amazonaws.com"
+];
+/**
+ * Register delegated administrators for security services.
+ * Idempotent — already-registered delegates are silently skipped.
+ */
+export async function registerSecurityDelegates(client, delegateAccountId, services = SECURITY_SERVICE_PRINCIPALS) {
+    const errors = [];
+    for (const service of services) {
+        try {
+            await client.send(new RegisterDelegatedAdministratorCommand({
+                AccountId: delegateAccountId,
+                ServicePrincipal: service
+            }), { abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS) });
+        }
+        catch (error) {
+            const errorName = extractErrorName(error);
+            if (errorName === AWS_ERROR_NAMES.ACCOUNT_ALREADY_REGISTERED) {
+                continue;
+            }
+            if (errorName === AWS_ERROR_NAMES.ACCESS_DENIED) {
+                const prefix = errors.length > 0 ? `${errors.join("; ")}; ` : "";
+                return failure(new Error(`${prefix}Access denied when registering delegated admin for ${service}. ` +
+                    "Ensure your credentials have organizations:RegisterDelegatedAdministrator permission."));
+            }
+            errors.push(`${service}: ${getErrorMessage(error)}`);
+        }
+    }
+    if (errors.length > 0) {
+        return failure(new Error(`Failed to register security delegates for account ${delegateAccountId}:\n  ${errors.join("\n  ")}`));
+    }
+    return success(undefined);
+}
+export { SECURITY_SERVICE_PRINCIPALS };

package/dist/src/aws/organisations/identityCentre.d.ts

@@ -1,6 +1,6 @@
 import { type SSOAdminClient } from "@aws-sdk/client-sso-admin";
 import { type Result } from "@fjall/generator";
-import type { IdentityCentreStatus } from "./types.js";
+import { type IdentityCentreStatus } from "./types.js";
 /**
  * Check if AWS Identity Centre (SSO) is enabled.
  * Returns the number of SSO instances found.

package/dist/src/aws/organisations/identityCentre.js

@@ -1,12 +1,16 @@
 import { ListInstancesCommand } from "@aws-sdk/client-sso-admin";
 import { success, failure } from "@fjall/generator";
+import { getErrorMessage } from "@fjall/util";
+import { SDK_TIMEOUT_MS } from "./types.js";
 /**
  * Check if AWS Identity Centre (SSO) is enabled.
  * Returns the number of SSO instances found.
  */
 export async function checkIdentityCentreStatus(client) {
     try {
-        const response = await client.send(new ListInstancesCommand({}));
+        const response = await client.send(new ListInstancesCommand({}), {
+            abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS)
+        });
         const instances = response.Instances ?? [];
         return success({
             enabled: instances.length > 0,
@@ -14,6 +18,6 @@ export async function checkIdentityCentreStatus(client) {
         });
     }
     catch (error) {
-        return failure(new Error(`Failed to check Identity Centre status: ${error instanceof Error ? error.message : String(error)}`));
+        return failure(new Error(`Failed to check Identity Centre status: ${getErrorMessage(error)}`));
     }
 }

package/dist/src/aws/organisations/index.d.ts

@@ -1,5 +1,5 @@
-export type { OrgDetails, OUMap, AccountPlacementResult, AccountInfo, IdentityCentreStatus } from "./types.js";
-export { extractErrorName } from "./types.js";
+export type { OrgDetails, OUMap, OUTree, AccountPlacementResult, AccountInfo, IdentityCentreStatus } from "./types.js";
+export { extractErrorName, isOULeaf } from "./types.js";
 export type { BackupGlobalSettings } from "./backup.js";
 export type { CostAllocationTag } from "./costAllocation.js";
 export type { CreateAccountResult } from "./accounts.js";
@@ -11,6 +11,7 @@ export { activateTrustedAccess } from "./trustedAccess.js";
 export { enableIpamDelegatedAdmin } from "./ipam.js";
 export { updateBackupGlobalSettings } from "./backup.js";
 export { listAccounts, findAccount, createAccount } from "./accounts.js";
-export { ensureOrganisationalUnitsExist, placeAccountsInOUs } from "./organisationalUnits.js";
+export { ensureOrganisationalUnitsExist, placeAccountsInOUs, buildAccountToOUMap } from "./organisationalUnits.js";
 export { activateCostAllocationTags } from "./costAllocation.js";
 export { checkIdentityCentreStatus } from "./identityCentre.js";
+export { registerSecurityDelegates, SECURITY_SERVICE_PRINCIPALS } from "./delegatedAdmin.js";

package/dist/src/aws/organisations/index.js

@@ -1,12 +1 @@
-export { extractErrorName } from "./types.js";
-export { ensureOrganisationExists, describeOrganisation } from "./organisation.js";
-export { enablePolicyTypes } from "./policies.js";
-export { enableServiceAccess } from "./serviceAccess.js";
-export { enableRamSharing } from "./ram.js";
-export { activateTrustedAccess } from "./trustedAccess.js";
-export { enableIpamDelegatedAdmin } from "./ipam.js";
-export { updateBackupGlobalSettings } from "./backup.js";
-export { listAccounts, findAccount, createAccount } from "./accounts.js";
-export { ensureOrganisationalUnitsExist, placeAccountsInOUs } from "./organisationalUnits.js";
-export { activateCostAllocationTags } from "./costAllocation.js";
-export { checkIdentityCentreStatus } from "./identityCentre.js";
+import{extractErrorName as r,isOULeaf as o}from"./types.js";import{ensureOrganisationExists as c,describeOrganisation as s}from"./organisation.js";import{enablePolicyTypes as i}from"./policies.js";import{enableServiceAccess as m}from"./serviceAccess.js";import{enableRamSharing as f}from"./ram.js";import{activateTrustedAccess as u}from"./trustedAccess.js";import{enableIpamDelegatedAdmin as g}from"./ipam.js";import{updateBackupGlobalSettings as S}from"./backup.js";import{listAccounts as I,findAccount as E,createAccount as O}from"./accounts.js";import{ensureOrganisationalUnitsExist as T,placeAccountsInOUs as U,buildAccountToOUMap as y}from"./organisationalUnits.js";import{activateCostAllocationTags as v}from"./costAllocation.js";import{checkIdentityCentreStatus as h}from"./identityCentre.js";import{registerSecurityDelegates as D,SECURITY_SERVICE_PRINCIPALS as L}from"./delegatedAdmin.js";export{L as SECURITY_SERVICE_PRINCIPALS,v as activateCostAllocationTags,u as activateTrustedAccess,y as buildAccountToOUMap,h as checkIdentityCentreStatus,O as createAccount,s as describeOrganisation,g as enableIpamDelegatedAdmin,i as enablePolicyTypes,f as enableRamSharing,m as enableServiceAccess,c as ensureOrganisationExists,T as ensureOrganisationalUnitsExist,r as extractErrorName,E as findAccount,o as isOULeaf,I as listAccounts,U as placeAccountsInOUs,D as registerSecurityDelegates,S as updateBackupGlobalSettings};

package/dist/src/aws/organisations/ipam.js

@@ -1,5 +1,7 @@
 import { EnableIpamOrganizationAdminAccountCommand } from "@aws-sdk/client-ec2";
 import { success, failure } from "@fjall/generator";
+import { getErrorMessage } from "@fjall/util";
+import { SDK_TIMEOUT_MS } from "./types.js";
 /**
  * Enable IPAM delegated administrator for the given account.
  * Idempotent — calling when already delegated is a no-op.
@@ -9,10 +11,10 @@ export async function enableIpamDelegatedAdmin(client, delegatedAdminAccountId)
         await client.send(new EnableIpamOrganizationAdminAccountCommand({
             DryRun: false,
             DelegatedAdminAccountId: delegatedAdminAccountId
-        }));
+        }), { abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS) });
         return success(undefined);
     }
     catch (error) {
-        return failure(new Error(`Failed to enable IPAM delegation for account ${delegatedAdminAccountId}: ${error instanceof Error ? error.message : String(error)}`));
+        return failure(new Error(`Failed to enable IPAM delegation for account ${delegatedAdminAccountId}: ${getErrorMessage(error)}`));
     }
 }

package/dist/src/aws/organisations/organisation.js

@@ -1,6 +1,7 @@
 import { DescribeOrganizationCommand, CreateOrganizationCommand, ListRootsCommand } from "@aws-sdk/client-organizations";
 import { success, failure } from "@fjall/generator";
-import { extractErrorName } from "./types.js";
+import { getErrorMessage } from "@fjall/util";
+import { extractErrorName, SDK_TIMEOUT_MS, AWS_ERROR_NAMES } from "./types.js";
 /**
  * Ensure an AWS Organisation exists, creating one if necessary.
  * Idempotent — safe to call when the organisation already exists.
@@ -13,7 +14,7 @@ export async function ensureOrganisationExists(client) {
         if (!org) {
             // Create new organisation with all features
             try {
-                const createResponse = await client.send(new CreateOrganizationCommand({ FeatureSet: "ALL" }));
+                const createResponse = await client.send(new CreateOrganizationCommand({ FeatureSet: "ALL" }), { abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS) });
                 org = createResponse.Organization ?? null;
                 created = true;
             }
@@ -35,20 +36,18 @@ export async function ensureOrganisationExists(client) {
             return failure(new Error("Organisation is missing required fields (Id or MasterAccountId)"));
         }
         // Get root ID
-        const rootsResponse = await client.send(new ListRootsCommand({}));
-        const roots = rootsResponse.Roots ?? [];
-        if (roots.length === 0 || !roots[0]?.Id) {
-            return failure(new Error("No organisation root found"));
-        }
+        const rootResult = await getOrganisationRootId(client);
+        if (!rootResult.success)
+            return rootResult;
         return success({
             orgId: org.Id,
-            rootId: roots[0].Id,
+            rootId: rootResult.data,
             managementAccountId: org.MasterAccountId,
             created
         });
     }
     catch (error) {
-        return failure(new Error(`Failed to ensure organisation exists: ${error instanceof Error ? error.message : String(error)}`));
+        return failure(new Error(`Failed to ensure organisation exists: ${getErrorMessage(error)}`));
     }
 }
 /**
@@ -63,30 +62,40 @@ export async function describeOrganisation(client) {
         if (!org.Id || !org.MasterAccountId) {
             return failure(new Error("Organisation is missing required fields (Id or MasterAccountId)"));
         }
-        const rootsResponse = await client.send(new ListRootsCommand({}));
-        const roots = rootsResponse.Roots ?? [];
-        if (roots.length === 0 || !roots[0]?.Id) {
-            return failure(new Error("No organisation root found"));
-        }
+        const rootResult = await getOrganisationRootId(client);
+        if (!rootResult.success)
+            return rootResult;
         return success({
             orgId: org.Id,
-            rootId: roots[0].Id,
+            rootId: rootResult.data,
             managementAccountId: org.MasterAccountId,
             created: false
         });
     }
     catch (error) {
-        return failure(new Error(`Failed to describe organisation: ${error instanceof Error ? error.message : String(error)}`));
+        return failure(new Error(`Failed to describe organisation: ${getErrorMessage(error)}`));
     }
 }
+async function getOrganisationRootId(client) {
+    const rootsResponse = await client.send(new ListRootsCommand({}), {
+        abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS)
+    });
+    const roots = rootsResponse.Roots ?? [];
+    if (roots.length === 0 || !roots[0]?.Id) {
+        return failure(new Error("No organisation root found"));
+    }
+    return success(roots[0].Id);
+}
 async function describeOrganisationRaw(client) {
     try {
-        const response = await client.send(new DescribeOrganizationCommand({}));
+        const response = await client.send(new DescribeOrganizationCommand({}), {
+            abortSignal: AbortSignal.timeout(SDK_TIMEOUT_MS)
+        });
         return response.Organization ?? null;
     }
     catch (error) {
         const errorName = extractErrorName(error);
-        if (errorName === "AWSOrganizationsNotInUseException") {
+        if (errorName === AWS_ERROR_NAMES.ORGS_NOT_IN_USE) {
             return null;
         }
         throw error;

package/dist/src/aws/organisations/organisationalUnits.d.ts

@@ -1,19 +1,39 @@
 import { type OrganizationsClient } from "@aws-sdk/client-organizations";
 import { type Result } from "@fjall/generator";
-import { type OUMap, type AccountInfo, type AccountPlacementResult } from "./types.js";
+import { type OUMap, type OUTree, type AccountInfo, type AccountPlacementResult } from "./types.js";
 /**
- * Ensure the specified organisational units exist under the root.
- * Creates any missing OUs. Returns a map of OU name (lowercase) → OU ID.
+ * Ensure the specified organisational units exist. Accepts either:
+ * - `string[]` (flat): creates OUs directly under root (original behaviour)
+ * - `OUTree` (nested): creates a recursive OU hierarchy
+ *
+ * Returns a map of OU key (lowercase) to OU ID. For nested trees, keys
+ * use dot notation (e.g., "workloads.production") with shorthand aliases
+ * for leaf names that don't collide with top-level keys.
  *
  * Idempotent — existing OUs are adopted, not duplicated.
  *
- * @param ouNames Array of OU names to ensure exist (will be capitalised)
+ * AWS cannot move OUs between parents. Migrating from flat to nested
+ * creates new OUs under new parents; old empty OUs remain at root.
+ */
+export declare function ensureOrganisationalUnitsExist(client: OrganizationsClient, rootId: string, ouConfig: string[] | OUTree): Promise<Result<OUMap>>;
+/**
+ * Build a flat map of accountName (lowercase) to OU ID from an OUTree
+ * and its resolved OUMap.
+ *
+ * Walks the tree recursively. For each leaf (string[]), maps each account
+ * name to the parent OU's ID using the dotted OUMap key.
+ *
+ * Callers must pass account names that match the tree leaf values.
  */
-export declare function ensureOrganisationalUnitsExist(client: OrganizationsClient, rootId: string, ouNames: string[]): Promise<Result<OUMap>>;
+export declare function buildAccountToOUMap(tree: OUTree, ouMap: OUMap, prefix?: string): Record<string, string>;
 /**
  * Place accounts into the correct organisational units.
  * Skips accounts with environment "root" and accounts already in the target OU.
  *
+ * When `accountToOU` is provided, looks up the target OU by account name
+ * (lowercase) instead of by environment. This supports tree-based placement
+ * where the OU is determined by which leaf the account appears in.
+ *
  * Idempotent — accounts already in the correct OU are counted but not moved.
  */
-export declare function placeAccountsInOUs(client: OrganizationsClient, ouMap: OUMap, accounts: AccountInfo[]): Promise<Result<AccountPlacementResult>>;
+export declare function placeAccountsInOUs(client: OrganizationsClient, ouMap: OUMap, accounts: AccountInfo[], accountToOU?: Record<string, string>): Promise<Result<AccountPlacementResult>>;