@fjall/deploy-core 2.20.1 → 2.22.0

package/dist/src/types/deployEvent.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{CASCADE_PHASES as h,DEPLOYMENT_EVENT_RESOURCE_CATEGORIES as E}from"./deploymentEventSchema.js";import{TRAIL_MIGRATION_PHASES as A,TRAIL_MIGRATION_STATUSES as C}from"./events.js";import{TRAIL_LIFECYCLE_STATES as p}from"@fjall/util/config";const Ue="fjall.deploy/1.1",Ve=1,Ye=1,_=["fjall.deploy/1.0","fjall.deploy/1.1"],a=256,o=256,s=2048,i=2048,n=4096,j=2048,m=8192,r=2048,g=4096,T=["completed","skipped","error","cancelled"],y=["info","debug","warn"],D=["emptying-bucket","deleting-stack","waiting","complete","error","quarantine-suspected","retained-buckets"],v=["bootstrap","synth","deploy","destroy"],P=["success","failure","cancelled","no-changes","rejected"],R=["detect","synth","hash","validate"],c=["started","completed"],l=["docker","buildpush","opennext"],d=["succeeded","skipped","failed"],N=["create","update","replace","delete","read","no-op"],K=["will","may","conditional","none"],O=["destructive","cost","policy"],f=["approved","rejected","expired","superseded"],u=e.object({create:e.number().int().nonnegative(),update:e.number().int().nonnegative(),replace:e.number().int().nonnegative(),delete:e.number().int().nonnegative(),read:e.number().int().nonnegative(),"no-op":e.number().int().nonnegative()}).strict(),L={create:!0,update:!0,replace:!0,delete:!0,read:!0,"no-op":!0},t={contract:e.enum(_),deploymentId:e.string().min(1).max(a),seq:e.number().int().nonnegative(),time:e.string().datetime()},x=e.object({index:e.number().int().nonnegative(),total:e.number().int().positive()}).strict(),b=e.object({id:e.string().max(a),name:e.string().max(o)}).strict(),k=e.object({logicalId:e.string().max(a),resourceType:e.string().max(a),status:e.string().max(64),displayName:e.string().max(o).optional(),category:e.enum(E).optional(),group:e.string().max(128).optional(),constructPath:e.string().max(512).optional(),statusReason:e.string().max(i).optional(),physicalId:e.string().max(r).optional(),expectedDurationSeconds:e.number().nonnegative().optional()}).strict(),M=e.object({pattern:e.string().max(128).nullable(),hasDockerfile:e.boolean(),hasDifferences:e.boolean(),resources:e.object({hasNetwork:e.boolean(),hasCompute:e.boolean(),hasDatabase:e.boolean(),hasStorage:e.boolean(),hasMessaging:e.boolean(),hasCdn:e.boolean()}).strict(),requiredSecrets:e.array(e.string().max(512)).max(100).optional()}).strict(),I=e.object({path:e.string().max(512),forcesReplacement:e.boolean()}).strict(),U=e.object({address:e.string().max(512),resourceType:e.string().max(a),action:e.enum(N),stack:e.string().max(a).optional(),replacementMode:e.enum(K).optional(),dataLoss:e.boolean().optional(),propertyChanges:e.array(I).max(100).optional()}).strict(),S=e.object({accountId:e.string().max(a),error:e.string().max(n)}).strict(),V=e.object({platformDeployed:e.boolean(),platformSkipped:e.boolean(),platformFailed:e.boolean(),domainsDeployed:e.boolean(),accountsDeployed:e.number().int().nonnegative(),accountsSkipped:e.number().int().nonnegative(),accountsFailed:e.number().int().nonnegative(),errors:e.array(S).max(1e3)}).strict(),Y=e.object({accountId:e.string().max(a),accountName:e.string().max(o),region:e.string().max(a),result:e.enum(d),durationMs:e.number().nonnegative(),error:e.string().max(n).optional()}).strict(),B=e.object({accountId:e.string().max(a),result:e.enum(d),durationMs:e.number().nonnegative(),error:e.string().max(n).optional()}).strict(),G=e.object({members:e.array(Y).max(1e3),platform:B.optional(),domainsDeployed:e.boolean(),errors:e.array(S).max(1e3),totalDurationMs:e.number().nonnegative()}).strict(),X=e.object({bucketName:e.string().max(o),accountId:e.string().max(a).optional()}).strict(),w=e.object({retainedBuckets:e.array(e.string().max(o)).max(1e3),message:e.string().max(s)}).strict(),H=e.union([X,w]),q=e.object({stack:e.string().max(a),success:e.boolean(),error:e.string().max(n).optional()}).strict(),F=e.object({accountId:e.string().max(a),region:e.string().max(a),profileName:e.string().max(o).optional()}).strict(),z=e.object({...t,progressKind:e.literal("step.started"),step:b,progress:x.optional()}).strict(),J=e.object({...t,progressKind:e.literal("step.completed"),step:b,status:e.enum(T),progress:x.optional(),errorMessage:e.string().max(n).optional()}).strict(),Q=e.object({...t,progressKind:e.literal("log"),level:e.enum(y),message:e.string().max(s)}).strict(),W=e.object({...t,progressKind:e.literal("output"),chunk:e.string().max(m)}).strict(),Z=e.object({...t,progressKind:e.literal("resource"),resource:k,scope:e.object({stack:e.string().max(a).optional(),operationKey:e.string().max(a).optional(),region:e.string().max(a).optional()}).strict().optional()}).strict(),$=e.object({...t,progressKind:e.literal("phase.parallel"),status:e.enum(c),stacks:e.array(e.string().max(a)).max(50),description:e.string().max(o).optional(),results:e.array(q).max(50).optional()}).strict(),ee=e.object({...t,progressKind:e.literal("build.started"),builder:e.enum(l),serviceName:e.string().max(o).optional(),imageTag:e.string().max(o).optional(),ecrRepositoryUri:e.string().max(r).optional()}).strict(),te=e.object({...t,progressKind:e.literal("build.progress"),builder:e.enum(l),message:e.string().max(s),serviceName:e.string().max(o).optional(),percentage:e.number().optional(),layerId:e.string().max(a).optional(),status:e.string().max(64).optional()}).strict(),ae=e.object({...t,progressKind:e.literal("build.completed"),builder:e.enum(l),success:e.boolean(),serviceName:e.string().max(o).optional(),imageTag:e.string().max(o).optional(),imageDigest:e.string().max(a).optional(),imageUri:e.string().max(g).optional(),ecrRepositoryArn:e.string().max(r).optional(),durationMs:e.number().nonnegative().optional(),error:e.string().max(n).optional()}).strict(),oe=e.object({...t,progressKind:e.literal("taskdef.registered"),serviceName:e.string().max(o),taskDefinitionArn:e.string().max(r),previousTaskDefinitionArn:e.string().max(r),revision:e.number().int().nonnegative(),family:e.string().max(o),imageDigest:e.string().max(a).optional()}).strict(),re=e.object({...t,progressKind:e.literal("ecs.update"),status:e.string().max(64),service:e.string().max(o).optional()}).strict(),se=e.object({...t,progressKind:e.literal("ecs.progress"),message:e.string().max(s),percentage:e.number().optional()}).strict(),ne=e.object({...t,progressKind:e.literal("ecs.completed"),serviceName:e.string().max(o),serviceArn:e.string().max(r),success:e.boolean(),taskDefinitionArn:e.string().max(r),durationMs:e.number().nonnegative(),reason:e.string().max(i).optional(),finalRunningCount:e.number().int().nonnegative().optional(),finalDesiredCount:e.number().int().nonnegative().optional()}).strict(),ie=e.object({...t,progressKind:e.literal("migrations.started"),family:e.string().max(o),taskDefinitionArn:e.string().max(r),imageDigest:e.string().max(a)}).strict(),ce=e.object({...t,progressKind:e.literal("migrations.completed"),family:e.string().max(o),taskDefinitionArn:e.string().max(r),success:e.boolean(),durationMs:e.number().nonnegative(),exitCode:e.number().int().optional(),reason:e.string().max(i).optional()}).strict(),le=e.object({...t,progressKind:e.literal("cdk.bootstrap"),status:e.string().max(s)}).strict(),pe=e.object({...t,progressKind:e.literal("cdk.output"),outputType:e.enum(["synth","diff"]),output:e.string().max(m)}).strict(),me=e.object({...t,progressKind:e.literal("detection.completed"),detection:M}).strict(),ge=e.object({...t,progressKind:e.literal("detection.phase"),phase:e.enum(R),status:e.enum(c)}).strict(),de=e.object({...t,progressKind:e.literal("cascade.started")}).strict(),ue=e.object({...t,progressKind:e.literal("cascade.accountsReconciled"),hasPlatformAccount:e.boolean(),hasMemberAccounts:e.boolean()}).strict(),xe=e.object({...t,progressKind:e.literal("cascade.orgChanges"),hasOrgChanges:e.boolean()}).strict(),be=e.object({...t,progressKind:e.literal("cascade.missingAccounts"),accountNames:e.array(e.string().max(o)).max(256)}).strict(),Se=e.object({...t,progressKind:e.literal("cascade.phase"),phase:e.enum(h),status:e.enum(c)}).strict(),he=e.object({...t,progressKind:e.literal("cascade.account.started"),operationKey:e.string().max(a),accountId:e.string().max(a),region:e.string().max(a),deployType:e.string().max(64).optional()}).strict(),Ee=e.object({...t,progressKind:e.literal("cascade.account.phase"),operationKey:e.string().max(a),phase:e.enum(v),region:e.string().max(a).optional()}).strict(),Ae=e.object({...t,progressKind:e.literal("cascade.account.completed"),operationKey:e.string().max(a),success:e.boolean(),error:e.string().max(n).optional(),region:e.string().max(a).optional(),outputs:e.record(e.string().max(o),e.string().max(i)).optional(),skipped:e.boolean().optional()}).strict(),Ce=e.object({...t,progressKind:e.literal("cascade.completed"),result:V}).strict(),_e=e.object({...t,progressKind:e.literal("cascade.ledger"),ledger:G}).strict(),je=e.object({...t,progressKind:e.literal("trail.phase"),accountId:e.string().max(a),accountName:e.string().max(o),phase:e.enum(A),status:e.enum(C),detail:e.string().max(j).optional()}).strict(),Te=e.object({...t,progressKind:e.literal("trail.lifecycle"),accountId:e.string().max(a),to:e.enum(p),from:e.enum(p).optional()}).strict(),ye=e.object({...t,progressKind:e.literal("cleanup.progress"),stackName:e.string().max(a),phase:e.enum(D),detail:H.optional()}).strict(),De=e.object({...t,progressKind:e.literal("auth.ssoUrl"),url:e.string().max(g).nullable()}).strict(),ve=e.object({...t,progressKind:e.literal("auth.completed"),result:F.nullable()}).strict(),Pe=e.object({...t,progressKind:e.literal("error"),message:e.string().max(n),name:e.string().max(o).optional()}).strict(),Re=e.object({...t,progressKind:e.literal("deploy.completed"),result:e.enum(P),ok:e.boolean(),errorType:e.string().max(128).optional(),message:e.string().max(s)}).strict(),Ne=e.object({...t,progressKind:e.literal("plan.available"),plan:e.object({summary:e.string().max(s),changeCount:e.number().int().nonnegative(),hasDestructiveChanges:e.boolean(),changes:e.array(U).max(1e3).optional(),diffRef:e.string().max(512).optional(),iamBroadening:e.boolean().optional(),securityGroupBroadening:e.boolean().optional(),changeCountsByAction:u.optional()}).strict()}).strict(),Ke=e.object({...t,progressKind:e.literal("approval.awaiting"),approval:e.object({token:e.string().max(512),kind:e.enum(O),reason:e.string().max(s),expiresAt:e.string().datetime(),assemblyDigest:e.string().max(128).optional(),changeCounts:u.optional(),approvalClass:e.string().max(64).optional(),requiredApprovers:e.array(e.string().max(256)).max(50).optional()}).strict()}).strict(),Oe=e.object({...t,progressKind:e.literal("approval.resolved"),approval:e.object({token:e.string().max(512),decision:e.enum(f),actor:e.string().max(o).optional()}).strict()}).strict(),Be=e.discriminatedUnion("progressKind",[z,J,Q,W,Z,$,ee,te,ae,oe,re,se,ne,ie,ce,le,pe,me,ge,de,ue,xe,be,Se,he,Ee,Ae,Ce,_e,je,Te,ye,De,ve,Pe,Re,Ne,Ke,Oe]),fe={"step.started":!0,"step.completed":!0,log:!0,output:!0,resource:!0,"phase.parallel":!0,"build.started":!0,"build.progress":!0,"build.completed":!0,"taskdef.registered":!0,"ecs.update":!0,"ecs.progress":!0,"ecs.completed":!0,"migrations.started":!0,"migrations.completed":!0,"cdk.bootstrap":!0,"cdk.output":!0,"detection.completed":!0,"detection.phase":!0,"cascade.started":!0,"cascade.accountsReconciled":!0,"cascade.orgChanges":!0,"cascade.missingAccounts":!0,"cascade.phase":!0,"cascade.account.started":!0,"cascade.account.phase":!0,"cascade.account.completed":!0,"cascade.completed":!0,"cascade.ledger":!0,"trail.phase":!0,"trail.lifecycle":!0,"cleanup.progress":!0,"auth.ssoUrl":!0,"auth.completed":!0,error:!0,"deploy.completed":!0,"plan.available":!0,"approval.awaiting":!0,"approval.resolved":!0},Ge=Object.keys(fe);export{Ge as ALL_PROGRESS_KINDS,f as APPROVAL_DECISIONS,O as APPROVAL_KINDS,l as BUILDERS,v as CASCADE_ACCOUNT_PHASES,d as CASCADE_OUTCOME_RESULTS,u as ChangeCountsSchema,r as DEPLOY_EVENT_ARN_MAX,Ue as DEPLOY_EVENT_CONTRACT,Ve as DEPLOY_EVENT_CONTRACT_MAJOR,Ye as DEPLOY_EVENT_CONTRACT_MINOR,n as DEPLOY_EVENT_ERROR_MESSAGE_MAX,a as DEPLOY_EVENT_ID_MAX,s as DEPLOY_EVENT_MESSAGE_MAX,o as DEPLOY_EVENT_NAME_MAX,m as DEPLOY_EVENT_OUTPUT_MAX,i as DEPLOY_EVENT_STATUS_REASON_MAX,j as DEPLOY_EVENT_TRAIL_DETAIL_MAX,g as DEPLOY_EVENT_URL_MAX,P as DEPLOY_RESULTS,R as DETECTION_PHASES,Be as DeployEventSchema,k as DeployResourceSchema,y as LOG_LEVELS,c as PHASE_STATUSES,N as PLAN_ACTIONS,U as PlanChangeSchema,I as PlanPropertyChangeSchema,K as REPLACEMENT_MODES,D as STACK_CLEANUP_PHASES,T as STEP_COMPLETE_STATUSES,_ as SUPPORTED_CONTRACT_MARKERS,x as StepProgressSchema};

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

@@ -0,0 +1,52 @@
+/**
+ * Safe, never-throwing parser for the {@link DeployEvent} contract.
+ *
+ * `parseDeployEvent` classifies any input into one of four outcomes so a consumer
+ * can distinguish forward-compatible events it should render best-effort from a
+ * same-version producer bug it must surface loudly:
+ *
+ *   - `ok`           — validates against the current contract.
+ *   - `unknown`      — same major, but a future minor OR an unrecognised
+ *                      progressKind. Forward-compatible; render best-effort.
+ *   - `invalid`      — same major, a KNOWN progressKind, yet validation failed.
+ *                      A producer bug (missing/mistyped field) — surface loudly.
+ *   - `incompatible` — different/unparseable major, or not a contract event.
+ *
+ * Conflating `invalid` into `unknown` would let a malformed in-version event be
+ * swallowed by forward-compat handling, so the taxonomy keeps them distinct.
+ */
+import { type DeployEvent } from "./deployEvent.js";
+/**
+ * Outcome of {@link parseDeployEvent}.
+ *
+ * `raw` and `reason` are diagnostic and are NOT masked — they may echo
+ * credential-bearing content from a malformed event. A consumer that logs them
+ * MUST mask first (`maskSensitiveOutput`).
+ */
+export type ParsedDeployEvent = {
+    status: "ok";
+    event: DeployEvent;
+} | {
+    status: "unknown";
+    contract: string;
+    progressKind?: string;
+    raw: unknown;
+} | {
+    status: "invalid";
+    reason: string;
+    progressKind?: string;
+    raw: unknown;
+} | {
+    status: "incompatible";
+    reason: string;
+    raw: unknown;
+};
+/**
+ * Extract the `{ major, minor }` from a contract marker, or `null` if the string
+ * is not a `fjall.deploy/<major>.<minor>` marker.
+ */
+export declare function parseDeployContractVersion(contract: string): {
+    major: number;
+    minor: number;
+} | null;
+export declare function parseDeployEvent(raw: unknown): ParsedDeployEvent;

package/dist/src/types/deployEventParse.js

@@ -0,0 +1 @@
+import{ALL_PROGRESS_KINDS as a,DEPLOY_EVENT_CONTRACT_MAJOR as i,DEPLOY_EVENT_CONTRACT_MINOR as d,DeployEventSchema as f}from"./deployEvent.js";const l=/^fjall\.deploy\/(\d+)\.(\d+)$/,p=new Set(a);function m(n){const e=l.exec(n);if(e===null)return null;const t=e[1],o=e[2];if(t===void 0||o===void 0)return null;const r=parseInt(t,10),s=parseInt(o,10);return Number.isNaN(r)||Number.isNaN(s)?null:{major:r,minor:s}}function u(n,e){if(!(e in n))return;const t=n[e];return typeof t=="string"?t:void 0}function E(n){const e=f.safeParse(n);if(e.success)return{status:"ok",event:e.data};if(typeof n!="object"||n===null)return{status:"incompatible",reason:"Event is not an object",raw:n};const t=u(n,"contract");if(t===void 0)return{status:"incompatible",reason:"Missing or non-string contract marker",raw:n};const o=m(t);if(o===null)return{status:"incompatible",reason:`Unrecognised contract marker: ${t}`,raw:n};if(o.major!==i)return{status:"incompatible",reason:`Contract major ${o.major} unsupported (expected ${i})`,raw:n};const r=u(n,"progressKind"),s=o.minor>d,c=r===void 0||!p.has(r);return s||c?{status:"unknown",contract:t,...r!==void 0&&{progressKind:r},raw:n}:{status:"invalid",reason:e.error.message,...r!==void 0&&{progressKind:r},raw:n}}export{m as parseDeployContractVersion,E as parseDeployEvent};

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

@@ -0,0 +1,10 @@
+/**
+ * Compile-time proof that the `{0,0}` step-progress footgun is unrepresentable in
+ * the TYPE, complementing the runtime `.positive()` / `.nonnegative()` checks the
+ * tests assert. These lines live in compiled `src/` (the package tsconfig
+ * excludes `__tests__/`, which `tsc --noEmit` would never see), so the package
+ * `typecheck` actually runs them. Each `@ts-expect-error` suppresses a real error;
+ * if the `StepProgress` shape ever loosened to permit one of these, the directive
+ * would become unused and `tsc` would fail `TS2578: Unused '@ts-expect-error'`.
+ */
+export {};

package/dist/src/types/deployEventTypeGuards.js

@@ -0,0 +1 @@
+const o={index:0},n={total:5},l={index:null,total:5};

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

@@ -1,12 +1,17 @@
 export { DeploymentEventSchema, DEPLOYMENT_EVENT_TYPES, DEPLOYMENT_EVENT_RESOURCE_CATEGORIES, DEPLOYMENT_EVENT_STATUS_REASON_MAX, DEPLOYMENT_EVENT_ERROR_MESSAGE_MAX, DEPLOYMENT_EVENT_TRAIL_DETAIL_MAX, CASCADE_PHASES, CASCADE_ACCOUNT_STATUSES, toCascadePhase } from "./deploymentEventSchema.js";
 export type { DeploymentEvent, DeploymentEventType, DeploymentEventResourceCategory, DeploymentEventCascadePhase, DeploymentEventCascadeAccountStatus } from "./deploymentEventSchema.js";
 export type { AwsCredentials, DeployIdentity } from "./credentials.js";
-export type { DeployCallbacks, StepCompleteStatus, StackCleanupQuarantineDetail, StackCleanupRetainedBucketsDetail } from "./callbacks.js";
+export type { DeployCallbacks, StepCompleteStatus, StackCleanupPhase, CascadeAccountPhase, LogLevel, StackCleanupQuarantineDetail, StackCleanupRetainedBucketsDetail } from "./callbacks.js";
 export { isQuarantineDetail, isRetainedBucketsDetail } from "./callbacks.js";
+export { DeployEventSchema, StepProgressSchema, DeployResourceSchema, PlanChangeSchema, PlanPropertyChangeSchema, ChangeCountsSchema, DEPLOY_EVENT_CONTRACT, DEPLOY_EVENT_CONTRACT_MAJOR, DEPLOY_EVENT_CONTRACT_MINOR, SUPPORTED_CONTRACT_MARKERS, DEPLOY_EVENT_ID_MAX, DEPLOY_EVENT_NAME_MAX, DEPLOY_EVENT_MESSAGE_MAX, DEPLOY_EVENT_STATUS_REASON_MAX, DEPLOY_EVENT_ERROR_MESSAGE_MAX, DEPLOY_EVENT_TRAIL_DETAIL_MAX, DEPLOY_EVENT_OUTPUT_MAX, DEPLOY_EVENT_ARN_MAX, DEPLOY_EVENT_URL_MAX, STEP_COMPLETE_STATUSES, LOG_LEVELS, STACK_CLEANUP_PHASES, CASCADE_ACCOUNT_PHASES, DEPLOY_RESULTS, DETECTION_PHASES, PHASE_STATUSES, BUILDERS, CASCADE_OUTCOME_RESULTS, PLAN_ACTIONS, REPLACEMENT_MODES, APPROVAL_KINDS, APPROVAL_DECISIONS, ALL_PROGRESS_KINDS } from "./deployEvent.js";
+export type { DeployEvent, ProgressKind, StepProgress, DeployResource, PlanChange, PlanPropertyChange, ChangeCounts, PlanAction, ReplacementMode, ApprovalKind, ApprovalDecision, DeployRunResult } from "./deployEvent.js";
+export { createDeployEmitter, type DeployEmitter, type CreateDeployEmitterOptions } from "./deployEmitter.js";
+export { parseDeployEvent, parseDeployContractVersion, type ParsedDeployEvent } from "./deployEventParse.js";
 export type { ProgressEvent, ProgressEventType, ResourceEvent, AwsAuthResult, CascadeDeploymentResult, CascadePhase, BuildPushStartEvent, BuildPushProgressEvent, BuildPushCompleteEvent, TaskDefRegisteredEvent, ECSCompleteEvent, MigrationsStartEvent, MigrationsCompleteEvent, TrailMigrationPhase, TrailMigrationStatus, TrailMigrationPhaseEvent } from "./events.js";
 export { TRAIL_MIGRATION_PHASES, TRAIL_MIGRATION_STATUSES } from "./events.js";
 export type { ApiClientInterface, EntitlementsData } from "./apiClient.js";
 export type { DeployParams, DeployOptions, DeploymentType, DeployResult, DestroyParams, DestroyOptions, DestroyResult } from "./params.js";
+export type { ApprovalGate, ApprovalRequest, GateResolution } from "./approval.js";
 export type { OrgConfig, ProviderAccount, RootAccessManagementMode, SSOSession } from "./config/orgConfig.js";
 export type { Entitlements } from "./config/entitlements.js";
 export type { StackOutput, StackOutputsRecord, DeploymentContext, StepOutput, ApplicationDeploymentContext, CallerIdentity } from "./deployment/index.js";

package/dist/src/types/index.js

@@ -1 +1 @@
-import{DeploymentEventSchema as t,DEPLOYMENT_EVENT_TYPES as A,DEPLOYMENT_EVENT_RESOURCE_CATEGORIES as T,DEPLOYMENT_EVENT_STATUS_REASON_MAX as r,DEPLOYMENT_EVENT_ERROR_MESSAGE_MAX as S,DEPLOYMENT_EVENT_TRAIL_DETAIL_MAX as _,CASCADE_PHASES as a,CASCADE_ACCOUNT_STATUSES as o,toCascadePhase as p}from"./deploymentEventSchema.js";import{isQuarantineDetail as i,isRetainedBucketsDetail as N}from"./callbacks.js";import{TRAIL_MIGRATION_PHASES as R,TRAIL_MIGRATION_STATUSES as l}from"./events.js";import{stubCallerIdentity as L}from"./deployment/index.js";import{ProgressReporter as n}from"./ProgressEvent.js";import{APPLICATION_STACKS as m,ORGANISATION_TYPES as C,APPLICATION_DEPLOY_ORDER as c,APPLICATION_DESTROY_ORDER as M,OPENNEXT_DEPLOY_ORDER as f,OPENNEXT_DESTROY_ORDER as x,PARALLEL_DEPLOY_GROUPS as Y,PARALLEL_DESTROY_GROUPS as g,OPENNEXT_PARALLEL_GROUPS as F,isApplicationOperation as U,isOrganisationOperation as d,getParallelDeployGroups as G,getParallelDestroyGroups as u,getApplicationDeployOrder as y,getApplicationDestroyOrder as X,getApplicationStackName as h,getOrganisationStackName as k,isApplicationStack as K,getApplicationStepName as V,getApplicationStepId as H,toPascalCase as v}from"./operations.js";import{PARALLEL_OPERATION_TYPES as b}from"./deployment/index.js";import{isOpenNextPattern as B,OPENNEXT_PATTERNS as Q}from"./detection/patternTypes.js";import{deriveResourcesFromManifestStacks as z}from"./detection/patternDetection.js";import{STACK_NOT_FOUND_PATTERN as W,STACK_FAILED_STATE_PATTERN as Z,CDK_NO_STACKS_MATCH as $,INFRASTRUCTURE_FILENAME as ee}from"./constants.js";import{ApplicationError as te,wrapApplicationError as Ae}from"./application/index.js";import{FjallStateFileSchema as re,readStateFile as Se,writeStateFile as _e,createEmptyState as ae,deleteStateFile as oe,updateTemplateHash as pe,getStateFilePath as Oe,regionSuffix as ie}from"./config/FjallState.js";import{STEP_IDS as Pe,STEP_NAMES as Re,INFRASTRUCTURE_STEP_NAMES as le,INFRA_STEP_NAME as De}from"./stepDefinitions.js";export{c as APPLICATION_DEPLOY_ORDER,M as APPLICATION_DESTROY_ORDER,m as APPLICATION_STACKS,te as ApplicationError,o as CASCADE_ACCOUNT_STATUSES,a as CASCADE_PHASES,$ as CDK_NO_STACKS_MATCH,S as DEPLOYMENT_EVENT_ERROR_MESSAGE_MAX,T as DEPLOYMENT_EVENT_RESOURCE_CATEGORIES,r as DEPLOYMENT_EVENT_STATUS_REASON_MAX,_ as DEPLOYMENT_EVENT_TRAIL_DETAIL_MAX,A as DEPLOYMENT_EVENT_TYPES,t as DeploymentEventSchema,re as FjallStateFileSchema,ee as INFRASTRUCTURE_FILENAME,le as INFRASTRUCTURE_STEP_NAMES,De as INFRA_STEP_NAME,f as OPENNEXT_DEPLOY_ORDER,x as OPENNEXT_DESTROY_ORDER,F as OPENNEXT_PARALLEL_GROUPS,Q as OPENNEXT_PATTERNS,C as ORGANISATION_TYPES,Y as PARALLEL_DEPLOY_GROUPS,g as PARALLEL_DESTROY_GROUPS,b as PARALLEL_OPERATION_TYPES,n as ProgressReporter,Z as STACK_FAILED_STATE_PATTERN,W as STACK_NOT_FOUND_PATTERN,Pe as STEP_IDS,Re as STEP_NAMES,R as TRAIL_MIGRATION_PHASES,l as TRAIL_MIGRATION_STATUSES,ae as createEmptyState,oe as deleteStateFile,z as deriveResourcesFromManifestStacks,y as getApplicationDeployOrder,X as getApplicationDestroyOrder,h as getApplicationStackName,H as getApplicationStepId,V as getApplicationStepName,k as getOrganisationStackName,G as getParallelDeployGroups,u as getParallelDestroyGroups,Oe as getStateFilePath,U as isApplicationOperation,K as isApplicationStack,B as isOpenNextPattern,d as isOrganisationOperation,i as isQuarantineDetail,N as isRetainedBucketsDetail,Se as readStateFile,ie as regionSuffix,L as stubCallerIdentity,p as toCascadePhase,v as toPascalCase,pe as updateTemplateHash,Ae as wrapApplicationError,_e as writeStateFile};
+import{DeploymentEventSchema as e,DEPLOYMENT_EVENT_TYPES as A,DEPLOYMENT_EVENT_RESOURCE_CATEGORIES as S,DEPLOYMENT_EVENT_STATUS_REASON_MAX as T,DEPLOYMENT_EVENT_ERROR_MESSAGE_MAX as t,DEPLOYMENT_EVENT_TRAIL_DETAIL_MAX as O,CASCADE_PHASES as P,CASCADE_ACCOUNT_STATUSES as r,toCascadePhase as N}from"./deploymentEventSchema.js";import{isQuarantineDetail as a,isRetainedBucketsDetail as R}from"./callbacks.js";import{DeployEventSchema as p,StepProgressSchema as D,DeployResourceSchema as C,PlanChangeSchema as i,PlanPropertyChangeSchema as l,ChangeCountsSchema as I,DEPLOY_EVENT_CONTRACT as M,DEPLOY_EVENT_CONTRACT_MAJOR as n,DEPLOY_EVENT_CONTRACT_MINOR as m,SUPPORTED_CONTRACT_MARKERS as s,DEPLOY_EVENT_ID_MAX as c,DEPLOY_EVENT_NAME_MAX as Y,DEPLOY_EVENT_MESSAGE_MAX as U,DEPLOY_EVENT_STATUS_REASON_MAX as V,DEPLOY_EVENT_ERROR_MESSAGE_MAX as f,DEPLOY_EVENT_TRAIL_DETAIL_MAX as x,DEPLOY_EVENT_OUTPUT_MAX as g,DEPLOY_EVENT_ARN_MAX as X,DEPLOY_EVENT_URL_MAX as h,STEP_COMPLETE_STATUSES as G,LOG_LEVELS as y,STACK_CLEANUP_PHASES as F,CASCADE_ACCOUNT_PHASES as d,DEPLOY_RESULTS as u,DETECTION_PHASES as K,PHASE_STATUSES as H,BUILDERS as k,CASCADE_OUTCOME_RESULTS as v,PLAN_ACTIONS as w,REPLACEMENT_MODES as B,APPROVAL_KINDS as b,APPROVAL_DECISIONS as j,ALL_PROGRESS_KINDS as J}from"./deployEvent.js";import{createDeployEmitter as q}from"./deployEmitter.js";import{parseDeployEvent as W,parseDeployContractVersion as Z}from"./deployEventParse.js";import{TRAIL_MIGRATION_PHASES as EE,TRAIL_MIGRATION_STATUSES as _E}from"./events.js";import{stubCallerIdentity as AE}from"./deployment/index.js";import{ProgressReporter as TE}from"./ProgressEvent.js";import{APPLICATION_STACKS as OE,ORGANISATION_TYPES as PE,APPLICATION_DEPLOY_ORDER as rE,APPLICATION_DESTROY_ORDER as NE,OPENNEXT_DEPLOY_ORDER as oE,OPENNEXT_DESTROY_ORDER as aE,PARALLEL_DEPLOY_GROUPS as RE,PARALLEL_DESTROY_GROUPS as LE,OPENNEXT_PARALLEL_GROUPS as pE,isApplicationOperation as DE,isOrganisationOperation as CE,getParallelDeployGroups as iE,getParallelDestroyGroups as lE,getApplicationDeployOrder as IE,getApplicationDestroyOrder as ME,getApplicationStackName as nE,getOrganisationStackName as mE,isApplicationStack as sE,getApplicationStepName as cE,getApplicationStepId as YE,toPascalCase as UE}from"./operations.js";import{PARALLEL_OPERATION_TYPES as fE}from"./deployment/index.js";import{isOpenNextPattern as gE,OPENNEXT_PATTERNS as XE}from"./detection/patternTypes.js";import{deriveResourcesFromManifestStacks as GE}from"./detection/patternDetection.js";import{STACK_NOT_FOUND_PATTERN as FE,STACK_FAILED_STATE_PATTERN as dE,CDK_NO_STACKS_MATCH as uE,INFRASTRUCTURE_FILENAME as KE}from"./constants.js";import{ApplicationError as kE,wrapApplicationError as vE}from"./application/index.js";import{FjallStateFileSchema as BE,readStateFile as bE,writeStateFile as jE,createEmptyState as JE,deleteStateFile as QE,updateTemplateHash as qE,getStateFilePath as zE,regionSuffix as WE}from"./config/FjallState.js";import{STEP_IDS as $E,STEP_NAMES as E_,INFRASTRUCTURE_STEP_NAMES as __,INFRA_STEP_NAME as e_}from"./stepDefinitions.js";export{J as ALL_PROGRESS_KINDS,rE as APPLICATION_DEPLOY_ORDER,NE as APPLICATION_DESTROY_ORDER,OE as APPLICATION_STACKS,j as APPROVAL_DECISIONS,b as APPROVAL_KINDS,kE as ApplicationError,k as BUILDERS,d as CASCADE_ACCOUNT_PHASES,r as CASCADE_ACCOUNT_STATUSES,v as CASCADE_OUTCOME_RESULTS,P as CASCADE_PHASES,uE as CDK_NO_STACKS_MATCH,I as ChangeCountsSchema,t as DEPLOYMENT_EVENT_ERROR_MESSAGE_MAX,S as DEPLOYMENT_EVENT_RESOURCE_CATEGORIES,T as DEPLOYMENT_EVENT_STATUS_REASON_MAX,O as DEPLOYMENT_EVENT_TRAIL_DETAIL_MAX,A as DEPLOYMENT_EVENT_TYPES,X as DEPLOY_EVENT_ARN_MAX,M as DEPLOY_EVENT_CONTRACT,n as DEPLOY_EVENT_CONTRACT_MAJOR,m as DEPLOY_EVENT_CONTRACT_MINOR,f as DEPLOY_EVENT_ERROR_MESSAGE_MAX,c as DEPLOY_EVENT_ID_MAX,U as DEPLOY_EVENT_MESSAGE_MAX,Y as DEPLOY_EVENT_NAME_MAX,g as DEPLOY_EVENT_OUTPUT_MAX,V as DEPLOY_EVENT_STATUS_REASON_MAX,x as DEPLOY_EVENT_TRAIL_DETAIL_MAX,h as DEPLOY_EVENT_URL_MAX,u as DEPLOY_RESULTS,K as DETECTION_PHASES,p as DeployEventSchema,C as DeployResourceSchema,e as DeploymentEventSchema,BE as FjallStateFileSchema,KE as INFRASTRUCTURE_FILENAME,__ as INFRASTRUCTURE_STEP_NAMES,e_ as INFRA_STEP_NAME,y as LOG_LEVELS,oE as OPENNEXT_DEPLOY_ORDER,aE as OPENNEXT_DESTROY_ORDER,pE as OPENNEXT_PARALLEL_GROUPS,XE as OPENNEXT_PATTERNS,PE as ORGANISATION_TYPES,RE as PARALLEL_DEPLOY_GROUPS,LE as PARALLEL_DESTROY_GROUPS,fE as PARALLEL_OPERATION_TYPES,H as PHASE_STATUSES,w as PLAN_ACTIONS,i as PlanChangeSchema,l as PlanPropertyChangeSchema,TE as ProgressReporter,B as REPLACEMENT_MODES,F as STACK_CLEANUP_PHASES,dE as STACK_FAILED_STATE_PATTERN,FE as STACK_NOT_FOUND_PATTERN,G as STEP_COMPLETE_STATUSES,$E as STEP_IDS,E_ as STEP_NAMES,s as SUPPORTED_CONTRACT_MARKERS,D as StepProgressSchema,EE as TRAIL_MIGRATION_PHASES,_E as TRAIL_MIGRATION_STATUSES,q as createDeployEmitter,JE as createEmptyState,QE as deleteStateFile,GE as deriveResourcesFromManifestStacks,IE as getApplicationDeployOrder,ME as getApplicationDestroyOrder,nE as getApplicationStackName,YE as getApplicationStepId,cE as getApplicationStepName,mE as getOrganisationStackName,iE as getParallelDeployGroups,lE as getParallelDestroyGroups,zE as getStateFilePath,DE as isApplicationOperation,sE as isApplicationStack,gE as isOpenNextPattern,CE as isOrganisationOperation,a as isQuarantineDetail,R as isRetainedBucketsDetail,Z as parseDeployContractVersion,W as parseDeployEvent,bE as readStateFile,WE as regionSuffix,AE as stubCallerIdentity,N as toCascadePhase,UE as toPascalCase,qE as updateTemplateHash,vE as wrapApplicationError,jE as writeStateFile};

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

@@ -5,6 +5,9 @@ import type { ApiClientInterface } from "./apiClient.js";
 import type { OrgConfig } from "./config/orgConfig.js";
 import type { DockerProvider } from "../orchestration/dockerInterface.js";
 import type { DomainDeployProvider } from "../orchestration/domainInterface.js";
+import type { ApprovalGate } from "./approval.js";
+import type { FailureAnalysis } from "@fjall/util/aws";
+import type { DockerBuildSecretRef } from "@fjall/util/manifest/schemas";
 export interface DeployParams {
     /** Deployment target name (e.g., "my-app", "organisation", "platform", "account-prod") */
     target: string;
@@ -55,6 +58,15 @@ export interface DeployParams {
      * per-request timeouts so SIGTERM is not stalled by an in-flight call.
      */
     abortSignal?: AbortSignal;
+    /**
+     * Optional engine-level approval gate. When supplied, the engine computes a
+     * typed resource-level plan at the read→mutate boundary and resolves an
+     * approve / reject / await decision through this surface resolver before any
+     * mutation. Omit it for the legacy ungated flow (fully backward-compatible).
+     * The non-resolver paths (`options.planOnly`, `options.approvalToken`) engage
+     * the gate even when this is omitted.
+     */
+    approvalGate?: ApprovalGate;
 }
 export interface DeployOptions {
     skipConfirmation?: boolean;
@@ -82,6 +94,48 @@ export interface DeployOptions {
      * build + push and rolls ECS to `<repo>:<imageTag>`. Implies `deployOnly`.
      */
     imageTag?: string;
+    /**
+     * Approval-gate: require an explicit approve decision before mutating. The
+     * engine only gates when a gate is engaged (resolver injected, `planOnly`, or
+     * `approvalToken` supplied); this flag is the surface's intent signal that the
+     * resolver fail-closes on (non-interactive refuses without `autoApprove`).
+     */
+    requireApproval?: boolean;
+    /**
+     * Approval-gate: approve the computed plan without prompting. The plan is
+     * still computed and emitted; the engine proceeds to mutate. FAIL-OPEN escape
+     * hatch — never the default.
+     */
+    autoApprove?: boolean;
+    /**
+     * Approval-gate: compute and emit the plan, then stop before any mutation,
+     * returning a signed approval token (`DeployResult.approvalToken`). Phase 1 of
+     * the two-phase plan→apply flow (`fjall deploy --plan`, MCP `plan_deployment`,
+     * webapp sheet).
+     */
+    planOnly?: boolean;
+    /**
+     * Approval-gate: a token from a prior plan-only run. The engine recomputes the
+     * plan, re-checks the token's bound digest against the fresh synth (TOCTOU
+     * guard), and proceeds to mutate only on a match — otherwise rejects as
+     * superseded / expired. Phase 2 of the two-phase flow.
+     */
+    approvalToken?: string;
+    /**
+     * CLI `--build-arg KEY=VALUE` overrides, the highest-precedence build-arg tier
+     * fed into `resolveBuildArgs` (`buildArgResolver.ts` § precedence ladder) by
+     * `dockerBuildHelper.buildGroup`. A key here widens the emitted set beyond the
+     * manifest. Parsed from the repeatable flag by `parseBuildArgFlags` (CLI).
+     */
+    flagBuildArgs?: Record<string, string>;
+    /**
+     * CLI `--build-secret id=…,ssm=…` ad-hoc references, merged with the manifest
+     * `docker.buildSecrets` before the build group's session scoping +
+     * `validateBuildGroup` so an ad-hoc ref participates in the least-privilege
+     * scope and id-collision check exactly like a manifest ref. Each ref is
+     * validated through `DockerBuildSecretRefSchema` (CLI) before it reaches here.
+     */
+    flagBuildSecrets?: readonly DockerBuildSecretRef[];
 }
 export type DeploymentType = "application" | "organisation";
 export interface DeployResult {
@@ -98,12 +152,54 @@ export interface DeployResult {
     durationMs?: number;
     /** Non-fatal warnings (e.g. cascade account failures) */
     warnings?: string[];
+    /**
+     * Structured root-cause analysis (category, dependency chain, remediation)
+     * captured when a stack failed during the deploy — the same analysis emitted
+     * over `DeployCallbacks.onFailureAnalysis`. Populated on a partial-success
+     * result (e.g. a cascade where a child stack failed but the run completed);
+     * a fully-failed deploy returns `Result.failure` and delivers the analysis
+     * over the callback instead. Consumers render it identically to the callback.
+     */
+    failureAnalysis?: FailureAnalysis;
     /**
      * Set when detection found no infrastructure changes and the engine
      * short-circuited the deploy. Consumers use this to render the
      * "already up to date" path instead of inferring it from output absence.
      */
     noChanges?: boolean;
+    /**
+     * Set when the deploy was aborted via `DeployParams.abortSignal` (CLI Ctrl-C
+     * or worker SIGTERM). The engine has killed the CDK child and issued
+     * `CancelUpdateStack` on the in-flight stack, so this is a *cancelled*
+     * outcome, NOT a failure. Consumers render it distinctly (CLI: "cancelled"
+     * exit 130; worker: retryable re-queue, never DLQ).
+     */
+    cancelled?: boolean;
+    /**
+     * Approval-gate: set when the computed plan was REJECTED at the gate (a
+     * surface declined, or a resume token was refused as superseded/expired).
+     * Conceptually a cancel-before-mutation: no CDK child ran, nothing was
+     * mutated. Distinct from `cancelled` (in-flight abort) and from a failure.
+     */
+    rejected?: boolean;
+    /**
+     * Approval-gate: set when the engine computed + emitted the plan and stopped
+     * before mutation, awaiting an out-of-band approval (`planOnly`, or a resolver
+     * that suspended). Pairs with `approvalToken` for the resuming apply call.
+     */
+    awaitingApproval?: boolean;
+    /**
+     * Approval-gate: the signed, digest-bound token to echo back on the resuming
+     * apply call. Present only when `awaitingApproval` is set. NOT a secret — an
+     * echoed-back capability bound to the synthesised plan; not masked.
+     */
+    approvalToken?: string;
+    /**
+     * Approval-gate: the assembly digest the plan was computed against. Present
+     * with `awaitingApproval` so a caller can persist + correlate the awaiting
+     * plan.
+     */
+    assemblyDigest?: string;
 }
 /**
  * Parameters for the destroy entry point.
@@ -163,6 +259,13 @@ export interface DestroyResult {
     skippedStacks?: string[];
     /** Non-fatal warnings (e.g. cascade account failures) */
     warnings?: string[];
+    /**
+     * Set when the destroy was aborted via `DestroyParams.abortSignal`. Mirrors
+     * {@link DeployResult.cancelled}: a *cancelled* outcome, not a failure. The
+     * in-flight DeleteStack continues server-side (a delete cannot be cancelled),
+     * but the local process stopped cleanly and the worker re-queues.
+     */
+    cancelled?: boolean;
 }
 /** Re-export Result from generator for consumers. */
 export type { Result };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/deploy-core",
-  "version": "2.20.1",
+  "version": "2.22.0",
   "description": "Shared deployment engine for Fjall — used by CLI and webapp worker",
   "type": "module",
   "main": "dist/src/index.js",
@@ -63,6 +63,8 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
+    "@aws-cdk/cloudformation-diff": "2.187.1",
+    "@aws-sdk/client-account": "^3.1067.0",
     "@aws-sdk/client-backup": "^3.1038.0",
     "@aws-sdk/client-cloudformation": "^3.1038.0",
     "@aws-sdk/client-cloudtrail": "^3.1065.0",
@@ -76,11 +78,13 @@
     "@aws-sdk/client-s3": "^3.1038.0",
     "@aws-sdk/client-secrets-manager": "^3.1038.0",
     "@aws-sdk/client-sqs": "^3.1067.0",
+    "@aws-sdk/client-ssm": "^3.1038.0",
     "@aws-sdk/client-sso-admin": "^3.1038.0",
     "@aws-sdk/client-sts": "^3.1038.0",
-    "@fjall/generator": "^2.20.1",
-    "@fjall/util": "^2.20.1",
+    "@fjall/generator": "^2.22.0",
+    "@fjall/util": "^2.22.0",
     "@smithy/node-http-handler": "^4.6.1",
+    "aws-cdk": "^2.1128.1",
     "tsx": "^4.21.0",
     "zod": "^4.4.3"
   },
@@ -89,5 +93,5 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },
-  "gitHead": "397880361ea533450ea5c888f7e7b9593254f663"
+  "gitHead": "448c771d258e87f0535ae7698f11438e0f7c57b1"
 }