@fjall/util 0.89.4 → 0.89.6

package/LICENSE

@@ -1,21 +1,50 @@
-MIT License
-
-Copyright (c) 2026 Fjall
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Fjall Proprietary Software Licence
+
+Copyright (c) 2026 Fjall. All rights reserved.
+
+This software, including all source, object, bundled, and minified forms
+("the Software"), is the proprietary and confidential property of Fjall.
+
+1. Permitted Use. Subject to the terms of this Licence, Fjall grants you
+   a non-exclusive, non-transferable, revocable licence to install the
+   Software via the npm registry and to execute it solely for the purpose
+   of deploying, operating, and managing your own applications and
+   infrastructure on cloud providers.
+
+2. Restrictions. You may NOT, and may not permit any third party to:
+   (a) copy, redistribute, sublicense, sell, rent, lease, or otherwise
+       transfer the Software;
+   (b) modify, adapt, translate, or create derivative works of the Software;
+   (c) reverse engineer, decompile, disassemble, deminify, or otherwise
+       attempt to derive the source code, structure, or organisation of
+       the Software, except to the minimum extent expressly permitted by
+       applicable mandatory law;
+   (d) use the Software, or any portion of it, to develop, train, or
+       improve any product or service that competes with Fjall;
+   (e) remove, alter, or obscure any proprietary notices contained in
+       the Software;
+   (f) publish, share, or otherwise disclose the Software or its contents
+       to any third party.
+
+3. Ownership. All right, title, and interest in and to the Software,
+   including all intellectual property rights, remain with Fjall. No
+   rights are granted except as expressly set out in this Licence.
+
+4. Termination. This Licence terminates automatically if you breach any
+   of its terms. Upon termination you must cease all use of the Software
+   and destroy all copies in your possession.
+
+5. Disclaimer of Warranty. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT
+   WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION
+   THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+   AND NON-INFRINGEMENT.
+
+6. Limitation of Liability. IN NO EVENT SHALL FJALL BE LIABLE FOR ANY
+   INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES
+   ARISING OUT OF OR RELATED TO THE SOFTWARE, EVEN IF ADVISED OF THE
+   POSSIBILITY OF SUCH DAMAGES.
+
+7. Governing Law. This Licence is governed by the laws of England and
+   Wales, without regard to conflict of laws principles.
+
+For commercial licensing enquiries, contact: contact@fjall.io

package/README.md

@@ -0,0 +1,22 @@
+# @fjall/util
+
+Shared utilities used across the Fjall ecosystem — `Result` types, structured logger, security helpers (`maskSensitiveOutput`, `filterDangerousEnvVars`, `parseShellArgs`), and small helpers consumed by `@fjall/cli`, `@fjall/generator`, `@fjall/deploy-core`, and the Fjall webapp.
+
+The `@fjall/util` barrel export does **not** include Node-only modules — those are exposed via subpath imports so the package can also be consumed by webapp client bundles.
+
+## Installation
+
+```bash
+npm install @fjall/util
+```
+
+## Usage
+
+```typescript
+import { success, failure, type Result } from "@fjall/util";
+import { maskSensitiveOutput } from "@fjall/util";
+```
+
+## Licence
+
+Proprietary — see [LICENSE](./LICENSE).

package/dist/.minified

@@ -0,0 +1 @@
+21 files minified at 2026-04-20T23:47:24.814Z

package/dist/Config.d.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+export type ProviderAccount = {
+    id: string;
+    name: string;
+    environment: string;
+    managed?: boolean;
+    oidcRoleArn?: string;
+};
+export type Profile = {
+    type: "sso" | "oidc";
+    region: string;
+    ssoAccountId?: string;
+    ssoRoleName?: string;
+    ssoSession?: string;
+    oidcRoleArn?: string;
+    oidcProviderArn?: string;
+    roleArn?: string;
+    roleSessionName?: string;
+};
+export type SSOSession = {
+    ssoRegion: string;
+    ssoStartUrl: string;
+};
+declare const DomainConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        apex: "apex";
+        delegated: "delegated";
+    }>;
+    parentDomain: z.ZodOptional<z.ZodString>;
+    account: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type DomainConfig = z.infer<typeof DomainConfigSchema>;
+export declare const RootConfigSchema: z.ZodObject<{
+    activeTarget: z.ZodOptional<z.ZodString>;
+    domains: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            apex: "apex";
+            delegated: "delegated";
+        }>;
+        parentDomain: z.ZodOptional<z.ZodString>;
+        account: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type RootConfig = z.infer<typeof RootConfigSchema>;
+/**
+ * Config class for loading and saving the root fjall-config.json.
+ * Single config file at fjall/fjall-config.json (or fjall-config.json at cwd).
+ * Stores active target and domains.
+ * Org-level config (accounts, primary/DR regions, OIDC) is served by OrgConfigClient from the API.
+ */
+export declare class Config {
+    rootConfig: RootConfig;
+    private configPath;
+    constructor(rootConfig?: RootConfig, configPath?: string);
+    /**
+     * Find the config directory by walking up the directory tree.
+     * Looks for fjall/fjall-config.json or direct fjall-config.json.
+     */
+    private static findConfigDirectory;
+    private static loadConfigFile;
+    static loadConfig(): Config;
+    private static formatZodError;
+    saveConfig(): void;
+    static getConfigDirectory(): string | null;
+    getActiveTarget(): string | undefined;
+    setActiveTarget(name: string): void;
+    clearActiveTarget(): void;
+    getDomains(): DomainConfig[];
+    setDomains(domains: DomainConfig[]): void;
+    addDomain(domain: DomainConfig): void;
+    getDomain(name: string): DomainConfig | undefined;
+    removeDomain(name: string): boolean;
+}
+export {};

package/dist/Config.js

@@ -0,0 +1 @@
+import*as r from"fs";import*as s from"path";import{z as e}from"zod";import{logger as g}from"./logger.js";const l=10,m=e.object({name:e.string(),type:e.enum(["apex","delegated"]),parentDomain:e.string().optional(),account:e.string().optional()}).strict(),d=e.object({activeTarget:e.string().optional(),domains:e.array(m).optional()}).strict();class a{rootConfig;configPath=null;constructor(o,t){this.rootConfig=o??{},this.configPath=t??null}static findConfigDirectory(){let o=process.cwd();for(let t=0;t<l;t++){const n=s.join(o,"fjall"),i=s.join(n,"fjall-config.json");if(r.existsSync(i))return n;const c=s.join(o,"fjall-config.json");if(r.existsSync(c))return o;const f=s.dirname(o);if(f===o)break;o=f}return null}static loadConfigFile(o){try{return r.accessSync(o,r.constants.R_OK|r.constants.W_OK),r.readFileSync(o,{encoding:"utf8"})}catch(t){return g.debug("Config","Config file not accessible",{file:o,error:t instanceof Error?t.message:String(t)}),null}}static loadConfig(){const o=a.findConfigDirectory();if(!o)return new a;const t=s.join(o,"fjall-config.json"),n=a.loadConfigFile(t);let i;if(n)try{i=d.parse(JSON.parse(n))}catch(c){throw a.formatZodError(c,"fjall-config.json")}return new a(i,t)}static formatZodError(o,t){if(o instanceof e.ZodError&&o.issues.length>0){const c=o.issues.map(f=>`${f.path.join(".")}: ${f.message}`).join("; ");return new Error(`Failed to parse ${t}: ${c}`)}const i=(o instanceof Error?o.message:String(o)).replace(/\n/g," ").substring(0,500);return new Error(`Failed to parse ${t}: ${i}`)}saveConfig(){let o=this.configPath;if(!o){const c=a.findConfigDirectory()||s.join(process.cwd(),"fjall");o=s.join(c,"fjall-config.json")}const t=s.dirname(o);r.mkdirSync(t,{recursive:!0});const n=JSON.stringify(this.rootConfig,null,2),i=`${o}.tmp`;r.writeFileSync(i,n,{mode:384}),r.renameSync(i,o)}static getConfigDirectory(){return a.findConfigDirectory()}getActiveTarget(){return this.rootConfig.activeTarget}setActiveTarget(o){this.rootConfig.activeTarget=o}clearActiveTarget(){this.rootConfig.activeTarget=void 0}getDomains(){return this.rootConfig.domains??[]}setDomains(o){this.rootConfig.domains=o}addDomain(o){this.rootConfig.domains||(this.rootConfig.domains=[]),this.rootConfig.domains.push(o)}getDomain(o){return this.rootConfig.domains?.find(t=>t.name.toLowerCase()===o.toLowerCase())}removeDomain(o){if(!this.rootConfig.domains)return!1;const t=this.rootConfig.domains.findIndex(n=>n.name.toLowerCase()===o.toLowerCase());return t===-1?!1:(this.rootConfig.domains.splice(t,1),!0)}}export{a as Config,d as RootConfigSchema};

package/dist/aws/CloudFormationFailureAnalyser.d.ts

@@ -0,0 +1,32 @@
+import { type ResourceEvent } from "./cloudformationTypes.js";
+export interface RootCause {
+    resource: ResourceEvent;
+    reason: string;
+    category: "permissions" | "validation" | "dependency" | "limit" | "network" | "unknown";
+    isDirectCause: boolean;
+}
+export interface FailureAnalysis {
+    rootCause: RootCause;
+    affectedResources: ResourceEvent[];
+    dependencyChain: string[];
+    summary: string;
+    remediation: string[];
+    errorPattern?: string;
+}
+/**
+ * CloudFormationFailureAnalyser provides intelligent analysis of deployment failures
+ * It identifies root causes, dependency chains, and provides actionable remediation
+ */
+export declare class CloudFormationFailureAnalyser {
+    private knownErrorPatterns;
+    analyseFailure(eventHistory: Map<string, ResourceEvent[]>): FailureAnalysis | null;
+    private findFailedResources;
+    private findRootCause;
+    private categoriseError;
+    private isDirectCause;
+    private buildDependencyChain;
+    private generateRemediation;
+    private generateSummary;
+    private simplifyResourceType;
+    private isFailedStatus;
+}

package/dist/aws/CloudFormationFailureAnalyser.js

@@ -0,0 +1 @@
+class a{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(e){const r=this.findFailedResources(e);if(r.length===0)return null;const s=this.findRootCause(r,e),n=this.buildDependencyChain(s.resource,r),i=this.generateRemediation(s),t=this.generateSummary(s,r);return{rootCause:s,affectedResources:r,dependencyChain:n,summary:t,remediation:i,errorPattern:s.category}}findFailedResources(e){const r=[];for(const[s,n]of e){const i=n[n.length-1];i&&this.isFailedStatus(i.status)&&r.push(i)}return r.sort((s,n)=>s.timestamp.getTime()-n.timestamp.getTime())}findRootCause(e,r){if(e.length===0)return{resource:{logicalId:"Unknown",resourceType:"Unknown",status:"FAILED",timestamp:new Date},reason:"No failed resources found",category:"unknown",isDirectCause:!1};const s=e[0],n=this.categoriseError(s.statusReason||""),i=this.isDirectCause(s,r);return{resource:s,reason:s.statusReason||"Unknown error",category:n,isDirectCause:i}}categoriseError(e){for(const r of this.knownErrorPatterns)if(r.pattern.test(e))return r.category;return"unknown"}isDirectCause(e,r){const s=e.statusReason||"";return s.includes("depends on")||s.includes("referenced by")||s.includes("required by")?!1:!(r.get(e.logicalId)||[]).some(t=>t.status.includes("COMPLETE")&&!t.status.includes("ROLLBACK"))}buildDependencyChain(e,r){const s=[];s.push(`${e.logicalId} (${e.resourceType}) - ROOT CAUSE`);for(const n of r)n.logicalId!==e.logicalId&&((n.statusReason||"").toLowerCase().includes(e.logicalId.toLowerCase())?s.push(`  \u2192 ${n.logicalId} (${n.resourceType}) - Failed due to ${e.logicalId}`):s.push(`  \u2192 ${n.logicalId} (${n.resourceType})`));return s}generateRemediation(e){const r=[];for(const s of this.knownErrorPatterns)if(s.category===e.category){r.push(...s.remediation);break}return e.resource.resourceType.includes("IAM")?r.push("Review IAM policies and trust relationships"):e.resource.resourceType.includes("Lambda")?r.push("Check Lambda function configuration and runtime"):e.resource.resourceType.includes("ECS")&&r.push("Verify ECS task definition and container configuration"),r.length===0&&r.push("Review the CloudFormation console for detailed error messages","Check the resource configuration in your CDK code","Ensure all dependencies are properly defined"),r}generateSummary(e,r){const s=this.simplifyResourceType(e.resource.resourceType),n=r.length;let i=`Deployment failed: ${s} "${e.resource.logicalId}" `;switch(e.category){case"permissions":i+="failed due to insufficient permissions";break;case"validation":i+="failed validation";break;case"dependency":i+="has missing or invalid dependencies";break;case"limit":i+="exceeded AWS service limits";break;case"network":i+="encountered network issues";break;default:i+="failed to create"}return n>1&&(i+=` (${n-1} dependent resources also failed)`),i}simplifyResourceType(e){return e.replace("AWS::","").replace("::"," ")}isFailedStatus(e){return e.includes("FAILED")}}export{a as CloudFormationFailureAnalyser};

package/dist/aws/cloudformationTypes.d.ts

@@ -0,0 +1,17 @@
+/** CloudFormation error pattern for stacks that haven't been created yet */
+export declare const STACK_NOT_FOUND_PATTERN = "does not exist";
+/** CDK error string indicating the targeted stack does not exist in the synthesised output */
+export declare const CDK_NO_STACKS_MATCH = "No stacks match the name(s)";
+export interface ResourceEvent {
+    logicalId: string;
+    physicalId?: string;
+    resourceType: string;
+    status: string;
+    statusReason?: string;
+    timestamp: Date;
+    /** Topology group derived from construct map (e.g., "monitoring"). */
+    group?: string;
+    /** CDK construct path (e.g., "/Account/CloudTrail/trail/Resource"). */
+    constructPath?: string;
+}
+export declare function isResourceEvent(event: unknown): event is ResourceEvent;

package/dist/aws/cloudformationTypes.js

@@ -0,0 +1 @@
+const o="does not exist",e="No stacks match the name(s)";function i(t){if(typeof t!="object"||t===null||!("logicalId"in t)||!("resourceType"in t)||!("status"in t)||!("timestamp"in t))return!1;const s=t;return typeof s.logicalId=="string"&&typeof s.resourceType=="string"&&typeof s.status=="string"&&s.timestamp instanceof Date}export{e as CDK_NO_STACKS_MATCH,o as STACK_NOT_FOUND_PATTERN,i as isResourceEvent};

package/dist/aws/errors.d.ts

@@ -0,0 +1,26 @@
+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, message?: 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/aws/errors.js

@@ -0,0 +1 @@
+class e extends Error{code;constructor(t,n){super(t),this.code=n,this.name=this.constructor.name,Object.setPrototypeOf(this,new.target.prototype)}}class s extends e{constructor(t,n){const r=t?`No roles found for account ${t}`:"No roles found for this account";super(n??r,"NO_ROLES_FOUND")}}class i extends e{constructor(t){super(t,"INVALID_CREDENTIALS")}}class c extends e{constructor(){super("SSO token has expired","SSO_TOKEN_EXPIRED")}}class u extends e{constructor(){super("Region is missing in AWS configuration and environment","MISSING_REGION")}}class p extends e{constructor(t){super(`AWS profile '${t}' not found`,"PROFILE_NOT_FOUND")}}function a(o){return o instanceof e}function d(o){return o instanceof s}function E(o){return!o||typeof o!="object"?!1:"name"in o&&o.name==="UnauthorizedException"||"Code"in o&&o.Code==="UnauthorizedException"||"__type"in o&&typeof o.__type=="string"&&o.__type.includes("UnauthorizedException")}class x extends e{tip;constructor(t,n){super(t,"COMMAND_ERROR"),this.tip=n}}export{e as AWSError,x as CommandError,i as InvalidCredentialsError,u as MissingRegionError,s as NoRolesFoundError,p as ProfileNotFoundError,c as SSOTokenExpiredError,a as isAWSError,d as isNoRolesFoundError,E as isSSOUnauthorizedError};

package/dist/aws/index.d.ts

@@ -0,0 +1,3 @@
+export { AWSError, NoRolesFoundError, InvalidCredentialsError, SSOTokenExpiredError, MissingRegionError, ProfileNotFoundError, CommandError, isAWSError, isNoRolesFoundError, isSSOUnauthorizedError } from "./errors.js";
+export { STACK_NOT_FOUND_PATTERN, CDK_NO_STACKS_MATCH, type ResourceEvent, isResourceEvent } from "./cloudformationTypes.js";
+export { CloudFormationFailureAnalyser, type RootCause, type FailureAnalysis } from "./CloudFormationFailureAnalyser.js";

package/dist/aws/index.js

@@ -0,0 +1 @@
+import{AWSError as e,NoRolesFoundError as i,InvalidCredentialsError as n,SSOTokenExpiredError as E,MissingRegionError as s,ProfileNotFoundError as d,CommandError as S,isAWSError as l,isNoRolesFoundError as t,isSSOUnauthorizedError as a}from"./errors.js";import{STACK_NOT_FOUND_PATTERN as A,CDK_NO_STACKS_MATCH as C,isResourceEvent as N}from"./cloudformationTypes.js";import{CloudFormationFailureAnalyser as m}from"./CloudFormationFailureAnalyser.js";export{e as AWSError,C as CDK_NO_STACKS_MATCH,m as CloudFormationFailureAnalyser,S as CommandError,n as InvalidCredentialsError,s as MissingRegionError,i as NoRolesFoundError,d as ProfileNotFoundError,E as SSOTokenExpiredError,A as STACK_NOT_FOUND_PATTERN,l as isAWSError,t as isNoRolesFoundError,N as isResourceEvent,a as isSSOUnauthorizedError};

package/dist/caseConversion.js

@@ -0,0 +1 @@
+function o(e){return e.replace(/[-_](.)/g,(a,t)=>t.toUpperCase()).replace(/^./,a=>a.toUpperCase())}function r(e){return e.replace(/([A-Z]+)([A-Z][a-z])/g,"$1-$2").replace(/([a-z\d])([A-Z])/g,"$1-$2").replace(/[\s_]+/g,"-").toLowerCase()}function n(e){return r(e).replace(/-/g,"_")}function p(e){return e.length===0?e:e.charAt(0).toUpperCase()+e.slice(1)}function c(e){return e.split(".").join("")}export{p as capitalise,c as getSafeZoneName,r as toKebab,o as toPascalCase,n as toValidDatabaseName};

package/dist/constructMap.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Construct-to-topology-group mapping.
+ *
+ * Maps CDK construct IDs (the first segment below the stack in the construct
+ * path) to topology groups. These maps are used to derive which topology node
+ * a resource belongs to based on which CDK construct created it.
+ *
+ * When a new CDK construct is added, add one entry here.
+ * When a new AWS resource type is added, nothing changes.
+ */
+/** Manifest file name — single source of truth across CLI, deploy-core, and infrastructure. */
+export declare const FJALL_MANIFEST_FILENAME = "fjall-manifest.json";
+/** Current manifest schema version. Shared between CLI and infrastructure. */
+export declare const MANIFEST_SCHEMA_VERSION: 1;
+import type { ResourceCategory } from "./resourceCategorisation.js";
+/** Entry in the resource map — maps a logical ID to its construct context. */
+export interface ResourceMapEntry {
+    /** Full CDK construct path (e.g., "/Account/CloudTrail/managementEventsTrail/Resource") */
+    constructPath: string;
+    /** Topology group derived from the construct (e.g., "monitoring") */
+    group: string;
+    /** AWS resource type (e.g., "AWS::KMS::Key") */
+    resourceType: string;
+}
+/**
+ * Account stack construct-to-group mapping.
+ * Keys are CDK construct IDs (first segment after stack name in construct path).
+ */
+export declare const ACCOUNT_CONSTRUCT_GROUPS: Readonly<Record<string, ResourceCategory>>;
+/**
+ * Application stack construct-to-group mapping.
+ * Keys are CDK construct IDs (first segment after stack name in construct path).
+ */
+export declare const APP_CONSTRUCT_GROUPS: Readonly<Record<string, ResourceCategory>>;
+/**
+ * Derives the topology group from a CDK construct path.
+ *
+ * The construct path format is: /<StackName>/<ConstructId>/.../<Resource>
+ * We extract the first construct below the stack and look it up in the
+ * construct group maps.
+ *
+ * @param constructPath - Full CDK construct path
+ * @param constructGroups - Map of construct ID → topology group
+ * @returns The topology group or undefined if not mapped
+ */
+export declare function deriveGroupFromPath(constructPath: string, constructGroups: Readonly<Record<string, ResourceCategory>>): ResourceCategory | undefined;
+/**
+ * Derives a display name from a CDK construct path.
+ * Extracts the most meaningful segment from the path.
+ */
+export declare function deriveDisplayName(constructPath: string): string;
+/**
+ * Builds a construct map from CDK's manifest.json metadata.
+ *
+ * Reads the CDK cloud assembly manifest, inverts the `aws:cdk:logicalId`
+ * metadata entries to `logicalId → { constructPath, group, resourceType }`,
+ * and derives topology groups from the construct path.
+ *
+ * @param cdkOutPath - Path to the cdk.out directory
+ * @param constructGroups - Construct-to-group mapping (Account or Application)
+ * @returns Map of logicalId → ResourceMapEntry
+ */
+export declare function buildConstructMap(cdkOutPath: string, constructGroups: Readonly<Record<string, ResourceCategory>>): Map<string, ResourceMapEntry>;
+/**
+ * Converts a construct map to a plain object for JSON serialisation.
+ */
+export declare function constructMapToRecord(map: Map<string, ResourceMapEntry>): Record<string, ResourceMapEntry>;
+/**
+ * Converts a plain object back to a construct map.
+ */
+export declare function recordToConstructMap(record: Record<string, ResourceMapEntry> | undefined): Map<string, ResourceMapEntry>;
+/**
+ * Enriches a resource event with construct map data.
+ * Returns the group, constructPath, and displayName when available.
+ */
+export declare function enrichFromConstructMap(logicalId: string, resourceType: string, constructMap: Map<string, ResourceMapEntry> | undefined): {
+    group?: string;
+    constructPath?: string;
+    displayName: string;
+};

package/dist/constructMap.js

@@ -0,0 +1 @@
+const R="fjall-manifest.json",S=1;import{readFileSync as p}from"fs";import{join as l}from"path";import{logger as g}from"./logger.js";import{categoriseResource as d,getFriendlyResourceType as y}from"./resourceCategorisation.js";const h=Object.freeze({CloudTrail:"monitoring",MonitoringRole:"monitoring",AuditRole:"security",OidcConnector:"security",EcrDefaultImage:"registry",EventBus:"events",DisasterRecovery:"backup"}),A=Object.freeze({Network:"network",Database:"database",Compute:"compute",Storage:"storage",Messaging:"events",Cdn:"dns"});function C(o,e){const t=o.split("/").filter(Boolean);if(t.length<2)return;const r=t[1];return e[r]}function T(o){const e=o.split("/").filter(Boolean);return e.length<2?o:(e.length>2&&e[e.length-1]==="Resource"?e[e.length-2]:e[e.length-1]).replace(/([a-z])([A-Z])/g,"$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g,"$1 $2")}function E(o,e){const t=new Map;let r;try{const n=p(l(o,"manifest.json"),"utf-8"),s=JSON.parse(n);if(typeof s!="object"||s===null)return t;r=s}catch(n){return g.debug("ConstructMap","Could not read CDK manifest",{error:n instanceof Error?n.message:String(n)}),t}if(!r.artifacts)return t;for(const n of Object.values(r.artifacts)){if(n.type!=="aws:cloudformation:stack"||!n.metadata)continue;const s=b(o,n.properties?.templateFile);for(const[a,c]of Object.entries(n.metadata))for(const i of c){if(i.type!=="aws:cdk:logicalId")continue;const u=i.data,f=s.get(u)??"",m=C(a,e)??d(f);t.set(u,{constructPath:a,group:m,resourceType:f})}}return t}function b(o,e){const t=new Map;if(!e)return t;try{const r=p(l(o,e),"utf-8"),n=JSON.parse(r);if(typeof n!="object"||n===null)return t;const s=n;if(s.Resources&&typeof s.Resources=="object")for(const[a,c]of Object.entries(s.Resources))typeof c=="object"&&c!==null&&c.Type&&t.set(a,c.Type)}catch(r){g.debug("ConstructMap","Could not read template file",{templateFile:e,error:r instanceof Error?r.message:String(r)})}return t}function v(o){const e={};for(const[t,r]of o)e[t]=r;return e}function x(o){const e=new Map;if(!o)return e;for(const[t,r]of Object.entries(o))e.set(t,r);return e}function I(o,e,t){const r=t?.get(o);return r?{group:r.group,constructPath:r.constructPath,displayName:T(r.constructPath)}:{displayName:y(e)}}export{h as ACCOUNT_CONSTRUCT_GROUPS,A as APP_CONSTRUCT_GROUPS,R as FJALL_MANIFEST_FILENAME,S as MANIFEST_SCHEMA_VERSION,E as buildConstructMap,v as constructMapToRecord,T as deriveDisplayName,C as deriveGroupFromPath,I as enrichFromConstructMap,x as recordToConstructMap};

package/dist/{src/domainExports.d.ts → domainExports.d.ts}

@@ -2,11 +2,13 @@ export declare const DNS_APEX: "@";
 /**
  * Compute predictable CloudFormation export names for domain stack outputs.
  * Used by both infrastructure constructs (to set export names) and CLI services
- * (to import zone ID and certificate ARN via Fn.importValue).
+ * (to import zone ID, certificate ARN, and delegation role ARN via Fn.importValue).
  */
 export declare function getDomainExportNames(domainName: string): {
     hostedZoneId: string;
     certificateArn: string;
+    delegationRoleArn: string;
+    nameservers: string;
 };
 /**
  * Props for importing zone and certificate from a managed domain stack.

package/dist/domainExports.js

@@ -0,0 +1 @@
+const n="@";function t(r){const e=r.replace(/\./g,"-");return{hostedZoneId:`${e}-hosted-zone-id`,certificateArn:`${e}-certificate-arn`,delegationRoleArn:`${e}-delegation-role-arn`,nameservers:`${e}-nameservers`}}export{n as DNS_APEX,t as getDomainExportNames};

package/dist/environments.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Standard environment constants shared across CLI, webapp, and deploy-core.
+ *
+ * "root" is implicit — always derived from role === "organisation",
+ * not user-selectable.
+ */
+export declare const STANDARD_ENVIRONMENTS: readonly ["production", "staging", "development", "platform", "compliance"];
+export type StandardEnvironment = (typeof STANDARD_ENVIRONMENTS)[number];
+/** Type guard: checks whether a string is a valid standard environment. */
+export declare function isValidEnvironment(value: string): value is StandardEnvironment;
+/**
+ * Structural environments used for cascade account partitioning.
+ * These are not user-selectable — "root" is implicit (management account),
+ * "platform" hosts shared infrastructure (IPAM, Transit Gateway, etc.).
+ */
+export declare const STRUCTURAL_ENVIRONMENTS: {
+    readonly ROOT: "root";
+    readonly PLATFORM: "platform";
+};
+/** Human-readable labels for each standard environment. */
+export declare const ENVIRONMENT_LABELS: Record<StandardEnvironment, string>;
+/** Returns the human-readable label for an environment, with capitalised fallback. */
+export declare function getEnvironmentLabel(env: string): string;

package/dist/environments.js

@@ -0,0 +1 @@
+const o=["production","staging","development","platform","compliance"];function n(t){return o.includes(t)}const r={ROOT:"root",PLATFORM:"platform"},e={production:"Production",staging:"Staging",development:"Development",platform:"Platform",compliance:"Compliance"};function i(t){return n(t)?e[t]:t.charAt(0).toUpperCase()+t.slice(1)}export{e as ENVIRONMENT_LABELS,o as STANDARD_ENVIRONMENTS,r as STRUCTURAL_ENVIRONMENTS,i as getEnvironmentLabel,n as isValidEnvironment};

package/dist/errorUtils.js

@@ -0,0 +1 @@
+function f(n){return n instanceof Error?n:new Error(String(n))}function o(n){return n instanceof Error?n.message:typeof n=="string"?n:n&&typeof n=="object"&&"message"in n?String(n.message):"An unknown error occurred"}function c(n,t){return!n||typeof n!="object"?!1:"code"in n&&n.code===t}function i(n){if(!(!n||typeof n!="object")&&"code"in n&&typeof n.code=="string")return n.code}function u(n){return n instanceof Error?n.stack:void 0}function s(n){const t=o(n),e=i(n);return e&&e!=="UNKNOWN_ERROR"?`[${e}] ${t}`:t}export{s as formatErrorString,i as getErrorCode,o as getErrorMessage,u as getErrorStack,c as hasErrorCode,f as normaliseError};

package/dist/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/fsHelpers.js

@@ -0,0 +1 @@
+import{access as e,constants as c}from"fs/promises";async function o(t){try{return await e(t,c.F_OK),!0}catch(r){if(r instanceof Error&&"code"in r&&r.code==="ENOENT")return!1;throw r}}export{o as fileExists};

package/dist/gitRemoteParser.d.ts

@@ -0,0 +1,8 @@
+export type GitProvider = "github" | "gitlab" | "bitbucket" | "other";
+export interface ParsedGitRemote {
+    provider: GitProvider;
+    owner: string;
+    repo: string;
+    host: string;
+}
+export declare function parseGitRemoteUrl(url: string): ParsedGitRemote | null;

package/dist/gitRemoteParser.js

@@ -0,0 +1 @@
+const r={"github.com":"github","gitlab.com":"gitlab","bitbucket.org":"bitbucket"},s=/^https?:\/\/([^/]+)\/(.+?)\/([^/.]+?)(?:\.git)?$/,h=/^git@([^:]+):(.+?)\/([^/.]+?)(?:\.git)?$/,u=/^ssh:\/\/[^@]+@([^:/]+)(?::\d+)?\/(.+?)\/([^/.]+?)(?:\.git)?$/;function g(t){if(!t)return null;const i=t.replace(/^(https?:\/\/)[^@]+@/,"$1"),n=i.match(s)??i.match(h)??t.match(u);if(!n)return null;const[,o,c,e]=n;return!o||!c||!e?null:{provider:r[o]??"other",owner:c,repo:e,host:o}}export{g as parseGitRemoteUrl};

package/dist/index.d.ts

@@ -1 +1,11 @@
-export * from './src';
+export { DNS_APEX, getDomainExportNames, type ManagedDomainExports } from "./domainExports.js";
+export { toPascalCase, toKebab, toValidDatabaseName, capitalise, getSafeZoneName } from "./caseConversion.js";
+export { normaliseError, getErrorMessage, hasErrorCode, getErrorCode, getErrorStack, formatErrorString } from "./errorUtils.js";
+export { singleton } from "./singleton.js";
+export { DANGEROUS_ENV_VARS, filterDangerousEnvVars, maskSensitiveOutput, parseShellArgs } from "./securityHelpers.js";
+export { sleep } from "./sleep.js";
+export { STANDARD_ENVIRONMENTS, STRUCTURAL_ENVIRONMENTS, type StandardEnvironment, isValidEnvironment, ENVIRONMENT_LABELS, getEnvironmentLabel } from "./environments.js";
+export { RESOURCE_CATEGORIES, type ResourceCategory, categoriseResource, getExpectedDuration, getFriendlyResourceType } from "./resourceCategorisation.js";
+export { parseGitRemoteUrl, type GitProvider, type ParsedGitRemote } from "./gitRemoteParser.js";
+export { abbreviateRegion } from "./regions.js";
+export { deriveRegionsFromOrgConfig, deriveTargets, deriveAllTargets, findTarget, generateTargetName, type OrgConfigRegions, type TargetAccount, type DerivedTarget } from "./targets.js";

package/dist/index.js

@@ -1,18 +1 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./src"), exports);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7O0FBQUEsd0NBQXNCIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0ICogZnJvbSAnLi9zcmMnOyJdfQ==
+import{DNS_APEX as o,getDomainExportNames as t}from"./domainExports.js";import{toPascalCase as i,toKebab as s,toValidDatabaseName as E,capitalise as g,getSafeZoneName as m}from"./caseConversion.js";import{normaliseError as p,getErrorMessage as N,hasErrorCode as f,getErrorCode as R,getErrorStack as l,formatErrorString as S}from"./errorUtils.js";import{singleton as T}from"./singleton.js";import{DANGEROUS_ENV_VARS as A,filterDangerousEnvVars as v,maskSensitiveOutput as D,parseShellArgs as O}from"./securityHelpers.js";import{sleep as c}from"./sleep.js";import{STANDARD_ENVIRONMENTS as _,STRUCTURAL_ENVIRONMENTS as b,isValidEnvironment as u,ENVIRONMENT_LABELS as U,getEnvironmentLabel as I}from"./environments.js";import{RESOURCE_CATEGORIES as M,categoriseResource as G,getExpectedDuration as h,getFriendlyResourceType as k}from"./resourceCategorisation.js";import{parseGitRemoteUrl as F}from"./gitRemoteParser.js";import{abbreviateRegion as B}from"./regions.js";import{deriveRegionsFromOrgConfig as X,deriveTargets as Z,deriveAllTargets as j,findTarget as q,generateTargetName as w}from"./targets.js";export{A as DANGEROUS_ENV_VARS,o as DNS_APEX,U as ENVIRONMENT_LABELS,M as RESOURCE_CATEGORIES,_ as STANDARD_ENVIRONMENTS,b as STRUCTURAL_ENVIRONMENTS,B as abbreviateRegion,g as capitalise,G as categoriseResource,j as deriveAllTargets,X as deriveRegionsFromOrgConfig,Z as deriveTargets,v as filterDangerousEnvVars,q as findTarget,S as formatErrorString,w as generateTargetName,t as getDomainExportNames,I as getEnvironmentLabel,R as getErrorCode,N as getErrorMessage,l as getErrorStack,h as getExpectedDuration,k as getFriendlyResourceType,m as getSafeZoneName,f as hasErrorCode,u as isValidEnvironment,D as maskSensitiveOutput,p as normaliseError,F as parseGitRemoteUrl,O as parseShellArgs,T as singleton,c as sleep,s as toKebab,i as toPascalCase,E as toValidDatabaseName};

package/dist/insights/computePatternFingerprint.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/**
+ * Input shape for the cross-recurrence pattern fingerprint used by the
+ * Auto-snoozed view pill pipeline.
+ *
+ * See `aiDocs/designs/2026-04-19-auto-snoozed-pill.md` §4.2. The fingerprint
+ * collides intentionally across distinct `insight_id`s representing the same
+ * finding class within an org, which is what the 3-in-30d dismissal
+ * heuristic aggregates over.
+ */
+export declare const FingerprintInputSchema: z.ZodObject<{
+    organisationId: z.ZodString;
+    category: z.ZodString;
+    resourceType: z.ZodString;
+    metricName: z.ZodString;
+    applicationId: z.ZodString;
+}, z.core.$strict>;
+export type PatternFingerprintInput = z.infer<typeof FingerprintInputSchema>;
+/**
+ * Compute a stable SHA-256 hex digest identifying a finding class within an
+ * organisation. Deterministic: the same input yields the same digest on every
+ * invocation across every runtime (webapp SSR, CLI, monitoring worker).
+ *
+ * Throws on invalid input so producers fail loudly at the call site rather
+ * than writing an empty fingerprint that would be filtered out of the MV.
+ */
+export declare function computePatternFingerprint(input: PatternFingerprintInput): string;

package/dist/insights/computePatternFingerprint.js

@@ -0,0 +1 @@
+import{createHash as p}from"node:crypto";import{z as r}from"zod";const m=r.object({organisationId:r.string().min(1),category:r.string().min(1),resourceType:r.string().min(1),metricName:r.string().min(1),applicationId:r.string().min(1)}).strict();function u(e){const t=m.safeParse(e);if(!t.success)throw new Error(`Invalid pattern fingerprint input: ${t.error.message}`);const{organisationId:n,category:i,resourceType:a,metricName:o,applicationId:s}=t.data,c=`${n}|${i}|${a}|${o}|${s}`;return p("sha256").update(c).digest("hex")}export{m as FingerprintInputSchema,u as computePatternFingerprint};

package/dist/logger.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared logger for @fjall/util and packages that depend on it (deploy-core, generator).
+ *
+ * By default, output goes to stderr. Consumers that need richer behaviour (Ink UI
+ * suppression, file logging, structured JSONL) call {@link configureLogWriter} at
+ * startup to redirect all output through their own logging infrastructure.
+ *
+ * Level gating (debug requires FJALL_DEBUG, trace requires FJALL_TRACE) is handled
+ * here — the writer is only invoked for levels that pass the gate.
+ */
+export type LogLevel = "info" | "warn" | "error" | "debug" | "trace";
+/**
+ * Function that receives a log entry. The CLI replaces the default writer so
+ * deploy-core output is routed through the CLI logger (which handles Ink
+ * suppression, file rotation, and console formatting).
+ */
+export type LogWriter = (level: LogLevel, component: string, message: string, data?: Record<string, unknown>) => void;
+/**
+ * Replace the log writer. Call once at startup — typically the CLI calls this
+ * to route deploy-core output through its own logger.
+ */
+export declare function configureLogWriter(writer: LogWriter): void;
+/** Reset to the default stderr writer (useful in tests). */
+export declare function resetLogWriter(): void;
+export declare const logger: {
+    info(component: string, message: string, data?: Record<string, unknown>): void;
+    warn(component: string, message: string, data?: Record<string, unknown>): void;
+    error(component: string, message: string, data?: Record<string, unknown>): void;
+    debug(component: string, message: string, data?: Record<string, unknown>): void;
+    trace(component: string, message: string, data?: Record<string, unknown>): void;
+    isDebugEnabled(): boolean;
+};

package/dist/logger.js

@@ -0,0 +1,2 @@
+const u=r=>{try{return JSON.stringify(r)}catch{return"[unserializable]"}},i=(r,e,t,o)=>{const s=new Date().toISOString(),c=r.toUpperCase(),a=o?` ${u(o)}`:"";process.stderr.write(`[${s}] [${c}] [${e}] ${t}${a}
+`)};let n=i;function g(r){n=r}function f(){n=i}const p={info(r,e,t){n("info",r,e,t)},warn(r,e,t){n("warn",r,e,t)},error(r,e,t){n("error",r,e,t)},debug(r,e,t){process.env.FJALL_DEBUG==="true"&&n("debug",r,e,t)},trace(r,e,t){process.env.FJALL_TRACE==="true"&&n("trace",r,e,t)},isDebugEnabled(){return process.env.FJALL_DEBUG==="true"}};export{g as configureLogWriter,p as logger,f as resetLogWriter};

package/dist/regions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Region abbreviation utilities shared across CLI, webapp, and deploy-core.
+ */
+/**
+ * Abbreviate an AWS region name to a compact form.
+ * e.g. "us-east-1" → "use1", "eu-west-1" → "euw1"
+ */
+export declare function abbreviateRegion(region: string): string;

package/dist/regions.js

@@ -0,0 +1 @@
+function n(e){const t=e.split("-");return t.length===3&&t[0]&&t[1]&&t[1].length>0&&t[2]?`${t[0]}${t[1][0]}${t[2]}`:e}export{n as abbreviateRegion};

package/dist/resourceCategorisation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared resource categorisation — single source of truth for mapping
+ * AWS resource types to topology categories, expected durations, and
+ * friendly display names.
+ *
+ * Consumed by: CLI, deploy-core, webapp (via deploy-core re-export).
+ */
+export declare const RESOURCE_CATEGORIES: readonly ["security", "network", "compute", "database", "storage", "monitoring", "dns", "identity", "bootstrap", "events", "registry", "backup"];
+export type ResourceCategory = (typeof RESOURCE_CATEGORIES)[number];
+/**
+ * Maps an AWS resource type to a topology category.
+ * Falls back to "compute" for unknown types (neutral default).
+ */
+export declare function categoriseResource(resourceType: string): ResourceCategory;
+/** Returns the set of resource types that fell through to the default category. */
+export declare function getUnmappedResourceTypes(): ReadonlySet<string>;
+/** Clears the unmapped resource types set (for testing). */
+export declare function clearUnmappedResourceTypes(): void;
+/**
+ * Returns the expected creation duration in seconds for a given AWS resource type.
+ * Falls back to 30s for unmapped types.
+ */
+export declare function getExpectedDuration(resourceType: string): number;
+/**
+ * Returns a friendly display name for an AWS resource type.
+ * Falls back to the last segment after `::` for unknown types.
+ */
+export declare function getFriendlyResourceType(resourceType: string): string;