@fjall/util 2.11.1 → 2.13.0

package/dist/.minified

@@ -1 +1 @@
-59 files minified at 2026-06-07T01:01:57.688Z
+61 files minified at 2026-06-10T21:04:19.408Z

package/dist/Config.d.ts

@@ -1,14 +1,69 @@
 import { z } from "zod";
+import { type Result } from "./docker/result.js";
+import { type AccountTier } from "./environments.js";
 /**
  * Backup Vault Lock modes for an account's DisasterRecovery vault.
  * See decisions/2026-06-03-backup-vault-lock-mode-by-intent.md.
  */
 export declare const VAULT_LOCK_MODES: readonly ["compliance", "governance", "none"];
 export type VaultLockMode = (typeof VAULT_LOCK_MODES)[number];
+/**
+ * Account-level S3 Block Public Access posture. Fjall observes-and-flags public
+ * buckets through the posture layer rather than hard-blocking, so enforcement is
+ * off by default; "enforced" opts an account into all four account-level flags.
+ */
+export declare const S3_BPA_MODES: readonly ["enforced", "off"];
+export type S3BpaMode = (typeof S3_BPA_MODES)[number];
+/**
+ * Per-account management-events-trail lifecycle for the organisation-trail
+ * migration. Absent ⇒ legacy per-account trail, auto-eligible for migration
+ * once org-trail delivery is verified. "account" pins the per-account trail
+ * (the explicit reverse path). "draining" removes the trail resource while
+ * retaining its bucket + CMK. "org" is terminal: the organisation trail
+ * covers the account and local storage has been decommissioned.
+ */
+export declare const TRAIL_LIFECYCLE_STATES: readonly ["account", "draining", "org"];
+export type TrailLifecycleState = (typeof TRAIL_LIFECYCLE_STATES)[number];
+/**
+ * Trail names shared between the CDK constructs
+ * (@fjall/components-infrastructure) and the deploy-core org-trail migration —
+ * SDK probes (DescribeTrails) must match what the constructs synthesise.
+ */
+export declare const ACCOUNT_TRAIL_NAME = "managementEvents";
+export declare const ORGANISATION_TRAIL_NAME = "organisationManagementEvents";
+/**
+ * CDK-side trail-state vocabulary (the `fjallAccountTrailState` context
+ * value), shared between the CDK constructs and deploy-core's context
+ * builders. Distinct from TRAIL_LIFECYCLE_STATES: config intent
+ * ("account"/"draining"/"org") maps onto synth behaviour
+ * ("active"/"draining"/"removed").
+ */
+export declare const ACCOUNT_TRAIL_STATES: readonly ["active", "draining", "removed"];
+export type AccountTrailState = (typeof ACCOUNT_TRAIL_STATES)[number];
+/**
+ * Stack output keys (CfnOutput key + exportName) emitted by the Account /
+ * Organisation CDK patterns and read back by the deploy-core org-trail
+ * migration reconciler — both sides must use the same literals.
+ */
+export declare const TRAIL_BUCKET_OUTPUT_KEY = "FjallTrailBucketName";
+export declare const TRAIL_KEY_ARN_OUTPUT_KEY = "FjallTrailKeyArn";
+export declare const ORG_TRAIL_BUCKET_OUTPUT_KEY = "OrganisationTrailBucketName";
 export type ProviderAccount = {
     id: string;
     name: string;
-    environment: string;
+    /**
+     * Workload STAGE — null for structural accounts (organisation/platform tiers
+     * carry no workload stage). Read the structural axis from `tier`, never from
+     * this field.
+     */
+    environment: string | null;
+    /**
+     * Structural TIER (organisation/platform/account). Optional for wire
+     * back-compat: old configs omit it and readers fall back to decoding
+     * `environment` via `accountTier()`. Producers (webapp buildOrgConfigPayload)
+     * emit it explicitly so the tier no longer rides on the environment string.
+     */
+    tier?: AccountTier;
     managed?: boolean;
     oidcRoleArn?: string;
     /**
@@ -26,6 +81,23 @@ export type ProviderAccount = {
     vaultLock?: VaultLockMode;
     /** Explicit acknowledgement that vaultLock: "compliance" is irreversible. */
     acknowledgeImmutableVaultLock?: boolean;
+    /**
+     * Account-level S3 Block Public Access posture. Absent ⇒ "off" — Fjall does
+     * not enforce account-level BPA (the posture layer flags exposed buckets
+     * instead). "enforced" sets all four account-level public-access flags true.
+     */
+    s3BlockPublicAccess?: S3BpaMode;
+    /**
+     * Management-events-trail lifecycle for the org-trail migration. Absent ⇒
+     * legacy per-account trail (auto-eligible); see TRAIL_LIFECYCLE_STATES.
+     */
+    trailLifecycle?: TrailLifecycleState;
+    /**
+     * Explicit acknowledgement that decommissioning the per-account trail
+     * discards its retained log history. Bucket deletion never proceeds without
+     * it — back up the bucket first if the history matters.
+     */
+    acknowledgeTrailHistoryLoss?: boolean;
 };
 export type Profile = {
     type: "sso" | "oidc";
@@ -74,17 +146,50 @@ export type RootConfig = z.infer<typeof RootConfigSchema>;
 export declare class Config {
     rootConfig: RootConfig;
     private configPath;
+    /**
+     * True when the config file was FOUND on disk but could not be read.
+     * saveConfig refuses to write in that state — the in-memory config never
+     * included the real file's contents, so writing would clobber them.
+     */
+    private loadFailed;
+    /**
+     * Top-level keys explicitly cleared this session (clearActiveTarget).
+     * The disk-preserving merge in saveConfig would otherwise resurrect them
+     * from the on-disk copy.
+     */
+    private readonly clearedKeys;
     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.
+     * Walks up from `startDir` when provided, otherwise from process.cwd().
      */
     private static findConfigDirectory;
     private static loadConfigFile;
-    static loadConfig(): Config;
+    /**
+     * Load the config, walking up from `startDir` (default process.cwd()).
+     */
+    static loadConfig(startDir?: string): Config;
     private static formatZodError;
-    saveConfig(): void;
-    static getConfigDirectory(): string | null;
+    saveConfig(): Result<void, Error>;
+    /**
+     * Writability is checked at save time, not load time: POSIX rename replaces
+     * a read-only destination whenever the directory is writable, so without
+     * this guard the tmp-plus-rename write would silently replace a chmod-444
+     * 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.
+     */
+    private mergeWithDisk;
+    private static readDiskConfigForMerge;
+    static getConfigDirectory(startDir?: string): string | null;
     getActiveTarget(): string | undefined;
     setActiveTarget(name: string): void;
     clearActiveTarget(): void;

package/dist/Config.js

@@ -1 +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,h=["compliance","governance","none"],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,h as VAULT_LOCK_MODES};
+import*as i from"fs";import*as f from"path";import{z as c}from"zod";import{failure as d,success as h}from"./docker/result.js";import{getErrorMessage as g}from"./errorUtils.js";import{logger as u}from"./logger.js";import{maskSensitiveOutput as l}from"./securityHelpers.js";const y=10,O=["compliance","governance","none"],$=["enforced","off"],_=["account","draining","org"],x="managementEvents",F="organisationManagementEvents",K=["active","draining","removed"],b="FjallTrailBucketName",k="FjallTrailKeyArn",L="OrganisationTrailBucketName",w=c.object({name:c.string(),type:c.enum(["apex","delegated"]),parentDomain:c.string().optional(),account:c.string().optional()}).strict(),m=c.object({activeTarget:c.string().optional(),domains:c.array(w).optional()}).strict(),T=m.keyof().options;function E(C,e,t){const n=e[t];n!==void 0&&(C[t]=n)}class s{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<y;n++){const o=f.join(t,"fjall"),a=f.join(o,"fjall-config.json");if(i.existsSync(a))return o;const r=f.join(t,"fjall-config.json");if(i.existsSync(r))return t;const p=f.dirname(t);if(p===t)break;t=p}return null}static loadConfigFile(e){try{return i.accessSync(e,i.constants.R_OK),i.readFileSync(e,{encoding:"utf8"})}catch(t){return u.warn("Config",`Config file at ${e} could not be read; using defaults`,{file:e,error:l(g(t))}),null}}static loadConfig(e){const t=s.findConfigDirectory(e);if(!t)return new s;const n=f.join(t,"fjall-config.json"),o=s.loadConfigFile(n);if(o===null){const r=new s(void 0,n);return r.loadFailed=!0,r}let a;if(o!=="")try{a=m.parse(JSON.parse(o))}catch(r){throw s.formatZodError(r,"fjall-config.json")}return new s(a,n)}static formatZodError(e,t){if(e instanceof c.ZodError&&e.issues.length>0){const a=e.issues.map(r=>`${r.path.join(".")}: ${r.message}`).join("; ");return new Error(`Failed to parse ${t}: ${a}`)}const o=(e instanceof Error?e.message:String(e)).replace(/\n/g," ").substring(0,500);return new Error(`Failed to parse ${t}: ${o}`)}saveConfig(){let e=this.configPath;if(!e){const r=s.findConfigDirectory()||f.join(process.cwd(),"fjall");e=f.join(r,"fjall-config.json")}if(this.loadFailed)return d(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(r){return d(new Error(`Cannot create config directory ${t}: ${l(g(r))}`))}const n=s.assertWritable(e,t);if(!n.success)return n;const o=JSON.stringify(this.mergeWithDisk(e),null,2),a=`${e}.tmp-${process.pid}`;try{i.writeFileSync(a,o,{mode:384}),i.renameSync(a,e)}catch(r){return d(new Error(`Failed to save ${e}: ${l(g(r))}`))}return h(void 0)}static assertWritable(e,t){if(i.existsSync(e))try{i.accessSync(e,i.constants.W_OK)}catch{return d(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 d(new Error(`Cannot save ${e}: the directory ${t} is not writable. Make it writable (e.g. chmod u+w ${t}) and retry.`))}return h(void 0)}mergeWithDisk(e){const t=s.readDiskConfigForMerge(e);if(t===void 0)return this.rootConfig;const n={...t};for(const o of T)E(n,this.rootConfig,o);for(const o of this.clearedKeys)delete n[o];return n}static readDiskConfigForMerge(e){if(!i.existsSync(e))return;let t;try{t=JSON.parse(i.readFileSync(e,{encoding:"utf8"}))}catch(o){u.warn("Config",`Could not re-read ${e} before saving; writing in-memory state without merging`,{file:e,error:l(g(o))});return}const n=m.safeParse(t);if(!n.success){u.warn("Config",`On-disk ${e} failed validation before saving; writing in-memory state without merging`,{file:e,error:l(n.error.message)});return}return n.data}static getConfigDirectory(e){return s.findConfigDirectory(e)}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{x as ACCOUNT_TRAIL_NAME,K as ACCOUNT_TRAIL_STATES,s as Config,F as ORGANISATION_TRAIL_NAME,L as ORG_TRAIL_BUCKET_OUTPUT_KEY,m as RootConfigSchema,$ as S3_BPA_MODES,b as TRAIL_BUCKET_OUTPUT_KEY,k as TRAIL_KEY_ARN_OUTPUT_KEY,_ as TRAIL_LIFECYCLE_STATES,O as VAULT_LOCK_MODES};

package/dist/backupVault.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Fixed name of the disaster-recovery backup vault. Single source of truth for
+ * the @fjall/components-infrastructure DisasterRecovery construct (which
+ * creates the vault under this name) and deploy-core's adopt-vs-create and
+ * survival probes (which look it up by the same name).
+ */
+export declare const BACKUP_VAULT_NAME = "backupVault";

package/dist/backupVault.js

@@ -0,0 +1 @@
+const t="backupVault";export{t as BACKUP_VAULT_NAME};

package/dist/connectionsWire.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Wire contract for `GET /api/connections/list` — the single shared shape
+ * between the webapp producer (`webapp/app/routes/api/connections/list.ts`)
+ * and the CLI consumer (`FjallApiClient.getConnectedAccounts`). Neither side
+ * may redeclare this record: the producer conforms at compile time via
+ * `satisfies ConnectionWire`, the consumer parses with `safeParse`.
+ */
+import { z } from "zod";
+export declare const ConnectionWireSchema: z.ZodObject<{
+    awsAccountId: z.ZodString;
+    accountName: z.ZodNullable<z.ZodString>;
+    status: z.ZodString;
+    role: z.ZodString;
+    roleArn: z.ZodString;
+    environment: z.ZodOptional<z.ZodString>;
+    connectedAt: z.ZodString;
+}, z.core.$strip>;
+export type ConnectionWire = z.infer<typeof ConnectionWireSchema>;
+export declare const ConnectionsListResponseSchema: z.ZodObject<{
+    accounts: z.ZodArray<z.ZodObject<{
+        awsAccountId: z.ZodString;
+        accountName: z.ZodNullable<z.ZodString>;
+        status: z.ZodString;
+        role: z.ZodString;
+        roleArn: z.ZodString;
+        environment: z.ZodOptional<z.ZodString>;
+        connectedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ConnectionsListResponse = z.infer<typeof ConnectionsListResponseSchema>;

package/dist/connectionsWire.js

@@ -0,0 +1 @@
+import{z as n}from"zod";const t=n.object({awsAccountId:n.string(),accountName:n.string().nullable(),status:n.string(),role:n.string(),roleArn:n.string(),environment:n.string().optional(),connectedAt:n.string()}),e=n.object({accounts:n.array(t)});export{t as ConnectionWireSchema,e as ConnectionsListResponseSchema};

package/dist/environments.d.ts

@@ -1,13 +1,18 @@
 /**
- * Standard environment constants shared across CLI, webapp, and deploy-core.
- *
- * "root" is implicit — always derived from role === "organisation",
- * not user-selectable.
+ * Environment + account-axis constants shared across CLI, webapp, and
+ * deploy-core. Two independent axes live here: the workload STAGE
+ * ([[ACCOUNT_STAGES]]) and the structural TIER ([[ACCOUNT_TIERS]]). "root" is
+ * NOT a stage and NOT a tier — it is the wire environment marker that decodes
+ * to tier "organisation" via [[environmentToTier]], and is never
+ * 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;
+import { z } from "zod";
+export declare const ACCOUNT_STAGES: readonly ["production", "staging", "development", "platform", "compliance"];
+export type AccountStage = (typeof ACCOUNT_STAGES)[number];
+/** Human-readable labels for each workload stage. */
+export declare const ACCOUNT_STAGE_LABELS: Record<AccountStage, string>;
+/** Type guard: checks whether a string is a user-selectable workload stage. */
+export declare function isAccountStage(value: string): value is AccountStage;
 /**
  * Structural environments used for cascade account partitioning.
  * These are not user-selectable — "root" is implicit (management account),
@@ -18,18 +23,36 @@ export declare const STRUCTURAL_ENVIRONMENTS: {
     readonly PLATFORM: "platform";
 };
 /**
- * Wire-format environment list including the implicit "root" value.
- * Use this for schemas and validators that accept a system-assigned root
- * environment (e.g. quick-create when called after `fjall create org`,
- * and the public org-config API). User-facing pickers should still use
- * STANDARD_ENVIRONMENTS — "root" is set by context, not chosen.
+ * Wire-tolerance vocabulary: the workload stages PLUS the structural "root"
+ * marker. Ingress schemas that face out-of-version CLIs or the org-config
+ * GET→PUT round-trip accept this superset, then decode "root" → null at
+ * PERSISTENCE via [[stageFromWireEnvironment]] (the DB never stores structural
+ * root). NOT a user-facing picker vocabulary — pickers use ACCOUNT_STAGES.
+ * PERMANENT ingest vocabulary, not a drain-gated shim: the separate-root
+ * connect deliberately carries environment:"root" as its intent marker
+ * (solo-to-org lifecycle ADR, decision 7), so wire-rejection of "root" is
+ * unreachable; only derived-EMIT of "root" retires, per-org, behind the CLI
+ * telemetry gate. See decisions/2026-06-07-account-tier-vs-stage-separation.md
+ * § "Wire back-compat (permanent, not transitional)".
  */
-export declare const STANDARD_ENVIRONMENTS_WITH_ROOT: readonly ["production", "staging", "development", "platform", "compliance", "root"];
-export type StandardEnvironmentWithRoot = (typeof STANDARD_ENVIRONMENTS_WITH_ROOT)[number];
-/** Human-readable labels for each standard environment. */
-export declare const ENVIRONMENT_LABELS: Record<StandardEnvironment, string>;
+export declare const ACCOUNT_STAGES_WITH_ROOT: readonly ["production", "staging", "development", "platform", "compliance", "root"];
+export type AccountStageWithRoot = (typeof ACCOUNT_STAGES_WITH_ROOT)[number];
 /** Returns the human-readable label for an environment, with capitalised fallback. */
 export declare function getEnvironmentLabel(env: string): string;
+/**
+ * Structural TIER axis: an account's role in the organisation. Independent of
+ * the workload STAGE axis ([[ACCOUNT_STAGES]]) — a tier is never derived from a
+ * stage and vice versa. Same literals as [[ACCOUNT_ROLES]]: its `satisfies`
+ * clause rejects non-tier values, and [[ACCOUNT_ROLE_TIER_PRESENCE]] rejects a
+ * missing or duplicated tier, so the two cannot drift.
+ */
+export declare const ACCOUNT_TIERS: readonly ["organisation", "platform", "account"];
+export type AccountTier = (typeof ACCOUNT_TIERS)[number];
+export declare const AccountTierSchema: z.ZodEnum<{
+    platform: "platform";
+    organisation: "organisation";
+    account: "account";
+}>;
 /**
  * AWS account roles in the wire format used across the CLI, webapp API
  * responses, and the Prisma `AccountRole` enum. This is the SINGLE SOURCE
@@ -40,14 +63,38 @@ export declare function getEnvironmentLabel(env: string): string;
  * a new role here without updating Prisma fails the parity test; renaming
  * a value here propagates structurally to the webapp.
  *
- * Coupling: `environment` and `role` move together via
- * `environmentToRole`/`roleToEnvironment` in
- * `webapp/app/.server/utils/orgConfigHelpers.ts`. See
- * [[STRUCTURAL_ENVIRONMENTS]] for the env-side equivalent.
+ * Independence: `role` (TIER) and `environment` (STAGE) are independent axes.
+ * Inbound wire values that still carry a structural environment are decoded via
+ * [[environmentToTier]] / [[stageFromWireEnvironment]] — nothing derives one
+ * axis from the other on a write. See [[STRUCTURAL_ENVIRONMENTS]].
  */
 export declare const ACCOUNT_ROLES: {
     readonly ORGANISATION: "organisation";
     readonly PLATFORM: "platform";
     readonly ACCOUNT: "account";
 };
-export type AccountRole = (typeof ACCOUNT_ROLES)[keyof typeof ACCOUNT_ROLES];
+/** Type guard: checks whether a string is a valid account tier. */
+export declare function isAccountTier(value: string): value is AccountTier;
+/**
+ * Decode an inbound wire `environment` to its structural TIER. The wire stays
+ * superset-tolerant: out-of-version CLIs and the post-`fjall create org`
+ * connect still submit "root"/"platform" as an environment. This is the only
+ * sanctioned environment→tier derivation — write paths must NOT re-derive a
+ * role from a stage. See decisions/2026-06-07-account-tier-vs-stage-separation.md.
+ */
+export declare function environmentToTier(environment: string | null | undefined): AccountTier;
+/**
+ * Decode an inbound wire `environment` to its workload STAGE, or null. "root"
+ * (the management account — no workloads), empty, null, or any unknown string
+ * yields null. "platform" is a real stage and passes through unchanged.
+ */
+export declare function stageFromWireEnvironment(environment: string | null | undefined): AccountStage | null;
+/**
+ * Canonical TIER accessor for deploy-core/CLI/MCP readers: prefer the explicit
+ * `tier` wire field, falling back to decoding a legacy structural environment.
+ * Replaces scattered `environment === STRUCTURAL_ENVIRONMENTS.*` comparisons.
+ */
+export declare function accountTier(acc: {
+    tier?: AccountTier | null;
+    environment?: string | null;
+}): AccountTier;

package/dist/environments.js

@@ -1 +1 @@
-const t=["production","staging","development","platform","compliance"];function n(o){return t.includes(o)}const e={ROOT:"root",PLATFORM:"platform"},p=[...t,e.ROOT],r={production:"Production",staging:"Staging",development:"Development",platform:"Platform",compliance:"Compliance"};function c(o){return n(o)?r[o]:o.charAt(0).toUpperCase()+o.slice(1)}const i={ORGANISATION:"organisation",PLATFORM:"platform",ACCOUNT:"account"};export{i as ACCOUNT_ROLES,r as ENVIRONMENT_LABELS,t as STANDARD_ENVIRONMENTS,p as STANDARD_ENVIRONMENTS_WITH_ROOT,e as STRUCTURAL_ENVIRONMENTS,c as getEnvironmentLabel,n as isValidEnvironment};
+import{z as c}from"zod";const n=["production","staging","development","platform","compliance"],T={production:"Production",staging:"Staging",development:"Development",platform:"Platform",compliance:"Compliance"},i=new Set(n);function e(t){return i.has(t)}const o={ROOT:"root",PLATFORM:"platform"},C=[...n,o.ROOT];function s(t){return e(t)?T[t]:t.charAt(0).toUpperCase()+t.slice(1)}const u=["organisation","platform","account"],l=c.enum(u),r={ORGANISATION:"organisation",PLATFORM:"platform",ACCOUNT:"account"},O={[r.ORGANISATION]:!0,[r.PLATFORM]:!0,[r.ACCOUNT]:!0},a=new Set(Object.keys(O));function S(t){return a.has(t)}function p(t){return t===o.ROOT?"organisation":t===o.PLATFORM?"platform":"account"}function R(t){return t==null||t===""||t===o.ROOT?null:e(t)?t:null}function E(t){return t.tier??p(t.environment)}export{r as ACCOUNT_ROLES,n as ACCOUNT_STAGES,C as ACCOUNT_STAGES_WITH_ROOT,T as ACCOUNT_STAGE_LABELS,u as ACCOUNT_TIERS,l as AccountTierSchema,o as STRUCTURAL_ENVIRONMENTS,E as accountTier,p as environmentToTier,s as getEnvironmentLabel,e as isAccountStage,S as isAccountTier,R as stageFromWireEnvironment};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { DNS_APEX, getDomainExportNames, type ManagedDomainExports } from "./domainExports.js";
+export { BACKUP_VAULT_NAME } from "./backupVault.js";
 export { toPascalCase, toKebab, toValidDatabaseName, toScreamingSnake, capitalise, getSafeZoneName, accountConstructKey, hasAsciiStableConstructKey } from "./caseConversion.js";
 export { findAccountNameCollision, type AccountNameCollision } from "./accountNameCollision.js";
 export { normaliseError, getErrorMessage, hasErrorCode, getErrorCode, getErrorStack, formatErrorString } from "./errorUtils.js";
@@ -6,12 +7,13 @@ export { singleton } from "./singleton.js";
 export { DANGEROUS_ENV_VARS, filterDangerousEnvVars, maskSensitiveOutput, parseShellArgs } from "./securityHelpers.js";
 export { sleep } from "./sleep.js";
 export { mapSettledWithConcurrency } from "./concurrency.js";
-export { STANDARD_ENVIRONMENTS, STANDARD_ENVIRONMENTS_WITH_ROOT, STRUCTURAL_ENVIRONMENTS, type StandardEnvironment, type StandardEnvironmentWithRoot, isValidEnvironment, ENVIRONMENT_LABELS, getEnvironmentLabel, ACCOUNT_ROLES, type AccountRole } from "./environments.js";
+export { ACCOUNT_STAGES_WITH_ROOT, STRUCTURAL_ENVIRONMENTS, ACCOUNT_STAGES, ACCOUNT_STAGE_LABELS, isAccountStage, ACCOUNT_TIERS, type AccountTier, AccountTierSchema, isAccountTier, environmentToTier, stageFromWireEnvironment, accountTier, type AccountStageWithRoot, type AccountStage, getEnvironmentLabel, ACCOUNT_ROLES } 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 { SCOPE_VALUES, type TokenScope } from "./tokenScopes.js";
-export { deriveRegionsFromOrgConfig, deriveTargets, deriveAllTargets, findTarget, generateTargetName, type OrgConfigRegions, type TargetAccount, type DerivedTarget } from "./targets.js";
+export { ConnectionWireSchema, type ConnectionWire, ConnectionsListResponseSchema, type ConnectionsListResponse } from "./connectionsWire.js";
+export { deriveRegionsFromOrgConfig, deriveTargets, deriveAllTargets, environmentOrTier, findTarget, generateTargetName, type OrgConfigRegions, type TargetAccount, type DerivedTarget } from "./targets.js";
 export { buildAppConfigPath } from "./appPath.js";
 export { type ScanPath } from "./scanTypes.js";
 export { findInfrastructurePaths, findBoundaryPath, isInfrastructureFile, type MarkerEntry, type FindInfrastructurePathsOptions } from "./findInfrastructurePaths.js";

package/dist/index.js

@@ -1 +1 @@
-import{DNS_APEX as o,getDomainExportNames as t}from"./domainExports.js";import{toPascalCase as a,toKebab as i,toValidDatabaseName as n,toScreamingSnake as S,capitalise as N,getSafeZoneName as _,accountConstructKey as s,hasAsciiStableConstructKey as m}from"./caseConversion.js";import{findAccountNameCollision as A}from"./accountNameCollision.js";import{normaliseError as f,getErrorMessage as C,hasErrorCode as g,getErrorCode as T,getErrorStack as O,formatErrorString as I}from"./errorUtils.js";import{singleton as l}from"./singleton.js";import{DANGEROUS_ENV_VARS as c,filterDangerousEnvVars as V,maskSensitiveOutput as D,parseShellArgs as M}from"./securityHelpers.js";import{sleep as P}from"./sleep.js";import{mapSettledWithConcurrency as H}from"./concurrency.js";import{STANDARD_ENVIRONMENTS as b,STANDARD_ENVIRONMENTS_WITH_ROOT as h,STRUCTURAL_ENVIRONMENTS as L,isValidEnvironment as y,ENVIRONMENT_LABELS as G,getEnvironmentLabel as F,ACCOUNT_ROLES as K}from"./environments.js";import{RESOURCE_CATEGORIES as k,categoriseResource as W,getExpectedDuration as B,getFriendlyResourceType as Z}from"./resourceCategorisation.js";import{parseGitRemoteUrl as q}from"./gitRemoteParser.js";import{abbreviateRegion as z}from"./regions.js";import{SCOPE_VALUES as Q}from"./tokenScopes.js";import{deriveRegionsFromOrgConfig as $,deriveTargets as ee,deriveAllTargets as re,findTarget as oe,generateTargetName as te}from"./targets.js";import{buildAppConfigPath as ae}from"./appPath.js";import{findInfrastructurePaths as ne,findBoundaryPath as Se,isInfrastructureFile as Ne}from"./findInfrastructurePaths.js";import{inferContainerFromCandidates as se}from"./inferContainerFromCandidates.js";import{RESERVED_APP_NAMES as Re,isReservedAppName as Ae}from"./reservedAppNames.js";import{deriveContentHashTag as fe}from"./deriveContentHashTag.js";import{MIGRATION_SNAPSHOT_NAME_PREFIX as ge,EXPECTED_SCHEMA_VERSION_ENV as Te,EXPECTED_SCHEMA_VERSION_TOOL_ENV as Oe,EXPECTED_CH_SCHEMA_VERSION_ENV as Ie,SCHEMA_ADMIN_USER_ENV as xe,SCHEMA_ADMIN_PASSWORD_ENV as le,PRISMA_MIGRATION_DIR_RE as de,CLICKHOUSE_MIGRATION_SKIP_RE as ce}from"./migration/constants.js";export{K as ACCOUNT_ROLES,ce as CLICKHOUSE_MIGRATION_SKIP_RE,c as DANGEROUS_ENV_VARS,o as DNS_APEX,G as ENVIRONMENT_LABELS,Ie as EXPECTED_CH_SCHEMA_VERSION_ENV,Te as EXPECTED_SCHEMA_VERSION_ENV,Oe as EXPECTED_SCHEMA_VERSION_TOOL_ENV,ge as MIGRATION_SNAPSHOT_NAME_PREFIX,de as PRISMA_MIGRATION_DIR_RE,Re as RESERVED_APP_NAMES,k as RESOURCE_CATEGORIES,le as SCHEMA_ADMIN_PASSWORD_ENV,xe as SCHEMA_ADMIN_USER_ENV,Q as SCOPE_VALUES,b as STANDARD_ENVIRONMENTS,h as STANDARD_ENVIRONMENTS_WITH_ROOT,L as STRUCTURAL_ENVIRONMENTS,z as abbreviateRegion,s as accountConstructKey,ae as buildAppConfigPath,N as capitalise,W as categoriseResource,re as deriveAllTargets,fe as deriveContentHashTag,$ as deriveRegionsFromOrgConfig,ee as deriveTargets,V as filterDangerousEnvVars,A as findAccountNameCollision,Se as findBoundaryPath,ne as findInfrastructurePaths,oe as findTarget,I as formatErrorString,te as generateTargetName,t as getDomainExportNames,F as getEnvironmentLabel,T as getErrorCode,C as getErrorMessage,O as getErrorStack,B as getExpectedDuration,Z as getFriendlyResourceType,_ as getSafeZoneName,m as hasAsciiStableConstructKey,g as hasErrorCode,se as inferContainerFromCandidates,Ne as isInfrastructureFile,Ae as isReservedAppName,y as isValidEnvironment,H as mapSettledWithConcurrency,D as maskSensitiveOutput,f as normaliseError,q as parseGitRemoteUrl,M as parseShellArgs,l as singleton,P as sleep,i as toKebab,a as toPascalCase,S as toScreamingSnake,n as toValidDatabaseName};
+import{DNS_APEX as o,getDomainExportNames as t}from"./domainExports.js";import{BACKUP_VAULT_NAME as n}from"./backupVault.js";import{toPascalCase as i,toKebab as S,toValidDatabaseName as m,toScreamingSnake as s,capitalise as _,getSafeZoneName as A,accountConstructKey as C,hasAsciiStableConstructKey as p}from"./caseConversion.js";import{findAccountNameCollision as f}from"./accountNameCollision.js";import{normaliseError as R,getErrorMessage as c,hasErrorCode as g,getErrorCode as O,getErrorStack as x,formatErrorString as I}from"./errorUtils.js";import{singleton as l}from"./singleton.js";import{DANGEROUS_ENV_VARS as P,filterDangerousEnvVars as M,maskSensitiveOutput as V,parseShellArgs as U}from"./securityHelpers.js";import{sleep as v}from"./sleep.js";import{mapSettledWithConcurrency as H}from"./concurrency.js";import{ACCOUNT_STAGES_WITH_ROOT as G,STRUCTURAL_ENVIRONMENTS as b,ACCOUNT_STAGES as y,ACCOUNT_STAGE_LABELS as F,isAccountStage as K,ACCOUNT_TIERS as W,AccountTierSchema as X,isAccountTier as k,environmentToTier as B,stageFromWireEnvironment as Z,accountTier as j,getEnvironmentLabel as q,ACCOUNT_ROLES as w}from"./environments.js";import{RESOURCE_CATEGORIES as J,categoriseResource as Q,getExpectedDuration as Y,getFriendlyResourceType as $}from"./resourceCategorisation.js";import{parseGitRemoteUrl as re}from"./gitRemoteParser.js";import{abbreviateRegion as te}from"./regions.js";import{SCOPE_VALUES as ne}from"./tokenScopes.js";import{ConnectionWireSchema as ie,ConnectionsListResponseSchema as Se}from"./connectionsWire.js";import{deriveRegionsFromOrgConfig as se,deriveTargets as _e,deriveAllTargets as Ae,environmentOrTier as Ce,findTarget as pe,generateTargetName as Te}from"./targets.js";import{buildAppConfigPath as Ne}from"./appPath.js";import{findInfrastructurePaths as ce,findBoundaryPath as ge,isInfrastructureFile as Oe}from"./findInfrastructurePaths.js";import{inferContainerFromCandidates as Ie}from"./inferContainerFromCandidates.js";import{RESERVED_APP_NAMES as le,isReservedAppName as de}from"./reservedAppNames.js";import{deriveContentHashTag as Me}from"./deriveContentHashTag.js";import{MIGRATION_SNAPSHOT_NAME_PREFIX as Ue,EXPECTED_SCHEMA_VERSION_ENV as De,EXPECTED_SCHEMA_VERSION_TOOL_ENV as ve,EXPECTED_CH_SCHEMA_VERSION_ENV as he,SCHEMA_ADMIN_USER_ENV as He,SCHEMA_ADMIN_PASSWORD_ENV as Le,PRISMA_MIGRATION_DIR_RE as Ge,CLICKHOUSE_MIGRATION_SKIP_RE as be}from"./migration/constants.js";export{w as ACCOUNT_ROLES,y as ACCOUNT_STAGES,G as ACCOUNT_STAGES_WITH_ROOT,F as ACCOUNT_STAGE_LABELS,W as ACCOUNT_TIERS,X as AccountTierSchema,n as BACKUP_VAULT_NAME,be as CLICKHOUSE_MIGRATION_SKIP_RE,ie as ConnectionWireSchema,Se as ConnectionsListResponseSchema,P as DANGEROUS_ENV_VARS,o as DNS_APEX,he as EXPECTED_CH_SCHEMA_VERSION_ENV,De as EXPECTED_SCHEMA_VERSION_ENV,ve as EXPECTED_SCHEMA_VERSION_TOOL_ENV,Ue as MIGRATION_SNAPSHOT_NAME_PREFIX,Ge as PRISMA_MIGRATION_DIR_RE,le as RESERVED_APP_NAMES,J as RESOURCE_CATEGORIES,Le as SCHEMA_ADMIN_PASSWORD_ENV,He as SCHEMA_ADMIN_USER_ENV,ne as SCOPE_VALUES,b as STRUCTURAL_ENVIRONMENTS,te as abbreviateRegion,C as accountConstructKey,j as accountTier,Ne as buildAppConfigPath,_ as capitalise,Q as categoriseResource,Ae as deriveAllTargets,Me as deriveContentHashTag,se as deriveRegionsFromOrgConfig,_e as deriveTargets,Ce as environmentOrTier,B as environmentToTier,M as filterDangerousEnvVars,f as findAccountNameCollision,ge as findBoundaryPath,ce as findInfrastructurePaths,pe as findTarget,I as formatErrorString,Te as generateTargetName,t as getDomainExportNames,q as getEnvironmentLabel,O as getErrorCode,c as getErrorMessage,x as getErrorStack,Y as getExpectedDuration,$ as getFriendlyResourceType,A as getSafeZoneName,p as hasAsciiStableConstructKey,g as hasErrorCode,Ie as inferContainerFromCandidates,K as isAccountStage,k as isAccountTier,Oe as isInfrastructureFile,de as isReservedAppName,H as mapSettledWithConcurrency,V as maskSensitiveOutput,R as normaliseError,re as parseGitRemoteUrl,U as parseShellArgs,l as singleton,v as sleep,Z as stageFromWireEnvironment,S as toKebab,i as toPascalCase,s as toScreamingSnake,m as toValidDatabaseName};

package/dist/mcpProtocol/index.d.ts

@@ -147,10 +147,9 @@ export type McpProtocolFrame = z.infer<typeof McpProtocolFrameSchema>;
  * Scaffold protocol schemas — wire types for the `plan_app_scaffold`,
  * `apply_app_scaffold`, and dry-run helper paths in `@fjall/mcp`.
  *
- * The shapes here mirror the CLI-side `DryRunArtefacts` (in
- * `cli/src/operations/types.ts`) by hand because `@fjall/util` is a leaf
- * dependency of the CLI and cannot import from it. Drift between the two
- * is a wire-level bug; both sides MUST move together.
+ * These schemas are the single source of truth: the CLI imports them from
+ * `@fjall/util/mcpProtocol` and re-exports aliases in
+ * `cli/src/operations/types.ts`.
  */
 export declare const FileToWriteSchema: z.ZodObject<{
     path: z.ZodString;
@@ -173,7 +172,7 @@ export declare const RegistryActionSchema: z.ZodObject<{
 export type ScaffoldRegistryAction = z.infer<typeof RegistryActionSchema>;
 export declare const TargetAccountSchema: z.ZodObject<{
     name: z.ZodString;
-    environment: z.ZodString;
+    environment: z.ZodNullable<z.ZodString>;
     source: z.ZodString;
 }, z.core.$strict>;
 export type TargetAccount = z.infer<typeof TargetAccountSchema>;
@@ -247,12 +246,12 @@ export declare const ScaffoldPlanSchema: z.ZodObject<{
     }, z.core.$strict>;
     targetAccount: z.ZodNullable<z.ZodObject<{
         name: z.ZodString;
-        environment: z.ZodString;
+        environment: z.ZodNullable<z.ZodString>;
         source: z.ZodString;
     }, z.core.$strict>>;
     targetAccountCandidates: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        environment: z.ZodString;
+        environment: z.ZodNullable<z.ZodString>;
         source: z.ZodString;
     }, z.core.$strict>>;
     filesToWrite: z.ZodArray<z.ZodObject<{

package/dist/mcpProtocol/index.js

@@ -1 +1 @@
-import{z as t}from"zod";const p=2,f={AUTHENTICATION_REQUIRED:"AUTHENTICATION_REQUIRED",VALIDATION_ERROR:"VALIDATION_ERROR",INTERNAL_ERROR:"INTERNAL_ERROR",INVALID_SUBCOMMAND:"INVALID_SUBCOMMAND",INVALID_FRAME:"INVALID_FRAME"},a=1e3,e=t.literal(p),l=t.enum(["completed","error","skipped"]),g=t.object({v:e,kind:t.literal("step.start"),stepId:t.string().min(1),name:t.string().min(1),index:t.number().int().min(0),total:t.number().int().min(1)}).strict(),u=t.object({v:e,kind:t.literal("step.complete"),stepId:t.string().min(1),name:t.string().min(1),status:l,index:t.number().int().min(0),total:t.number().int().min(1),errorMessage:t.string().optional()}).strict(),d=t.object({v:e,kind:t.literal("warning"),message:t.string().min(1)}).strict(),b=t.object({code:t.string().min(1),message:t.string().min(1),details:t.record(t.string(),t.unknown()).optional()}).strict(),h=t.object({v:e,kind:t.literal("error"),error:b}).strict(),R=t.object({v:e,kind:t.literal("result"),data:t.unknown()}).strict(),A=t.object({v:e,kind:t.literal("auth.browser.required"),url:t.string().url(),externalId:t.string().min(1),region:t.string().min(1),environment:t.string().min(1),reason:t.string().min(1)}).strict(),S=t.object({v:e,kind:t.literal("auth.browser.complete"),awsAccountId:t.string().min(1),accountName:t.string().min(1),roleArn:t.string().min(1)}).strict(),I=t.discriminatedUnion("kind",[g,u,d,h,R,A,S]),s=t.object({path:t.string().min(1),sizeBytes:t.number().int().nonnegative(),collisionMode:t.enum(["create","overwrite"])}).strict(),c=t.object({type:t.enum(["register-application","create-activity","auto-link-repository","writeback-config-path"]),description:t.string().min(1)}).strict(),x=t.enum(["tinkerer","lightweight","standard","resilient","enterprise"]),k=t.enum(["lightweight","standard","resilient","enterprise","none"]),m=t.object({name:t.string().min(1),environment:t.string().min(1),source:t.string().min(1)}).strict(),E=t.object({name:t.string().min(1),pattern:t.string().min(1).optional(),patternTier:x.optional(),patternDomain:t.string().min(1).optional(),network:k.optional(),template:t.string().min(1).optional(),docker:t.object({path:t.string().min(1).optional(),context:t.string().min(1).optional(),target:t.string().min(1).optional()}).strict().optional(),git:t.boolean().optional(),github:t.boolean().optional(),repoVisibility:t.enum(["private","public"]).optional(),intent:t.string().max(a).optional()}).strict(),T=t.object({planId:t.string().regex(/^[0-9a-f]{32}$/),normalisedPath:t.string().min(1),resolvedInputs:E,targetAccount:m.nullable(),targetAccountCandidates:t.array(m),filesToWrite:t.array(s),npmPackages:t.array(t.string().min(1)),registryActions:t.array(c),patternUnsupportedForDryRun:t.boolean().optional(),intent:t.string().max(a).optional(),framework:t.string().min(1).optional(),summary:t.string().min(1)}).strict(),N=t.object({filesToWrite:t.array(s),npmPackages:t.array(t.string().min(1)),registryActions:t.array(c),patternUnsupportedForDryRun:t.boolean().optional()}).strict(),j=t.object({path:t.string().min(1),name:t.string().min(1),mode:t.enum(["application","pattern"]),dependenciesInstalled:t.boolean().optional(),warning:t.string().optional(),dryRunArtefacts:N.optional()}).strict(),v=t.object({step:t.string().min(1),current:t.number().int().nonnegative(),total:t.number().int().positive().optional(),message:t.string().min(1)}).strict();function w(n){let o;try{o=JSON.parse(n)}catch(i){return{ok:!1,reason:"json",raw:n,error:i instanceof Error?i.message:String(i)}}const r=I.safeParse(o);return r.success?{ok:!0,frame:r.data}:{ok:!1,reason:"schema",raw:n,error:r.error.message}}export{S as AuthBrowserCompleteFrameSchema,A as AuthBrowserRequiredFrameSchema,N as DryRunArtefactsSchema,h as ErrorFrameSchema,s as FileToWriteSchema,a as INTENT_MAX_LENGTH,f as MCP_ERROR_CODES,p as MCP_PROTOCOL_VERSION,I as McpProtocolFrameSchema,c as RegistryActionSchema,E as ResolvedInputsSchema,R as ResultFrameSchema,T as ScaffoldPlanSchema,v as ScaffoldProgressFrameSchema,j as ScaffoldResultDataSchema,u as StepCompleteFrameSchema,g as StepStartFrameSchema,m as TargetAccountSchema,d as WarningFrameSchema,w as parseFrame};
+import{z as t}from"zod";const l=2,f={AUTHENTICATION_REQUIRED:"AUTHENTICATION_REQUIRED",VALIDATION_ERROR:"VALIDATION_ERROR",INTERNAL_ERROR:"INTERNAL_ERROR",INVALID_SUBCOMMAND:"INVALID_SUBCOMMAND",INVALID_FRAME:"INVALID_FRAME"},a=1e3,e=t.literal(l),p=t.enum(["completed","error","skipped"]),g=t.object({v:e,kind:t.literal("step.start"),stepId:t.string().min(1),name:t.string().min(1),index:t.number().int().min(0),total:t.number().int().min(1)}).strict(),u=t.object({v:e,kind:t.literal("step.complete"),stepId:t.string().min(1),name:t.string().min(1),status:p,index:t.number().int().min(0),total:t.number().int().min(1),errorMessage:t.string().optional()}).strict(),d=t.object({v:e,kind:t.literal("warning"),message:t.string().min(1)}).strict(),b=t.object({code:t.string().min(1),message:t.string().min(1),details:t.record(t.string(),t.unknown()).optional()}).strict(),h=t.object({v:e,kind:t.literal("error"),error:b}).strict(),R=t.object({v:e,kind:t.literal("result"),data:t.unknown()}).strict(),A=t.object({v:e,kind:t.literal("auth.browser.required"),url:t.string().url(),externalId:t.string().min(1),region:t.string().min(1),environment:t.string().min(1),reason:t.string().min(1)}).strict(),S=t.object({v:e,kind:t.literal("auth.browser.complete"),awsAccountId:t.string().min(1),accountName:t.string().min(1),roleArn:t.string().min(1)}).strict(),I=t.discriminatedUnion("kind",[g,u,d,h,R,A,S]),s=t.object({path:t.string().min(1),sizeBytes:t.number().int().nonnegative(),collisionMode:t.enum(["create","overwrite"])}).strict(),c=t.object({type:t.enum(["register-application","create-activity","auto-link-repository","writeback-config-path"]),description:t.string().min(1)}).strict(),x=t.enum(["tinkerer","lightweight","standard","resilient","enterprise"]),k=t.enum(["lightweight","standard","resilient","enterprise","none"]),m=t.object({name:t.string().min(1),environment:t.string().min(1).nullable(),source:t.string().min(1)}).strict(),E=t.object({name:t.string().min(1),pattern:t.string().min(1).optional(),patternTier:x.optional(),patternDomain:t.string().min(1).optional(),network:k.optional(),template:t.string().min(1).optional(),docker:t.object({path:t.string().min(1).optional(),context:t.string().min(1).optional(),target:t.string().min(1).optional()}).strict().optional(),git:t.boolean().optional(),github:t.boolean().optional(),repoVisibility:t.enum(["private","public"]).optional(),intent:t.string().max(a).optional()}).strict(),T=t.object({planId:t.string().regex(/^[0-9a-f]{32}$/),normalisedPath:t.string().min(1),resolvedInputs:E,targetAccount:m.nullable(),targetAccountCandidates:t.array(m),filesToWrite:t.array(s),npmPackages:t.array(t.string().min(1)),registryActions:t.array(c),patternUnsupportedForDryRun:t.boolean().optional(),intent:t.string().max(a).optional(),framework:t.string().min(1).optional(),summary:t.string().min(1)}).strict(),N=t.object({filesToWrite:t.array(s),npmPackages:t.array(t.string().min(1)),registryActions:t.array(c),patternUnsupportedForDryRun:t.boolean().optional()}).strict(),j=t.object({path:t.string().min(1),name:t.string().min(1),mode:t.enum(["application","pattern"]),dependenciesInstalled:t.boolean().optional(),warning:t.string().optional(),dryRunArtefacts:N.optional()}).strict(),v=t.object({step:t.string().min(1),current:t.number().int().nonnegative(),total:t.number().int().positive().optional(),message:t.string().min(1)}).strict();function w(n){let o;try{o=JSON.parse(n)}catch(i){return{ok:!1,reason:"json",raw:n,error:i instanceof Error?i.message:String(i)}}const r=I.safeParse(o);return r.success?{ok:!0,frame:r.data}:{ok:!1,reason:"schema",raw:n,error:r.error.message}}export{S as AuthBrowserCompleteFrameSchema,A as AuthBrowserRequiredFrameSchema,N as DryRunArtefactsSchema,h as ErrorFrameSchema,s as FileToWriteSchema,a as INTENT_MAX_LENGTH,f as MCP_ERROR_CODES,l as MCP_PROTOCOL_VERSION,I as McpProtocolFrameSchema,c as RegistryActionSchema,E as ResolvedInputsSchema,R as ResultFrameSchema,T as ScaffoldPlanSchema,v as ScaffoldProgressFrameSchema,j as ScaffoldResultDataSchema,u as StepCompleteFrameSchema,g as StepStartFrameSchema,m as TargetAccountSchema,d as WarningFrameSchema,w as parseFrame};

package/dist/targets.d.ts

@@ -4,6 +4,7 @@
  * A "target" is a deployment destination: an account + region combination
  * with a canonical name derived from org config at runtime.
  */
+import { type AccountTier } from "./environments.js";
 /** Structural interface for the region fields on OrgConfig. */
 export interface OrgConfigRegions {
     primaryRegion?: string;
@@ -18,7 +19,9 @@ export declare function deriveRegionsFromOrgConfig(config: OrgConfigRegions): st
 export interface TargetAccount {
     name: string;
     id: string;
-    environment: string;
+    /** Workload STAGE — null for structural accounts; read tier from `tier`. */
+    environment: string | null;
+    tier?: AccountTier;
 }
 export interface DerivedTarget {
     name: string;
@@ -27,6 +30,15 @@ export interface DerivedTarget {
     environment: string;
     region: string;
 }
+/**
+ * Canonical stage-or-tier fallback. Structural accounts carry a null workload
+ * stage, so display/naming/OU derivation fall back to the structural tier to
+ * stay non-null. Single source for every `environment ?? tier` consumer.
+ */
+export declare function environmentOrTier(account: {
+    environment?: string | null;
+    tier?: AccountTier | null;
+}): string;
 /**
  * Generate a canonical target name from account name and region.
  * e.g. ("Production-US", "us-east-1") → "production-us-use1"

package/dist/targets.js

@@ -1 +1 @@
-import{abbreviateRegion as c}from"./regions.js";function s(e){const r=[e.primaryRegion,...e.secondaryRegions??[],e.disasterRecoveryRegion].filter(t=>t!==void 0);return[...new Set(r)]}function m(e,r){return`${e.toLowerCase()}-${c(r)}`}function u(e,r){const t=[];for(const n of e)if(n.environment!=="root")for(const o of r)t.push({name:m(n.name,o),accountName:n.name,accountId:n.id,environment:n.environment,region:o});return t.sort((n,o)=>{const i=n.environment.localeCompare(o.environment);if(i!==0)return i;const a=n.accountName.localeCompare(o.accountName);return a!==0?a:n.region.localeCompare(o.region)})}function f(e){return u(e.providerAccounts,s(e))}function p(e,r){if(r.length===0)return e;const t=new Set([e.primaryRegion,e.disasterRecoveryRegion].filter(Boolean)),n=r.filter(o=>!t.has(o));return{...e,secondaryRegions:n.length>0?n:void 0}}function g(e,r){return e.find(t=>t.name===r)}export{f as deriveAllTargets,s as deriveRegionsFromOrgConfig,u as deriveTargets,g as findTarget,m as generateTargetName,p as mergeSecondaryRegions};
+import{abbreviateRegion as m}from"./regions.js";import{accountTier as c}from"./environments.js";function s(e){const r=[e.primaryRegion,...e.secondaryRegions??[],e.disasterRecoveryRegion].filter(t=>t!==void 0);return[...new Set(r)]}function u(e){return e.environment??c(e)}function f(e,r){return`${e.toLowerCase()}-${m(r)}`}function p(e,r){const t=[];for(const n of e){if(c(n)==="organisation")continue;const o=u(n);for(const i of r)t.push({name:f(n.name,i),accountName:n.name,accountId:n.id,environment:o,region:i})}return t.sort((n,o)=>{const i=n.environment.localeCompare(o.environment);if(i!==0)return i;const a=n.accountName.localeCompare(o.accountName);return a!==0?a:n.region.localeCompare(o.region)})}function v(e){return p(e.providerAccounts,s(e))}function l(e,r){if(r.length===0)return e;const t=new Set([e.primaryRegion,e.disasterRecoveryRegion].filter(Boolean)),n=r.filter(o=>!t.has(o));return{...e,secondaryRegions:n.length>0?n:void 0}}function R(e,r){return e.find(t=>t.name===r)}export{v as deriveAllTargets,s as deriveRegionsFromOrgConfig,p as deriveTargets,u as environmentOrTier,R as findTarget,f as generateTargetName,l as mergeSecondaryRegions};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/util",
-  "version": "2.11.1",
+  "version": "2.13.0",
   "description": "Common utility methods",
   "type": "module",
   "main": "dist/index.js",
@@ -117,5 +117,5 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "gitHead": "69823c3d7f2eacba419657464381119c5b5b5fd6"
+  "gitHead": "5b16c5731256628f829d4168c65cf165b3516f9a"
 }