@fjall/deploy-core 0.89.2

package/dist/src/orchestration/organisationSetup.js

@@ -0,0 +1,227 @@
+import { success, failure } from "@fjall/generator";
+import { OrganizationsClient } from "@aws-sdk/client-organizations";
+import { RAMClient } from "@aws-sdk/client-ram";
+import { CloudFormationClient } from "@aws-sdk/client-cloudformation";
+import { EC2Client } from "@aws-sdk/client-ec2";
+import { BackupClient } from "@aws-sdk/client-backup";
+import { CostExplorerClient } from "@aws-sdk/client-cost-explorer";
+import { SSOAdminClient } from "@aws-sdk/client-sso-admin";
+import { ensureOrganisationExists } from "../aws/organisations/organisation.js";
+import { enablePolicyTypes } from "../aws/organisations/policies.js";
+import { enableServiceAccess } from "../aws/organisations/serviceAccess.js";
+import { enableRamSharing } from "../aws/organisations/ram.js";
+import { activateTrustedAccess } from "../aws/organisations/trustedAccess.js";
+import { enableIpamDelegatedAdmin } from "../aws/organisations/ipam.js";
+import { updateBackupGlobalSettings } from "../aws/organisations/backup.js";
+import { listAccounts, createAccount } from "../aws/organisations/accounts.js";
+import { ensureOrganisationalUnitsExist, placeAccountsInOUs } from "../aws/organisations/organisationalUnits.js";
+import { activateCostAllocationTags } from "../aws/organisations/costAllocation.js";
+import { checkIdentityCentreStatus } from "../aws/organisations/identityCentre.js";
+/**
+ * Orchestrate the full AWS Organisation setup sequence.
+ *
+ * Runs 12 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.
+ */
+export async function runOrganisationSetup(awsProvider, config, callbacks) {
+    const phasesCompleted = [];
+    const phasesSkipped = [];
+    const errors = [];
+    const createdAccounts = [];
+    let identityCentreStatus;
+    const orgsClient = awsProvider.getClient(OrganizationsClient);
+    const ramClient = awsProvider.getClient(RAMClient);
+    const cfnClient = awsProvider.getClient(CloudFormationClient);
+    const ec2Client = awsProvider.getClient(EC2Client);
+    const backupClient = awsProvider.getClient(BackupClient);
+    const ceClient = awsProvider.getClient(CostExplorerClient);
+    const ssoClient = awsProvider.getClient(SSOAdminClient);
+    // Phase 1: Ensure organisation exists (fatal if fails)
+    callbacks?.onPhaseStart?.("create-organisation");
+    callbacks?.onProgress?.("Ensuring AWS Organisation exists");
+    const orgResult = await ensureOrganisationExists(orgsClient);
+    if (!orgResult.success) {
+        callbacks?.onError?.("create-organisation", orgResult.error);
+        callbacks?.onPhaseComplete?.("create-organisation", "error");
+        return failure(orgResult.error);
+    }
+    const { orgId, rootId } = orgResult.data;
+    callbacks?.onPhaseComplete?.("create-organisation", "completed");
+    phasesCompleted.push("create-organisation");
+    // Phase 2: Enable policy types
+    await executePhase("enable-policies", () => {
+        callbacks?.onProgress?.("Enabling organisation policy types");
+        return enablePolicyTypes(orgsClient, rootId);
+    }, phasesCompleted, errors, callbacks);
+    // Phase 3: Enable service access
+    await executePhase("enable-service-access", () => {
+        callbacks?.onProgress?.("Enabling AWS service access");
+        return enableServiceAccess(orgsClient);
+    }, phasesCompleted, errors, callbacks);
+    // Phase 4: Enable RAM sharing
+    await executePhase("enable-ram-sharing", () => {
+        callbacks?.onProgress?.("Enabling RAM sharing");
+        return enableRamSharing(ramClient);
+    }, phasesCompleted, errors, callbacks);
+    // Phase 5: Activate trusted access
+    await executePhase("activate-trusted-access", () => {
+        callbacks?.onProgress?.("Activating CloudFormation trusted access");
+        return activateTrustedAccess(cfnClient);
+    }, phasesCompleted, errors, callbacks);
+    // Phase 6: Enable IPAM delegated admin
+    await executePhase("enable-ipam", () => {
+        callbacks?.onProgress?.("Enabling IPAM delegated administrator");
+        return enableIpamDelegatedAdmin(ec2Client, config.platformAccountId);
+    }, phasesCompleted, errors, callbacks);
+    // Phase 7: Configure backup settings
+    await executePhase("configure-backup", () => {
+        callbacks?.onProgress?.("Updating backup global settings");
+        return updateBackupGlobalSettings(backupClient);
+    }, phasesCompleted, errors, callbacks);
+    // Phase 8: Create missing accounts
+    callbacks?.onPhaseStart?.("create-accounts");
+    callbacks?.onProgress?.("Checking for missing accounts");
+    const accountsResult = await createMissingAccounts(orgsClient, config.accounts, createdAccounts);
+    if (!accountsResult.success) {
+        errors.push({
+            phase: "create-accounts",
+            error: accountsResult.error.message
+        });
+        callbacks?.onError?.("create-accounts", accountsResult.error);
+        callbacks?.onPhaseComplete?.("create-accounts", "error");
+    }
+    else {
+        phasesCompleted.push("create-accounts");
+        callbacks?.onPhaseComplete?.("create-accounts", "completed");
+    }
+    // Phase 9: Ensure organisational units exist
+    let ouMap = {};
+    callbacks?.onPhaseStart?.("create-organisational-units");
+    callbacks?.onProgress?.("Ensuring organisational units exist");
+    const ouResult = await ensureOrganisationalUnitsExist(orgsClient, rootId, config.organisationalUnits);
+    if (!ouResult.success) {
+        errors.push({
+            phase: "create-organisational-units",
+            error: ouResult.error.message
+        });
+        callbacks?.onError?.("create-organisational-units", ouResult.error);
+        callbacks?.onPhaseComplete?.("create-organisational-units", "error");
+    }
+    else {
+        ouMap = ouResult.data;
+        phasesCompleted.push("create-organisational-units");
+        callbacks?.onPhaseComplete?.("create-organisational-units", "completed");
+    }
+    // Phase 10: Place accounts in OUs
+    if (Object.keys(ouMap).length > 0 && config.accountPlacements) {
+        const accountInfos = buildAccountInfos(config.accountPlacements);
+        await executePhase("place-accounts", () => {
+            callbacks?.onProgress?.("Placing accounts in organisational units");
+            return placeAccountsInOUs(orgsClient, ouMap, accountInfos);
+        }, phasesCompleted, errors, callbacks);
+    }
+    else {
+        phasesSkipped.push("place-accounts");
+        callbacks?.onPhaseStart?.("place-accounts");
+        callbacks?.onPhaseComplete?.("place-accounts", "skipped");
+    }
+    // Phase 11: Activate cost allocation tags
+    const tags = config.costAllocationTags ?? [];
+    if (tags.length > 0) {
+        await executePhase("activate-cost-tags", () => {
+            callbacks?.onProgress?.("Activating cost allocation tags");
+            return activateCostAllocationTags(ceClient, tags.map((t) => ({ TagKey: t })));
+        }, phasesCompleted, errors, callbacks);
+    }
+    else {
+        phasesSkipped.push("activate-cost-tags");
+        callbacks?.onPhaseStart?.("activate-cost-tags");
+        callbacks?.onPhaseComplete?.("activate-cost-tags", "skipped");
+    }
+    // Phase 12: Check Identity Centre
+    if (config.skipIdentityCentre) {
+        phasesSkipped.push("check-identity-centre");
+        callbacks?.onPhaseStart?.("check-identity-centre");
+        callbacks?.onPhaseComplete?.("check-identity-centre", "skipped");
+    }
+    else {
+        callbacks?.onPhaseStart?.("check-identity-centre");
+        callbacks?.onProgress?.("Checking Identity Centre status");
+        const icResult = await checkIdentityCentreStatus(ssoClient);
+        if (!icResult.success) {
+            errors.push({
+                phase: "check-identity-centre",
+                error: icResult.error.message
+            });
+            callbacks?.onError?.("check-identity-centre", icResult.error);
+            callbacks?.onPhaseComplete?.("check-identity-centre", "error");
+        }
+        else {
+            identityCentreStatus = icResult.data.enabled ? "enabled" : "not-enabled";
+            phasesCompleted.push("check-identity-centre");
+            callbacks?.onPhaseComplete?.("check-identity-centre", "completed");
+        }
+    }
+    return success({
+        organisationId: orgId,
+        createdAccounts,
+        identityCentreStatus,
+        phasesCompleted,
+        phasesSkipped,
+        errors
+    });
+}
+/**
+ * Execute a single phase with standard callback handling.
+ * Records success or error; never throws.
+ */
+async function executePhase(phase, fn, phasesCompleted, errors, callbacks) {
+    callbacks?.onPhaseStart?.(phase);
+    const result = await fn();
+    if (!result.success) {
+        errors.push({ phase, error: result.error.message });
+        callbacks?.onError?.(phase, result.error);
+        callbacks?.onPhaseComplete?.(phase, "error");
+    }
+    else {
+        phasesCompleted.push(phase);
+        callbacks?.onPhaseComplete?.(phase, "completed");
+    }
+}
+/**
+ * List existing accounts, then create any that are missing by name.
+ */
+async function createMissingAccounts(client, desiredAccounts, createdAccounts) {
+    const listResult = await listAccounts(client);
+    if (!listResult.success) {
+        return failure(listResult.error);
+    }
+    const existingNames = new Set(listResult.data
+        .map((a) => a.Name?.toLowerCase())
+        .filter((n) => n !== undefined));
+    for (const desired of desiredAccounts) {
+        if (existingNames.has(desired.name.toLowerCase())) {
+            continue;
+        }
+        const createResult = await createAccount(client, desired.name, desired.email);
+        if (!createResult.success) {
+            return failure(createResult.error);
+        }
+        createdAccounts.push({
+            name: createResult.data.accountName,
+            accountId: createResult.data.accountId
+        });
+    }
+    return success(undefined);
+}
+/**
+ * Convert account placement config into AccountInfo[] for placeAccountsInOUs.
+ */
+function buildAccountInfos(placements) {
+    return Object.entries(placements).map(([accountId, environment]) => ({
+        id: accountId,
+        name: accountId,
+        environment
+    }));
+}

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

@@ -0,0 +1,10 @@
+import { type Result } from "@fjall/generator";
+import type { DeploymentOperation } from "../types/operations.js";
+/**
+ * Determine the deployment operation type from the target string and filesystem.
+ *
+ * - If target matches an organisation type → OrganisationOperation
+ * - If fjall/<target> directory exists → ApplicationOperation
+ * - Otherwise → failure
+ */
+export declare function resolveOperation(target: string, workingDirectory: string): Promise<Result<DeploymentOperation>>;

package/dist/src/orchestration/resolveOperation.js

@@ -0,0 +1,53 @@
+import { join, relative } from "path";
+import { success, failure } from "@fjall/generator";
+import { ORGANISATION_TYPES } from "../types/operations.js";
+import { fileExists } from "../util/fsHelpers.js";
+const ORGANISATION_TYPE_VALUES = new Set(Object.values(ORGANISATION_TYPES));
+const TARGET_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Determine the deployment operation type from the target string and filesystem.
+ *
+ * - If target matches an organisation type → OrganisationOperation
+ * - If fjall/<target> directory exists → ApplicationOperation
+ * - Otherwise → failure
+ */
+export async function resolveOperation(target, workingDirectory) {
+    // Check for organisation-level deployment
+    const normalisedTarget = target.toLowerCase();
+    if (ORGANISATION_TYPE_VALUES.has(normalisedTarget)) {
+        return success({
+            kind: "organisation",
+            type: normalisedTarget,
+            target,
+            path: workingDirectory
+        });
+    }
+    // Check for account-prefixed targets (e.g., "account-prod")
+    if (normalisedTarget.startsWith("account")) {
+        return success({
+            kind: "organisation",
+            type: ORGANISATION_TYPES.ACCOUNT,
+            target,
+            path: workingDirectory
+        });
+    }
+    // Validate target before joining into filesystem path
+    if (!TARGET_PATTERN.test(target)) {
+        return failure(new Error(`Invalid target "${target}": must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens`));
+    }
+    // Check for application deployment
+    const appPath = join(workingDirectory, "fjall", target);
+    // Defence-in-depth: ensure resolved path stays under workingDirectory
+    const rel = relative(workingDirectory, appPath);
+    if (rel.startsWith("..")) {
+        return failure(new Error(`Invalid target "${target}": resolved path escapes working directory`));
+    }
+    if (await fileExists(appPath)) {
+        return success({
+            kind: "application",
+            appName: target,
+            path: appPath
+        });
+    }
+    return failure(new Error(`Target "${target}" is not a recognised organisation type and no directory found at fjall/${target}`));
+}

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

@@ -0,0 +1,15 @@
+import { SimpleAwsProvider } from "../aws/SimpleAwsProvider.js";
+import { CdkService } from "../services/infrastructure/CdkService.js";
+import { CloudFormationService } from "../services/infrastructure/CloudFormationService.js";
+import { ApplicationStackService } from "../services/application/ApplicationStackService.js";
+import { TemplateHashService } from "../services/supporting/TemplateHashService.js";
+import type { DeployParams } from "../types/params.js";
+export interface DeployServices {
+    awsProvider: SimpleAwsProvider;
+    cdkService: CdkService;
+    cfnService: CloudFormationService;
+    stackService: ApplicationStackService;
+    hashService: TemplateHashService;
+}
+/** CDK needs AWS credentials as env vars, so exportToEnv() is called immediately. */
+export declare function createDeployServices(params: DeployParams): DeployServices;

package/dist/src/orchestration/serviceFactory.js

@@ -0,0 +1,16 @@
+import { SimpleAwsProvider } from "../aws/SimpleAwsProvider.js";
+import { CdkService } from "../services/infrastructure/CdkService.js";
+import { CloudFormationService } from "../services/infrastructure/CloudFormationService.js";
+import { ApplicationStackService } from "../services/application/ApplicationStackService.js";
+import { TemplateHashService } from "../services/supporting/TemplateHashService.js";
+/** CDK needs AWS credentials as env vars, so exportToEnv() is called immediately. */
+export function createDeployServices(params) {
+    const awsProvider = new SimpleAwsProvider(params.awsCredentials);
+    awsProvider.exportToEnv();
+    const cdkService = new CdkService();
+    const cfnService = new CloudFormationService(awsProvider);
+    const stackService = new ApplicationStackService(cdkService, cfnService);
+    stackService.setAwsContext(awsProvider);
+    const hashService = new TemplateHashService();
+    return { awsProvider, cdkService, cfnService, stackService, hashService };
+}

package/dist/src/services/application/ApplicationStackService.d.ts

@@ -0,0 +1,93 @@
+import type { CdkService } from "../infrastructure/CdkService.js";
+import type { CloudFormationService } from "../infrastructure/CloudFormationService.js";
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import type { ResourceEvent } from "../../types/events.js";
+import type { DeploymentContext } from "../../types/deployment/DeploymentTypes.js";
+import { type ApplicationStack } from "../../types/operations.js";
+import type { ParallelDeploymentResult } from "../../types/deployment/parallel.js";
+import { type AppResourceFlags } from "../../types/patternDetection.js";
+import { type Result } from "@fjall/generator";
+import { ApplicationError, type StackDeploymentData } from "../../types/application/ApplicationServiceTypes.js";
+/**
+ * Service for deploying and destroying individual CloudFormation stacks.
+ *
+ * Handles single-stack deploy/destroy, parallel operations, and the full
+ * destroy-all-stacks orchestration.
+ *
+ * Unlike the CLI version, services are constructor-injected rather than
+ * fetched via singleton factories.
+ */
+export declare class ApplicationStackService {
+    private cdkService;
+    private cloudFormationService;
+    private aws;
+    constructor(cdkService: CdkService, cloudFormationService: CloudFormationService);
+    setAwsContext(aws: AwsProvider | undefined): void;
+    /**
+     * Deploy a specific stack type for an application
+     */
+    deployStack(stackType: ApplicationStack, context: DeploymentContext, callbacks?: {
+        onOutput?: (chunk: string) => void;
+        onResourceProgress?: (event: ResourceEvent) => void;
+    }): Promise<Result<StackDeploymentData, ApplicationError>>;
+    /**
+     * Deploy multiple stacks in parallel within a deployment phase.
+     *
+     * Uses Promise.allSettled to ensure all stacks are attempted even if some fail.
+     */
+    deployStacksInParallel(stacks: readonly ApplicationStack[], context: DeploymentContext, callbacks?: {
+        onOutput?: (chunk: string, stackId: ApplicationStack) => void;
+        onResourceProgress?: (event: ResourceEvent, stackId: ApplicationStack) => void;
+        onStackComplete?: (stack: ApplicationStack, success: boolean, duration: number, error?: Error) => void;
+    }): Promise<Result<ParallelDeploymentResult[], ApplicationError>>;
+    /**
+     * Destroy a specific stack type
+     */
+    destroyStack(stackType: ApplicationStack, context: DeploymentContext, callbacks?: {
+        onOutput?: (chunk: string) => void;
+        onResourceProgress?: (event: ResourceEvent) => void;
+    }, useCdkOut?: boolean): Promise<Result<StackDeploymentData, ApplicationError>>;
+    /**
+     * Destroy multiple stacks in parallel within a destroy phase.
+     *
+     * IMPORTANT: For parallel operations, useCdkOut must be true and CDK synth must
+     * be run beforehand. Multiple CDK commands cannot run in parallel because they
+     * all try to synthesise to the same cdk.out directory.
+     */
+    destroyStacksInParallel(stacks: readonly ApplicationStack[], context: DeploymentContext, callbacks?: {
+        onOutput?: (chunk: string, stackId: ApplicationStack) => void;
+        onResourceProgress?: (event: ResourceEvent, stackId: ApplicationStack) => void;
+        onStackComplete?: (stack: ApplicationStack, success: boolean, duration: number, error?: Error) => void;
+    }, useCdkOut?: boolean): Promise<Result<ParallelDeploymentResult[], ApplicationError>>;
+    /**
+     * Get stack outputs for a deployed stack
+     */
+    getStackOutputs(appName: string, stackType: ApplicationStack): Promise<Result<Record<string, string | number | boolean>, ApplicationError>>;
+    /**
+     * Resolve the website URL for an application from CloudFormation stack outputs.
+     * Checks Compute stack for LoadBalancer URL, then CDN stack for CloudFront distribution.
+     */
+    resolveWebsiteUrl(appName: string): Promise<string | undefined>;
+    /**
+     * Destroy all stacks for an application in reverse order.
+     * Supports parallel destruction for OpenNext patterns (nextjs/payload).
+     */
+    destroyAllStacks(context: DeploymentContext, callbacks?: {
+        onOutput?: (chunk: string, stackId?: ApplicationStack) => void;
+        onResourceProgress?: (event: ResourceEvent, stackId?: ApplicationStack) => void;
+        onStackStart?: (stackType: ApplicationStack, stackName: string) => void;
+        onStackComplete?: (stackType: ApplicationStack, result: Result<StackDeploymentData, ApplicationError>) => void | Promise<void>;
+        onParallelPhaseStart?: (stacks: readonly ApplicationStack[], description: string) => void;
+        onParallelPhaseComplete?: (results: ParallelDeploymentResult[]) => void;
+    }, resources?: AppResourceFlags): Promise<Result<{
+        message: string;
+    }, ApplicationError>>;
+    /**
+     * Convert "doesn't exist" errors to success for destroy operations.
+     */
+    private convertDestroyResultIfNotExists;
+    /**
+     * Handle destroy errors and determine if we should continue or fail
+     */
+    private handleDestroyError;
+}