@fjall/deploy-core 0.89.4 → 0.89.6

package/dist/src/orchestration/organisationDestroy.js

@@ -0,0 +1,189 @@
+/**
+ * Organisation destroy orchestration.
+ *
+ * Receives pre-authenticated credentials and destroys all organisation
+ * infrastructure in cascade order:
+ * 1. Member accounts across ALL regions in parallel
+ * 2. Platform account in primary region
+ * 3. Organisation root stack
+ *
+ * Auth, verification, and interactive prompts are the caller's job
+ * (per engine/consumer boundary).
+ */
+import { success, failure } from "@fjall/generator";
+import { maskSensitiveOutput, getErrorMessage } from "@fjall/util";
+import { stubCallerIdentity } from "../types/deployment/index.js";
+import { ORGANISATION_TYPES, getOrganisationStackName } from "../types/operations.js";
+import { CdkContextBuilder } from "../services/supporting/CdkContextBuilder.js";
+import { buildParamsContext, synthOrFail, forwardOutput, forwardResourceProgress } from "./contextHelpers.js";
+import { destroyCascadeAccount } from "./cascadeDestroyHelpers.js";
+import { partitionAccounts } from "./cascadeHelpers.js";
+import { DEFAULT_REGION } from "../aws/utils/regions.js";
+import { STEP_IDS } from "../types/stepDefinitions.js";
+const ORG_DESTROY_STEP_ID = STEP_IDS.ORG_DESTROY;
+const ORG_DESTROY_STEP_NAME = "Destroying organisation infrastructure";
+/**
+ * Destroy organisation infrastructure with cascade.
+ *
+ * The cascade ordering is: members (parallel, multi-region) -> platform -> org stack.
+ * If any member or platform destruction fails, the org stack is NOT destroyed
+ * (to avoid orphaning resources).
+ */
+export async function destroyOrganisation(params, services, operation) {
+    const startTime = Date.now();
+    const { callbacks } = params;
+    const providerAccounts = params.orgConfig?.providerAccounts ?? [];
+    const primaryRegion = params.orgConfig?.primaryRegion ?? services.awsProvider.getRegion();
+    const allRegions = buildRegionList(params);
+    const { platformAccount, memberAccounts } = partitionAccounts(providerAccounts);
+    const cascadeEnabled = params.options?.cascade !== false;
+    callbacks.onLog?.(`Destroying organisation infrastructure (${providerAccounts.length} accounts, ${allRegions.length} region(s))`, "info");
+    const cascadeErrors = [];
+    const stacksDestroyed = [];
+    if (cascadeEnabled) {
+        callbacks.onCascadeStart?.();
+        // Phase 1: Destroy member accounts across all regions in parallel
+        if (memberAccounts.length > 0) {
+            callbacks.onCascadePhaseStart?.("accounts");
+            const pairs = buildAccountRegionPairs(memberAccounts, allRegions);
+            const memberResults = await Promise.allSettled(pairs.map(({ account, region }) => destroyCascadeAccount(params, services, operation, account, "account", region, callbacks)));
+            for (let i = 0; i < memberResults.length; i++) {
+                const result = memberResults[i];
+                const pair = pairs[i];
+                if (!result || !pair)
+                    continue;
+                if (result.status === "fulfilled") {
+                    if (result.value.success) {
+                        stacksDestroyed.push(`Account-${pair.account.name}-${pair.region}`);
+                    }
+                    else {
+                        cascadeErrors.push({
+                            accountId: pair.account.id,
+                            error: result.value.error ?? "Unknown error"
+                        });
+                    }
+                }
+                else {
+                    cascadeErrors.push({
+                        accountId: pair.account.id,
+                        error: getErrorMessage(result.reason)
+                    });
+                }
+            }
+        }
+        // Phase 2: Destroy platform account (primary region only)
+        if (platformAccount) {
+            callbacks.onCascadePhaseStart?.("platform");
+            const platformResult = await destroyCascadeAccount(params, services, operation, platformAccount, "platform", primaryRegion, callbacks);
+            if (platformResult.success) {
+                stacksDestroyed.push("Platform");
+            }
+            else {
+                cascadeErrors.push({
+                    accountId: platformAccount.id,
+                    error: platformResult.error ?? "Platform destroy failed"
+                });
+            }
+        }
+        // Emit cascade completion
+        callbacks.onCascadeComplete?.({
+            platformDeployed: false,
+            domainsDeployed: false,
+            accountsDeployed: 0,
+            accountsFailed: cascadeErrors.length,
+            errors: cascadeErrors
+        });
+        if (cascadeErrors.length > 0) {
+            const errorSummary = cascadeErrors
+                .map((e) => `  ${e.accountId}: ${e.error}`)
+                .join("\n");
+            const cascadeError = new Error(`Cascade destroy completed with ${cascadeErrors.length} failure(s):\n${errorSummary}`);
+            callbacks.onError?.(cascadeError);
+            callbacks.onLog?.(maskSensitiveOutput(cascadeError.message), "warn");
+        }
+    }
+    // Phase 3: Destroy the organisation root stack
+    // Gate: if any cascade failure, skip org stack destroy to avoid orphaning resources
+    if (cascadeErrors.length > 0) {
+        const msg = "Skipping organisation root stack destroy due to cascade failures";
+        callbacks.onLog?.(msg, "warn");
+        return success({
+            target: operation.target,
+            deploymentType: "organisation",
+            stacksDestroyed,
+            durationMs: Date.now() - startTime,
+            warnings: cascadeErrors.map((e) => maskSensitiveOutput(`${e.accountId}: ${e.error}`))
+        });
+    }
+    // Destroy org root stack
+    callbacks.onStepStart?.(ORG_DESTROY_STEP_ID, ORG_DESTROY_STEP_NAME, 0, 1);
+    const orgResult = await destroyOrgRootStack(params, services, operation, primaryRegion, callbacks);
+    if (orgResult.success) {
+        stacksDestroyed.push("Organisation");
+        callbacks.onStepComplete?.(ORG_DESTROY_STEP_ID, ORG_DESTROY_STEP_NAME, "completed", 0, 1);
+    }
+    else {
+        callbacks.onStepComplete?.(ORG_DESTROY_STEP_ID, ORG_DESTROY_STEP_NAME, "error", 0, 1);
+        return failure(orgResult.error);
+    }
+    return success({
+        target: operation.target,
+        deploymentType: "organisation",
+        stacksDestroyed,
+        durationMs: Date.now() - startTime
+    });
+}
+/**
+ * Destroy the organisation root stack via CDK.
+ */
+async function destroyOrgRootStack(params, services, operation, region, callbacks) {
+    const context = CdkContextBuilder.buildDeploymentContext({
+        deployType: "organisation",
+        target: operation.target,
+        path: operation.path,
+        region,
+        callerIdentity: stubCallerIdentity(services.awsProvider.getAccountId()),
+        ...buildParamsContext({
+            orgConfig: params.orgConfig,
+            identity: params.identity
+        })
+    }, { verbose: params.options?.verbose }, params.orgConfig);
+    const stackName = getOrganisationStackName(ORGANISATION_TYPES.ORGANISATION);
+    callbacks.onLog?.("Synthesising organisation infrastructure…", "info");
+    const synthResult = await synthOrFail(services, context, callbacks, "Organisation synth failed");
+    if (!synthResult.success)
+        return synthResult;
+    callbacks.onLog?.(`Destroying ${stackName} stack…`, "info");
+    const destroyResult = await services.cdkService.runCdkDestroy(context, stackName, forwardOutput(callbacks), forwardResourceProgress(callbacks), services.awsProvider, true);
+    if (!destroyResult.success) {
+        const error = new Error(maskSensitiveOutput(`Organisation destroy failed: ${destroyResult.error}`));
+        callbacks.onError?.(error);
+        return failure(error);
+    }
+    return success(undefined);
+}
+/**
+ * Build the full list of regions to destroy across (primary + secondary + DR).
+ */
+function buildRegionList(params) {
+    const primaryRegion = params.orgConfig?.primaryRegion ?? DEFAULT_REGION;
+    const secondaryRegions = params.orgConfig?.secondaryRegions ?? [];
+    const allRegions = [primaryRegion, ...secondaryRegions];
+    const drRegion = params.orgConfig?.disasterRecoveryRegion;
+    if (drRegion && !allRegions.includes(drRegion)) {
+        allRegions.push(drRegion);
+    }
+    return allRegions;
+}
+/**
+ * Build all account x region pairs for parallel destruction.
+ */
+function buildAccountRegionPairs(accounts, regions) {
+    const pairs = [];
+    for (const region of regions) {
+        for (const account of accounts) {
+            pairs.push({ account, region });
+        }
+    }
+    return pairs;
+}

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

@@ -1,6 +1,7 @@
 import { type Result } from "@fjall/generator";
 import type { AwsProvider } from "../aws/AwsProvider.js";
-export type OrgSetupPhase = "create-organisation" | "enable-policies" | "enable-service-access" | "enable-ram-sharing" | "activate-trusted-access" | "enable-ipam" | "configure-backup" | "create-accounts" | "create-organisational-units" | "place-accounts" | "activate-cost-tags" | "check-identity-centre";
+import type { OUTree } from "../aws/organisations/types.js";
+export type OrgSetupPhase = "create-organisation" | "enable-policies" | "enable-service-access" | "enable-ram-sharing" | "activate-trusted-access" | "enable-ipam" | "configure-backup" | "create-accounts" | "create-organisational-units" | "place-accounts" | "activate-cost-tags" | "check-identity-centre" | "register-security-delegates";
 export interface OrgSetupCallbacks {
     onPhaseStart?(phase: OrgSetupPhase): void;
     onPhaseComplete?(phase: OrgSetupPhase, result: "completed" | "skipped" | "error"): void;
@@ -12,11 +13,12 @@ export interface OrgSetupConfig {
         name: string;
         email: string;
     }>;
-    platformAccountId: string;
-    organisationalUnits: string[];
+    platformAccountId?: string;
+    organisationalUnits: string[] | OUTree;
     accountPlacements?: Record<string, string>;
     costAllocationTags?: string[];
     skipIdentityCentre?: boolean;
+    securityDelegateAccountId?: string;
 }
 export interface OrgSetupResult {
     organisationId: string;
@@ -35,7 +37,7 @@ export interface OrgSetupResult {
 /**
  * Orchestrate the full AWS Organisation setup sequence.
  *
- * Runs 12 phases sequentially. Non-fatal phase failures are recorded
+ * Runs up to 13 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.
  */

package/dist/src/orchestration/organisationSetup.js

@@ -14,13 +14,14 @@ 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 { ensureOrganisationalUnitsExist, placeAccountsInOUs, buildAccountToOUMap } from "../aws/organisations/organisationalUnits.js";
 import { activateCostAllocationTags } from "../aws/organisations/costAllocation.js";
 import { checkIdentityCentreStatus } from "../aws/organisations/identityCentre.js";
+import { registerSecurityDelegates } from "../aws/organisations/delegatedAdmin.js";
 /**
  * Orchestrate the full AWS Organisation setup sequence.
  *
- * Runs 12 phases sequentially. Non-fatal phase failures are recorded
+ * Runs up to 13 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.
  */
@@ -69,11 +70,14 @@ export async function runOrganisationSetup(awsProvider, config, callbacks) {
         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 6: Enable IPAM delegated admin (requires a platform account)
+    if (config.platformAccountId) {
+        const platformId = config.platformAccountId;
+        await executePhase("enable-ipam", () => {
+            callbacks?.onProgress?.("Enabling IPAM delegated administrator");
+            return enableIpamDelegatedAdmin(ec2Client, platformId);
+        }, phasesCompleted, errors, callbacks);
+    }
     // Phase 7: Configure backup settings
     await executePhase("configure-backup", () => {
         callbacks?.onProgress?.("Updating backup global settings");
@@ -116,9 +120,12 @@ export async function runOrganisationSetup(awsProvider, config, callbacks) {
     // Phase 10: Place accounts in OUs
     if (Object.keys(ouMap).length > 0 && config.accountPlacements) {
         const accountInfos = buildAccountInfos(config.accountPlacements);
+        const accountToOU = !Array.isArray(config.organisationalUnits)
+            ? buildAccountToOUMap(config.organisationalUnits, ouMap)
+            : undefined;
         await executePhase("place-accounts", () => {
             callbacks?.onProgress?.("Placing accounts in organisational units");
-            return placeAccountsInOUs(orgsClient, ouMap, accountInfos);
+            return placeAccountsInOUs(orgsClient, ouMap, accountInfos, accountToOU);
         }, phasesCompleted, errors, callbacks);
     }
     else {
@@ -163,6 +170,19 @@ export async function runOrganisationSetup(awsProvider, config, callbacks) {
             callbacks?.onPhaseComplete?.("check-identity-centre", "completed");
         }
     }
+    // Phase 13: Register security delegated administrators
+    const delegateAccountId = config.securityDelegateAccountId;
+    if (delegateAccountId) {
+        await executePhase("register-security-delegates", () => {
+            callbacks?.onProgress?.("Registering security service delegated administrators");
+            return registerSecurityDelegates(orgsClient, delegateAccountId);
+        }, phasesCompleted, errors, callbacks);
+    }
+    else {
+        phasesSkipped.push("register-security-delegates");
+        callbacks?.onPhaseStart?.("register-security-delegates");
+        callbacks?.onPhaseComplete?.("register-security-delegates", "skipped");
+    }
     return success({
         organisationId: orgId,
         createdAccounts,

package/dist/src/orchestration/resolveOperation.js

@@ -1,8 +1,13 @@
 import { join, relative } from "path";
+import { readdir } from "fs/promises";
 import { success, failure } from "@fjall/generator";
+import { logger } from "@fjall/util/logger";
 import { ORGANISATION_TYPES } from "../types/operations.js";
-import { fileExists } from "../util/fsHelpers.js";
+import { fileExists } from "@fjall/util/fsHelpers";
 const ORGANISATION_TYPE_VALUES = new Set(Object.values(ORGANISATION_TYPES));
+function isOrganisationType(value) {
+    return ORGANISATION_TYPE_VALUES.has(value);
+}
 const TARGET_PATTERN = /^[a-z][a-z0-9-]*$/;
 /**
  * Determine the deployment operation type from the target string and filesystem.
@@ -12,11 +17,39 @@ const TARGET_PATTERN = /^[a-z][a-z0-9-]*$/;
  * - Otherwise → failure
  */
 export async function resolveOperation(target, workingDirectory) {
+    logger.debug("resolveOperation", "called", { target, workingDirectory });
+    const workingDirExists = await fileExists(workingDirectory);
+    logger.debug("resolveOperation", "workingDirectory exists", {
+        exists: workingDirExists
+    });
+    const fjallDir = join(workingDirectory, "fjall");
+    const fjallDirExists = await fileExists(fjallDir);
+    logger.debug("resolveOperation", "fjall/ dir check", {
+        fjallDir,
+        exists: fjallDirExists
+    });
+    if (fjallDirExists && logger.isDebugEnabled()) {
+        try {
+            const entries = await readdir(fjallDir);
+            logger.debug("resolveOperation", "fjall/ contents", { entries });
+        }
+        catch (err) {
+            logger.debug("resolveOperation", "fjall/ readdir failed", {
+                error: String(err)
+            });
+        }
+    }
     // Check for organisation-level deployment
     const normalisedTarget = target.toLowerCase();
-    if (ORGANISATION_TYPE_VALUES.has(normalisedTarget)) {
+    if (isOrganisationType(normalisedTarget)) {
         const orgPath = join(workingDirectory, "fjall", normalisedTarget);
-        if (!(await fileExists(orgPath))) {
+        const orgPathExists = await fileExists(orgPath);
+        logger.debug("resolveOperation", "org type match", {
+            normalisedTarget,
+            orgPath,
+            exists: orgPathExists
+        });
+        if (!orgPathExists) {
             return failure(new Error(`Organisation target "${target}" resolved to fjall/${normalisedTarget}/ but directory not found`));
         }
         return success({
@@ -27,9 +60,19 @@ export async function resolveOperation(target, workingDirectory) {
         });
     }
     // Check for account-prefixed targets (e.g., "account-prod")
-    if (normalisedTarget.startsWith("account")) {
+    if (normalisedTarget.startsWith("account-")) {
+        const suffix = normalisedTarget.slice("account-".length);
+        if (!TARGET_PATTERN.test(suffix)) {
+            return failure(new Error(`Invalid account target "${target}": suffix must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens`));
+        }
         const orgPath = join(workingDirectory, "fjall", ORGANISATION_TYPES.ACCOUNT);
-        if (!(await fileExists(orgPath))) {
+        const orgPathExists = await fileExists(orgPath);
+        logger.debug("resolveOperation", "account-prefixed target", {
+            suffix,
+            orgPath,
+            exists: orgPathExists
+        });
+        if (!orgPathExists) {
             return failure(new Error(`Organisation target "${target}" resolved to fjall/${ORGANISATION_TYPES.ACCOUNT}/ but directory not found`));
         }
         return success({
@@ -41,6 +84,10 @@ export async function resolveOperation(target, workingDirectory) {
     }
     // Validate target before joining into filesystem path
     if (!TARGET_PATTERN.test(target)) {
+        logger.debug("resolveOperation", "target failed pattern validation", {
+            target,
+            pattern: TARGET_PATTERN.source
+        });
         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
@@ -50,12 +97,27 @@ export async function resolveOperation(target, workingDirectory) {
     if (rel.startsWith("..")) {
         return failure(new Error(`Invalid target "${target}": resolved path escapes working directory`));
     }
-    if (await fileExists(appPath)) {
+    const appPathExists = await fileExists(appPath);
+    logger.debug("resolveOperation", "app path check", {
+        appPath,
+        exists: appPathExists,
+        relative: rel
+    });
+    if (appPathExists) {
+        logger.debug("resolveOperation", "resolved as application", {
+            appName: target,
+            path: appPath
+        });
         return success({
             kind: "application",
             appName: target,
             path: appPath
         });
     }
+    logger.debug("resolveOperation", "FAILED — no match", {
+        target,
+        workingDirectory,
+        checkedPath: 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

@@ -3,6 +3,7 @@ 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 { FrameworkRegistry } from "./builders/frameworkRegistry.js";
 import type { DeployParams } from "../types/params.js";
 export interface DeployServices {
     awsProvider: SimpleAwsProvider;
@@ -10,6 +11,9 @@ export interface DeployServices {
     cfnService: CloudFormationService;
     stackService: ApplicationStackService;
     hashService: TemplateHashService;
+    frameworkRegistry: FrameworkRegistry;
+    /** Deregister process signal handlers and clean up child processes. */
+    dispose(): void;
 }
 /** 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

@@ -1,16 +1 @@
-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 };
-}
+import{SimpleAwsProvider as a}from"../aws/SimpleAwsProvider.js";import{CdkService as p}from"../services/infrastructure/CdkService.js";import{CdkArgumentBuilder as d}from"../services/infrastructure/CdkArgumentBuilder.js";import{CdkProcessManager as f}from"../services/infrastructure/CdkProcessManager.js";import{CloudFormationService as v}from"../services/infrastructure/CloudFormationService.js";import{ApplicationStackService as w}from"../services/application/ApplicationStackService.js";import{TemplateHashService as S}from"../services/supporting/TemplateHashService.js";import{FrameworkRegistry as l}from"./builders/frameworkRegistry.js";function x(i){const e=new a(i.awsCredentials);e.exportToEnv();const c=new d,r=new f(c),o=new p({processManager:r}),t=new v(e),n=new w(o,t,e),s=new S,m=l.createDefault();return{awsProvider:e,cdkService:o,cfnService:t,stackService:n,hashService:s,frameworkRegistry:m,dispose(){r.dispose()}}}export{x as createDeployServices};

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

@@ -0,0 +1,47 @@
+/**
+ * Generic process-spawning utilities with timeout handling,
+ * stream cleanup, and discriminated result types.
+ *
+ * Extracted from openNextBuild.ts so other builders can reuse
+ * the same timeout/stream/ENOENT patterns.
+ */
+import { spawn } from "child_process";
+/**
+ * Result from a spawned process with timeout handling.
+ */
+export type SpawnResult = {
+    type: "success";
+    code: number;
+    stdout: string;
+    stderr: string;
+} | {
+    type: "timeout";
+    stdout: string;
+    stderr: string;
+} | {
+    type: "enoent";
+    error: Error;
+} | {
+    type: "spawn_error";
+    error: Error;
+};
+/**
+ * Safely destroy process streams to prevent resource leaks.
+ */
+export declare function destroyProcessStreams(childProcess: ReturnType<typeof spawn>): void;
+/**
+ * Type guard for ENOENT errors (command not found).
+ */
+export declare function isEnoentError(err: unknown): err is NodeJS.ErrnoException;
+/**
+ * Spawn a child process with timeout handling and stream collection.
+ */
+export declare function spawnWithTimeout(options: {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string | undefined>;
+    timeout: number;
+    onStdoutData?: (data: string) => void;
+    onStderrData?: (data: string) => void;
+}): Promise<SpawnResult>;

package/dist/src/orchestration/spawnHelpers.js

@@ -0,0 +1 @@
+import{spawn as S}from"child_process";import{logger as a}from"@fjall/util/logger";function w(o){try{o.stdout?.destroy()}catch(r){a.debug("spawnHelpers","stdout destroy failed",{error:String(r)})}try{o.stderr?.destroy()}catch(r){a.debug("spawnHelpers","stderr destroy failed",{error:String(r)})}}function E(o){return o instanceof Error&&"code"in o&&o.code==="ENOENT"}function k(o){const{command:r,args:p,cwd:l,env:m,timeout:f,onStdoutData:y,onStderrData:g}=o;return new Promise(h=>{let u=!1;const n=t=>{u||(u=!0,h(t))},e=S(r,p,{cwd:l,shell:!1,stdio:["ignore","pipe","pipe"],env:m}),i=[],d=[];e.stdout?.on("data",t=>{const s=t.toString();i.push(s),y?.(s)}),e.stderr?.on("data",t=>{const s=t.toString();d.push(s),g?.(s)});const c=setTimeout(()=>{w(e),e.kill("SIGTERM"),n({type:"timeout",stdout:i.join(""),stderr:d.join("")})},f);e.on("close",t=>{clearTimeout(c),n({type:"success",code:t??1,stdout:i.join(""),stderr:d.join("")})}),e.on("error",t=>{clearTimeout(c),E(t)?n({type:"enoent",error:t}):n({type:"spawn_error",error:t})})})}export{w as destroyProcessStreams,E as isEnoentError,k as spawnWithTimeout};

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

@@ -0,0 +1,39 @@
+/**
+ * Utility functions for cleaning up CloudFormation stacks stuck in failed states.
+ *
+ * Only operates on stacks that never successfully deployed:
+ * - ROLLBACK_FAILED -- creation failed, rollback failed
+ * - ROLLBACK_COMPLETE -- creation failed, rollback succeeded
+ * - DELETE_FAILED -- deletion already started
+ *
+ * Never touches UPDATE_ROLLBACK_FAILED (has live resources from previous deploy).
+ *
+ * Ported from cli/src/services/utils/stackCleanup.ts for deploy-core consumers
+ * (webapp worker, CLI via deploy-core).
+ */
+import type { DeployCallbacks } from "../types/callbacks.js";
+/** Stack states safe to auto-delete -- never had a successful deployment. */
+export declare const SAFE_CLEANUP_STATES: Set<string>;
+/** Check whether a stack status is safe for automatic cleanup. */
+export declare function isCleanableState(status: string): boolean;
+interface StackCleanupCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/**
+ * Clean up a CloudFormation stack stuck in a failed state.
+ * Best-effort: all errors are caught and logged, never throws.
+ *
+ * Flow:
+ * 1. Check stack status -- skip if not in SAFE_CLEANUP_STATES
+ * 2. Find and empty S3 buckets blocking deletion
+ * 3. Delete the stack
+ * 4. Poll for DELETE_COMPLETE (5min timeout, 5s interval)
+ * 5. If DELETE_FAILED again, retry once with RetainResources for non-S3 failures
+ */
+export declare function cleanupFailedStack(stackName: string, region: string, credentials: StackCleanupCredentials, options?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}, callbacks?: DeployCallbacks): Promise<void>;
+export {};

package/dist/src/orchestration/stackCleanup.js

@@ -0,0 +1 @@
+import{CloudFormationClient as y,DescribeStacksCommand as w,DeleteStackCommand as C,ListStackResourcesCommand as D}from"@aws-sdk/client-cloudformation";import{S3Client as _,ListObjectVersionsCommand as $,DeleteObjectsCommand as A}from"@aws-sdk/client-s3";import{NodeHttpHandler as f}from"@smithy/node-http-handler";import{logger as o}from"@fjall/util/logger";import{getErrorMessage as S,sleep as h}from"@fjall/util";import{STACK_NOT_FOUND_PATTERN as k}from"../types/constants.js";const L=1e3,m=new Set(["ROLLBACK_FAILED","ROLLBACK_COMPLETE","DELETE_FAILED"]);function M(e){return m.has(e)}async function P(e,t,n){let d,s;n?.onStackCleanupProgress?.(t,"emptying-bucket");const c=1e3;let l=0;for(;l++<c;){let r;try{r=await e.send(new $({Bucket:t,KeyMarker:d,VersionIdMarker:s}))}catch(u){if(u instanceof Error&&(u.name==="NoSuchBucket"||u.message?.includes("NoSuchBucket"))){o.debug("stackCleanup",`Bucket ${t} no longer exists, skipping`);return}const p=`Unexpected error emptying bucket ${t}: ${S(u)}`;o.warn("stackCleanup",p),n?.onLog?.(p,"warn");return}const i=[...r.Versions??[],...r.DeleteMarkers??[]];if(i.length===0)break;for(let u=0;u<i.length;u+=L){const p=i.slice(u,u+L);try{await e.send(new A({Bucket:t,Delete:{Objects:p.map(a=>({Key:a.Key,VersionId:a.VersionId})),Quiet:!0}}))}catch(a){const E=`Failed to delete batch from ${t}: ${S(a)}`;o.warn("stackCleanup",E),n?.onLog?.(E,"warn")}}if(!r.IsTruncated)break;d=r.NextKeyMarker,s=r.NextVersionIdMarker}if(l>c){const r=`Bucket ${t} reached ${c} page limit \u2014 some objects may remain`;o.warn("stackCleanup",r),n?.onLog?.(r,"warn")}o.debug("stackCleanup",`Emptied bucket ${t}`)}async function g(e,t,n,d){const s=[];let c,r=0;do{if(r++>=100){o.warn("stackCleanup","Reached 100 page limit listing stack resources",{stackName:t});break}const i=await e.send(new D({StackName:t,NextToken:c}));for(const u of i.StackResourceSummaries??[])if(n(u)){const p=d(u);p&&s.push(p)}c=i.NextToken}while(c);return s}async function R(e,t){return g(e,t,n=>n.ResourceType==="AWS::S3::Bucket"&&n.ResourceStatus==="DELETE_FAILED",n=>n.PhysicalResourceId)}async function V(e,t,n,d,s){const c=d?.timeoutMs??3e5,l=d?.pollMs??5e3;try{const r=new y({region:t,credentials:n,requestHandler:new f({requestTimeout:15e3})});let i;try{i=(await r.send(new w({StackName:e}))).Stacks?.[0]?.StackStatus}catch(a){if(a instanceof Error&&a.message?.includes(k)){o.debug("stackCleanup",`Stack ${e} does not exist, no cleanup needed`);return}o.warn("stackCleanup",`Failed to check stack status: ${S(a)}`,{stackName:e,region:t});return}if(!i||!M(i)){o.debug("stackCleanup",`Stack ${e} status ${i??"unknown"} is not cleanable, skipping`);return}o.warn("stackCleanup",`Cleaning up ${e} stack in ${i} state`,{region:t}),s?.onStackCleanupProgress?.(e,"deleting-stack");const u=new _({region:t,credentials:n,requestHandler:new f({requestTimeout:15e3})});try{const a=await R(r,e);for(const E of a)o.warn("stackCleanup",`Emptying bucket ${E}`,{region:t}),await P(u,E,s)}catch(a){const E=`Failed to empty S3 buckets: ${S(a)}`;o.warn("stackCleanup",E,{stackName:e,region:t}),s?.onLog?.(E,"warn")}await r.send(new C({StackName:e})),s?.onStackCleanupProgress?.(e,"waiting");const p=await T(r,e,c,l);if(p==="DELETE_COMPLETE"){o.warn("stackCleanup",`${e} stack deleted successfully`,{region:t}),s?.onStackCleanupProgress?.(e,"complete");return}if(p==="DELETE_FAILED"){o.warn("stackCleanup",`${e} still in DELETE_FAILED, retrying with RetainResources`,{region:t});const a=await F(r,e);if(a.length===0)o.warn("stackCleanup",`${e} in DELETE_FAILED but no non-bucket resources to retain \u2014 cannot retry`,{region:t}),s?.onStackCleanupProgress?.(e,"error");else{await r.send(new C({StackName:e,RetainResources:a}));const E=await T(r,e,c,l);E==="DELETE_COMPLETE"?(o.warn("stackCleanup",`${e} stack deleted on retry (retained: ${a.join(", ")})`,{region:t}),s?.onStackCleanupProgress?.(e,"complete")):(o.warn("stackCleanup",`${e} stack still not deleted after retry: ${E}`,{region:t}),s?.onStackCleanupProgress?.(e,"error"))}}}catch(r){o.warn("stackCleanup",`Stack cleanup failed: ${S(r)}`,{stackName:e,region:t}),s?.onStackCleanupProgress?.(e,"error")}}async function T(e,t,n,d){const s=Date.now();for(;Date.now()-s<n;){await h(d);try{const l=(await e.send(new w({StackName:t}))).Stacks?.[0]?.StackStatus;if(!l||l==="DELETE_COMPLETE")return"DELETE_COMPLETE";if(l==="DELETE_FAILED")return"DELETE_FAILED";o.debug("stackCleanup",`Waiting for ${t}: ${l}`)}catch(c){if(c instanceof Error&&c.message?.includes(k))return"DELETE_COMPLETE";throw o.debug("stackCleanup",`Unexpected error polling ${t}: ${S(c)}`),c}}return"TIMEOUT"}async function F(e,t){return g(e,t,n=>n.ResourceStatus==="DELETE_FAILED"&&n.ResourceType!=="AWS::S3::Bucket",n=>n.LogicalResourceId)}export{m as SAFE_CLEANUP_STATES,V as cleanupFailedStack,M as isCleanableState};

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

@@ -0,0 +1,15 @@
+import { type Result } from "@fjall/generator";
+import type { DeployParams } from "../types/params.js";
+import type { DeployCallbacks } from "../types/callbacks.js";
+import type { ApplicationOperation } from "../types/operations.js";
+import type { DeployServices } from "./serviceFactory.js";
+/**
+ * Initialise ECR with the welcome image and tag for ECS services.
+ * Runs before Compute stack for apps without a Dockerfile.
+ *
+ * Two phases:
+ * 1. ECR init — ensures the welcome image exists in the private ECR repo
+ * 2. Image tagging — copies :latest/:backend to :<serviceName>-latest
+ *    so ECS task definitions can pull the correct tag
+ */
+export declare function runWelcomeImageSetup(params: DeployParams, services: DeployServices, operation: ApplicationOperation, callbacks: DeployCallbacks): Promise<Result<void>>;

package/dist/src/orchestration/welcomeImageHelper.js

@@ -0,0 +1,64 @@
+import { success, failure } from "@fjall/generator";
+import { maskSensitiveOutput } from "@fjall/util";
+import { STEP_IDS } from "../types/stepDefinitions.js";
+const TAG_IMAGES_STEP_NAME = "Tagging container images";
+/**
+ * Initialise ECR with the welcome image and tag for ECS services.
+ * Runs before Compute stack for apps without a Dockerfile.
+ *
+ * Two phases:
+ * 1. ECR init — ensures the welcome image exists in the private ECR repo
+ * 2. Image tagging — copies :latest/:backend to :<serviceName>-latest
+ *    so ECS task definitions can pull the correct tag
+ */
+export async function runWelcomeImageSetup(params, services, operation, callbacks) {
+    const dockerProvider = params.dockerProvider;
+    if (!dockerProvider)
+        return success(undefined);
+    const accountId = services.awsProvider.getAccountId();
+    if (!accountId) {
+        callbacks.onLog?.("Skipping ECR initialisation — account ID not available", "warn");
+        return success(undefined);
+    }
+    const region = services.awsProvider.getRegion();
+    // Phase 1: Initialise ECR repository with welcome image
+    callbacks.onStepStart?.(STEP_IDS.DOCKER_OPERATIONS, "Initialising container repository");
+    callbacks.onLog?.("Initialising ECR repository with welcome image…", "info");
+    const ecrResult = await dockerProvider.initialiseECR({
+        appName: operation.appName,
+        region,
+        accountId
+    });
+    if (!ecrResult.success) {
+        callbacks.onLog?.(maskSensitiveOutput(`ECR initialisation warning: ${ecrResult.error.message}`), "warn");
+    }
+    callbacks.onStepComplete?.(STEP_IDS.DOCKER_OPERATIONS, "Initialising container repository", "completed");
+    // Phase 2: Tag images for ECS services
+    if (dockerProvider.tagImages) {
+        callbacks.onStepStart?.(STEP_IDS.TAG_ECR_IMAGES, TAG_IMAGES_STEP_NAME);
+        callbacks.onLog?.("Tagging ECR images for ECS services…", "info");
+        const tagProgress = (message) => {
+            callbacks.onLog?.(maskSensitiveOutput(message), "info");
+        };
+        const tagResult = await dockerProvider.tagImages({
+            appName: operation.appName,
+            appPath: operation.path,
+            region,
+            accountId
+        }, tagProgress);
+        if (!tagResult.success) {
+            const error = new Error(maskSensitiveOutput(tagResult.error.message));
+            callbacks.onError?.(error);
+            callbacks.onStepComplete?.(STEP_IDS.TAG_ECR_IMAGES, TAG_IMAGES_STEP_NAME, "error");
+            return failure(error);
+        }
+        callbacks.onLog?.(`Tagged ${tagResult.data.taggedServices.length} service(s): ${tagResult.data.taggedServices.join(", ")}`, "info");
+        // Emit sub-step events for each tagged service so the detail panel shows per-service progress
+        for (const service of tagResult.data.taggedServices) {
+            callbacks.onStepStart?.(`tag-ecr-images-${service}`, `Tagged ${service}`);
+            callbacks.onStepComplete?.(`tag-ecr-images-${service}`, `Tagged ${service}`, "completed");
+        }
+        callbacks.onStepComplete?.(STEP_IDS.TAG_ECR_IMAGES, TAG_IMAGES_STEP_NAME, "completed");
+    }
+    return success(undefined);
+}