@hubble-ventures/infisicml 1.2.1 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,72 @@ All notable changes to `infisicml` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-07-17
+
+### Changed (breaking — manifest format)
+
+- **The manifest is now a `secrets` array of folders.** The flat `paths` +
+  `include` + `aliases` trio is replaced by a single `secrets` array that mirrors
+  your Infisical structure. Each of the three old fields was really an attribute
+  of a specific `(folder, key)` pair; the tree binds them together, so a key's
+  allowlist membership and its alias live in one place, provenance is explicit,
+  and the manifest reads like the vault. `secrets` is an array of folder objects
+  `{ name: [ ...contents ] }`; inside a folder's array, a **bare string** is a
+  plain key, an object with a **string value** `{ SOURCE: "TARGET" }` is an
+  alias, and an object with an **array value** `{ sub: [ ... ] }` is a **real
+  subfolder** (nesting mirrors the vault tree — `sub` under `posthog` reads
+  `/posthog/sub`). Value type discriminates alias vs subfolder, so subfolders
+  need no leading `/`. Fan a key out to several targets by repeating the alias,
+  one target each.
+
+  ```jsonc
+  // before (v1)                          // after (v2)
+  {                                       {
+    "paths": ["posthog"],                   "secrets": [
+    "aliases": {                              { "posthog": [
+      "POSTHOG_PROJECT_TOKEN":                  { "POSTHOG_PROJECT_TOKEN": "VITE_POSTHOG_KEY" }
+        "VITE_POSTHOG_KEY"                    ] }
+    },                                      ]
+    "include": ["POSTHOG_PROJECT_TOKEN"]  }
+  }
+  ```
+
+- **Default-deny everywhere.** There is no wildcard: every emitted key must be
+  named, and an empty folder array is a schema error. The tree *is* the
+  allowlist, so the separate `include` field is **removed** — a folder emits
+  exactly the keys it declares, from that folder (provenance-aware selection).
+- **`fetch: "keys"` no longer needs an allowlist.** Because the tree always
+  names every canonical key (an alias entry's key *is* the real vault key),
+  key mode requests those names directly — the v1 reverse-mapping from alias
+  target to source is gone, and `keys` is always satisfiable. The
+  `fetch`-requires-`include` cross-check is removed.
+- **Optional keys stay env-scoped** via `environments.<slug>.optionalKeys`
+  (unchanged), now referencing declared canonical key names.
+- **Profiles** carry an alternate `secrets` array (replacing the base tree when
+  `--profile` is set) plus an optional `fetch`; `profiles.<name>.paths` /
+  `.include` are gone.
+- **Programmatic API.** `resolvePaths` / `resolveInclude` / `applyInclude` /
+  `resolveFetchKeys` / `checkFetchIncludeConsistency` / `fetchManifestSecrets` /
+  `selectEmittedSecrets` are replaced by `resolveCompiledFolders`, `compileTree`,
+  `fetchCompiledFolders`, and `materializeSecrets` (the latter applies aliases
+  and enforces missing keys **per folder**, before merging, so a key name shared
+  across folders keeps each folder's value and miss); `enforceIncludeKnown` is
+  renamed `enforceKnownKeys`. New exports: `compileTree`, `treeSchema`,
+  `materializeSecrets`, and the `CompiledFolder` / `CompiledKey` / `FolderEntry` /
+  `FolderArray` / `SecretsTree` / `FolderSecrets` types.
+- **Schema** rewritten around the `secrets` array and published at `@2`.
+
+### Migration
+
+Convert each `secrets.json`: replace `paths`/`include`/`aliases` with a
+`secrets` array of `{ folder: [ ...keys ] }` objects; list plain keys as bare
+strings and each `aliases` source as a `{ SOURCE: "TARGET" }` object (repeat for
+several targets); keep only the keys you want (the array is the allowlist).
+Point `$schema` at `…/infisicml@2/…`.
+Behavior note: an alias entry now emits **both** its canonical name and the
+target(s) — v1 could suppress the canonical via `include`; v2 does not (the
+security boundary is default-deny provenance, not alias suppression).
+
 ## [1.2.1] - 2026-07-17
 
 ### Changed (BREAKING)
@@ -97,7 +163,6 @@ changes to either ship only in a new major.
 - **Published JSON Schema** for `secrets.json`, served from
   `https://cdn.jsdelivr.net/npm/@hubble-ventures/infisicml@1/schema/secrets.schema.json`.
 
-[1.2.1]: https://github.com/hubble-ventures/infisicml/releases/tag/v1.2.1
 [1.2.0]: https://github.com/hubble-ventures/infisicml/releases/tag/v1.2.0
 [1.1.0]: https://github.com/hubble-ventures/infisicml/releases/tag/v1.1.0
 [1.0.0]: https://github.com/hubble-ventures/infisicml/releases/tag/v1.0.0

package/README.md

@@ -36,29 +36,43 @@ Requires the [`infisical` CLI](https://infisical.com/docs/cli/overview) for loca
      projectIdEnvFile: ".env.infisical", // provides INFISICAL_PROJECT_ID
      discovery: { roots: ["apps", "services"], packages: [{ id: "postgres", dir: "infra/postgres" }] },
      auth: { oidcAudience: "https://github.com/your-org" },
-     hooks: { advertiseKeys: [{ envVar: "INFISCML_FLY_KEYS", scope: "runtime" }] },
+     hooks: { advertiseKeys: [{ envVar: "INFISICML_FLY_KEYS", scope: "runtime" }] },
    });
    ```
 
-2. Add a `secrets.json` next to each package:
+2. Add a `secrets.json` next to each package. `secrets` is an **array of
+   folders** mirroring your Infisical structure; each folder is
+   `{ "name": [ ...contents ] }`. Inside a folder's array, a **bare string** is a
+   plain key, an object with a **string value** `{ "SOURCE": "TARGET" }` is an
+   alias, and an object with an **array value** `{ "sub": [ ... ] }` is a
+   subfolder. Every emitted key is named (default-deny; there is no wildcard).
 
    ```jsonc
    {
-     "$schema": "https://cdn.jsdelivr.net/npm/@hubble-ventures/infisicml@1/schema/secrets.schema.json",
-     "paths": ["clerk", "posthog"],
+     "$schema": "https://cdn.jsdelivr.net/npm/@hubble-ventures/infisicml@2/schema/secrets.schema.json",
      "output": ".env", // written next to this manifest; defaults to .env.secrets
-     "aliases": {
-       // One canonical vault key → several prefixed copies in a single output.
-       "GOOGLE_MAPS_API_KEY": [
-         "EXPO_PUBLIC_GOOGLE_MAPS_API_KEY",
-         "VITE_GOOGLE_MAPS_API_KEY"
-       ],
-       // A single target is also fine (string form).
-       "CLERK_PUBLISHABLE_KEY": "VITE_CLERK_PUBLISHABLE_KEY"
-     }
+     "secrets": [
+       // Canonical vault key → the prefixed name a build tool expects.
+       { "clerk": [{ "CLERK_PUBLISHABLE_KEY": "VITE_CLERK_PUBLISHABLE_KEY" }] },
+       // Fan one canonical key out to several prefixes: repeat the alias, one
+       // target each (an array value would mean a subfolder, not multi-target).
+       { "google": [
+         { "GOOGLE_MAPS_API_KEY": "EXPO_PUBLIC_GOOGLE_MAPS_API_KEY" },
+         { "GOOGLE_MAPS_API_KEY": "VITE_GOOGLE_MAPS_API_KEY" }
+       ] },
+       { "posthog": [
+         "POSTHOG_PROJECT_TOKEN",
+         // A real Infisical subfolder at /posthog/eu.
+         { "eu": ["POSTHOG_EU_HOST"] }
+       ] }
+     ]
    }
    ```
 
+   An alias entry emits **both** its canonical name and the target. Keys you
+   don't name are never pulled, so a client package can share a vendor folder yet
+   emit only the public key — the server secret is simply undeclared.
+
 3. Pull secrets into gitignored `.env.secrets` files:
 
    ```bash
@@ -75,9 +89,9 @@ See [`examples/`](./examples) for a fuller config and manifest.
 |---|---|
 | `pull [ids...]` | Write `.env.secrets` locally (uses `infisical export`) |
 | `export-gha <id>` | Mask + append secrets to `GITHUB_ENV` (REST API + GitHub OIDC) |
-| `list` | Show every manifest and its Infisical paths |
+| `list` | Show every manifest's folder tree and declared keys |
 | `validate` | Validate every `secrets.json` against the schema |
-| `paths <id>` | Print resolved paths (`--comma` for scripting) |
+| `paths <id>` | Print resolved folder paths (`--comma` for scripting) |
 | `run <id> -- <cmd...>` | Thin `infisical run` wrapper (prefer `pull` + `.env.secrets`) |
 
 Common flags: `--env`, `--profile`, `--force`, `--here` (pull the cwd package), `--turbo` (always write, for Turbo caching).
@@ -132,89 +146,75 @@ Load `.env.secrets` however your dev runtime already loads env files. See [`exam
 
 ## Concepts
 
-- **Manifest (`secrets.json`)** — per package: `paths` (vault folders), optional `profiles`, `aliases`, `include`, `fetch`, `ci`, `environments`, `output`.
+- **Manifest (`secrets.json`)** — per package: `secrets` (an array of folders → keys), optional `profiles`, `fetch`, `ci`, `environments`, `output`.
 - **Output file** — `output` sets the written filename (default `.env.secrets`), placed **next to the manifest**. Because each package owns its own `secrets.json`, this gives a distinct file per package: a root manifest with `"output": ".env.local"` writes the repo-root `.env.local`; a manifest in `apps/backend` with `"output": ".env"` writes `apps/backend/.env`. `output` is a filename only (no path separators) — to target a different directory, place the manifest in that directory.
-- **Profiles** — named path sets that *replace* base `paths` when `--profile` is set. Base paths are runtime secrets; profile-only paths (e.g. `fly`) are deploy/release credentials.
-- **Aliases** — copy a canonical secret to extra tool-specific names. Each source maps to **one target (string) or many (array)**, so a single vault key can fan out to every framework prefix (`EXPO_PUBLIC_*`, `VITE_*`, `NEXT_PUBLIC_*`) in one output. Real secrets of a target name always win; the operation is idempotent and never overwrites.
-- **Include (key allowlist)** — `include` emits **only** the listed keys from whatever the folders yielded (default-deny key selection). Omit it and every key is emitted (unchanged). See [Key selection](#key-selection-include) below.
-- **Fetch mode** — `fetch: "keys"` requests only the keys `include` resolves to, so the vault never transmits the rest (wire-level least privilege). Default `"folder"` reads whole folders and filters locally. See [Wire-level least privilege](#wire-level-least-privilege-fetch-keys) below.
+- **Secrets tree** — an **array of folders** mirroring your Infisical vault; each folder is `{ "name": [ ...contents ] }`. Inside the array: a bare string is a plain key, an object with a string value `{ "SOURCE": "TARGET" }` is an alias, and an object with an array value `{ "sub": [ ... ] }` is a real subfolder. Every emitted key is named — there is no wildcard, so a folder never leaks a key you didn't declare (default-deny). See [Key selection](#key-selection-the-tree-is-the-allowlist) below.
+- **Profiles** — named alternate trees that *replace* the base `secrets` when `--profile` is set. The base tree is runtime secrets; a profile can add deploy/release folders (e.g. `fly`).
+- **Aliases** — an alias entry `{ "SOURCE": "TARGET" }` maps a canonical vault key to one target. To fan a single key out to every framework prefix (`EXPO_PUBLIC_*`, `VITE_*`, `NEXT_PUBLIC_*`), repeat the entry — one target each (an array value means a subfolder). Both the canonical name and each target are emitted. Real secrets of a target name always win; the operation is idempotent and never overwrites.
+- **Fetch mode** — `fetch: "keys"` requests only the declared keys, so the vault never transmits the rest (wire-level least privilege). Default `"folder"` reads whole folders and selects the declared keys locally. See [Wire-level least privilege](#wire-level-least-privilege-fetch-keys) below.
 - **CI skip/stub** — `ci.skipWhenEnv` skips the pull when all listed vars are already set in CI; `ci.stubInCi` always stubs in CI. Both write a `.env.secrets` from `process.env` instead of calling Infisical.
-- **Optional keys** — `environments.<slug>.optionalKeys` downgrade a missing key to a `::notice::` in `export-gha` instead of a failure.
+- **Optional keys** — `environments.<slug>.optionalKeys` downgrade a missing declared key to a `::notice::` instead of a failure.
 - **Advertise-keys hooks** — publish runtime key *names* (never values) to `GITHUB_ENV` for deploy forwarding.
 
-### Key selection (`include`)
+### Key selection (the tree is the allowlist)
 
 Vaults are often organized by **vendor, not by access scope** — a single `/stripe` folder
 holds both a server secret and a client-public key:
 
 ```
-/stripe → STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY
+/stripe → STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PUBLISHABLE_KEY
 ```
 
-A web/mobile client needs **only** the publishable key. With folder-only selection it would
-be forced to pull the whole folder — writing `STRIPE_SECRET_KEY` into a Vite/Expo client
-build's env (and, via the CI action, into `GITHUB_ENV` for jobs that shouldn't see it).
-
-`include` is a **default-deny allowlist**: only the listed env var names are emitted.
+A web/mobile client needs **only** the publishable key. Because the tree is default-deny, you
+name that one key and nothing else is pulled — `STRIPE_SECRET_KEY` is simply never declared,
+so it can't reach a Vite/Expo client build's env (or, via the CI action, `GITHUB_ENV`).
 
 ```jsonc
 // apps/web/secrets.json — a client package
 {
-  "paths": ["stripe", "google", "vercel"],
-  "aliases": {
-    "STRIPE_PUBLISHABLE_KEY": ["EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY"],
-    "GOOGLE_MAPS_API_KEY": ["EXPO_PUBLIC_GOOGLE_MAPS_API_KEY"]
-  },
-  "include": [
-    "EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY",
-    "EXPO_PUBLIC_GOOGLE_MAPS_API_KEY",
-    "EXPO_PUBLIC_VERCEL_AUTOMATION_BYPASS_SECRET"
+  "secrets": [
+    { "stripe": [{ "STRIPE_PUBLISHABLE_KEY": "EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY" }] },
+    { "google": [{ "GOOGLE_MAPS_API_KEY": "EXPO_PUBLIC_GOOGLE_MAPS_API_KEY" }] },
+    { "vercel": ["VERCEL_AUTOMATION_BYPASS_SECRET"] }
   ]
 }
 ```
 
-The written `.env.secrets` (and, in CI, `GITHUB_ENV`) contains **only** those three keys —
-server secrets in the same folders are never emitted.
-
-- **Ordering** — folders are pulled, then `aliases` are applied, then `include` filters the
-  **final** set of names. So aliasing a canonical key to a public name and listing only the
-  public name in `include` drops the canonical key (and every other folder key). An alias
-  whose source isn't in `include` still emits its target.
-- **Names, not paths** — `include` is a flat list of env var names; key names must be unique
-  across a package's folders.
-- **Unknown keys** — a name in `include` that no folder produced is an error (fail the pull /
-  CI step), **unless** it's also in `environments.<slug>.optionalKeys`, which downgrades it to
-  a `::notice::`. Enforced the same way in `pull` and `export-gha`.
-- **Profiles** — a profile may set its own `include`, which **replaces** the root `include`
-  for that profile (like `profiles.<name>.paths`). A profile without `include` inherits the
-  root one.
-- **Backward compatible** — omit `include` and behavior is unchanged (every key is emitted).
+The written `.env.secrets` (and, in CI, `GITHUB_ENV`) contains **only** the declared keys and
+their alias targets — server secrets in the same folders are never emitted.
+
+- **Provenance** — a key is emitted from the folder it's declared under, and only that folder.
+  Selection is per-folder, so the same name in two folders doesn't cross-contaminate.
+- **Alias emits both names** — an alias entry copies the canonical key to its target; *both*
+  the canonical name and the target land in the output. (To emit only a prefixed name, don't
+  declare the canonical one — but the canonical publishable key is usually harmless.)
+- **Unknown keys** — a declared key that its folder didn't produce is an error (fail the pull /
+  CI step), **unless** it's in `environments.<slug>.optionalKeys`, which downgrades it to a
+  `::notice::`. Enforced the same way in `pull` and `export-gha`.
+- **Profiles** — a profile supplies its own `secrets`, which **replaces** the root tree for that
+  profile.
 
 ### Wire-level least privilege (`fetch: "keys"`)
 
-`include` on its own is a **post-fetch filter**: infisicml pulls each whole folder, then drops
-the unwanted keys before writing the output. The excluded values still travel over the wire
-into your machine / the CI runner — they're just never written to `.env` or `GITHUB_ENV`. For
-most setups that's fine. When you need the vault to **not even transmit** the secrets you
-don't use, set `fetch: "keys"`:
+By default (`fetch: "folder"`) infisicml pulls each whole folder, then selects the declared
+keys before writing the output. The undeclared values still travel over the wire into your
+machine / the CI runner — they're just never written to `.env` or `GITHUB_ENV`. For most
+setups that's fine. When you need the vault to **not even transmit** the secrets you don't
+use, set `fetch: "keys"`:
 
 ```jsonc
 // apps/web/secrets.json — client package, strict wire-level least privilege
 {
-  "paths": ["stripe", "google"],
   "fetch": "keys",
-  "aliases": {
-    "STRIPE_PUBLISHABLE_KEY": ["EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY"]
-  },
-  "include": [
-    "EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY",
-    "GOOGLE_MAPS_API_KEY"
+  "secrets": [
+    { "stripe": [{ "STRIPE_PUBLISHABLE_KEY": "EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY" }] },
+    { "google": ["GOOGLE_MAPS_API_KEY"] }
   ]
 }
 ```
 
-In `keys` mode infisicml emits **only** the keys `include` resolves to. Where the guarantee
-bites depends on the lane:
+In `keys` mode infisicml reads **only** the declared keys. Where the guarantee bites depends on
+the lane:
 
 - **CI (`export-gha`)** — true **wire-level** least privilege: each key is fetched with the
   single-secret REST endpoint (`GET /api/v3/secrets/raw/{name}`), so the other keys in
@@ -225,23 +225,18 @@ bites depends on the lane:
   once and selects the keys. It narrows what's **written to disk**, not what the vault
   transmits — on your own machine, where folder mode already lands.
 
-- **Requires `include`** — key mode fetches exactly what `include` names, so an allowlist is
-  mandatory (root or the active profile). `validate` and the pull/CI step both enforce this.
-- **Aliases are reverse-mapped** — `include` names the *final* (post-alias) keys, so infisicml
-  fetches the canonical vault source behind each alias target. Above, listing
-  `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY` fetches the canonical `STRIPE_PUBLISHABLE_KEY`.
-- **Imports still resolve** — a key surfaced into a `paths` folder via an Infisical import is
-  fetched in `keys` mode too (the per-key read follows imports but returns only that one
-  secret), so enabling `keys` never silently drops an import-backed key.
-- **Same emit result** — everything after the fetch (aliases, `include` filtering, unknown-key
-  enforcement, `optionalKeys`) is identical to folder mode; only what's read narrows.
-- **Cost** — in CI, one request **per key** instead of one per folder; the `paths` list becomes
+- **No allowlist needed** — the tree already names every canonical key (an alias entry's key
+  *is* the real vault key), so `keys` mode requests exactly those names directly — no reverse
+  mapping, and `keys` is always satisfiable.
+- **Imports still resolve** — a key surfaced into a folder via an Infisical import is fetched in
+  `keys` mode too (the per-key read follows imports but returns only that one secret), so
+  enabling `keys` never silently drops an import-backed key.
+- **Same emit result** — everything after the fetch (aliases, unknown-key enforcement,
+  `optionalKeys`) is identical to folder mode; only what's read narrows.
+- **Cost** — in CI, one request **per key** instead of one per folder; the folder list becomes
   advisory (`infisicml paths` notes this).
-- **Profiles** — a profile may set its own `fetch`, which **replaces** the root value (like
-  `paths` / `include`). A deploy profile can stay in `folder` mode while the runtime default
-  is `keys`, or vice versa.
-- **Backward compatible** — omit `fetch` (or set `"folder"`) and behavior is byte-for-byte
-  unchanged.
+- **Profiles** — a profile may set its own `fetch`, which **replaces** the root value. A deploy
+  profile can stay in `folder` mode while the runtime default is `keys`, or vice versa.
 
 ### Non-secret defaults (`.env.sample`)
 
@@ -278,19 +273,24 @@ for (const manifest of discoverManifests(config)) {
 
 ## Releasing
 
-Releases are cut by pushing a semver tag; [`.github/workflows/release.yml`](./.github/workflows/release.yml) does the rest:
+**Releases are automatic — you don't tag anything.** Bump the version in a PR
+and merging it to `main` cuts the release:
 
 ```bash
-npm version 1.2.3 --no-git-tag-version
-git commit -am "release: v1.2.3"
-git tag v1.2.3 && git push origin main --tags
+npm run release -- minor    # or patch / major / 2.1.0 — bumps package.json + rebuilds dist
+# edit CHANGELOG.md: add the new version's section
+git commit -am "release: v2.1.0"
+# open a PR, merge it → release fires
 ```
 
-The workflow builds + tests the tagged commit, publishes to npm via **trusted
-publishing** (OIDC — no `NPM_TOKEN` secret, provenance attached automatically),
-creates a GitHub Release from the matching [`CHANGELOG.md`](./CHANGELOG.md) section, and
-moves the floating `v1` tag to the release commit. The publish step is idempotent — a
-version already on npm is skipped.
+On the push to `main`, [`.github/workflows/release.yml`](./.github/workflows/release.yml)
+reads `package.json`; if that version isn't tagged yet it builds + tests, **creates and
+pushes the `vX.Y.Z` tag**, publishes to npm via **trusted publishing** (OIDC — no
+`NPM_TOKEN` secret, provenance attached automatically), creates a GitHub Release from the
+matching [`CHANGELOG.md`](./CHANGELOG.md) section, and moves the floating major tag (e.g.
+`v2`). A main push that doesn't bump the version is a no-op, and the publish step is
+idempotent — a version already on npm is skipped. Manually pushing a `vX.Y.Z` tag still
+works if you ever need it.
 
 > **First publish (one time).** The `@hubble-ventures` npm **organization** must exist,
 > and npm trusted publishing can only be configured against an *existing* package — so
@@ -304,8 +304,8 @@ version already on npm is skipped.
 > (`publishConfig.access: public` in `package.json` enforces this even if the flag is
 > omitted.) Then, in the package's npm settings, add a **trusted publisher** for
 > `hubble-ventures/infisicml` → workflow `release.yml`, with **no environment** (the release
-> job sets none — the OIDC claims must match). Every subsequent tag push publishes
-> automatically with no token.
+> job sets none — the OIDC claims must match). Every subsequent version bump merged to
+> `main` publishes automatically with no token.
 
 ## Design
 

package/dist/aliases.d.ts

@@ -1,20 +1,26 @@
-import type { SecretsManifest } from "./manifest.js";
+import type { CompiledFolder } from "./tree.js";
 export type ResolvedAlias = {
     source: string;
     targets: string[];
 };
-/** Normalize the manifest's alias map to a list of {source, targets[]}. */
-export declare function resolveAliases(manifest: SecretsManifest): ResolvedAlias[];
+/**
+ * Collect the alias `source -> targets` pairs from the compiled folders. Each
+ * `aliased` entry in the tree names a canonical vault key (the source) and the
+ * extra env var name(s) a build/runtime expects (the targets).
+ */
+export declare function resolveAliases(folders: CompiledFolder[]): ResolvedAlias[];
 /**
  * Copy each aliased source secret's value to its target env var name(s).
  *
  * Used wherever the CLI materializes secrets (CI `export-gha`, local
  * `.env.secrets` pull) so the conventional, tool-specific name each deployment
- * expects is always present — see the `aliases` doc in manifest.ts.
+ * expects is always present — the vault names a secret once (e.g. /posthog
+ * exposes POSTHOG_PROJECT_TOKEN), but build tools inline it by a tool-specific
+ * name (Vite reads VITE_*, Next reads NEXT_PUBLIC_*).
  *
  * Returns a new object. An absent source is skipped, and an existing target (a
  * real secret of that name) is never overwritten, so real values win over
  * aliases and the operation is idempotent.
  */
-export declare function applyAliases(merged: Record<string, string>, manifest: SecretsManifest): Record<string, string>;
+export declare function applyAliases(merged: Record<string, string>, folders: CompiledFolder[]): Record<string, string>;
 //# sourceMappingURL=aliases.d.ts.map

package/dist/aliases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAElE,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa,EAAE,CAOzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,eAAe,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB"}
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,aAAa,EAAE,CAUzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,EAAE,cAAc,EAAE,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB"}

package/dist/aliases.js

@@ -1,27 +1,35 @@
-/** Normalize the manifest's alias map to a list of {source, targets[]}. */
-export function resolveAliases(manifest) {
-    const aliases = manifest.aliases;
-    if (!aliases)
-        return [];
-    return Object.entries(aliases).map(([source, value]) => ({
-        source,
-        targets: Array.isArray(value) ? value : [value],
-    }));
+/**
+ * Collect the alias `source -> targets` pairs from the compiled folders. Each
+ * `aliased` entry in the tree names a canonical vault key (the source) and the
+ * extra env var name(s) a build/runtime expects (the targets).
+ */
+export function resolveAliases(folders) {
+    const out = [];
+    for (const folder of folders) {
+        for (const key of folder.keys) {
+            if (key.aliases.length > 0) {
+                out.push({ source: key.key, targets: key.aliases });
+            }
+        }
+    }
+    return out;
 }
 /**
  * Copy each aliased source secret's value to its target env var name(s).
  *
  * Used wherever the CLI materializes secrets (CI `export-gha`, local
  * `.env.secrets` pull) so the conventional, tool-specific name each deployment
- * expects is always present — see the `aliases` doc in manifest.ts.
+ * expects is always present — the vault names a secret once (e.g. /posthog
+ * exposes POSTHOG_PROJECT_TOKEN), but build tools inline it by a tool-specific
+ * name (Vite reads VITE_*, Next reads NEXT_PUBLIC_*).
  *
  * Returns a new object. An absent source is skipped, and an existing target (a
  * real secret of that name) is never overwritten, so real values win over
  * aliases and the operation is idempotent.
  */
-export function applyAliases(merged, manifest) {
+export function applyAliases(merged, folders) {
     const out = { ...merged };
-    for (const { source, targets } of resolveAliases(manifest)) {
+    for (const { source, targets } of resolveAliases(folders)) {
         const value = merged[source];
         if (value === undefined)
             continue;

package/dist/aliases.js.map

@@ -1 +1 @@
-{"version":3,"file":"aliases.js","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAIA,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,QAAyB;IACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IACjC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QACvD,MAAM;QACN,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;KAChD,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC1B,MAA8B,EAC9B,QAAyB;IAEzB,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC1B,KAAK,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,SAAS;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;QACrD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"aliases.js","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAyB;IACtD,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAC9B,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAC1B,MAA8B,EAC9B,OAAyB;IAEzB,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC1B,KAAK,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,SAAS;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;QACrD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/ci-skip.d.ts

@@ -1,26 +1,43 @@
-import { type SecretsManifest } from "./manifest.js";
+import type { SecretsManifest } from "./manifest.js";
 import type { SecretsProvider } from "./providers/types.js";
+import type { CompiledFolder } from "./tree.js";
 export type { SecretsProvider };
+/** A folder's declared keys paired with the values that folder actually held. */
+export type FolderSecrets = {
+    folder: CompiledFolder;
+    /** Declared keys present in this folder (canonical, pre-alias). */
+    selected: Record<string, string>;
+};
 export declare function mergeFolderSecrets(chunks: Record<string, string>[]): Record<string, string>;
-export declare function fetchSecretsForPaths(provider: SecretsProvider, envName: string, paths: string[]): Promise<Record<string, string>>;
 /**
- * `fetch: "keys"` counterpart to {@link fetchSecretsForPaths}: request only the
- * given canonical keys from each folder and merge. A key absent from one folder
- * is simply not returned by that folder; the merge (last folder wins, matching
- * the folder path) collects it from whichever folder holds it.
+ * Fetch each compiled folder and select *that folder's* declared keys from it,
+ * honoring the resolved `fetch` mode. `keys` mode requests only the declared
+ * keys per folder (the tree names the exact canonical vault keys, so no
+ * allowlist reverse-map is needed — the alias *source* is the real key);
+ * `folder` mode reads the whole folder and picks the declared keys locally.
+ *
+ * Returns one {@link FolderSecrets} per folder so downstream steps keep folder
+ * provenance: two folders declaring the same key name are distinct entries here,
+ * and only collapse (last-wins) at the final merge — see {@link materializeSecrets}.
  */
-export declare function fetchSecretsForKeys(provider: SecretsProvider, envName: string, paths: string[], keys: string[]): Promise<Record<string, string>>;
+export declare function fetchCompiledFolders(provider: SecretsProvider, envName: string, folders: CompiledFolder[], fetchMode: "folder" | "keys"): Promise<FolderSecrets[]>;
 /**
- * Fetch a manifest's secrets for the given folder set, honoring its resolved
- * `fetch` mode: `keys` requests only the canonical keys `include` resolves to
- * (least privilege at the wire), `folder` reads whole folders. `keys` requires
- * an `include` allowlist — the whole point is to name exactly what to fetch.
+ * Turn per-folder fetched secrets into the final emit map, preserving folder
+ * provenance:
+ *
+ * - **Missing keys are checked per folder/key pair, before merging.** A key
+ *   declared in `/a` but absent from `/a` is unknown even if a same-named key in
+ *   `/b` was produced — so a genuine miss can't be masked by another folder.
+ * - **Aliases expand from the folder-local value.** `/a`'s `TOKEN -> A_TOKEN`
+ *   uses `/a`'s `TOKEN`, and `/b`'s `TOKEN -> B_TOKEN` uses `/b`'s — the flat
+ *   merge (which keeps only one `TOKEN`) can no longer route one folder's secret
+ *   to another folder's alias.
  *
- * Callers pass an explicit `paths` subset (export-gha splits runtime vs
- * deploy-only) rather than re-deriving it, so the runtime/deploy provenance the
- * caller already computed is preserved.
+ * Folder-local aliased maps then merge in tree order (last-wins on a genuine
+ * cross-folder name collision). A declared key absent from its folder fails
+ * unless its name is in `optionalKeys` for the environment.
  */
-export declare function fetchManifestSecrets(provider: SecretsProvider, envName: string, paths: string[], manifest: SecretsManifest, profile?: string): Promise<Record<string, string>>;
+export declare function materializeSecrets(folderSecrets: FolderSecrets[], optionalKeys: string[]): Record<string, string>;
 export declare function isCi(): boolean;
 export declare function shouldSkipInfisicalPull(manifest: SecretsManifest, force: boolean): boolean;
 export declare function keysForCiStub(manifest: SecretsManifest): string[];

package/dist/ci-skip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ci-skip.d.ts","sourceRoot":"","sources":["../src/ci-skip.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMjC;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMjC;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAuBjC;AAED,wBAAgB,IAAI,IAAI,OAAO,CAG9B;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,OAAO,GACb,OAAO,CAgBT;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,EAAE,CAEjE"}
+{"version":3,"file":"ci-skip.d.ts","sourceRoot":"","sources":["../src/ci-skip.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,iFAAiF;AACjF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,cAAc,CAAC;IACvB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,EAAE,EACzB,SAAS,EAAE,QAAQ,GAAG,MAAM,GAC3B,OAAO,CAAC,aAAa,EAAE,CAAC,CAe1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,aAAa,EAAE,EAC9B,YAAY,EAAE,MAAM,EAAE,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED,wBAAgB,IAAI,IAAI,OAAO,CAG9B;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,OAAO,GACb,OAAO,CAgBT;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,EAAE,CAEjE"}