@monster-orange/den 0.0.0 → 0.1.0

package/src/shared/edge/render.ts

@@ -0,0 +1,221 @@
+/**
+ * Pure renderers for the edge's Traefik configuration. No I/O, so routing is
+ * unit-testable; runtime.ts writes the results.
+ */
+import * as yaml from "yaml";
+import type { EdgeConfig } from "./types.js";
+
+const DOMAIN_RE =
+  /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export function assertDomain(d: string): void {
+  if (!DOMAIN_RE.test(d)) throw new Error(`"${d}" is not a valid domain`);
+}
+
+function slug(s: string): string {
+  return s.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+}
+
+export function edgeNames(org: string) {
+  const s = slug(org);
+  return { container: `${s}-edge`, network: `${s}-edge`, project: `${s}-edge` };
+}
+
+/** Hostname for a route: `<name>.<domain>`. */
+export function routeHost(name: string, domain: string): string {
+  return `${name}.${domain}`;
+}
+
+/** Every apex domain the edge serves: the primary first, then aliases. */
+export function edgeDomains(cfg: EdgeConfig): string[] {
+  return [...new Set([cfg.domain, ...(cfg.aliases ?? [])])];
+}
+
+/** `Host()` rule matching `<name>` under every edge domain. */
+function hostRule(name: string, cfg: EdgeConfig): string {
+  return edgeDomains(cfg)
+    .map((d) => `Host(\`${routeHost(name, d)}\`)`)
+    .join(" || ");
+}
+
+/** Public URL for a route, including the port when it isn't 443. */
+export function routeUrl(
+  name: string,
+  cfg: EdgeConfig,
+  domain = cfg.domain,
+): string {
+  const p = cfg.ports?.https ?? 443;
+  return `https://${routeHost(name, domain)}${p === 443 ? "" : `:${p}`}`;
+}
+
+/** Names that go on the org's certificate. */
+export function certNames(cfg: EdgeConfig): string[] {
+  const zones = [...cfg.workspaces, ...(cfg.subzones ?? [])];
+  // A dotted route (`app.shop`) is served at app.shop.<domain>, which `*.<domain>`
+  // does not cover: add its zone (`shop`) unless a workspace or subzone has it.
+  const routeZones = Object.keys(cfg.routes)
+    .filter((n) => n.includes("."))
+    .map((n) => n.slice(n.indexOf(".") + 1))
+    .filter((z, i, all) => !zones.includes(z) && all.indexOf(z) === i);
+  return edgeDomains(cfg).flatMap((d) => [
+    d,
+    `*.${d}`,
+    ...[...zones, ...routeZones].map((z) => `*.${z}.${d}`),
+  ]);
+}
+
+/** Dynamic config: TLS cert, HTTP→HTTPS redirect, dashboard, routes. */
+export function renderEdgeDynamic(cfg: EdgeConfig): string {
+  const httpsPort = cfg.ports?.https ?? 443;
+  const redirectPort = httpsPort !== 443 ? { port: String(httpsPort) } : {};
+  const routers: Record<string, unknown> = {
+    ...(cfg.httpsRedirect
+      ? {
+          "to-https": {
+            entryPoints: ["web"],
+            rule: "PathPrefix(`/`)",
+            priority: 1,
+            middlewares: ["to-https"],
+            service: "noop@internal",
+          },
+        }
+      : {}),
+    dashboard: {
+      entryPoints: ["websecure"],
+      rule: hostRule("edge", cfg),
+      service: "api@internal",
+      tls: {},
+    },
+  };
+  const services: Record<string, unknown> = {};
+  for (const [name, url] of Object.entries(cfg.routes).sort()) {
+    if (name === "edge")
+      throw new Error(`route name "edge" is reserved for the dashboard`);
+    if (!/^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/.test(name))
+      throw new Error(
+        `route name "${name}" must be lowercase letters, digits, dots or dashes`,
+      );
+    const key = `route-${slug(name)}`;
+    routers[key] = {
+      entryPoints: ["websecure"],
+      rule: hostRule(name, cfg),
+      service: key,
+      tls: {},
+    };
+    services[key] = { loadBalancer: { servers: [{ url }] } };
+  }
+  const cert = {
+    certFile: "/etc/edge/certs/edge.pem",
+    keyFile: "/etc/edge/certs/edge-key.pem",
+  };
+  return (
+    "# Generated by `edge up` — edit config, not this file.\n" +
+    yaml.stringify({
+      http: {
+        routers,
+        ...(cfg.httpsRedirect
+          ? {
+              middlewares: {
+                "to-https": {
+                  redirectScheme: {
+                    scheme: "https",
+                    permanent: false,
+                    ...redirectPort,
+                  },
+                },
+              },
+            }
+          : {}),
+        ...(Object.keys(services).length ? { services } : {}),
+      },
+      ...(cfg.issueCert
+        ? {
+            tls: {
+              stores: { default: { defaultCertificate: cert } },
+              certificates: [cert],
+            },
+          }
+        : {}),
+    })
+  );
+}
+
+/** The socket proxy's container (and its private network) for docker_labels. */
+export function dockerProxyName(org: string): string {
+  return `${edgeNames(org).container}-docker`;
+}
+
+/** Compose file for the edge; publishes host ports only when configured. */
+export function renderEdgeCompose(cfg: EdgeConfig): string {
+  const n = edgeNames(cfg.org);
+  const proxy = dockerProxyName(cfg.org);
+  const labels = cfg.dockerLabels;
+  const external = [
+    ...new Set([...(labels ? [labels.network] : []), ...cfg.networks]),
+  ].filter((x) => x !== n.network && x !== proxy);
+  const edgeNets = [n.network, ...(labels ? [proxy] : []), ...external];
+  const services: Record<string, unknown> = {
+    edge: {
+      image: cfg.image,
+      container_name: n.container,
+      restart: "unless-stopped",
+      ...(labels ? { depends_on: ["docker-proxy"] } : {}),
+      command: [
+        "--entrypoints.web.address=:80",
+        "--entrypoints.websecure.address=:443",
+        "--providers.file.directory=/etc/edge/dynamic",
+        "--providers.file.watch=true",
+        ...(labels
+          ? [
+              "--providers.docker=true",
+              `--providers.docker.endpoint=tcp://${proxy}:2375`,
+              "--providers.docker.exposedbydefault=false",
+              `--providers.docker.network=${labels.network}`,
+            ]
+          : []),
+        "--api.dashboard=true",
+        "--ping=true",
+        "--log.level=WARN",
+        ...cfg.args,
+      ],
+      ...(cfg.ports
+        ? { ports: [`${cfg.ports.http}:80`, `${cfg.ports.https}:443`] }
+        : {}),
+      extra_hosts: ["host.docker.internal:host-gateway"],
+      volumes: [
+        "./dynamic:/etc/edge/dynamic:ro",
+        ...(cfg.issueCert ? ["./certs:/etc/edge/certs:ro"] : []),
+        ...Object.entries(cfg.mounts)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([host, target]) => `${host}:${target}:ro`),
+      ],
+      networks: edgeNets,
+    },
+  };
+  if (labels)
+    // Read-only Docker API: container listing and events, nothing that writes.
+    services["docker-proxy"] = {
+      image: "tecnativa/docker-socket-proxy:0.3.0",
+      container_name: proxy,
+      restart: "unless-stopped",
+      environment: {
+        CONTAINERS: "1",
+        NETWORKS: "1",
+        EVENTS: "1",
+        PING: "1",
+        VERSION: "1",
+        POST: "0",
+      },
+      volumes: ["/var/run/docker.sock:/var/run/docker.sock:ro"],
+      networks: [proxy],
+    };
+  return yaml.stringify({
+    name: n.project,
+    services,
+    networks: {
+      [n.network]: { external: true },
+      ...(labels ? { [proxy]: { internal: true } } : {}),
+      ...Object.fromEntries(external.map((x) => [x, { external: true }])),
+    },
+  });
+}

package/src/shared/edge/runtime.ts

@@ -0,0 +1,268 @@
+/**
+ * Side effects for the edge: docker, mkcert, files. Thin on purpose — every
+ * routing decision lives in render.ts.
+ */
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as net from "net";
+import * as path from "path";
+import {
+  certNames,
+  edgeNames,
+  renderEdgeCompose,
+  renderEdgeDynamic,
+} from "./render.js";
+import type { EdgeConfig } from "./types.js";
+
+function sh(
+  cmd: string,
+  args: string[],
+  opts: { env?: NodeJS.ProcessEnv; inherit?: boolean } = {},
+) {
+  const r = spawnSync(cmd, args, {
+    encoding: "utf-8",
+    env: { ...process.env, ...opts.env },
+    stdio: opts.inherit ? "inherit" : "pipe",
+  });
+  if (r.error) throw new Error(`${cmd} is not installed (${r.error.message})`);
+  return {
+    code: r.status ?? 1,
+    out: (r.stdout ?? "").trim(),
+    err: (r.stderr ?? "").trim(),
+  };
+}
+
+function must(
+  cmd: string,
+  args: string[],
+  opts: { env?: NodeJS.ProcessEnv } = {},
+): string {
+  const r = sh(cmd, args, opts);
+  if (r.code !== 0)
+    throw new Error(`${cmd} ${args.join(" ")} failed:\n${r.err || r.out}`);
+  return r.out;
+}
+
+function write(file: string, content: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, "utf-8");
+}
+
+function ensureNetwork(name: string): void {
+  if (sh("docker", ["network", "inspect", name]).code !== 0)
+    must("docker", ["network", "create", name]);
+}
+
+export function containerState(name: string): string {
+  const r = sh("docker", ["inspect", "-f", "{{.State.Status}}", name]);
+  return r.code === 0 ? r.out : "absent";
+}
+
+/** True when something on 127.0.0.1 accepts connections on `port`. */
+export function portInUse(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const s = net.connect({ host: "127.0.0.1", port });
+    s.once("connect", () => (s.destroy(), resolve(true)));
+    s.once("error", () => resolve(false));
+    s.setTimeout(500, () => (s.destroy(), resolve(false)));
+  });
+}
+
+// ── Certificates (org-scoped CA) ─────────────────────────────────────────────
+
+export function caDir(cfg: EdgeConfig): string {
+  return cfg.caroot ?? path.join(cfg.stateDir, "ca");
+}
+
+/** True when the edge uses an existing CA (`caroot`) rather than its own. */
+export function sharedCa(cfg: EdgeConfig): boolean {
+  return cfg.caroot !== null;
+}
+
+/**
+ * A shared CA must already exist with its key: mkcert silently creates a new
+ * CA in an empty CAROOT, and devices that trust the shared one would not
+ * trust that. The org's own CA may be created on first use.
+ */
+export function assertCaUsable(cfg: EdgeConfig): void {
+  if (!sharedCa(cfg)) return;
+  const dir = caDir(cfg);
+  if (!fs.existsSync(dir))
+    throw new Error(
+      `edge.caroot ${dir} does not exist. The edge never creates a CA there; ` +
+        `point caroot at the existing CA (\`mkcert -CAROOT\`).`,
+    );
+  for (const f of ["rootCA.pem", "rootCA-key.pem"])
+    if (!fs.existsSync(path.join(dir, f)))
+      throw new Error(
+        `edge.caroot ${dir} has no ${f}. Refusing to run: mkcert would mint a ` +
+          `new CA that other devices don't trust.`,
+      );
+}
+
+function mkcertEnv(cfg: EdgeConfig): NodeJS.ProcessEnv {
+  return { CAROOT: caDir(cfg) };
+}
+
+/** Issue (or re-issue when names changed) the edge cert from the org's own CA. */
+export function ensureCerts(cfg: EdgeConfig): {
+  issued: boolean;
+  names: string[];
+} {
+  const names = certNames(cfg);
+  if (!cfg.issueCert) return { issued: false, names: [] };
+  assertCaUsable(cfg);
+  const dir = path.join(cfg.stateDir, "certs");
+  const stamp = path.join(dir, "names.txt");
+  const want = names.join("\n");
+  if (
+    fs.existsSync(path.join(dir, "edge.pem")) &&
+    fs.existsSync(stamp) &&
+    fs.readFileSync(stamp, "utf-8") === want
+  )
+    return { issued: false, names };
+  fs.mkdirSync(dir, { recursive: true });
+  if (!sharedCa(cfg))
+    fs.mkdirSync(caDir(cfg), { recursive: true, mode: 0o700 });
+  must(
+    "mkcert",
+    [
+      "-cert-file",
+      path.join(dir, "edge.pem"),
+      "-key-file",
+      path.join(dir, "edge-key.pem"),
+      ...names,
+    ],
+    { env: mkcertEnv(cfg) },
+  );
+  write(stamp, want);
+  return { issued: true, names };
+}
+
+/** Install the org CA into the system + browser trust stores (prompts for a password). */
+export function trustCa(cfg: EdgeConfig): number {
+  assertCaUsable(cfg);
+  if (!sharedCa(cfg))
+    fs.mkdirSync(caDir(cfg), { recursive: true, mode: 0o700 });
+  return sh("mkcert", ["-install"], { env: mkcertEnv(cfg), inherit: true })
+    .code;
+}
+
+export function untrustCa(cfg: EdgeConfig): number {
+  if (sharedCa(cfg))
+    throw new Error(
+      `edge.caroot is a shared CA (${caDir(cfg)}); other tools and devices ` +
+        `rely on it being trusted, so the edge never uninstalls it.`,
+    );
+  return sh("mkcert", ["-uninstall"], { env: mkcertEnv(cfg), inherit: true })
+    .code;
+}
+
+/** Whether the org CA is in the macOS system keychain (null: can't tell). */
+export function caTrusted(cfg: EdgeConfig): boolean | null {
+  const pem = path.join(caDir(cfg), "rootCA.pem");
+  if (!fs.existsSync(pem)) return false;
+  if (process.platform !== "darwin") return null;
+  return sh("security", ["verify-cert", "-c", pem]).code === 0;
+}
+
+// ── Included dynamic config ─────────────────────────────────────────────────
+
+const GENERATED = "edge.yml";
+
+/** The dynamic-config files in `dir` to copy in (top level, YAML only). */
+export function includeFiles(dir: string | null): string[] {
+  if (!dir) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter(
+      (e) => e.isFile() && /\.ya?ml$/.test(e.name) && e.name !== GENERATED,
+    )
+    .map((e) => e.name)
+    .sort();
+}
+
+/**
+ * Names the last sync copied in. Kept in the state dir, outside dynamic/,
+ * so the watching Traefik never reads it.
+ */
+const INCLUDED_LEDGER = "included.json";
+
+/** Files other writers own in the dynamic directory: never copied over or pruned. */
+const isOwnedElsewhere = (f: string): boolean =>
+  f === GENERATED || /^stack-.*\.ya?ml$/.test(f);
+
+function readLedger(stateDir: string): string[] {
+  try {
+    const v: unknown = JSON.parse(
+      fs.readFileSync(path.join(stateDir, INCLUDED_LEDGER), "utf-8"),
+    );
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+  } catch {
+    return []; // no ledger yet: nothing is known to be ours, so prune nothing
+  }
+}
+
+/**
+ * Copy the included files beside the generated one, then drop copies whose
+ * source is gone. Only files a previous sync copied in (its ledger) are ever
+ * removed: stacks write their own route files (stack-*.yml) into the same
+ * directory, and those belong to the running stacks. New files land before
+ * stale ones go, so the watching Traefik never sees a gap.
+ */
+export function syncIncluded(cfg: EdgeConfig): string[] {
+  const dyn = path.join(cfg.stateDir, "dynamic");
+  fs.mkdirSync(dyn, { recursive: true });
+  const files = includeFiles(cfg.include).filter((f) => !isOwnedElsewhere(f));
+  for (const f of files)
+    fs.copyFileSync(path.join(cfg.include!, f), path.join(dyn, f));
+  for (const f of readLedger(cfg.stateDir))
+    if (!files.includes(f) && !isOwnedElsewhere(f) && !f.includes("/"))
+      fs.rmSync(path.join(dyn, f), { force: true });
+  fs.writeFileSync(
+    path.join(cfg.stateDir, INCLUDED_LEDGER),
+    JSON.stringify(files, null, 2) + "\n",
+  );
+  return files;
+}
+
+// ── Edge ─────────────────────────────────────────────────────────────────────
+
+export async function edgeUp(cfg: EdgeConfig) {
+  const n = edgeNames(cfg.org);
+  if (cfg.ports && containerState(n.container) !== "running") {
+    for (const p of [cfg.ports.http, cfg.ports.https])
+      if (await portInUse(p))
+        throw new Error(
+          `port ${p} is already in use. Free it, pick other ports ` +
+            `(edge.http_port / edge.https_port in config/local/user.yml), or ` +
+            `set edge.publish: false if another proxy forwards to ${n.container}.`,
+        );
+  }
+  assertCaUsable(cfg);
+  ensureNetwork(n.network);
+  for (const net of [
+    ...(cfg.dockerLabels ? [cfg.dockerLabels.network] : []),
+    ...cfg.networks,
+  ])
+    if (sh("docker", ["network", "inspect", net]).code !== 0)
+      throw new Error(
+        `Docker network ${net} does not exist; the edge joins it but never creates it.`,
+      );
+  for (const host of Object.keys(cfg.mounts))
+    if (!fs.existsSync(host))
+      throw new Error(`edge.mounts: ${host} does not exist on this machine`);
+  const certs = ensureCerts(cfg);
+  const included = syncIncluded(cfg);
+  write(path.join(cfg.stateDir, "dynamic", GENERATED), renderEdgeDynamic(cfg));
+  const compose = path.join(cfg.stateDir, "compose.yml");
+  write(compose, renderEdgeCompose(cfg));
+  must("docker", ["compose", "-f", compose, "up", "-d", "--remove-orphans"]);
+  return { certs, included };
+}
+
+export function edgeDown(cfg: EdgeConfig): void {
+  const compose = path.join(cfg.stateDir, "compose.yml");
+  if (fs.existsSync(compose))
+    must("docker", ["compose", "-f", compose, "down"]);
+}

package/src/shared/edge/types.ts

@@ -0,0 +1,62 @@
+/**
+ * The org's HTTPS edge: one Traefik that terminates TLS with the org's own CA
+ * (mkcert, separate CAROOT) and routes `<name>.<domain>` to local services.
+ * File-provider routes, plus Docker labels when `docker_labels` opts in
+ * (through a read-only socket proxy; the edge never mounts the socket).
+ *
+ * Standalone by default: the edge publishes host :80/:443 itself. Set
+ * `edge.publish: false` when something else on the machine owns those ports
+ * and forwards to the edge over its Docker network (`<org>-edge`); the edge
+ * neither knows nor cares what that is.
+ */
+
+export interface EdgePorts {
+  http: number;
+  https: number;
+}
+
+export interface EdgeConfig {
+  /** Org slug — names the edge container and its Docker network. */
+  org: string;
+  /** Apex domain; every subdomain is served. */
+  domain: string;
+  /** More apex domains served identically (e.g. a tailnet-resolvable one). */
+  aliases: string[];
+  /** Pinned Traefik image. */
+  image: string;
+  /** Workspaces that get a wildcard cert (`*.<ws>.<domain>`). */
+  workspaces: string[];
+  /** Extra wildcard labels on the cert (`*.<label>.<domain>`), e.g. stack names. */
+  subzones?: string[];
+  /** `<name>` → upstream URL, served at `https://<name>.<domain>`. */
+  routes: Record<string, string>;
+  /** Host ports to publish, or null when another proxy fronts the edge. */
+  ports: EdgePorts | null;
+  /** Where the org's CA, certs and generated config live. */
+  stateDir: string;
+  /**
+   * An existing mkcert CA to use instead of the org's own under `stateDir`
+   * (e.g. a CA other devices already trust). The edge refuses to run if its
+   * key is missing, so mkcert can never mint a replacement, and it never
+   * uninstalls a shared CA.
+   */
+  caroot: string | null;
+  /** Issue the edge's own wildcard cert. Off when included config holds the certs. */
+  issueCert: boolean;
+  /** Catch-all HTTP→HTTPS redirect. Off when included config decides per name. */
+  httpsRedirect: boolean;
+  /**
+   * Opt-in: also route by `traefik.*` labels on containers, read through a
+   * read-only socket proxy. Nothing is exposed unless labelled; `network` is
+   * the Docker network the edge reaches labelled containers on.
+   */
+  dockerLabels: { network: string } | null;
+  /** A directory of Traefik dynamic-config files copied in beside the generated one. */
+  include: string | null;
+  /** Extra read-only bind mounts: host path → container path. */
+  mounts: Record<string, string>;
+  /** Extra external Docker networks the edge joins. */
+  networks: string[];
+  /** Extra Traefik static-config arguments. */
+  args: string[];
+}

package/src/shared/engine.ts

@@ -0,0 +1,67 @@
+/**
+ * Den's own files, wherever Den is installed.
+ *
+ * Two roots, never confused:
+ *   - the engine root (getEngineRoot): Den's package — src/, scripts/, make/.
+ *     In a distribution that is node_modules/@monster-orange/den.
+ *   - the distribution root (getDistRoot): den.yml, config/, manifests/,
+ *     tests/pillars/, reports/, results/.
+ * In Den's own checkout they are the same directory.
+ *
+ * Anything that names an engine file or runs an engine script goes through
+ * here instead of joining "src/…" onto the dist root or relying on the cwd.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getDistRoot, getEngineRoot } from "./paths.js";
+
+/** An absolute path inside Den's own package. */
+export function enginePath(...parts: string[]): string {
+  return path.join(getEngineRoot(), ...parts);
+}
+
+/**
+ * A binary Den depends on (tsx, playwright, …): the nearest
+ * node_modules/.bin/<name> at or above the engine root. npm hoists Den's
+ * dependencies into the distribution's node_modules, so the walk covers both
+ * a Den checkout and a packaged install. Falls back to the bare name (PATH).
+ */
+export function engineBin(name: string, engineRoot = getEngineRoot()): string {
+  let dir = path.resolve(engineRoot);
+  for (;;) {
+    const candidate = path.join(dir, "node_modules", ".bin", name);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return name;
+    dir = parent;
+  }
+}
+
+/** The tsx binary that runs Den's TypeScript sources. */
+export function tsxBin(): string {
+  return engineBin("tsx");
+}
+
+/** A command that runs one of Den's scripts with tsx. */
+export interface EngineCommand {
+  command: string;
+  args: string[];
+}
+
+/** `tsx <engine>/<script> ...args`. `script` is relative to the engine root. */
+export function tsxCommand(script: string, ...args: string[]): EngineCommand {
+  return { command: tsxBin(), args: [enginePath(script), ...args] };
+}
+
+/**
+ * An absolute path inside the distribution (reports, results, staged tests,
+ * config): the counterpart of enginePath. Same directory in Den's checkout.
+ */
+export function distPath(...parts: string[]): string {
+  return path.join(getDistRoot(), ...parts);
+}
+
+/** `playwright ...args` from Den's own @playwright/test. */
+export function playwrightCommand(...args: string[]): EngineCommand {
+  return { command: engineBin("playwright"), args };
+}

package/src/shared/environment/aws-profiles.ts

@@ -0,0 +1,49 @@
+/**
+ * AWS Profile loader
+ *
+ * Reads config/local/aws-profiles.json — a gitignored per-user file that maps
+ * den environments to AWS CLI profile names (set via `make aws-configure`).
+ *
+ * Returns empty object if the file doesn't exist (local-only usage).
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { Environment } from "../types/index.js";
+import { getDistRoot } from "../paths.js";
+
+// The profiles file lives under the den repo root, not the caller's cwd —
+// den is frequently invoked from inside other repos.
+const PROFILES_FILE = path.resolve(
+  getDistRoot(),
+  "config",
+  "local",
+  "aws-profiles.json",
+);
+
+let cache: Partial<Record<Environment, string>> | null = null;
+
+export function loadAwsProfiles(): Partial<Record<Environment, string>> {
+  if (cache) return cache;
+  if (!fs.existsSync(PROFILES_FILE)) return (cache = {});
+  try {
+    cache = JSON.parse(fs.readFileSync(PROFILES_FILE, "utf-8"));
+    return cache!;
+  } catch {
+    return (cache = {});
+  }
+}
+
+/**
+ * Returns { AWS_PROFILE: "..." } for the given env if a profile is configured,
+ * otherwise returns {}. Spread into process.env when spawning AWS CLI commands.
+ */
+export function awsProfileEnv(env: Environment): Record<string, string> {
+  const profile = loadAwsProfiles()[env];
+  return profile ? { AWS_PROFILE: profile } : {};
+}
+
+/** Invalidate cache (used in tests or after aws-configure runs). */
+export function clearAwsProfileCache(): void {
+  cache = null;
+}