@fjall/deploy-core 0.89.2

package/LICENSE

@@ -0,0 +1,21 @@
+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.

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

@@ -0,0 +1,39 @@
+/**
+ * Interface for AWS credential and client management.
+ *
+ * CLI provides: its full AwsContext (SSO, OIDC, credential caching).
+ * Worker provides: SimpleAwsProvider (pre-assumed OIDC credentials).
+ *
+ * deploy-core services use this interface — they never care HOW
+ * credentials were obtained.
+ */
+export interface AwsProvider {
+    /** Get a configured AWS SDK v3 client instance. */
+    getClient<T>(ClientClass: AwsSdkClientConstructor<T>): T;
+    /** AWS region for this context. */
+    getRegion(): string;
+    /** AWS account ID (resolved via STS GetCallerIdentity). */
+    getAccountId(): string | undefined;
+    /** Raw credentials for subprocess environments (CDK). */
+    getCredentials(): AwsProviderCredentials | undefined;
+    /** Export credentials to process.env for spawned subprocesses. */
+    exportToEnv(): void;
+    /**
+     * Assume an IAM role and return credentials for the assumed session.
+     * Used by organisation cascade to assume roles in member accounts.
+     */
+    assumeRole?(roleArn: string, sessionName: string): Promise<AwsProviderCredentials>;
+}
+export interface AwsProviderCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/**
+ * Constructor type for AWS SDK v3 clients.
+ * Matches the signature of all @aws-sdk/client-* default exports.
+ */
+export type AwsSdkClientConstructor<T> = new (config: {
+    region?: string;
+    credentials?: AwsProviderCredentials;
+}) => T;

package/dist/src/aws/AwsProvider.js

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

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

@@ -0,0 +1,22 @@
+import type { AwsCredentials } from "../types/credentials.js";
+import type { AwsProvider, AwsProviderCredentials, AwsSdkClientConstructor } from "./AwsProvider.js";
+/**
+ * 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 declare class SimpleAwsProvider implements AwsProvider {
+    private readonly credentials;
+    private readonly region;
+    private accountId;
+    private readonly clientCache;
+    constructor(awsCredentials: AwsCredentials);
+    getClient<T>(ClientClass: AwsSdkClientConstructor<T>): T;
+    getRegion(): string;
+    getAccountId(): string | undefined;
+    setAccountId(accountId: string): void;
+    getCredentials(): AwsProviderCredentials;
+    exportToEnv(): void;
+    assumeRole(roleArn: string, sessionName: string): Promise<AwsProviderCredentials>;
+}

package/dist/src/aws/SimpleAwsProvider.js

@@ -0,0 +1,73 @@
+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;
+    }
+    setAccountId(accountId) {
+        this.accountId = 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
+        }));
+        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
+        };
+    }
+}

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

@@ -0,0 +1,4 @@
+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";

package/dist/src/aws/index.js

@@ -0,0 +1,3 @@
+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";

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

@@ -0,0 +1,21 @@
+import { type OrganizationsClient, type Account } from "@aws-sdk/client-organizations";
+import { type Result } from "@fjall/generator";
+export interface CreateAccountResult {
+    accountId: string;
+    accountName: string;
+}
+/**
+ * List all accounts in the organisation, handling pagination.
+ */
+export declare function listAccounts(client: OrganizationsClient): Promise<Result<Account[]>>;
+/**
+ * Find an account by ID in the organisation.
+ */
+export declare function findAccount(client: OrganizationsClient, accountId: string): Promise<Result<Account | undefined>>;
+/**
+ * Create an AWS account and poll until creation completes.
+ *
+ * @param maxAttempts Maximum polling attempts (default: 180 = ~15 minutes at 5s intervals)
+ * @param delayMs Delay between polling attempts in milliseconds (default: 5000)
+ */
+export declare function createAccount(client: OrganizationsClient, accountName: string, email: string, maxAttempts?: number, delayMs?: number): Promise<Result<CreateAccountResult>>;

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

@@ -0,0 +1,99 @@
+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";
+/**
+ * List all accounts in the organisation, handling pagination.
+ */
+export async function listAccounts(client) {
+    try {
+        const response = await client.send(new ListAccountsCommand({ MaxResults: 20 }));
+        let accounts = response.Accounts ?? [];
+        let nextToken = response.NextToken;
+        while (nextToken) {
+            const nextResponse = await client.send(new ListAccountsCommand({
+                MaxResults: 20,
+                NextToken: nextToken
+            }));
+            accounts = accounts.concat(nextResponse.Accounts ?? []);
+            nextToken = nextResponse.NextToken;
+        }
+        return success(accounts);
+    }
+    catch (error) {
+        const errorName = extractErrorName(error);
+        if (errorName === "AWSOrganizationsNotInUseException") {
+            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)}`));
+    }
+}
+/**
+ * Find an account by ID in the organisation.
+ */
+export async function findAccount(client, accountId) {
+    const listResult = await listAccounts(client);
+    if (!listResult.success) {
+        return listResult;
+    }
+    return success(listResult.data.find((acc) => acc.Id === accountId));
+}
+/**
+ * Create an AWS account and poll until creation completes.
+ *
+ * @param maxAttempts Maximum polling attempts (default: 180 = ~15 minutes at 5s intervals)
+ * @param delayMs Delay between polling attempts in milliseconds (default: 5000)
+ */
+export async function createAccount(client, accountName, email, maxAttempts = 180, delayMs = 5000) {
+    try {
+        let response;
+        try {
+            response = await client.send(new CreateAccountCommand({
+                AccountName: accountName,
+                Email: email
+            }));
+        }
+        catch (error) {
+            const errorName = extractErrorName(error);
+            if (errorName === "AccessDeniedException") {
+                return failure(new Error(`Access denied when creating account "${accountName}". ` +
+                    "Ensure your credentials have organizations:CreateAccount permission."));
+            }
+            if (errorName === "DuplicateAccountException") {
+                return failure(new Error(`An account with the email "${email}" already exists in the organisation.`));
+            }
+            if (errorName === "FinalizingOrganizationException") {
+                return failure(new Error("The organisation is still being initialised. Please wait and try again."));
+            }
+            throw error;
+        }
+        const requestId = response.CreateAccountStatus?.Id;
+        if (!requestId) {
+            return failure(new Error(`CreateAccount request for "${accountName}" did not return a status ID`));
+        }
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const statusResponse = await client.send(new DescribeCreateAccountStatusCommand({
+                CreateAccountRequestId: requestId
+            }));
+            const status = statusResponse.CreateAccountStatus;
+            if (!status) {
+                return failure(new Error(`No status returned for CreateAccount request ${requestId}`));
+            }
+            if (status.State === CreateAccountState.SUCCEEDED) {
+                if (!status.AccountId) {
+                    return failure(new Error(`Account creation succeeded but no account ID returned for "${accountName}"`));
+                }
+                return success({ accountId: status.AccountId, accountName });
+            }
+            if (status.State === CreateAccountState.FAILED) {
+                return failure(new Error(`Account creation failed for "${accountName}": ${status.FailureReason}`));
+            }
+            // Still IN_PROGRESS
+            await sleep(delayMs);
+        }
+        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)}`));
+    }
+}

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

@@ -0,0 +1,12 @@
+import { type BackupClient } from "@aws-sdk/client-backup";
+import { type Result } from "@fjall/generator";
+export interface BackupGlobalSettings {
+    enableCrossAccountBackup?: boolean;
+    enableDelegatedAdministrator?: boolean;
+    enableMpa?: boolean;
+}
+/**
+ * Update AWS Backup global settings for the organisation.
+ * Idempotent — safe to call repeatedly with the same settings.
+ */
+export declare function updateBackupGlobalSettings(client: BackupClient, settings?: BackupGlobalSettings): Promise<Result<void>>;

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

@@ -0,0 +1,28 @@
+import { UpdateGlobalSettingsCommand } from "@aws-sdk/client-backup";
+import { success, failure } from "@fjall/generator";
+const DEFAULT_BACKUP_SETTINGS = {
+    enableCrossAccountBackup: true,
+    enableDelegatedAdministrator: true,
+    enableMpa: false
+};
+/**
+ * Update AWS Backup global settings for the organisation.
+ * Idempotent — safe to call repeatedly with the same settings.
+ */
+export async function updateBackupGlobalSettings(client, settings) {
+    try {
+        const finalSettings = { ...DEFAULT_BACKUP_SETTINGS, ...settings };
+        const globalSettings = {
+            isCrossAccountBackupEnabled: finalSettings.enableCrossAccountBackup.toString(),
+            isDelegatedAdministratorEnabled: finalSettings.enableDelegatedAdministrator.toString(),
+            isMpaEnabled: finalSettings.enableMpa.toString()
+        };
+        await client.send(new UpdateGlobalSettingsCommand({
+            GlobalSettings: globalSettings
+        }));
+        return success(undefined);
+    }
+    catch (error) {
+        return failure(new Error(`Failed to update backup global settings: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}

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

@@ -0,0 +1,12 @@
+import { type CostExplorerClient } from "@aws-sdk/client-cost-explorer";
+import { type Result } from "@fjall/generator";
+export interface CostAllocationTag {
+    TagKey: string;
+}
+/**
+ * Activate cost allocation tags for billing tracking.
+ * Idempotent — activating already-active tags is a no-op.
+ *
+ * Returns success with no action if the tags array is empty.
+ */
+export declare function activateCostAllocationTags(client: CostExplorerClient, tags: CostAllocationTag[]): Promise<Result<void>>;

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

@@ -0,0 +1,26 @@
+import { UpdateCostAllocationTagsStatusCommand } from "@aws-sdk/client-cost-explorer";
+import { success, failure } from "@fjall/generator";
+/**
+ * Activate cost allocation tags for billing tracking.
+ * Idempotent — activating already-active tags is a no-op.
+ *
+ * Returns success with no action if the tags array is empty.
+ */
+export async function activateCostAllocationTags(client, tags) {
+    if (tags.length === 0) {
+        return success(undefined);
+    }
+    try {
+        const costAllocationTagsStatus = tags.map((tag) => ({
+            TagKey: tag.TagKey,
+            Status: "Active"
+        }));
+        await client.send(new UpdateCostAllocationTagsStatusCommand({
+            CostAllocationTagsStatus: costAllocationTagsStatus
+        }));
+        return success(undefined);
+    }
+    catch (error) {
+        return failure(new Error(`Failed to activate cost allocation tags: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}

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

@@ -0,0 +1,8 @@
+import { type SSOAdminClient } from "@aws-sdk/client-sso-admin";
+import { type Result } from "@fjall/generator";
+import type { IdentityCentreStatus } from "./types.js";
+/**
+ * Check if AWS Identity Centre (SSO) is enabled.
+ * Returns the number of SSO instances found.
+ */
+export declare function checkIdentityCentreStatus(client: SSOAdminClient): Promise<Result<IdentityCentreStatus>>;

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

@@ -0,0 +1,19 @@
+import { ListInstancesCommand } from "@aws-sdk/client-sso-admin";
+import { success, failure } from "@fjall/generator";
+/**
+ * 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 instances = response.Instances ?? [];
+        return success({
+            enabled: instances.length > 0,
+            instanceCount: instances.length
+        });
+    }
+    catch (error) {
+        return failure(new Error(`Failed to check Identity Centre status: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}

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

@@ -0,0 +1,16 @@
+export type { OrgDetails, OUMap, AccountPlacementResult, AccountInfo, IdentityCentreStatus } from "./types.js";
+export { extractErrorName } from "./types.js";
+export type { BackupGlobalSettings } from "./backup.js";
+export type { CostAllocationTag } from "./costAllocation.js";
+export type { CreateAccountResult } from "./accounts.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";

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

@@ -0,0 +1,12 @@
+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";

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

@@ -0,0 +1,7 @@
+import { type EC2Client } from "@aws-sdk/client-ec2";
+import { type Result } from "@fjall/generator";
+/**
+ * Enable IPAM delegated administrator for the given account.
+ * Idempotent — calling when already delegated is a no-op.
+ */
+export declare function enableIpamDelegatedAdmin(client: EC2Client, delegatedAdminAccountId: string): Promise<Result<void>>;

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

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

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

@@ -0,0 +1,12 @@
+import { type OrganizationsClient } from "@aws-sdk/client-organizations";
+import { type Result } from "@fjall/generator";
+import { type OrgDetails } from "./types.js";
+/**
+ * Ensure an AWS Organisation exists, creating one if necessary.
+ * Idempotent — safe to call when the organisation already exists.
+ */
+export declare function ensureOrganisationExists(client: OrganizationsClient): Promise<Result<OrgDetails>>;
+/**
+ * Describe the current AWS Organisation, returning null if none exists.
+ */
+export declare function describeOrganisation(client: OrganizationsClient): Promise<Result<OrgDetails | null>>;

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

@@ -0,0 +1,94 @@
+import { DescribeOrganizationCommand, CreateOrganizationCommand, ListRootsCommand } from "@aws-sdk/client-organizations";
+import { success, failure } from "@fjall/generator";
+import { extractErrorName } from "./types.js";
+/**
+ * Ensure an AWS Organisation exists, creating one if necessary.
+ * Idempotent — safe to call when the organisation already exists.
+ */
+export async function ensureOrganisationExists(client) {
+    try {
+        let created = false;
+        // Try to describe existing organisation
+        let org = await describeOrganisationRaw(client);
+        if (!org) {
+            // Create new organisation with all features
+            try {
+                const createResponse = await client.send(new CreateOrganizationCommand({ FeatureSet: "ALL" }));
+                org = createResponse.Organization ?? null;
+                created = true;
+            }
+            catch (createError) {
+                const errorName = extractErrorName(createError);
+                if (errorName === "AlreadyInOrganizationException") {
+                    // Race condition — another process created it
+                    org = await describeOrganisationRaw(client);
+                    if (!org) {
+                        return failure(new Error("Account is already in an organisation but DescribeOrganization returned nothing"));
+                    }
+                }
+                else {
+                    throw createError;
+                }
+            }
+        }
+        if (!org?.Id || !org.MasterAccountId) {
+            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"));
+        }
+        return success({
+            orgId: org.Id,
+            rootId: roots[0].Id,
+            managementAccountId: org.MasterAccountId,
+            created
+        });
+    }
+    catch (error) {
+        return failure(new Error(`Failed to ensure organisation exists: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}
+/**
+ * Describe the current AWS Organisation, returning null if none exists.
+ */
+export async function describeOrganisation(client) {
+    try {
+        const org = await describeOrganisationRaw(client);
+        if (!org) {
+            return success(null);
+        }
+        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"));
+        }
+        return success({
+            orgId: org.Id,
+            rootId: roots[0].Id,
+            managementAccountId: org.MasterAccountId,
+            created: false
+        });
+    }
+    catch (error) {
+        return failure(new Error(`Failed to describe organisation: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}
+async function describeOrganisationRaw(client) {
+    try {
+        const response = await client.send(new DescribeOrganizationCommand({}));
+        return response.Organization ?? null;
+    }
+    catch (error) {
+        const errorName = extractErrorName(error);
+        if (errorName === "AWSOrganizationsNotInUseException") {
+            return null;
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type OrganizationsClient } from "@aws-sdk/client-organizations";
+import { type Result } from "@fjall/generator";
+import { type OUMap, 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.
+ *
+ * Idempotent — existing OUs are adopted, not duplicated.
+ *
+ * @param ouNames Array of OU names to ensure exist (will be capitalised)
+ */
+export declare function ensureOrganisationalUnitsExist(client: OrganizationsClient, rootId: string, ouNames: string[]): Promise<Result<OUMap>>;
+/**
+ * Place accounts into the correct organisational units.
+ * Skips accounts with environment "root" and accounts already in the target OU.
+ *
+ * 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>>;