@fjall/deploy-core 0.89.2

package/dist/src/services/infrastructure/CloudFormationService.d.ts

@@ -0,0 +1,79 @@
+import { CloudFormationClient } from "@aws-sdk/client-cloudformation";
+import type { AwsProvider } from "../../aws/AwsProvider.js";
+import { type CloudFormationStackStatus, type CloudFormationOutput } from "../../aws/utils/stackStatus.js";
+import { type ProgressCallbacks } from "../../types/ProgressEvent.js";
+import { type Result } from "@fjall/generator";
+import { BaseServiceError } from "../../types/errors/ServiceError.js";
+/**
+ * CloudFormation-specific error
+ */
+export declare class CloudFormationError extends BaseServiceError {
+    readonly errorType: "stack_not_found" | "stack_in_progress" | "stack_failed" | "invalid_state" | "throttled" | "network_error" | "auth_error" | "timeout" | "unknown";
+    readonly stackName?: string | undefined;
+    readonly stackStatus?: string | undefined;
+    constructor(message: string, errorType: "stack_not_found" | "stack_in_progress" | "stack_failed" | "invalid_state" | "throttled" | "network_error" | "auth_error" | "timeout" | "unknown", stackName?: string | undefined, stackStatus?: string | undefined, details?: unknown, recoverable?: boolean);
+}
+/**
+ * Callbacks for CloudFormation operations
+ */
+export interface CloudFormationCallbacks extends ProgressCallbacks {
+    onStackCheck?: (stackName: string) => void;
+    onStackFound?: (stackName: string, status: string) => void;
+    onStackNotFound?: (stackName: string) => void;
+    onOutputsRetrieved?: (stackName: string, outputCount: number) => void;
+    onExportsRetrieved?: (exportCount: number) => void;
+}
+/**
+ * CloudFormation service using the AwsProvider interface.
+ *
+ * Unlike the CLI version which lazily initialises AwsContext,
+ * deploy-core receives a pre-configured AwsProvider at construction.
+ */
+export declare class CloudFormationService {
+    private aws;
+    constructor(aws: AwsProvider);
+    /**
+     * Classify an AWS SDK error into a typed CloudFormationError.
+     */
+    private classifyAwsError;
+    /**
+     * Get stack outputs for services that need them
+     */
+    getStackOutputs(stackName: string, callbacks?: CloudFormationCallbacks): Promise<Result<CloudFormationOutput[], CloudFormationError>>;
+    /**
+     * Get stack status directly
+     */
+    getStackStatus(stackName: string, callbacks?: CloudFormationCallbacks): Promise<Result<CloudFormationStackStatus | null, CloudFormationError>>;
+    /**
+     * Internal helper to list all CloudFormation exports with pagination.
+     */
+    private listAllExports;
+    /**
+     * Look up specific CloudFormation exports by exact name.
+     */
+    getExportsByNames(names: string[]): Promise<Result<Map<string, string>, CloudFormationError>>;
+    /**
+     * List all CloudFormation exports
+     */
+    listExports(callbacks?: CloudFormationCallbacks): Promise<Result<Array<{
+        Name: string;
+        Value: string;
+    }>, CloudFormationError>>;
+    /**
+     * Delete a CloudFormation stack directly via the API.
+     * Unlike CDK destroy, this works on stacks in DELETE_FAILED state.
+     */
+    deleteStack(stackName: string): Promise<Result<void, CloudFormationError>>;
+    /**
+     * Check whether a CloudFormation stack exists and is in a deployable state.
+     */
+    stackExists(stackName: string, client?: CloudFormationClient): Promise<boolean>;
+    /**
+     * Poll stack status until deletion completes, fails, or times out.
+     */
+    waitForDeleteComplete(stackName: string, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+        onProgress?: (message: string) => void;
+    }): Promise<Result<void, CloudFormationError>>;
+}

package/dist/src/services/infrastructure/CloudFormationService.js

@@ -0,0 +1,249 @@
+import { CloudFormationClient, DeleteStackCommand, DescribeStacksCommand, ListExportsCommand } from "@aws-sdk/client-cloudformation";
+import { stackStatusMap } from "../../aws/utils/stackStatus.js";
+import { success, failure } from "@fjall/generator";
+import { BaseServiceError } from "../../types/errors/ServiceError.js";
+import { getErrorMessage, logger } from "@fjall/util";
+import { sleep } from "../../util/sleep.js";
+import { STACK_NOT_FOUND_PATTERN } from "../../aws/utils/cloudformationEvents.js";
+/**
+ * CloudFormation-specific error
+ */
+export class CloudFormationError extends BaseServiceError {
+    errorType;
+    stackName;
+    stackStatus;
+    constructor(message, errorType, stackName, stackStatus, details, recoverable = false) {
+        super(`CFN_${errorType.toUpperCase()}`, message, details, recoverable);
+        this.errorType = errorType;
+        this.stackName = stackName;
+        this.stackStatus = stackStatus;
+    }
+}
+/**
+ * CloudFormation service using the AwsProvider interface.
+ *
+ * Unlike the CLI version which lazily initialises AwsContext,
+ * deploy-core receives a pre-configured AwsProvider at construction.
+ */
+export class CloudFormationService {
+    aws;
+    constructor(aws) {
+        this.aws = aws;
+    }
+    /**
+     * Classify an AWS SDK error into a typed CloudFormationError.
+     */
+    classifyAwsError(error, fallbackMessage, stackName) {
+        const errorCode = error instanceof Error && "code" in error
+            ? String(error.code)
+            : undefined;
+        const errorMessage = getErrorMessage(error);
+        if (errorCode === "CredentialsError" || errorCode === "UnauthorizedError") {
+            return new CloudFormationError(`AWS credentials error: ${errorMessage}`, "auth_error", stackName, undefined, error, false);
+        }
+        if (errorCode === "Throttling" ||
+            errorCode === "TooManyRequestsException") {
+            return new CloudFormationError(`AWS rate limit exceeded: ${errorMessage}`, "throttled", stackName, undefined, error, true);
+        }
+        if (errorCode === "NetworkingError" || errorCode === "ENOTFOUND") {
+            return new CloudFormationError(`Network error: ${errorMessage}`, "network_error", stackName, undefined, error, true);
+        }
+        return new CloudFormationError(`${fallbackMessage}: ${errorMessage}`, "unknown", stackName, undefined, error);
+    }
+    /**
+     * Get stack outputs for services that need them
+     */
+    async getStackOutputs(stackName, callbacks) {
+        callbacks?.onStackCheck?.(stackName);
+        const client = this.aws.getClient(CloudFormationClient);
+        const command = new DescribeStacksCommand({ StackName: stackName });
+        try {
+            const response = await client.send(command);
+            const stack = response.Stacks?.[0];
+            if (!stack?.Outputs) {
+                return success([]);
+            }
+            const outputs = stack.Outputs.map((output) => ({
+                OutputKey: output.OutputKey,
+                OutputValue: output.OutputValue,
+                ExportName: output.ExportName
+            }));
+            callbacks?.onOutputsRetrieved?.(stackName, outputs.length);
+            return success(outputs);
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.name === "ValidationError" &&
+                error.message?.includes(STACK_NOT_FOUND_PATTERN)) {
+                callbacks?.onStackNotFound?.(stackName);
+                return success([]);
+            }
+            return failure(new CloudFormationError(`Failed to get outputs for stack ${stackName}: ${getErrorMessage(error)}`, "unknown", stackName, undefined, error));
+        }
+    }
+    /**
+     * Get stack status directly
+     */
+    async getStackStatus(stackName, callbacks) {
+        callbacks?.onStackCheck?.(stackName);
+        const client = this.aws.getClient(CloudFormationClient);
+        const command = new DescribeStacksCommand({ StackName: stackName });
+        try {
+            const response = await client.send(command);
+            const stack = response.Stacks?.[0];
+            if (!stack) {
+                return success({
+                    status: "DOES_NOT_EXIST",
+                    safeToRedeploy: "Yes",
+                    description: "Stack does not exist yet"
+                });
+            }
+            const status = stack.StackStatus || "UNKNOWN";
+            const statusInfo = stackStatusMap[status] || stackStatusMap["UNKNOWN"];
+            callbacks?.onStackFound?.(stackName, status);
+            return success({
+                status,
+                safeToRedeploy: statusInfo.safeToRedeploy,
+                description: statusInfo.description,
+                statusReason: stack.StackStatusReason
+            });
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.name === "ValidationError" &&
+                error.message?.includes(STACK_NOT_FOUND_PATTERN)) {
+                return success({
+                    status: "DOES_NOT_EXIST",
+                    safeToRedeploy: "Yes",
+                    description: "Stack does not exist yet"
+                });
+            }
+            return failure(this.classifyAwsError(error, `Failed to get stack status for ${stackName}`, stackName));
+        }
+    }
+    /**
+     * Internal helper to list all CloudFormation exports with pagination.
+     */
+    async listAllExports(earlyExit) {
+        const client = this.aws.getClient(CloudFormationClient);
+        const allExports = [];
+        try {
+            let nextToken;
+            do {
+                const command = new ListExportsCommand({ NextToken: nextToken });
+                const response = await client.send(command);
+                const pageExports = response.Exports || [];
+                for (const exp of pageExports) {
+                    if (exp.Name && exp.Value) {
+                        allExports.push({ Name: exp.Name, Value: exp.Value });
+                    }
+                }
+                if (earlyExit?.(pageExports)) {
+                    break;
+                }
+                nextToken = response.NextToken;
+            } while (nextToken);
+            return success(allExports);
+        }
+        catch (error) {
+            return failure(new CloudFormationError(`Failed to list exports: ${getErrorMessage(error)}`, "unknown", undefined, undefined, error, false));
+        }
+    }
+    /**
+     * Look up specific CloudFormation exports by exact name.
+     */
+    async getExportsByNames(names) {
+        if (names.length === 0) {
+            return success(new Map());
+        }
+        const nameSet = new Set(names);
+        const found = new Map();
+        const result = await this.listAllExports((pageExports) => {
+            for (const exp of pageExports) {
+                if (exp.Name && nameSet.has(exp.Name) && exp.Value) {
+                    found.set(exp.Name, exp.Value);
+                }
+            }
+            return found.size >= nameSet.size;
+        });
+        if (!result.success) {
+            return failure(result.error);
+        }
+        return success(found);
+    }
+    /**
+     * List all CloudFormation exports
+     */
+    async listExports(callbacks) {
+        const result = await this.listAllExports();
+        if (result.success) {
+            callbacks?.onExportsRetrieved?.(result.data.length);
+        }
+        return result;
+    }
+    /**
+     * Delete a CloudFormation stack directly via the API.
+     * Unlike CDK destroy, this works on stacks in DELETE_FAILED state.
+     */
+    async deleteStack(stackName) {
+        const client = this.aws.getClient(CloudFormationClient);
+        try {
+            await client.send(new DeleteStackCommand({ StackName: stackName }));
+            return success(undefined);
+        }
+        catch (error) {
+            return failure(this.classifyAwsError(error, `Failed to delete stack ${stackName}`, stackName));
+        }
+    }
+    /**
+     * Check whether a CloudFormation stack exists and is in a deployable state.
+     */
+    async stackExists(stackName, client) {
+        const cfnClient = client ?? this.aws.getClient(CloudFormationClient);
+        try {
+            const response = await cfnClient.send(new DescribeStacksCommand({ StackName: stackName }));
+            const status = response.Stacks?.[0]?.StackStatus;
+            return !!status && status !== "REVIEW_IN_PROGRESS";
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message?.includes(STACK_NOT_FOUND_PATTERN)) {
+                return false;
+            }
+            logger.debug("CloudFormationService", "Error checking stack existence, assuming exists", {
+                stackName,
+                error: getErrorMessage(error)
+            });
+            return true;
+        }
+    }
+    /**
+     * Poll stack status until deletion completes, fails, or times out.
+     */
+    async waitForDeleteComplete(stackName, options) {
+        const timeoutMs = options?.timeoutMs ?? 10 * 60 * 1000;
+        const pollIntervalMs = options?.pollIntervalMs ?? 5000;
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            const statusResult = await this.getStackStatus(stackName);
+            if (!statusResult.success) {
+                if (statusResult.error.recoverable) {
+                    options?.onProgress?.(`Transient error polling stack ${stackName}, retrying: ${statusResult.error.message}`);
+                    await sleep(pollIntervalMs);
+                    continue;
+                }
+                return failure(statusResult.error);
+            }
+            const status = statusResult.data?.status;
+            if (status === "DELETE_COMPLETE" || status === "DOES_NOT_EXIST") {
+                return success(undefined);
+            }
+            if (status === "DELETE_FAILED") {
+                return failure(new CloudFormationError(`Stack ${stackName} deletion failed: ${statusResult.data?.statusReason || "unknown reason"}`, "stack_failed", stackName, status, undefined, false));
+            }
+            options?.onProgress?.(`Stack ${stackName} status: ${status ?? "unknown"}`);
+            await sleep(pollIntervalMs);
+        }
+        return failure(new CloudFormationError(`Timed out waiting for stack ${stackName} deletion after ${Math.round(timeoutMs / 1000)}s`, "timeout", stackName, undefined, undefined, true));
+    }
+}

package/dist/src/services/infrastructure/index.d.ts

@@ -0,0 +1,8 @@
+export { CdkService } from "./CdkService.js";
+export type { CdkContext, CdkOptions, CdkOutput, CheckDifferencesResult, CdkServiceOptions } from "./CdkService.js";
+export { CdkArgumentBuilder } from "./CdkArgumentBuilder.js";
+export { CdkProcessManager } from "./CdkProcessManager.js";
+export { CdkEventMonitor, startStackMonitoring, DEFAULT_DEPLOY_TIMEOUT_MS } from "./CdkEventMonitoring.js";
+export { isCdkError, formatInfrastructureError, getStructuralHint, getSourceContext } from "./CdkErrorFormatter.js";
+export { hasCdkDifferences, parseDiffOutput, type DiffDetails } from "./CdkOutputParser.js";
+export { CloudFormationService, CloudFormationError, type CloudFormationCallbacks } from "./CloudFormationService.js";

package/dist/src/services/infrastructure/index.js

@@ -0,0 +1,7 @@
+export { CdkService } from "./CdkService.js";
+export { CdkArgumentBuilder } from "./CdkArgumentBuilder.js";
+export { CdkProcessManager } from "./CdkProcessManager.js";
+export { CdkEventMonitor, startStackMonitoring, DEFAULT_DEPLOY_TIMEOUT_MS } from "./CdkEventMonitoring.js";
+export { isCdkError, formatInfrastructureError, getStructuralHint, getSourceContext } from "./CdkErrorFormatter.js";
+export { hasCdkDifferences, parseDiffOutput } from "./CdkOutputParser.js";
+export { CloudFormationService, CloudFormationError } from "./CloudFormationService.js";

package/dist/src/services/supporting/CdkContextBuilder.d.ts

@@ -0,0 +1,49 @@
+import type { DeploymentContext } from "../../types/deployment/DeploymentTypes.js";
+import type { CallerIdentity } from "../../types/deployment/DeploymentServiceTypes.js";
+import type { StackOutputsRecord } from "../../types/deployment/cloudformation.js";
+import type { OrgConfig } from "../../types/orgConfig.js";
+/**
+ * Builder for creating standardised CDK deployment contexts.
+ * Ensures all required fields are present with proper defaults.
+ *
+ * Unlike the CLI version, this uses OrgConfig (injected) rather than
+ * Config.loadConfig() (file-based) for region resolution.
+ */
+export declare class CdkContextBuilder {
+    /**
+     * Build a standardised deployment context for CDK operations.
+     * Ensures all required fields are present with proper defaults.
+     */
+    static buildDeploymentContext(input: {
+        deployType: "application" | "organisation" | "platform" | "account";
+        target: string;
+        path: string;
+        callerIdentity?: CallerIdentity;
+        region?: string;
+        stackOutputs?: StackOutputsRecord;
+        isManagedAccount?: boolean;
+        accountName?: string;
+        logPath?: string;
+        imageVersion?: string;
+        orgId?: string;
+        rootId?: string;
+        managementAccountId?: string;
+        ipamPoolId?: string;
+        fjallOrgId?: string;
+        orgConfig?: string;
+    }, options: {
+        verbose?: boolean;
+        infraOnly?: boolean;
+    }, orgConfig?: OrgConfig): DeploymentContext;
+    /**
+     * Build context from an existing context with updated options
+     */
+    static updateContext(existingContext: DeploymentContext, updates: Partial<{
+        options: {
+            verbose?: boolean;
+            infraOnly?: boolean;
+        };
+        stackOutputs: StackOutputsRecord;
+        region: string;
+    }>): DeploymentContext;
+}

package/dist/src/services/supporting/CdkContextBuilder.js

@@ -0,0 +1,44 @@
+import { DEFAULT_REGION } from "@fjall/generator";
+/**
+ * Builder for creating standardised CDK deployment contexts.
+ * Ensures all required fields are present with proper defaults.
+ *
+ * Unlike the CLI version, this uses OrgConfig (injected) rather than
+ * Config.loadConfig() (file-based) for region resolution.
+ */
+export class CdkContextBuilder {
+    /**
+     * Build a standardised deployment context for CDK operations.
+     * Ensures all required fields are present with proper defaults.
+     */
+    static buildDeploymentContext(input, options, orgConfig) {
+        return {
+            deployType: input.deployType,
+            target: input.target,
+            path: input.path,
+            options: options,
+            stackOutputs: input.stackOutputs || {},
+            callerIdentity: input.callerIdentity,
+            region: input.region || orgConfig?.primaryRegion || DEFAULT_REGION,
+            isManagedAccount: input.isManagedAccount,
+            accountName: input.accountName,
+            logPath: input.logPath,
+            imageVersion: input.imageVersion,
+            orgId: input.orgId,
+            rootId: input.rootId,
+            managementAccountId: input.managementAccountId,
+            ipamPoolId: input.ipamPoolId,
+            fjallOrgId: input.fjallOrgId,
+            orgConfig: input.orgConfig
+        };
+    }
+    /**
+     * Build context from an existing context with updated options
+     */
+    static updateContext(existingContext, updates) {
+        return {
+            ...existingContext,
+            ...updates
+        };
+    }
+}

package/dist/src/services/supporting/TemplateHashService.d.ts

@@ -0,0 +1,67 @@
+/**
+ * TemplateHashService - Hash-based change detection for CDK templates
+ *
+ * Replaces slow CDK diff with fast local hash comparison.
+ * Uses SHA-256 hashing of synthesised templates.
+ */
+import { type Result } from "@fjall/generator";
+import { BaseServiceError } from "../../types/errors/ServiceError.js";
+/**
+ * TemplateHash-specific error types
+ */
+export declare class TemplateHashError extends BaseServiceError {
+    readonly errorType: "read_failed" | "hash_failed" | "state_write_failed" | "cdk_out_not_found";
+    constructor(message: string, errorType: "read_failed" | "hash_failed" | "state_write_failed" | "cdk_out_not_found", details?: unknown, recoverable?: boolean);
+}
+/**
+ * Result of comparing template hashes with state
+ */
+export interface TemplateComparisonResult {
+    /** Map of stack name to whether it has changes (true = changed or new) */
+    stackChanges: Map<string, boolean>;
+    /** Current hashes for all stacks */
+    currentHashes: Map<string, string>;
+    /** Number of stacks with changes */
+    changedCount: number;
+    /** Number of stacks unchanged */
+    unchangedCount: number;
+}
+/**
+ * Template Hash Service - provides hash-based change detection
+ */
+export declare class TemplateHashService {
+    /**
+     * Compute SHA-256 hash of a template file
+     */
+    computeTemplateHash(templatePath: string): Promise<Result<string, TemplateHashError>>;
+    /**
+     * Get hashes for all templates in cdk.out directory.
+     * Returns map of stack name to hash.
+     */
+    getTemplateHashes(cdkOutPath: string): Promise<Result<Map<string, string>, TemplateHashError>>;
+    /**
+     * Compare current template hashes with stored state.
+     * Returns which stacks have changed.
+     */
+    compareWithState(currentHashes: Map<string, string>, appPath: string): Promise<Result<TemplateComparisonResult, TemplateHashError>>;
+    /**
+     * Update state file with new hashes after successful deployment
+     */
+    updateStateAfterDeploy(appPath: string, deployedStacks: Map<string, string>, stackStatuses?: Map<string, string>): Promise<Result<void, TemplateHashError>>;
+    /**
+     * Get state file path for an application (exposed for testing/logging)
+     */
+    getStateFilePath(appPath: string): string;
+    /**
+     * Check if a specific stack has changes
+     */
+    stackHasChanges(comparison: TemplateComparisonResult, stackName: string): boolean;
+    /**
+     * Get list of stacks that have changes
+     */
+    getChangedStacks(comparison: TemplateComparisonResult): string[];
+    /**
+     * Get list of stacks that are unchanged
+     */
+    getUnchangedStacks(comparison: TemplateComparisonResult): string[];
+}

package/dist/src/services/supporting/TemplateHashService.js

@@ -0,0 +1,152 @@
+/**
+ * TemplateHashService - Hash-based change detection for CDK templates
+ *
+ * Replaces slow CDK diff with fast local hash comparison.
+ * Uses SHA-256 hashing of synthesised templates.
+ */
+import { createHash } from "crypto";
+import { readFile, readdir } from "fs/promises";
+import { join, basename } from "path";
+import { fileExists } from "../../util/fsHelpers.js";
+import { success, failure } from "@fjall/generator";
+import { BaseServiceError } from "../../types/errors/ServiceError.js";
+import { readStateFile, writeStateFile, createEmptyState, updateTemplateHash, getStateFilePath } from "../../types/FjallState.js";
+/**
+ * TemplateHash-specific error types
+ */
+export class TemplateHashError extends BaseServiceError {
+    errorType;
+    constructor(message, errorType, details, recoverable = false) {
+        super(`TEMPLATE_HASH_${errorType.toUpperCase()}`, message, details, recoverable);
+        this.errorType = errorType;
+    }
+}
+/** CDK template file extension */
+const TEMPLATE_EXTENSION = ".template.json";
+/**
+ * Template Hash Service - provides hash-based change detection
+ */
+export class TemplateHashService {
+    /**
+     * Compute SHA-256 hash of a template file
+     */
+    async computeTemplateHash(templatePath) {
+        try {
+            const content = await readFile(templatePath, "utf-8");
+            const normalised = JSON.stringify(JSON.parse(content));
+            const hash = createHash("sha256").update(normalised).digest("hex");
+            return success(hash);
+        }
+        catch (error) {
+            return failure(new TemplateHashError(`Failed to hash template: ${templatePath}`, "hash_failed", { path: templatePath, error }));
+        }
+    }
+    /**
+     * Get hashes for all templates in cdk.out directory.
+     * Returns map of stack name to hash.
+     */
+    async getTemplateHashes(cdkOutPath) {
+        if (!(await fileExists(cdkOutPath))) {
+            return failure(new TemplateHashError(`CDK output directory not found: ${cdkOutPath}`, "cdk_out_not_found", { path: cdkOutPath }));
+        }
+        try {
+            const files = await readdir(cdkOutPath);
+            const templateFiles = files.filter((f) => f.endsWith(TEMPLATE_EXTENSION));
+            const hashes = new Map();
+            for (const file of templateFiles) {
+                const stackName = basename(file, TEMPLATE_EXTENSION);
+                const templatePath = join(cdkOutPath, file);
+                const hashResult = await this.computeTemplateHash(templatePath);
+                if (!hashResult.success) {
+                    return failure(hashResult.error);
+                }
+                hashes.set(stackName, hashResult.data);
+            }
+            return success(hashes);
+        }
+        catch (error) {
+            return failure(new TemplateHashError(`Failed to read CDK output directory: ${cdkOutPath}`, "read_failed", { path: cdkOutPath, error }));
+        }
+    }
+    /**
+     * Compare current template hashes with stored state.
+     * Returns which stacks have changed.
+     */
+    async compareWithState(currentHashes, appPath) {
+        const state = await readStateFile(appPath);
+        const stackChanges = new Map();
+        let changedCount = 0;
+        let unchangedCount = 0;
+        for (const [stackName, currentHash] of currentHashes) {
+            const storedEntry = state?.templateHashes[stackName];
+            const hasChanged = !storedEntry || storedEntry.hash !== currentHash;
+            stackChanges.set(stackName, hasChanged);
+            if (hasChanged) {
+                changedCount++;
+            }
+            else {
+                unchangedCount++;
+            }
+        }
+        // Detect stacks that were previously deployed but no longer synthesised (removed stacks)
+        if (state?.templateHashes) {
+            for (const stackName of Object.keys(state.templateHashes)) {
+                if (!currentHashes.has(stackName)) {
+                    stackChanges.set(stackName, true);
+                    changedCount++;
+                }
+            }
+        }
+        return success({
+            stackChanges,
+            currentHashes,
+            changedCount,
+            unchangedCount
+        });
+    }
+    /**
+     * Update state file with new hashes after successful deployment
+     */
+    async updateStateAfterDeploy(appPath, deployedStacks, stackStatuses) {
+        try {
+            let state = (await readStateFile(appPath)) ?? createEmptyState();
+            for (const [stackName, hash] of deployedStacks) {
+                const status = stackStatuses?.get(stackName);
+                state = updateTemplateHash(state, stackName, hash, status);
+            }
+            await writeStateFile(appPath, state);
+            return success(undefined);
+        }
+        catch (error) {
+            return failure(new TemplateHashError(`Failed to write state file: ${getStateFilePath(appPath)}`, "state_write_failed", { appPath, error }));
+        }
+    }
+    /**
+     * Get state file path for an application (exposed for testing/logging)
+     */
+    getStateFilePath(appPath) {
+        return getStateFilePath(appPath);
+    }
+    /**
+     * Check if a specific stack has changes
+     */
+    stackHasChanges(comparison, stackName) {
+        return comparison.stackChanges.get(stackName) ?? true;
+    }
+    /**
+     * Get list of stacks that have changes
+     */
+    getChangedStacks(comparison) {
+        return Array.from(comparison.stackChanges.entries())
+            .filter(([, hasChanges]) => hasChanges)
+            .map(([stackName]) => stackName);
+    }
+    /**
+     * Get list of stacks that are unchanged
+     */
+    getUnchangedStacks(comparison) {
+        return Array.from(comparison.stackChanges.entries())
+            .filter(([, hasChanges]) => !hasChanges)
+            .map(([stackName]) => stackName);
+    }
+}