@fjall/util 3.8.0 → 3.9.0

package/dist/.minified

@@ -1 +1 @@
-89 files minified at 2026-07-20T10:43:55.097Z
+89 files minified at 2026-07-20T22:26:24.729Z

package/dist/config.d.ts

@@ -144,6 +144,7 @@ export declare const DomainConfigSchema: z.ZodObject<{
     }>;
     parentDomain: z.ZodOptional<z.ZodString>;
     account: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type DomainConfig = z.infer<typeof DomainConfigSchema>;
 export declare const RootConfigSchema: z.ZodObject<{
@@ -156,6 +157,7 @@ export declare const RootConfigSchema: z.ZodObject<{
         }>;
         parentDomain: z.ZodOptional<z.ZodString>;
         account: z.ZodOptional<z.ZodString>;
+        region: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type RootConfig = z.infer<typeof RootConfigSchema>;
@@ -180,17 +182,21 @@ export declare const RootConfigReadSchema: z.ZodObject<{
         }>;
         parentDomain: z.ZodOptional<z.ZodString>;
         account: z.ZodOptional<z.ZodString>;
+        region: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
 }, z.core.$strip>;
 export type RootConfigRead = z.infer<typeof RootConfigReadSchema>;
 /**
- * Canonical serialiser for the root fjall-config.json — the single source of
+ * Canonical serialiser for the root fjall-config.json - the single source of
  * truth for the file's on-disk shape. Both `Config.saveConfig` and the webapp
  * scaffold MUST route through this rather than hand-rolling the JSON, so the
  * two can never drift (a scaffold emitting a key the loader later rejects is
- * exactly the bug this prevents). The `RootConfig` input type makes an unknown
- * key unrepresentable at compile time; the round-trip test asserts the emitted
- * default validates against RootConfigSchema.
+ * exactly the bug this prevents). The `RootConfig` input type keeps OUR keys
+ * honest at compile time, but the emitted JSON is deliberately NOT
+ * strict-validated: `mergeWithDisk` routes top-level keys another fjall
+ * version wrote through the save verbatim (see its doc), so a merged save may
+ * carry keys RootConfigSchema does not recognise. The round-trip test asserts
+ * only that the emitted DEFAULT validates against RootConfigSchema.
  */
 export declare function serialiseRootConfig(config?: RootConfig): string;
 /**
@@ -214,6 +220,19 @@ export declare class Config {
      * from the on-disk copy.
      */
     private readonly clearedKeys;
+    /**
+     * Deep copy of the state this instance LOADED from disk (empty for a
+     * programmatically-constructed Config, whose entire state is session
+     * intent). saveConfig diffs the live state against this snapshot so it
+     * only re-asserts what this session actually changed - an untouched key
+     * (or an untouched domains[] entry) keeps whatever a concurrent process
+     * wrote to disk between load and save. This is the structural fix for
+     * the activeTarget lost-update incident: previously every save re-wrote
+     * the whole load-time snapshot at top-level-key granularity, clobbering
+     * a concurrent `fjall target set` and erasing concurrently-registered
+     * sibling domain entries.
+     */
+    private loadedSnapshot;
     constructor(rootConfig?: RootConfig, configPath?: string);
     /**
      * Find the config directory by walking up the directory tree.
@@ -236,14 +255,32 @@ export declare class Config {
      */
     private static assertWritable;
     /**
-     * Disk-preserving merge: re-reads the on-disk config immediately before
-     * writing so sibling top-level keys written by a concurrent process between
-     * this session's load and save survive. In-memory keys win at top-level-key
-     * granularity; keys explicitly cleared this session are removed even when
-     * the disk copy still carries them. Unreadable or invalid disk state falls
-     * back to the in-memory state with a warning rather than blocking the save.
+     * Session-intent merge: re-reads the on-disk config immediately before
+     * writing and asserts ONLY what this session actually changed relative to
+     * its load-time snapshot (see loadedSnapshot). An untouched key keeps the
+     * disk's current value, the `domains` key merges PER ENTRY (keyed by name)
+     * so concurrently-registered siblings survive, keys this version does not
+     * recognise ride through verbatim, and keys explicitly cleared this
+     * session are removed even when the disk copy still carries them.
+     * Unreadable or invalid disk state falls back to the in-memory state with
+     * a warning rather than blocking the save.
      */
     private mergeWithDisk;
+    /**
+     * Did this session change `key` relative to its load-time snapshot?
+     * JSON comparison is exact for today's scalar keys; a future nested
+     * top-level key needs its own per-entry merge (as `domains` has).
+     */
+    private sessionChangedKey;
+    /**
+     * Per-entry merge of the `domains` key. Disk order is the base: an entry
+     * this session changed is asserted, an entry this session removed (it was
+     * in the load snapshot, it is gone from live state) drops out, and any
+     * entry this session never touched keeps the DISK version - including
+     * entries a concurrent process registered after this session loaded.
+     * Session additions append after the disk entries.
+     */
+    private mergeDomains;
     private static readDiskConfigForMerge;
     static getConfigDirectory(startDir?: string): string | null;
     /**

package/dist/config.js

@@ -1 +1 @@
-var S=Object.defineProperty;var h=(d,e)=>S(d,"name",{value:e,configurable:!0});import*as i from"fs";import*as f from"path";import{z as s}from"zod";import{failure as g,success as w}from"./docker/result.js";import{getErrorMessage as C}from"./errorUtils.js";import{logger as y}from"./logger.js";import{maskSensitiveOutput as u}from"./securityHelpers.js";const v=10,m="fjall-config.json",M=["compliance","governance","none"],N=["enforced","off"],b=["centralised","off"],k=["account","draining","org"],I="managementEvents",L="organisationManagementEvents",U=["active","draining","removed"],J="FjallTrailBucketName",P="FjallTrailKeyArn",G="OrganisationTrailBucketName",E=s.object({name:s.string(),type:s.enum(["apex","delegated"]),parentDomain:s.string().optional(),account:s.string().optional()}).strict(),T=s.object({activeTarget:s.string().optional(),domains:s.array(E).optional()}).strict(),O=s.object({activeTarget:s.string().optional(),domains:s.array(E).optional()});function A(d={}){return JSON.stringify(d,null,2)}h(A,"serialiseRootConfig");const _=T.keyof().options;function x(d,e,t){const n=e[t];n!==void 0&&(d[t]=n)}h(x,"copyDefinedKey");class a{static{h(this,"Config")}rootConfig;configPath=null;loadFailed=!1;clearedKeys=new Set;constructor(e,t){this.rootConfig=e??{},this.configPath=t??null}static findConfigDirectory(e){let t=e!==void 0&&e!==""?e:process.cwd();for(let n=0;n<v;n++){const r=f.join(t,"fjall"),c=f.join(r,m);if(i.existsSync(c))return r;const o=f.join(t,m);if(i.existsSync(o))return t;const l=f.dirname(t);if(l===t)break;t=l}return null}static loadConfigFile(e){try{return i.accessSync(e,i.constants.R_OK),i.readFileSync(e,{encoding:"utf8"})}catch(t){return y.warn("Config",`Config file at ${e} could not be read; using defaults`,{file:e,error:u(C(t))}),null}}static loadConfig(e){const t=a.findConfigDirectory(e);if(!t)return new a;const n=f.join(t,m),r=a.loadConfigFile(n);if(r===null){const o=new a(void 0,n);return o.loadFailed=!0,o}let c;if(r!==""){let o;try{o=JSON.parse(r)}catch(p){throw a.formatZodError(p,m)}const l=T.safeParse(o);if(l.success)c=l.data;else{const p=O.safeParse(o);c=p.success?p.data:{},y.warn("Config","fjall-config.json contains keys this version does not recognise; they were ignored (only activeTarget and domains are read). If this is an old config, regenerate it with `fjall create ...` or re-run `fjall connect`.",{file:n})}}return new a(c,n)}static formatZodError(e,t){if(e instanceof s.ZodError&&e.issues.length>0){const c=e.issues.map(o=>`${o.path.join(".")}: ${o.message}`).join("; ");return new Error(`Failed to parse ${t}: ${c}`)}const r=(e instanceof Error?e.message:String(e)).replace(/\n/g," ").substring(0,500);return new Error(`Failed to parse ${t}: ${r}`)}saveConfig(){let e=this.configPath;if(!e){const o=a.findConfigDirectory()||f.join(process.cwd(),"fjall");e=f.join(o,m)}if(this.loadFailed)return g(new Error(`Refusing to save ${e}: the file exists but could not be read when this config loaded, so saving would replace its contents with state that never included them. Fix the file permissions (e.g. chmod u+rw ${e}) and retry.`));const t=f.dirname(e);try{i.mkdirSync(t,{recursive:!0})}catch(o){return g(new Error(`Cannot create config directory ${t}: ${u(C(o))}`))}const n=a.assertWritable(e,t);if(!n.success)return n;const r=A(this.mergeWithDisk(e)),c=`${e}.tmp-${process.pid}`;try{i.writeFileSync(c,r,{mode:384}),i.renameSync(c,e)}catch(o){return g(new Error(`Failed to save ${e}: ${u(C(o))}`))}return w(void 0)}static assertWritable(e,t){if(i.existsSync(e))try{i.accessSync(e,i.constants.W_OK)}catch{return g(new Error(`Cannot save ${e}: the file is read-only. Make it writable (e.g. chmod u+w ${e}) and retry.`))}try{i.accessSync(t,i.constants.W_OK)}catch{return g(new Error(`Cannot save ${e}: the directory ${t} is not writable. Make it writable (e.g. chmod u+w ${t}) and retry.`))}return w(void 0)}mergeWithDisk(e){const t=a.readDiskConfigForMerge(e);if(t===void 0)return this.rootConfig;const n={...t};for(const r of _)x(n,this.rootConfig,r);for(const r of this.clearedKeys)delete n[r];return n}static readDiskConfigForMerge(e){if(!i.existsSync(e))return;let t;try{t=JSON.parse(i.readFileSync(e,{encoding:"utf8"}))}catch(r){y.warn("Config",`Could not re-read ${e} before saving; writing in-memory state without merging`,{file:e,error:u(C(r))});return}const n=T.safeParse(t);if(!n.success){y.warn("Config",`On-disk ${e} failed validation before saving; writing in-memory state without merging`,{file:e,error:u(n.error.message)});return}return n.data}static getConfigDirectory(e){return a.findConfigDirectory(e)}getConfigPath(){return this.configPath}getActiveTarget(){return this.rootConfig.activeTarget}setActiveTarget(e){this.rootConfig.activeTarget=e,this.clearedKeys.delete("activeTarget")}clearActiveTarget(){this.rootConfig.activeTarget=void 0,this.clearedKeys.add("activeTarget")}getDomains(){return this.rootConfig.domains??[]}setDomains(e){this.rootConfig.domains=e}addDomain(e){this.rootConfig.domains||(this.rootConfig.domains=[]),this.rootConfig.domains.push(e)}getDomain(e){return this.rootConfig.domains?.find(t=>t.name.toLowerCase()===e.toLowerCase())}removeDomain(e){if(!this.rootConfig.domains)return!1;const t=this.rootConfig.domains.findIndex(n=>n.name.toLowerCase()===e.toLowerCase());return t===-1?!1:(this.rootConfig.domains.splice(t,1),!0)}}export{I as ACCOUNT_TRAIL_NAME,U as ACCOUNT_TRAIL_STATES,a as Config,E as DomainConfigSchema,L as ORGANISATION_TRAIL_NAME,G as ORG_TRAIL_BUCKET_OUTPUT_KEY,b as ROOT_ACCESS_MANAGEMENT_MODES,m as ROOT_CONFIG_FILENAME,O as RootConfigReadSchema,T as RootConfigSchema,N as S3_BPA_MODES,J as TRAIL_BUCKET_OUTPUT_KEY,P as TRAIL_KEY_ARN_OUTPUT_KEY,k as TRAIL_LIFECYCLE_STATES,M as VAULT_LOCK_MODES,A as serialiseRootConfig};
+var x=Object.defineProperty;var p=(l,e)=>x(l,"name",{value:e,configurable:!0});import*as s from"fs";import*as g from"path";import{z as f}from"zod";import{failure as y,success as O}from"./docker/result.js";import{getErrorMessage as S}from"./errorUtils.js";import{logger as T}from"./logger.js";import{maskSensitiveOutput as C}from"./securityHelpers.js";const $=10,w="fjall-config.json",U=["compliance","governance","none"],J=["enforced","off"],B=["centralised","off"],P=["account","draining","org"],G="managementEvents",W="organisationManagementEvents",Y=["active","draining","removed"],Z="FjallTrailBucketName",H="FjallTrailKeyArn",q="OrganisationTrailBucketName",A=f.object({name:f.string(),type:f.enum(["apex","delegated"]),parentDomain:f.string().optional(),account:f.string().optional(),region:f.string().optional()}).strict(),D=f.object({activeTarget:f.string().optional(),domains:f.array(A).optional()}).strict(),j=f.object({activeTarget:f.string().optional(),domains:f.array(A).optional()});function F(l={}){return JSON.stringify(l,null,2)}p(F,"serialiseRootConfig");const _=D.keyof().options;function N(l,e,n){const t=e[n];t!==void 0&&(l[n]=t)}p(N,"copyDefinedKey");function k(l,e){if(e===void 0)return!1;const n=new Set([...Object.keys(l),...Object.keys(e)]);for(const t of n)if(l[t]!==e[t])return!1;return!0}p(k,"domainEntriesEqual");class d{static{p(this,"Config")}rootConfig;configPath=null;loadFailed=!1;clearedKeys=new Set;loadedSnapshot={};constructor(e,n){this.rootConfig=e??{},this.configPath=n??null}static findConfigDirectory(e){let n=e!==void 0&&e!==""?e:process.cwd();for(let t=0;t<$;t++){const r=g.join(n,"fjall"),o=g.join(r,w);if(s.existsSync(o))return r;const i=g.join(n,w);if(s.existsSync(i))return n;const c=g.dirname(n);if(c===n)break;n=c}return null}static loadConfigFile(e){try{return s.accessSync(e,s.constants.R_OK),s.readFileSync(e,{encoding:"utf8"})}catch(n){return T.warn("Config",`Config file at ${e} could not be read; using defaults`,{file:e,error:C(S(n))}),null}}static loadConfig(e){const n=d.findConfigDirectory(e);if(!n)return new d;const t=g.join(n,w),r=d.loadConfigFile(t);if(r===null){const c=new d(void 0,t);return c.loadFailed=!0,c}let o;if(r!==""){let c;try{c=JSON.parse(r)}catch(m){throw d.formatZodError(m,w)}const u=D.safeParse(c);if(u.success)o=u.data;else{const m=j.safeParse(c);o=m.success?m.data:{},T.warn("Config","fjall-config.json contains keys this version does not recognise; they were ignored (only activeTarget and domains are read). If this is an old config, regenerate it with `fjall create ...` or re-run `fjall connect`.",{file:t})}}const i=new d(o,t);return i.loadedSnapshot=structuredClone(i.rootConfig),i}static formatZodError(e,n){if(e instanceof f.ZodError&&e.issues.length>0){const o=e.issues.map(i=>`${i.path.join(".")}: ${i.message}`).join("; ");return new Error(`Failed to parse ${n}: ${o}`)}const r=(e instanceof Error?e.message:String(e)).replace(/\n/g," ").substring(0,500);return new Error(`Failed to parse ${n}: ${r}`)}saveConfig(){let e=this.configPath;if(!e){const i=d.findConfigDirectory()||g.join(process.cwd(),"fjall");e=g.join(i,w)}if(this.loadFailed)return y(new Error(`Refusing to save ${e}: the file exists but could not be read when this config loaded, so saving would replace its contents with state that never included them. Fix the file permissions (e.g. chmod u+rw ${e}) and retry.`));const n=g.dirname(e);try{s.mkdirSync(n,{recursive:!0})}catch(i){return y(new Error(`Cannot create config directory ${n}: ${C(S(i))}`))}const t=d.assertWritable(e,n);if(!t.success)return t;const r=F(this.mergeWithDisk(e)),o=`${e}.tmp-${process.pid}`;try{s.writeFileSync(o,r,{mode:384}),s.renameSync(o,e)}catch(i){return y(new Error(`Failed to save ${e}: ${C(S(i))}`))}return O(void 0)}static assertWritable(e,n){if(s.existsSync(e))try{s.accessSync(e,s.constants.W_OK)}catch{return y(new Error(`Cannot save ${e}: the file is read-only. Make it writable (e.g. chmod u+w ${e}) and retry.`))}try{s.accessSync(n,s.constants.W_OK)}catch{return y(new Error(`Cannot save ${e}: the directory ${n} is not writable. Make it writable (e.g. chmod u+w ${n}) and retry.`))}return O(void 0)}mergeWithDisk(e){const n=d.readDiskConfigForMerge(e);if(n===void 0)return this.rootConfig;const t={...n.foreign,...n.known};for(const o of _)o!=="domains"&&this.sessionChangedKey(o)&&(this.rootConfig[o]===void 0?delete t[o]:N(t,this.rootConfig,o));const r=this.mergeDomains(n.known.domains);r!==void 0?t.domains=r:delete t.domains;for(const o of this.clearedKeys)delete t[o];return t}sessionChangedKey(e){return JSON.stringify(this.rootConfig[e])!==JSON.stringify(this.loadedSnapshot[e])}mergeDomains(e){const n=this.rootConfig.domains,t=this.loadedSnapshot.domains??[];if(n===void 0&&t.length===0)return e;const r=p(a=>a.toLowerCase(),"norm"),o=n??[],i=new Map(t.map(a=>[r(a.name),a])),c=new Map(o.map(a=>[r(a.name),a])),u=[],m=new Set;for(const a of e??[]){const h=r(a.name);m.add(h);const E=c.get(h),v=i.get(h);if(E!==void 0&&!k(E,v)){u.push(E);continue}E===void 0&&v!==void 0||u.push(a)}for(const a of o){const h=r(a.name);m.has(h)||k(a,i.get(h))||u.push(a)}return u}static readDiskConfigForMerge(e){if(!s.existsSync(e))return;let n;try{n=JSON.parse(s.readFileSync(e,{encoding:"utf8"}))}catch(o){T.warn("Config",`Could not re-read ${e} before saving; writing in-memory state without merging`,{file:e,error:C(S(o))});return}const t=j.safeParse(n);if(!t.success){T.warn("Config",`On-disk ${e} failed validation before saving; writing in-memory state without merging`,{file:e,error:C(t.error.message)});return}const r={};if(typeof n=="object"&&n!==null){const o=_;for(const[i,c]of Object.entries(n))o.includes(i)||(r[i]=c)}return{known:t.data,foreign:r}}static getConfigDirectory(e){return d.findConfigDirectory(e)}getConfigPath(){return this.configPath}getActiveTarget(){return this.rootConfig.activeTarget}setActiveTarget(e){this.rootConfig.activeTarget=e,this.clearedKeys.delete("activeTarget")}clearActiveTarget(){this.rootConfig.activeTarget=void 0,this.clearedKeys.add("activeTarget")}getDomains(){return this.rootConfig.domains??[]}setDomains(e){this.rootConfig.domains=e}addDomain(e){this.rootConfig.domains||(this.rootConfig.domains=[]),this.rootConfig.domains.push(e)}getDomain(e){return this.rootConfig.domains?.find(n=>n.name.toLowerCase()===e.toLowerCase())}removeDomain(e){if(!this.rootConfig.domains)return!1;const n=this.rootConfig.domains.findIndex(t=>t.name.toLowerCase()===e.toLowerCase());return n===-1?!1:(this.rootConfig.domains.splice(n,1),!0)}}export{G as ACCOUNT_TRAIL_NAME,Y as ACCOUNT_TRAIL_STATES,d as Config,A as DomainConfigSchema,W as ORGANISATION_TRAIL_NAME,q as ORG_TRAIL_BUCKET_OUTPUT_KEY,B as ROOT_ACCESS_MANAGEMENT_MODES,w as ROOT_CONFIG_FILENAME,j as RootConfigReadSchema,D as RootConfigSchema,J as S3_BPA_MODES,Z as TRAIL_BUCKET_OUTPUT_KEY,H as TRAIL_KEY_ARN_OUTPUT_KEY,P as TRAIL_LIFECYCLE_STATES,U as VAULT_LOCK_MODES,F as serialiseRootConfig};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/util",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Common utility methods",
   "type": "module",
   "main": "dist/index.js",
@@ -134,5 +134,5 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "gitHead": "9a137b6bd380f432f6c6e8e43b7932dec0b64a13"
+  "gitHead": "7cef1c5c3c09bb333888e65ede3d92b2d88c3c63"
 }