@fjall/deploy-core 0.89.2

package/dist/src/types/operations.js

@@ -0,0 +1,285 @@
+import { isOpenNextPattern } from "./patternDetection.js";
+import { toPascalCase } from "@fjall/util";
+/**
+ * Application infrastructure stacks
+ */
+export const APPLICATION_STACKS = {
+    NETWORK: "Network",
+    DATABASE: "Database",
+    STORAGE: "Storage",
+    COMPUTE: "Compute",
+    CDN: "Cdn",
+    MESSAGING: "Messaging"
+};
+/**
+ * Organisation infrastructure types
+ * Note: These are deployment types, not stacks - each maps to a single CDK stack
+ */
+export const ORGANISATION_TYPES = {
+    ORGANISATION: "organisation",
+    PLATFORM: "platform",
+    ACCOUNT: "account"
+};
+/**
+ * Type guards for safe type narrowing
+ */
+export function isApplicationOperation(op) {
+    return op.kind === "application";
+}
+export function isOrganisationOperation(op) {
+    return op.kind === "organisation";
+}
+/**
+ * Stack ordering for application deployments
+ */
+export const APPLICATION_DEPLOY_ORDER = [
+    APPLICATION_STACKS.NETWORK,
+    APPLICATION_STACKS.DATABASE,
+    APPLICATION_STACKS.COMPUTE
+];
+export const APPLICATION_DESTROY_ORDER = [
+    APPLICATION_STACKS.COMPUTE,
+    APPLICATION_STACKS.DATABASE,
+    APPLICATION_STACKS.NETWORK
+];
+/**
+ * Stack ordering for OpenNext (Next.js/Payload) deployments
+ * These patterns require additional infrastructure: S3, DynamoDB, SQS, CloudFront
+ */
+export const OPENNEXT_DEPLOY_ORDER = [
+    APPLICATION_STACKS.NETWORK,
+    APPLICATION_STACKS.STORAGE,
+    APPLICATION_STACKS.MESSAGING,
+    APPLICATION_STACKS.DATABASE,
+    APPLICATION_STACKS.COMPUTE,
+    APPLICATION_STACKS.CDN
+];
+/**
+ * Stack ordering for OpenNext destroy operations (reverse of deploy order)
+ * CDN must be destroyed first as it depends on Compute, then work backwards
+ */
+export const OPENNEXT_DESTROY_ORDER = [
+    APPLICATION_STACKS.CDN,
+    APPLICATION_STACKS.COMPUTE,
+    APPLICATION_STACKS.DATABASE,
+    APPLICATION_STACKS.MESSAGING,
+    APPLICATION_STACKS.STORAGE,
+    APPLICATION_STACKS.NETWORK
+];
+/**
+ * Parallel deployment groups for concurrent stack deployment
+ * Stacks within each phase can be deployed in parallel.
+ *
+ * Dependency structure:
+ * - Phase 1: Network (required by all other stacks)
+ * - Phase 2: Storage, Messaging, Database (independent of each other, only need Network)
+ * - Phase 3: Compute (needs Database outputs)
+ * - Phase 4: CDN (needs Compute outputs)
+ */
+export const PARALLEL_DEPLOY_GROUPS = {
+    PHASE_1: {
+        phase: 1,
+        stacks: [APPLICATION_STACKS.NETWORK],
+        description: "Network infrastructure"
+    },
+    PHASE_2: {
+        phase: 2,
+        stacks: [
+            APPLICATION_STACKS.STORAGE,
+            APPLICATION_STACKS.MESSAGING,
+            APPLICATION_STACKS.DATABASE
+        ],
+        description: "Storage and database resources (parallel)"
+    },
+    PHASE_3: {
+        phase: 3,
+        stacks: [APPLICATION_STACKS.COMPUTE],
+        description: "Compute resources"
+    },
+    PHASE_4: {
+        phase: 4,
+        stacks: [APPLICATION_STACKS.CDN],
+        description: "CDN distribution"
+    }
+};
+/**
+ * Parallel deployment groups for OpenNext (Next.js/Payload) deployments
+ * Optimised to run BUILD in parallel with infrastructure stacks.
+ */
+export const OPENNEXT_PARALLEL_GROUPS = {
+    /** Regular Next.js: BUILD + all Phase 2 stacks in parallel */
+    NEXTJS_PARALLEL: {
+        stacks: [
+            APPLICATION_STACKS.STORAGE,
+            APPLICATION_STACKS.MESSAGING,
+            APPLICATION_STACKS.DATABASE
+        ],
+        includeBuild: true,
+        description: "Build + Storage/Messaging/Database (parallel)"
+    },
+    /** Payload: BUILD + remaining stacks (after Database + migrations) */
+    PAYLOAD_PARALLEL: {
+        stacks: [APPLICATION_STACKS.STORAGE, APPLICATION_STACKS.MESSAGING],
+        includeBuild: true,
+        description: "Build + Storage/Messaging (parallel)"
+    }
+};
+/**
+ * Get all parallel deploy groups as an ordered array
+ */
+export function getParallelDeployGroups() {
+    return [
+        PARALLEL_DEPLOY_GROUPS.PHASE_1,
+        PARALLEL_DEPLOY_GROUPS.PHASE_2,
+        PARALLEL_DEPLOY_GROUPS.PHASE_3,
+        PARALLEL_DEPLOY_GROUPS.PHASE_4
+    ];
+}
+/**
+ * Parallel destroy groups for OpenNext destroy operations.
+ * Reverse of deploy order to respect dependencies.
+ */
+export const PARALLEL_DESTROY_GROUPS = {
+    PHASE_1: {
+        phase: 1,
+        stacks: [APPLICATION_STACKS.CDN],
+        description: "CDN distribution"
+    },
+    PHASE_2: {
+        phase: 2,
+        stacks: [APPLICATION_STACKS.COMPUTE],
+        description: "Compute resources"
+    },
+    PHASE_3: {
+        phase: 3,
+        stacks: [
+            APPLICATION_STACKS.DATABASE,
+            APPLICATION_STACKS.MESSAGING,
+            APPLICATION_STACKS.STORAGE
+        ],
+        description: "Database, messaging, and storage (parallel)"
+    },
+    PHASE_4: {
+        phase: 4,
+        stacks: [APPLICATION_STACKS.NETWORK],
+        description: "Network infrastructure"
+    }
+};
+/**
+ * Get all parallel destroy groups as an ordered array
+ */
+export function getParallelDestroyGroups() {
+    return [
+        PARALLEL_DESTROY_GROUPS.PHASE_1,
+        PARALLEL_DESTROY_GROUPS.PHASE_2,
+        PARALLEL_DESTROY_GROUPS.PHASE_3,
+        PARALLEL_DESTROY_GROUPS.PHASE_4
+    ];
+}
+/**
+ * Deploy tier priority — lower number deploys first, higher destroys first.
+ * Used for dynamic ordering based on manifest-detected resources.
+ */
+const STACK_DEPLOY_TIER = {
+    Network: 1,
+    Storage: 2,
+    Messaging: 2,
+    Database: 2,
+    Compute: 3,
+    Cdn: 4
+};
+/**
+ * Get deployment order based on application configuration.
+ *
+ * Strategies:
+ * 1. OpenNext (pattern = "payload" or "nextjs"): Predefined order (build orchestration)
+ * 2. Dynamic: Include only detected stacks, ordered by tier
+ * 3. Fallback: Standard order (no manifest available)
+ */
+export function getApplicationDeployOrder(options) {
+    const { pattern, resources } = options ?? {};
+    if (isOpenNextPattern(pattern)) {
+        return OPENNEXT_DEPLOY_ORDER;
+    }
+    if (resources) {
+        return buildOrderFromResources(resources, "asc");
+    }
+    return APPLICATION_DEPLOY_ORDER;
+}
+/**
+ * Get destroy order based on application configuration.
+ * Destroy order respects dependencies (reverse of deploy order).
+ */
+export function getApplicationDestroyOrder(options) {
+    const { pattern, resources } = options ?? {};
+    if (isOpenNextPattern(pattern)) {
+        return OPENNEXT_DESTROY_ORDER;
+    }
+    if (resources) {
+        return buildOrderFromResources(resources, "desc");
+    }
+    return APPLICATION_DESTROY_ORDER;
+}
+/**
+ * Build a stack order from resource flags, sorted by tier priority.
+ */
+function buildOrderFromResources(resources, direction) {
+    const stacks = [];
+    if (resources.hasNetwork)
+        stacks.push(APPLICATION_STACKS.NETWORK);
+    if (resources.hasStorage)
+        stacks.push(APPLICATION_STACKS.STORAGE);
+    if (resources.hasMessaging)
+        stacks.push(APPLICATION_STACKS.MESSAGING);
+    if (resources.hasDatabase)
+        stacks.push(APPLICATION_STACKS.DATABASE);
+    if (resources.hasCompute)
+        stacks.push(APPLICATION_STACKS.COMPUTE);
+    if (resources.hasCdn)
+        stacks.push(APPLICATION_STACKS.CDN);
+    return stacks.sort((a, b) => {
+        const diff = STACK_DEPLOY_TIER[a] - STACK_DEPLOY_TIER[b];
+        return direction === "asc" ? diff : -diff;
+    });
+}
+/**
+ * Helper functions for stack operations
+ */
+export { toPascalCase };
+export function getApplicationStackName(appName, stack) {
+    return `${toPascalCase(appName)}${stack}`;
+}
+export function getOrganisationStackName(type) {
+    switch (type) {
+        case "organisation":
+            return "Organisation";
+        case "platform":
+            return "Platform";
+        case "account":
+            return "Account";
+        default: {
+            const _exhaustive = type;
+            throw new Error(`Unsupported organisation type: ${String(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Type guard for ApplicationStack
+ */
+export function isApplicationStack(value) {
+    return Object.values(APPLICATION_STACKS).includes(value);
+}
+/**
+ * Step name generators for UI display
+ */
+export function getApplicationStepName(stack, action) {
+    const verb = action === "deploy" ? "Deploying" : "Destroying";
+    return `${verb} ${stack.toLowerCase()} infrastructure`;
+}
+/**
+ * Step ID generators for tracking
+ */
+export function getApplicationStepId(stack, action) {
+    const suffix = action === "destroy" ? "-destroy" : "";
+    return `${stack.toLowerCase()}${suffix}`;
+}

package/dist/src/types/orgConfig.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Organisation-level configuration.
+ *
+ * This config is injected by the caller, not read from disk:
+ * - CLI: fetches from GET /api/organisation-config (cached locally with TTL)
+ * - Worker: reads from DB (Organization + ConnectedAwsAccount models)
+ *
+ * Passed to CDK via -c orgConfig=<json> context at synthesis time.
+ * See: investigations/2026-03-16-config-split-investigation.md
+ */
+export interface OrgConfig {
+    providerAccounts: ProviderAccount[];
+    primaryRegion?: string;
+    secondaryRegions?: string[];
+    disasterRecoveryRegion?: string;
+    rootOidcRoleArn?: string;
+    ssoSessions?: Record<string, SSOSession>;
+}
+export interface ProviderAccount {
+    id: string;
+    name: string;
+    environment: string;
+    managed?: boolean;
+}
+export interface SSOSession {
+    ssoRegion: string;
+    ssoStartUrl: string;
+}

package/dist/src/types/orgConfig.js

@@ -0,0 +1,11 @@
+/**
+ * Organisation-level configuration.
+ *
+ * This config is injected by the caller, not read from disk:
+ * - CLI: fetches from GET /api/organisation-config (cached locally with TTL)
+ * - Worker: reads from DB (Organization + ConnectedAwsAccount models)
+ *
+ * Passed to CDK via -c orgConfig=<json> context at synthesis time.
+ * See: investigations/2026-03-16-config-split-investigation.md
+ */
+export {};

package/dist/src/types/params.d.ts

@@ -0,0 +1,74 @@
+import type { Result } from "@fjall/generator";
+import type { AwsCredentials, DeployIdentity } from "./credentials.js";
+import type { DeployCallbacks } from "./callbacks.js";
+import type { ApiClientInterface } from "./apiClient.js";
+import type { OrgConfig } from "./orgConfig.js";
+import type { DockerProvider } from "../orchestration/dockerInterface.js";
+import type { DomainDeployProvider } from "../orchestration/domainInterface.js";
+export interface DeployParams {
+    /** Deployment target name (e.g., "my-app", "organisation", "platform", "account-prod") */
+    target: string;
+    /** Absolute path to the repository root containing fjall-config.json */
+    workingDirectory: string;
+    /** AWS credentials for the deployment. deploy-core never resolves these itself. */
+    awsCredentials: AwsCredentials;
+    /** Typed callbacks for progress events. CLI and worker implement differently. */
+    callbacks: DeployCallbacks;
+    /** Deployment options */
+    options?: DeployOptions;
+    /**
+     * Org-level config (accounts, regions, OIDC).
+     * CLI: fetches from GET /api/organisation-config (cached locally with TTL).
+     * Worker: reads from DB (Organization + ConnectedAwsAccount models).
+     * Passed to CDK via -c orgConfig=<json> context.
+     * See: investigations/2026-03-16-config-split-investigation.md
+     */
+    orgConfig?: OrgConfig;
+    /**
+     * Pre-fetched identity for org deployments.
+     * CLI: omit this, provide apiClient instead (fetches from API).
+     * Worker: provide this from DB, omit apiClient.
+     */
+    identity?: DeployIdentity;
+    /**
+     * Optional API client for non-critical operations (app registration,
+     * account verification, config push). Worker omits this — those
+     * operations are handled by the webapp directly.
+     */
+    apiClient?: ApiClientInterface;
+    /**
+     * Optional Docker provider for building and pushing container images.
+     * CLI and worker provide their own implementations.
+     * If omitted, Docker operations are skipped.
+     */
+    dockerProvider?: DockerProvider;
+    /**
+     * Optional domain deployment provider for organisation cascade.
+     * CLI provides an implementation backed by DomainService + zone files.
+     * Worker omits this (domains managed via CLI only for now).
+     * If omitted, the domains cascade phase is skipped.
+     */
+    domainProvider?: DomainDeployProvider;
+}
+export interface DeployOptions {
+    skipConfirmation?: boolean;
+    force?: boolean;
+    cascade?: boolean;
+    skipBuild?: boolean;
+    verbose?: boolean;
+    infraOnly?: boolean;
+    deployOnly?: boolean;
+    passThroughCDK?: boolean;
+    environment?: string;
+}
+export type DeploymentType = "application" | "organisation";
+export interface DeployResult {
+    target: string;
+    deploymentType: DeploymentType;
+    /** Stack outputs (website URL, OIDC role ARN, etc.) */
+    outputs?: Record<string, string>;
+    /** Duration in milliseconds */
+    durationMs?: number;
+}
+/** Re-export Result from generator for consumers. */
+export type { Result };

package/dist/src/types/params.js

@@ -0,0 +1 @@
+export {};

package/dist/src/types/patternDetection.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pattern detection types and functions.
+ *
+ * Contains both pure predicates used by operations.ts and
+ * filesystem-based detection functions used by orchestration services.
+ */
+import type { PatternType } from "@fjall/generator";
+declare const OPENNEXT_PATTERNS_ARRAY: readonly ["payload", "nextjs"];
+export type OpenNextPattern = (typeof OPENNEXT_PATTERNS_ARRAY)[number];
+export declare const OPENNEXT_PATTERNS: Set<string>;
+export declare function isOpenNextPattern(pattern: string | undefined | null): pattern is OpenNextPattern;
+export interface AppResourceFlags {
+    hasNetwork: boolean;
+    hasCompute: boolean;
+    hasDatabase: boolean;
+    hasStorage: boolean;
+    hasMessaging: boolean;
+    hasCdn: boolean;
+}
+/** Derive resource flags from manifest stack names (authoritative, post-synth) */
+export declare function deriveResourcesFromManifestStacks(stackNames: string[]): AppResourceFlags;
+/**
+ * Detect the application pattern (Payload, Next.js, or none) from infrastructure.ts.
+ *
+ * Pattern detection is based on the IaC file (infrastructure.ts), NOT on
+ * project files like package.json. This ensures accurate detection even
+ * when multiple apps coexist in the same project directory.
+ *
+ * @param appPath - The fjall app path (e.g., "fjall/app8" or absolute path)
+ */
+export declare function detectPattern(appPath: string): {
+    pattern: PatternType | null;
+    hasDatabase: boolean;
+};
+/**
+ * Detect if infrastructure.ts contains a Payload CMS pattern.
+ */
+export declare function detectPayloadPattern(appPath: string): boolean;
+/**
+ * Detect if infrastructure.ts contains a database resource.
+ */
+export declare function detectDatabase(appPath: string): boolean;
+export {};

package/dist/src/types/patternDetection.js

@@ -0,0 +1,92 @@
+/**
+ * Pattern detection types and functions.
+ *
+ * Contains both pure predicates used by operations.ts and
+ * filesystem-based detection functions used by orchestration services.
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { logger, getErrorMessage } from "@fjall/util";
+import { APPLICATION_STACKS } from "./operations.js";
+import { INFRASTRUCTURE_FILENAME } from "./constants.js";
+const OPENNEXT_PATTERNS_ARRAY = ["payload", "nextjs"];
+export const OPENNEXT_PATTERNS = new Set(OPENNEXT_PATTERNS_ARRAY);
+export function isOpenNextPattern(pattern) {
+    return (pattern !== undefined && pattern !== null && OPENNEXT_PATTERNS.has(pattern));
+}
+/** Derive resource flags from manifest stack names (authoritative, post-synth) */
+export function deriveResourcesFromManifestStacks(stackNames) {
+    const has = (suffix) => stackNames.some((s) => s.endsWith(suffix));
+    return {
+        hasNetwork: has(APPLICATION_STACKS.NETWORK),
+        hasCompute: has(APPLICATION_STACKS.COMPUTE),
+        hasDatabase: has(APPLICATION_STACKS.DATABASE),
+        hasStorage: has(APPLICATION_STACKS.STORAGE),
+        hasMessaging: has(APPLICATION_STACKS.MESSAGING),
+        hasCdn: has(APPLICATION_STACKS.CDN)
+    };
+}
+/**
+ * Read infrastructure.ts content from an app path.
+ * Returns null if file doesn't exist or can't be read.
+ */
+function readInfrastructureContent(appPath) {
+    try {
+        const filePath = join(appPath, INFRASTRUCTURE_FILENAME);
+        if (!existsSync(filePath))
+            return null;
+        return readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        logger.debug("patternDetection", "Failed to read infrastructure file", {
+            appPath,
+            error: getErrorMessage(error)
+        });
+        return null;
+    }
+}
+/**
+ * Detect the application pattern (Payload, Next.js, or none) from infrastructure.ts.
+ *
+ * Pattern detection is based on the IaC file (infrastructure.ts), NOT on
+ * project files like package.json. This ensures accurate detection even
+ * when multiple apps coexist in the same project directory.
+ *
+ * @param appPath - The fjall app path (e.g., "fjall/app8" or absolute path)
+ */
+export function detectPattern(appPath) {
+    const content = readInfrastructureContent(appPath);
+    if (!content) {
+        return { pattern: null, hasDatabase: false };
+    }
+    if (content.includes("PatternFactory")) {
+        if (content.includes('type: "payload"')) {
+            return { pattern: "payload", hasDatabase: true };
+        }
+        if (content.includes('type: "nextjs"')) {
+            const hasDatabase = content.includes("DatabaseFactory.build(") ||
+                content.includes("database:");
+            return { pattern: "nextjs", hasDatabase };
+        }
+    }
+    const hasDatabase = content.includes("DatabaseFactory.build(");
+    return { pattern: null, hasDatabase };
+}
+/**
+ * Detect if infrastructure.ts contains a Payload CMS pattern.
+ */
+export function detectPayloadPattern(appPath) {
+    const content = readInfrastructureContent(appPath);
+    if (!content)
+        return false;
+    return (content.includes("PatternFactory") && content.includes('type: "payload"'));
+}
+/**
+ * Detect if infrastructure.ts contains a database resource.
+ */
+export function detectDatabase(appPath) {
+    const content = readInfrastructureContent(appPath);
+    if (!content)
+        return false;
+    return content.includes("DatabaseFactory.build(");
+}

package/dist/src/types/validation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Result of a validation operation
+ * Used for form validation, input validation, etc.
+ */
+export interface ValidationResult {
+    /** Whether the validation passed */
+    valid: boolean;
+    /** Error messages if validation failed */
+    errors: string[];
+    /** Warning messages (non-blocking) */
+    warnings?: string[];
+}

package/dist/src/types/validation.js

@@ -0,0 +1 @@
+export {};

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

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

package/dist/src/util/fsHelpers.js

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

@@ -0,0 +1,3 @@
+export { DANGEROUS_ENV_VARS, filterDangerousEnvVars, maskSensitiveOutput, parseShellArgs } from "./securityHelpers.js";
+export { sleep } from "./sleep.js";
+export { singleton } from "./singleton.js";

package/dist/src/util/index.js

@@ -0,0 +1,3 @@
+export { DANGEROUS_ENV_VARS, filterDangerousEnvVars, maskSensitiveOutput, parseShellArgs } from "./securityHelpers.js";
+export { sleep } from "./sleep.js";
+export { singleton } from "./singleton.js";

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

@@ -0,0 +1,31 @@
+/**
+ * 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[];