@fjall/deploy-core 0.89.2

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

@@ -0,0 +1,125 @@
+import { CreateOrganizationalUnitCommand, ListOrganizationalUnitsForParentCommand, ListParentsCommand, MoveAccountCommand } from "@aws-sdk/client-organizations";
+import { success, failure } from "@fjall/generator";
+import { extractErrorName } from "./types.js";
+/**
+ * List all OUs under a parent, handling pagination.
+ */
+async function listOUsForParent(client, parentId) {
+    const response = await client.send(new ListOrganizationalUnitsForParentCommand({ ParentId: parentId }));
+    let ous = response.OrganizationalUnits ?? [];
+    let nextToken = response.NextToken;
+    while (nextToken) {
+        const nextResponse = await client.send(new ListOrganizationalUnitsForParentCommand({
+            ParentId: parentId,
+            NextToken: nextToken
+        }));
+        ous = ous.concat(nextResponse.OrganizationalUnits ?? []);
+        nextToken = nextResponse.NextToken;
+    }
+    return ous;
+}
+/**
+ * Get the parent ID for a child (account or OU).
+ */
+async function getParentId(client, childId) {
+    try {
+        const response = await client.send(new ListParentsCommand({ ChildId: childId }));
+        return response.Parents?.[0]?.Id;
+    }
+    catch (error) {
+        const errorName = extractErrorName(error);
+        if (errorName === "ChildNotFoundException") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * 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 async function ensureOrganisationalUnitsExist(client, rootId, ouNames) {
+    try {
+        const ouMap = {};
+        for (const ouName of ouNames) {
+            const capitalised = ouName.charAt(0).toUpperCase() + ouName.slice(1);
+            // Check if OU already exists
+            const existing = await listOUsForParent(client, rootId);
+            const match = existing.find((ou) => ou.Name === capitalised);
+            if (match?.Id) {
+                ouMap[ouName.toLowerCase()] = match.Id;
+                continue;
+            }
+            // Create the OU
+            const response = await client.send(new CreateOrganizationalUnitCommand({
+                Name: capitalised,
+                ParentId: rootId
+            }));
+            const ou = response.OrganizationalUnit;
+            if (!ou?.Id) {
+                return failure(new Error(`OU "${capitalised}" was created but has no ID`));
+            }
+            ouMap[ouName.toLowerCase()] = ou.Id;
+        }
+        return success(ouMap);
+    }
+    catch (error) {
+        return failure(new Error(`Failed to ensure OUs exist: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}
+/**
+ * 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 async function placeAccountsInOUs(client, ouMap, accounts) {
+    try {
+        if (accounts.length === 0) {
+            return success({ moved: 0, alreadyPlaced: 0 });
+        }
+        let moved = 0;
+        let alreadyPlaced = 0;
+        for (const account of accounts) {
+            if (account.environment === "root") {
+                continue;
+            }
+            const targetOuId = ouMap[account.environment.toLowerCase()];
+            if (!targetOuId) {
+                continue;
+            }
+            const currentParentId = await getParentId(client, account.id);
+            if (!currentParentId) {
+                // Account not found in organisation
+                continue;
+            }
+            if (currentParentId === targetOuId) {
+                alreadyPlaced++;
+                continue;
+            }
+            try {
+                await client.send(new MoveAccountCommand({
+                    AccountId: account.id,
+                    SourceParentId: currentParentId,
+                    DestinationParentId: targetOuId
+                }));
+                moved++;
+            }
+            catch (error) {
+                const errorName = extractErrorName(error);
+                if (errorName === "AccountNotFoundException") {
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return success({ moved, alreadyPlaced });
+    }
+    catch (error) {
+        return failure(new Error(`Failed to place accounts in OUs: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}

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

@@ -0,0 +1,7 @@
+import { type OrganizationsClient } from "@aws-sdk/client-organizations";
+import { type Result } from "@fjall/generator";
+/**
+ * Enable all required policy types on the organisation root.
+ * Idempotent — skips policy types that are already enabled.
+ */
+export declare function enablePolicyTypes(client: OrganizationsClient, rootId: string): Promise<Result<void>>;

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

@@ -0,0 +1,36 @@
+import { EnablePolicyTypeCommand, PolicyType } from "@aws-sdk/client-organizations";
+import { success, failure } from "@fjall/generator";
+import { extractErrorName } from "./types.js";
+const POLICY_TYPES = [
+    PolicyType.SERVICE_CONTROL_POLICY,
+    PolicyType.TAG_POLICY,
+    PolicyType.BACKUP_POLICY,
+    PolicyType.AISERVICES_OPT_OUT_POLICY
+];
+/**
+ * Enable all required policy types on the organisation root.
+ * Idempotent — skips policy types that are already enabled.
+ */
+export async function enablePolicyTypes(client, rootId) {
+    try {
+        for (const policyType of POLICY_TYPES) {
+            try {
+                await client.send(new EnablePolicyTypeCommand({
+                    RootId: rootId,
+                    PolicyType: policyType
+                }));
+            }
+            catch (error) {
+                const errorName = extractErrorName(error);
+                if (errorName === "PolicyTypeAlreadyEnabledException") {
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return success(undefined);
+    }
+    catch (error) {
+        return failure(new Error(`Failed to enable policy types: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}

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

@@ -0,0 +1,7 @@
+import { type RAMClient } from "@aws-sdk/client-ram";
+import { type Result } from "@fjall/generator";
+/**
+ * Enable RAM sharing with the AWS Organisation.
+ * Idempotent — calling when already enabled is a no-op.
+ */
+export declare function enableRamSharing(client: RAMClient): Promise<Result<void>>;

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

@@ -0,0 +1,15 @@
+import { EnableSharingWithAwsOrganizationCommand } from "@aws-sdk/client-ram";
+import { success, failure } from "@fjall/generator";
+/**
+ * Enable RAM sharing with the AWS Organisation.
+ * Idempotent — calling when already enabled is a no-op.
+ */
+export async function enableRamSharing(client) {
+    try {
+        await client.send(new EnableSharingWithAwsOrganizationCommand({}));
+        return success(undefined);
+    }
+    catch (error) {
+        return failure(new Error(`Failed to enable RAM sharing: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}

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

@@ -0,0 +1,7 @@
+import { type OrganizationsClient } from "@aws-sdk/client-organizations";
+import { type Result } from "@fjall/generator";
+/**
+ * Enable AWS service access for all required service principals.
+ * Idempotent — enabling an already-enabled principal is a no-op.
+ */
+export declare function enableServiceAccess(client: OrganizationsClient): Promise<Result<void>>;

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

@@ -0,0 +1,38 @@
+import { EnableAWSServiceAccessCommand } from "@aws-sdk/client-organizations";
+import { success, failure } from "@fjall/generator";
+import { extractErrorName } from "./types.js";
+const SERVICE_PRINCIPALS = [
+    "account.amazonaws.com",
+    "sso.amazonaws.com",
+    "ipam.amazonaws.com",
+    "ram.amazonaws.com",
+    "backup.amazonaws.com",
+    "member.org.stacksets.cloudformation.amazonaws.com"
+];
+/**
+ * Enable AWS service access for all required service principals.
+ * Idempotent — enabling an already-enabled principal is a no-op.
+ */
+export async function enableServiceAccess(client) {
+    try {
+        for (const principal of SERVICE_PRINCIPALS) {
+            try {
+                await client.send(new EnableAWSServiceAccessCommand({
+                    ServicePrincipal: principal
+                }));
+            }
+            catch (error) {
+                const errorName = extractErrorName(error);
+                if (errorName === "AccessDeniedException") {
+                    return failure(new Error(`Access denied when enabling service access for ${principal}. ` +
+                        "Ensure your credentials have organizations:EnableAWSServiceAccess permission."));
+                }
+                throw error;
+            }
+        }
+        return success(undefined);
+    }
+    catch (error) {
+        return failure(new Error(`Failed to enable service access: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}

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

@@ -0,0 +1,7 @@
+import { type CloudFormationClient } from "@aws-sdk/client-cloudformation";
+import { type Result } from "@fjall/generator";
+/**
+ * Activate trusted access for CloudFormation StackSets.
+ * Idempotent — calling when already activated is a no-op.
+ */
+export declare function activateTrustedAccess(client: CloudFormationClient): Promise<Result<void>>;

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

@@ -0,0 +1,15 @@
+import { ActivateOrganizationsAccessCommand } from "@aws-sdk/client-cloudformation";
+import { success, failure } from "@fjall/generator";
+/**
+ * Activate trusted access for CloudFormation StackSets.
+ * Idempotent — calling when already activated is a no-op.
+ */
+export async function activateTrustedAccess(client) {
+    try {
+        await client.send(new ActivateOrganizationsAccessCommand({}));
+        return success(undefined);
+    }
+    catch (error) {
+        return failure(new Error(`Failed to activate trusted access: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Shared types for AWS Organisation setup primitives.
+ */
+export interface OrgDetails {
+    orgId: string;
+    rootId: string;
+    managementAccountId: string;
+    created: boolean;
+}
+/** Map of environment type (lowercase) → OU ID */
+export type OUMap = Record<string, string>;
+export interface AccountPlacementResult {
+    moved: number;
+    alreadyPlaced: number;
+}
+export interface AccountInfo {
+    id: string;
+    name: string;
+    environment: string;
+}
+export interface IdentityCentreStatus {
+    enabled: boolean;
+    instanceCount: number;
+}
+/**
+ * Extract the error name from an AWS SDK error.
+ * AWS SDK v3 errors have a `name` property that identifies the error type.
+ */
+export declare function extractErrorName(error: unknown): string;

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

@@ -0,0 +1,16 @@
+/**
+ * Shared types for AWS Organisation setup primitives.
+ */
+/**
+ * Extract the error name from an AWS SDK error.
+ * AWS SDK v3 errors have a `name` property that identifies the error type.
+ */
+export function extractErrorName(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "name" in error &&
+        typeof error.name === "string") {
+        return error.name;
+    }
+    return "UnknownError";
+}

package/dist/src/aws/utils/CloudFormationFailureAnalyser.d.ts

@@ -0,0 +1,32 @@
+import { type ResourceEvent } from "./cloudformationEvents.js";
+export interface RootCause {
+    resource: ResourceEvent;
+    reason: string;
+    category: "permissions" | "validation" | "dependency" | "limit" | "network" | "unknown";
+    isDirectCause: boolean;
+}
+export interface FailureAnalysis {
+    rootCause: RootCause;
+    affectedResources: ResourceEvent[];
+    dependencyChain: string[];
+    summary: string;
+    remediation: string[];
+    errorPattern?: string;
+}
+/**
+ * CloudFormationFailureAnalyser provides intelligent analysis of deployment failures
+ * It identifies root causes, dependency chains, and provides actionable remediation
+ */
+export declare class CloudFormationFailureAnalyser {
+    private knownErrorPatterns;
+    analyseFailure(eventHistory: Map<string, ResourceEvent[]>): FailureAnalysis | null;
+    private findFailedResources;
+    private findRootCause;
+    private categoriseError;
+    private isDirectCause;
+    private buildDependencyChain;
+    private generateRemediation;
+    private generateSummary;
+    private simplifyResourceType;
+    private isFailedStatus;
+}

package/dist/src/aws/utils/CloudFormationFailureAnalyser.js

@@ -0,0 +1,228 @@
+/**
+ * CloudFormationFailureAnalyser provides intelligent analysis of deployment failures
+ * It identifies root causes, dependency chains, and provides actionable remediation
+ */
+export class CloudFormationFailureAnalyser {
+    knownErrorPatterns = [
+        {
+            pattern: /AccessDenied|UnauthorizedOperation|Forbidden/i,
+            category: "permissions",
+            remediation: [
+                "Check IAM permissions for the deployment role",
+                "Ensure the role has necessary CloudFormation permissions",
+                "Verify service-linked roles are created if needed"
+            ]
+        },
+        {
+            pattern: /Invalid.*Parameter|ValidationError|Invalid.*Value/i,
+            category: "validation",
+            remediation: [
+                "Review parameter values in your CDK code",
+                "Check for typos in resource names or ARNs",
+                "Ensure all required parameters are provided"
+            ]
+        },
+        {
+            pattern: /Limit.*Exceeded|Quota.*Exceeded|Maximum.*reached/i,
+            category: "limit",
+            remediation: [
+                "Check AWS service quotas in the Service Quotas console",
+                "Request a quota increase if needed",
+                "Consider using a different region with available capacity"
+            ]
+        },
+        {
+            pattern: /Timeout|Connection.*refused|Network.*unreachable/i,
+            category: "network",
+            remediation: [
+                "Check network connectivity and VPC settings",
+                "Verify security groups and NACLs",
+                "Ensure endpoints are accessible"
+            ]
+        },
+        {
+            pattern: /already exists|Duplicate|ConflictException/i,
+            category: "validation",
+            remediation: [
+                "Resource with this name already exists",
+                "Consider using a different name or deleting the existing resource",
+                "Check if you are deploying to the correct account/region"
+            ]
+        },
+        {
+            pattern: /Role.*not.*found|Role.*does.*not.*exist/i,
+            category: "dependency",
+            remediation: [
+                "Ensure IAM roles are created before dependent resources",
+                "Check role names and ARNs are correct",
+                "Verify cross-stack references are properly configured"
+            ]
+        }
+    ];
+    analyseFailure(eventHistory) {
+        // Find all failed resources
+        const failedResources = this.findFailedResources(eventHistory);
+        if (failedResources.length === 0) {
+            return null;
+        }
+        // Find the root cause
+        const rootCause = this.findRootCause(failedResources, eventHistory);
+        // Build dependency chain
+        const dependencyChain = this.buildDependencyChain(rootCause.resource, failedResources);
+        // Generate remediation suggestions
+        const remediation = this.generateRemediation(rootCause);
+        // Create summary
+        const summary = this.generateSummary(rootCause, failedResources);
+        return {
+            rootCause,
+            affectedResources: failedResources,
+            dependencyChain,
+            summary,
+            remediation,
+            errorPattern: rootCause.category
+        };
+    }
+    findFailedResources(eventHistory) {
+        const failed = [];
+        for (const [_logicalId, events] of eventHistory) {
+            // Get the latest event for this resource
+            const latestEvent = events[events.length - 1];
+            if (latestEvent && this.isFailedStatus(latestEvent.status)) {
+                failed.push(latestEvent);
+            }
+        }
+        // Sort by timestamp to find the first failure
+        return failed.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    }
+    findRootCause(failedResources, eventHistory) {
+        if (failedResources.length === 0) {
+            return {
+                resource: {
+                    logicalId: "Unknown",
+                    resourceType: "Unknown",
+                    status: "FAILED",
+                    timestamp: new Date()
+                },
+                reason: "No failed resources found",
+                category: "unknown",
+                isDirectCause: false
+            };
+        }
+        // The first failed resource is usually the root cause
+        const firstFailed = failedResources[0];
+        // Analyse the failure reason
+        const category = this.categoriseError(firstFailed.statusReason || "");
+        // Check if this is a direct cause or a cascading failure
+        const isDirectCause = this.isDirectCause(firstFailed, eventHistory);
+        return {
+            resource: firstFailed,
+            reason: firstFailed.statusReason || "Unknown error",
+            category,
+            isDirectCause
+        };
+    }
+    categoriseError(errorMessage) {
+        for (const pattern of this.knownErrorPatterns) {
+            if (pattern.pattern.test(errorMessage)) {
+                return pattern.category;
+            }
+        }
+        return "unknown";
+    }
+    isDirectCause(resource, eventHistory) {
+        // If the error mentions another resource, it's likely cascading
+        const reason = resource.statusReason || "";
+        // Check for references to other resources
+        if (reason.includes("depends on") ||
+            reason.includes("referenced by") ||
+            reason.includes("required by")) {
+            return false;
+        }
+        // Check if this resource had any successful events before failing
+        const history = eventHistory.get(resource.logicalId) || [];
+        const hasSuccessfulEvents = history.some((e) => e.status.includes("COMPLETE") && !e.status.includes("ROLLBACK"));
+        // If it never succeeded, it's likely a direct cause
+        return !hasSuccessfulEvents;
+    }
+    buildDependencyChain(rootCause, failedResources) {
+        const chain = [];
+        // Start with root cause
+        chain.push(`${rootCause.logicalId} (${rootCause.resourceType}) - ROOT CAUSE`);
+        // Add cascading failures in chronological order
+        for (const resource of failedResources) {
+            if (resource.logicalId !== rootCause.logicalId) {
+                const reason = resource.statusReason || "";
+                if (reason.toLowerCase().includes(rootCause.logicalId.toLowerCase())) {
+                    chain.push(`  → ${resource.logicalId} (${resource.resourceType}) - Failed due to ${rootCause.logicalId}`);
+                }
+                else {
+                    chain.push(`  → ${resource.logicalId} (${resource.resourceType})`);
+                }
+            }
+        }
+        return chain;
+    }
+    generateRemediation(rootCause) {
+        const suggestions = [];
+        // Add pattern-based suggestions
+        for (const pattern of this.knownErrorPatterns) {
+            if (pattern.category === rootCause.category) {
+                suggestions.push(...pattern.remediation);
+                break;
+            }
+        }
+        // Add resource-specific suggestions
+        if (rootCause.resource.resourceType.includes("IAM")) {
+            suggestions.push("Review IAM policies and trust relationships");
+        }
+        else if (rootCause.resource.resourceType.includes("Lambda")) {
+            suggestions.push("Check Lambda function configuration and runtime");
+        }
+        else if (rootCause.resource.resourceType.includes("ECS")) {
+            suggestions.push("Verify ECS task definition and container configuration");
+        }
+        // Add general suggestions if no specific ones found
+        if (suggestions.length === 0) {
+            suggestions.push("Review the CloudFormation console for detailed error messages", "Check the resource configuration in your CDK code", "Ensure all dependencies are properly defined");
+        }
+        return suggestions;
+    }
+    generateSummary(rootCause, failedResources) {
+        const resourceType = this.simplifyResourceType(rootCause.resource.resourceType);
+        const failureCount = failedResources.length;
+        let summary = `Deployment failed: ${resourceType} "${rootCause.resource.logicalId}" `;
+        switch (rootCause.category) {
+            case "permissions":
+                summary += "failed due to insufficient permissions";
+                break;
+            case "validation":
+                summary += "failed validation";
+                break;
+            case "dependency":
+                summary += "has missing or invalid dependencies";
+                break;
+            case "limit":
+                summary += "exceeded AWS service limits";
+                break;
+            case "network":
+                summary += "encountered network issues";
+                break;
+            default:
+                summary += "failed to create";
+        }
+        if (failureCount > 1) {
+            summary += ` (${failureCount - 1} dependent resources also failed)`;
+        }
+        return summary;
+    }
+    simplifyResourceType(resourceType) {
+        return resourceType
+            .replace("AWS::", "")
+            .replace("::", " ")
+            .replace(/([A-Z])/g, " $1")
+            .trim();
+    }
+    isFailedStatus(status) {
+        return status.includes("FAILED");
+    }
+}

package/dist/src/aws/utils/cloudformationEvents.d.ts

@@ -0,0 +1,98 @@
+import type { AwsProvider } from "../AwsProvider.js";
+import type { FailureAnalysis } from "./CloudFormationFailureAnalyser.js";
+export declare const STACK_NOT_FOUND_PATTERN = "does not exist";
+export declare const CDK_NO_STACKS_MATCH = "No stacks match the name(s)";
+export interface ResourceEvent {
+    logicalId: string;
+    physicalId?: string;
+    resourceType: string;
+    status: string;
+    statusReason?: string;
+    timestamp: Date;
+}
+export declare function isResourceEvent(event: unknown): event is ResourceEvent;
+/** Interface for event logging — decouples from concrete CloudFormationEventLogger */
+export interface EventLogWriter {
+    writeEvent(event: ResourceEvent, metadata?: {
+        phase?: string;
+        isMainStack?: boolean;
+        parentStack?: string;
+    }): void;
+    writeDeploymentEnd(success: boolean, finalStatus: string, failureMessage?: string): void;
+    writeFailureSummary(failures: Array<{
+        logicalId: string;
+        reason: string;
+    }>): void;
+    writeFailureAnalysis(analysis: {
+        rootCause: string;
+        failedResources: Array<{
+            logicalId: string;
+            resourceType: string;
+            reason: string;
+        }>;
+        dependencyChain?: string[];
+        remediation?: string[];
+    }): void;
+    writeCdkOutput(stream: "stdout" | "stderr", chunk: string): void;
+    getLogPath(): string;
+    getLogSummary(): string;
+}
+/** Interface for failure analysis — decouples from concrete CloudFormationFailureAnalyser */
+export interface EventFailureAnalyser {
+    analyseFailure(eventHistory: Map<string, ResourceEvent[]>): FailureAnalysis | null;
+}
+/** Factory to create an EventLogWriter for a specific deployment */
+export type EventLogWriterFactory = (deploymentId: string, stackName: string, region: string, deploymentName?: string) => EventLogWriter;
+/** Dependencies injected into CloudFormationEventMonitor */
+export interface EventMonitorDeps {
+    failureAnalyser?: EventFailureAnalyser;
+    eventLogWriterFactory?: EventLogWriterFactory;
+}
+export declare class CloudFormationEventMonitor {
+    private aws;
+    private seenEventIds;
+    private isMonitoring;
+    private pollInterval;
+    private activeNestedStacks;
+    private failureReasons;
+    private eventHistory;
+    private eventLogger;
+    private failureAnalyser;
+    private eventLogWriterFactory;
+    private lastAnalysis;
+    private deploymentStartTime;
+    private maxHistorySize;
+    private maxSeenEventIds;
+    private ipamInProgress;
+    constructor(aws: AwsProvider, deps?: EventMonitorDeps);
+    enableLogging(deploymentId: string, stackName: string, region: string, deploymentName?: string): void;
+    startMonitoring(stackName: string, onResourceUpdate: (event: ResourceEvent) => void, onStackComplete?: (success: boolean, message?: string) => void): Promise<void>;
+    stopMonitoring(): void;
+    private cleanup;
+    getResourceHistory(logicalId: string): ResourceEvent[];
+    getEventHistory(): Map<string, ResourceEvent[]>;
+    getFailureAnalysis(): FailureAnalysis | null;
+    getFirstFailureReason(): string | null;
+    getEventLogger(): EventLogWriter | null;
+    getEventLogPath(): string | null;
+    getLogSummary(): string | null;
+    waitForStackComplete(stackName: string, options?: {
+        timeout?: number;
+        pollInterval?: number;
+        onResourceUpdate?: (event: ResourceEvent) => void;
+        onStackComplete?: (success: boolean, message?: string) => void;
+    }): Promise<{
+        success: boolean;
+        status?: string;
+        failureReason?: string;
+        logPath?: string;
+    }>;
+    private isTerminalState;
+    private isSuccessState;
+    private pollEvents;
+    getStackStatus(stackName: string): Promise<{
+        status: string;
+        statusReason?: string;
+    } | null>;
+    getCurrentResources(stackName: string): Promise<ResourceEvent[]>;
+}