@fjall/deploy-core 0.89.5 → 0.94.0

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

@@ -1,228 +0,0 @@
-/**
- * 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/errors.d.ts

@@ -1,26 +0,0 @@
-export declare class AWSError extends Error {
-    readonly code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
-}
-export declare class NoRolesFoundError extends AWSError {
-    constructor(accountId?: string);
-}
-export declare class InvalidCredentialsError extends AWSError {
-    constructor(message: string);
-}
-export declare class SSOTokenExpiredError extends AWSError {
-    constructor();
-}
-export declare class MissingRegionError extends AWSError {
-    constructor();
-}
-export declare class ProfileNotFoundError extends AWSError {
-    constructor(profileName: string);
-}
-export declare function isAWSError(error: unknown): error is AWSError;
-export declare function isNoRolesFoundError(error: unknown): error is NoRolesFoundError;
-export declare function isSSOUnauthorizedError(error: unknown): boolean;
-export declare class CommandError extends AWSError {
-    readonly tip?: string;
-    constructor(message: string, tip?: string);
-}

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

@@ -1,59 +0,0 @@
-export class AWSError extends Error {
-    code;
-    constructor(message, code) {
-        super(message);
-        this.code = code;
-        this.name = this.constructor.name;
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
-export class NoRolesFoundError extends AWSError {
-    constructor(accountId) {
-        const message = accountId
-            ? `No roles found for account ${accountId}`
-            : "No roles found for this account";
-        super(message, "NO_ROLES_FOUND");
-    }
-}
-export class InvalidCredentialsError extends AWSError {
-    constructor(message) {
-        super(message, "INVALID_CREDENTIALS");
-    }
-}
-export class SSOTokenExpiredError extends AWSError {
-    constructor() {
-        super("SSO token has expired", "SSO_TOKEN_EXPIRED");
-    }
-}
-export class MissingRegionError extends AWSError {
-    constructor() {
-        super("Region is missing in AWS configuration and environment", "MISSING_REGION");
-    }
-}
-export class ProfileNotFoundError extends AWSError {
-    constructor(profileName) {
-        super(`AWS profile '${profileName}' not found`, "PROFILE_NOT_FOUND");
-    }
-}
-export function isAWSError(error) {
-    return error instanceof AWSError;
-}
-export function isNoRolesFoundError(error) {
-    return error instanceof NoRolesFoundError;
-}
-export function isSSOUnauthorizedError(error) {
-    if (!error || typeof error !== "object")
-        return false;
-    return (("name" in error && error.name === "UnauthorizedException") ||
-        ("Code" in error && error.Code === "UnauthorizedException") ||
-        ("__type" in error &&
-            typeof error.__type === "string" &&
-            error.__type.includes("UnauthorizedException")));
-}
-export class CommandError extends AWSError {
-    tip;
-    constructor(message, tip) {
-        super(message, "COMMAND_ERROR");
-        this.tip = tip;
-    }
-}

package/dist/src/util/fsHelpers.d.ts

@@ -1,4 +0,0 @@
-/**
- * Async check for file existence. Replaces blocking existsSync().
- */
-export declare function fileExists(filePath: string): Promise<boolean>;

package/dist/src/util/fsHelpers.js

@@ -1,16 +0,0 @@
-/**
- * Async file system helpers.
- */
-import { access, constants } from "fs/promises";
-/**
- * Async check for file existence. Replaces blocking existsSync().
- */
-export async function fileExists(filePath) {
-    try {
-        await access(filePath, constants.F_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/src/util/securityHelpers.d.ts

@@ -1,31 +0,0 @@
-/**
- * Security helpers for spawn operations
- *
- * Provides environment variable filtering and credential masking
- * to prevent command injection and credential leakage.
- */
-/**
- * Environment variables that MUST NOT be passed from user input to spawned processes.
- * These can be exploited for:
- * - Code execution hijacking (PATH, NODE_OPTIONS)
- * - Dynamic linker injection (LD_PRELOAD, DYLD_INSERT_LIBRARIES)
- * - Interpreter code injection (PYTHONPATH, RUBYLIB)
- * - Credential/identity hijacking (HOME, AWS_CONFIG_FILE)
- * - Shell injection (BASH_ENV, ENV)
- */
-export declare const DANGEROUS_ENV_VARS: Set<string>;
-/**
- * Filter dangerous environment variables from a record.
- * Returns a new object with only safe environment variables.
- */
-export declare function filterDangerousEnvVars(env: Record<string, string | undefined>): Record<string, string | undefined>;
-/**
- * Mask sensitive information in output strings to prevent credential leakage.
- * Patterns: postgres://user:pass@host, password=xxx, secret=xxx, apikey=xxx
- */
-export declare function maskSensitiveOutput(output: string): string;
-/**
- * Parse a shell command string into an array of arguments.
- * Handles single quotes, double quotes, and escaped characters.
- */
-export declare function parseShellArgs(command: string): string[];

package/dist/src/util/securityHelpers.js

@@ -1,124 +0,0 @@
-/**
- * Security helpers for spawn operations
- *
- * Provides environment variable filtering and credential masking
- * to prevent command injection and credential leakage.
- */
-/**
- * Environment variables that MUST NOT be passed from user input to spawned processes.
- * These can be exploited for:
- * - Code execution hijacking (PATH, NODE_OPTIONS)
- * - Dynamic linker injection (LD_PRELOAD, DYLD_INSERT_LIBRARIES)
- * - Interpreter code injection (PYTHONPATH, RUBYLIB)
- * - Credential/identity hijacking (HOME, AWS_CONFIG_FILE)
- * - Shell injection (BASH_ENV, ENV)
- */
-export const DANGEROUS_ENV_VARS = new Set([
-    // Execution hijacking
-    // NOTE: PATH is intentionally NOT included here - it's required for spawn() to find executables
-    // See: aiDocs/patterns/spawn-security-pattern.md for rationale
-    "NODE_OPTIONS",
-    "NODE_PATH",
-    "NODE_EXTRA_CA_CERTS",
-    "NODE_DEBUG",
-    "NODE_PRESERVE_SYMLINKS",
-    // Dynamic linker injection (Linux)
-    "LD_PRELOAD",
-    "LD_LIBRARY_PATH",
-    "LD_AUDIT",
-    "LD_BIND_NOW",
-    // Dynamic linker injection (macOS)
-    "DYLD_INSERT_LIBRARIES",
-    "DYLD_LIBRARY_PATH",
-    "DYLD_FRAMEWORK_PATH",
-    // Interpreter code injection
-    "PYTHONPATH",
-    "PYTHONSTARTUP",
-    "PERL5LIB",
-    "PERL5OPT",
-    "RUBYLIB",
-    "RUBYOPT",
-    // Credential/identity hijacking
-    "HOME",
-    "XDG_CONFIG_HOME",
-    "AWS_SHARED_CREDENTIALS_FILE",
-    "AWS_CONFIG_FILE",
-    // Shell injection
-    "SHELL",
-    "BASH_ENV",
-    "ENV",
-    "ZDOTDIR"
-]);
-/**
- * Filter dangerous environment variables from a record.
- * Returns a new object with only safe environment variables.
- */
-export function filterDangerousEnvVars(env) {
-    return Object.fromEntries(Object.entries(env).filter(([key]) => !DANGEROUS_ENV_VARS.has(key.toUpperCase())));
-}
-/**
- * Mask sensitive information in output strings to prevent credential leakage.
- * Patterns: postgres://user:pass@host, password=xxx, secret=xxx, apikey=xxx
- */
-export function maskSensitiveOutput(output) {
-    return (output
-        // Mask postgres/mysql connection strings with credentials
-        .replace(/(\w+:\/\/[^:]+:)[^@]+(@)/gi, "$1***$2")
-        // Mask common credential patterns
-        .replace(/(password|passwd|secret|api[_-]?key|token|auth|credential)[=:]["']?[^\s"']+/gi, "$1=***")
-        // Mask GitHub tokens (ghu_, ghs_, ghp_, github_pat_) appearing as bare values
-        .replace(/\b(ghu_|ghs_|ghp_|github_pat_)[A-Za-z0-9_]+/g, "***")
-        // Mask AWS secret access keys (40 chars, base64-ish) — only when preceded
-        // by a known credential context to avoid false-positive masking of ARNs,
-        // physical resource IDs, and other legitimate 40-char strings.
-        .replace(/(?<=AWS_SECRET_ACCESS_KEY=|SecretAccessKey[=:]\s*|"secretAccessKey":\s*")[A-Za-z0-9/+=]{40}/g, "***"));
-}
-/**
- * Parse a shell command string into an array of arguments.
- * Handles single quotes, double quotes, and escaped characters.
- */
-export function parseShellArgs(command) {
-    const args = [];
-    let current = "";
-    let inSingleQuote = false;
-    let inDoubleQuote = false;
-    let escaped = false;
-    for (const char of command) {
-        if (escaped) {
-            current += char;
-            escaped = false;
-            continue;
-        }
-        if (char === "\\") {
-            escaped = true;
-            continue;
-        }
-        if (char === "'" && !inDoubleQuote) {
-            inSingleQuote = !inSingleQuote;
-            continue;
-        }
-        if (char === '"' && !inSingleQuote) {
-            inDoubleQuote = !inDoubleQuote;
-            continue;
-        }
-        if (char === " " && !inSingleQuote && !inDoubleQuote) {
-            if (current) {
-                args.push(current);
-                current = "";
-            }
-            continue;
-        }
-        current += char;
-    }
-    if (inSingleQuote || inDoubleQuote) {
-        // Unbalanced quotes — include the partial token. Callers should validate
-        // their input if quote-balancing is required.
-        if (current) {
-            args.push(current);
-        }
-    }
-    else if (current) {
-        args.push(current);
-    }
-    return args;
-}

package/dist/src/util/singleton.d.ts

@@ -1,2 +0,0 @@
-/** Lazily creates one instance per factory — shared singleton helper. */
-export declare function singleton<T>(factory: () => T): () => T;

package/dist/src/util/singleton.js

@@ -1,9 +0,0 @@
-/** Lazily creates one instance per factory — shared singleton helper. */
-export function singleton(factory) {
-    let instance;
-    return () => {
-        if (instance === undefined)
-            instance = factory();
-        return instance;
-    };
-}

package/dist/src/util/sleep.d.ts

@@ -1,4 +0,0 @@
-/**
- * Delay execution for the given number of milliseconds.
- */
-export declare const sleep: (ms: number) => Promise<void>;

package/dist/src/util/sleep.js

@@ -1,4 +0,0 @@
-/**
- * Delay execution for the given number of milliseconds.
- */
-export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));