@hubble-ventures/infisicml 1.2.1 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,107 @@ 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.1.0] - 2026-07-18
+
+### Added
+
+- **YAML manifests, as the primary format.** Each package's manifest may now be
+  `secrets.yaml`, `secrets.yml`, or `secrets.json` — the same schema either way.
+  YAML is the default and reads best for hand-authored manifests; JSON stays
+  fully supported (handy for generated manifests). Discovery prefers YAML, but a
+  directory containing **more than one** manifest file is a **hard error** rather
+  than a silent pick — a stale extra manifest must never change which secret tree
+  a non-interactive lane (`export-gha` → `GITHUB_ENV`) writes. No migration is
+  required — existing `secrets.json` files keep working unchanged.
+
+  ```yaml
+  # secrets.yaml
+  secrets:
+    - clerk:
+        - CLERK_PUBLISHABLE_KEY: VITE_CLERK_PUBLISHABLE_KEY
+    - posthog:
+        - POSTHOG_PROJECT_TOKEN
+  ```
+
+  The ambiguity error is **scoped to the package actually being loaded**:
+  discovery now enumerates packages without parsing them, so a single ambiguous
+  (or invalid) directory no longer aborts commands that don't touch it — `pull web`
+  or `paths web` succeed even if an unrelated `apps/legacy/` holds two manifests;
+  only a command that loads that package (`pull legacy`, `pull` with no ids,
+  `list`, `validate`) surfaces the error.
+
+  New public API: `findManifestFile`, `hasManifestFile`, `loadManifestFromDir`,
+  `parseManifestFile`, `MANIFEST_FILENAMES`, the `ManifestFile` / `ManifestFormat`
+  types, plus `discoverPackages` / `loadPackage` and the `PackageRef` type for
+  two-phase (enumerate-then-load) discovery. A discovered `PackageManifest` now
+  carries the `file` it was loaded from.
+
+## [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 +198,8 @@ 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
+[2.1.0]: https://github.com/hubble-ventures/infisicml/releases/tag/v2.1.0
+[2.0.0]: https://github.com/hubble-ventures/infisicml/releases/tag/v2.0.0
 [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

@@ -2,7 +2,7 @@
 
 **Infisical Secret Orchestration** — federated, per-package secret manifests for monorepos, unified across local development and CI.
 
-[Infisical](https://infisical.com) gives you a vault and the primitives to read from it (a CLI, a REST API, machine-identity auth, a GitHub Action). All of those operate on **one folder / one environment / one process at a time**. Infisicml is the layer above that: it lets each package in a monorepo declare which vault folders it needs in a committed `secrets.json`, then materializes those secrets **the same way** whether you're a developer running a local pull or a CI job exporting into `GITHUB_ENV`.
+[Infisical](https://infisical.com) gives you a vault and the primitives to read from it (a CLI, a REST API, machine-identity auth, a GitHub Action). All of those operate on **one folder / one environment / one process at a time**. Infisicml is the layer above that: it lets each package in a monorepo declare which vault folders it needs in a committed manifest (`secrets.yaml`, or `secrets.json`), then materializes those secrets **the same way** whether you're a developer running a local pull or a CI job exporting into `GITHUB_ENV`.
 
 > Infisicml orchestrates Infisical. It stores no secrets and never sees your vault contents at rest — the vault, auth, and secret values stay in Infisical.
 
@@ -10,11 +10,11 @@
 
 | Problem | Native Infisical | Infisicml |
 |---|---|---|
-| N packages each need a different slice of the vault | Hand-write export commands per app×folder | One committed `secrets.json` per package, auto-discovered |
+| N packages each need a different slice of the vault | Hand-write export commands per app×folder | One committed manifest (`secrets.yaml`/`.json`) per package, auto-discovered |
 | Dev uses the CLI, CI uses the API | Two integrations kept in sync by hand | One `SecretsProvider` abstraction; identical downstream logic |
 | Vault names a secret once, but Vite wants `VITE_*` and Next wants `NEXT_PUBLIC_*` | Each workflow re-derives the prefixed copy | Declare `aliases` once; applied in dev **and** CI |
 | Skip the pull in CI when vars are already injected | Bash guards in every workflow | `ci.skipWhenEnv` / `ci.stubInCi` policy |
-| A deploy needs exactly the runtime keys, not the deploy creds | Hand-maintained allowlist | `profiles` + `advertiseKeys` hook — `secrets.json` is the source of truth |
+| A deploy needs exactly the runtime keys, not the deploy creds | Hand-maintained allowlist | `profiles` + `advertiseKeys` hook — the manifest is the source of truth |
 | A client must read a shared vendor folder without ever receiving its server secrets | Split the vault or accept over-fetch | `fetch: "keys"` requests only the named keys — the vault never transmits the rest |
 
 ## Install
@@ -36,35 +36,55 @@ 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:
-
-   ```jsonc
-   {
-     "$schema": "https://cdn.jsdelivr.net/npm/@hubble-ventures/infisicml@1/schema/secrets.schema.json",
-     "paths": ["clerk", "posthog"],
-     "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"
-     }
-   }
+2. Add a `secrets.yaml` next to each package (YAML is the primary format;
+   `secrets.json` is equally supported — see the note below). `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 entry with a **string value** `SOURCE: TARGET` is an alias, and
+   an entry with an **array value** `sub: [ ... ]` is a subfolder. Every emitted
+   key is named (default-deny; there is no wildcard).
+
+   ```yaml
+   # yaml-language-server: $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
+   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.
+
+   > **Format:** each package's manifest may be `secrets.yaml`, `secrets.yml`, or
+   > `secrets.json` — the same schema either way. YAML is the default and reads
+   > best for hand-authored manifests; JSON is handy for generated ones. If a
+   > directory has more than one, `secrets.yaml` wins. See
+   > [`examples/yaml/secrets.yaml`](./examples/yaml/secrets.yaml) and
+   > [`examples/json/secrets.json`](./examples/json/secrets.json) for the same manifest in
+   > both formats.
+
 3. Pull secrets into gitignored `.env.secrets` files:
 
    ```bash
    npx infisicml pull                 # every package
    npx infisicml pull web api --force # specific ids, bypass the exists-check
-   npx infisicml validate             # check every secrets.json against the schema
+   npx infisicml validate             # check every manifest against the schema
    ```
 
 See [`examples/`](./examples) for a fuller config and manifest.
@@ -75,9 +95,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 |
-| `validate` | Validate every `secrets.json` against the schema |
-| `paths <id>` | Print resolved paths (`--comma` for scripting) |
+| `list` | Show every manifest's folder tree and declared keys |
+| `validate` | Validate every manifest against the schema |
+| `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).
@@ -125,96 +145,81 @@ Log in once as yourself; infisicml shells out to `infisical export` under your s
 
 ```bash
 infisical login          # authenticate as you
-npx infisicml pull          # write .env.secrets next to every secrets.json
+npx infisicml pull          # write .env.secrets next to every manifest
 ```
 
 Load `.env.secrets` however your dev runtime already loads env files. See [`examples/local-dev.md`](./examples/local-dev.md) for package-script and task-runner wiring.
 
 ## Concepts
 
-- **Manifest (`secrets.json`)** — per package: `paths` (vault folders), optional `profiles`, `aliases`, `include`, `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.
+- **Manifest (`secrets.yaml` or `secrets.json`)** — per package: `secrets` (an array of folders → keys), optional `profiles`, `fetch`, `ci`, `environments`, `output`. YAML is the default format; JSON is equally supported. When a directory has both, `secrets.yaml` wins.
+- **Output file** — `output` sets the written filename (default `.env.secrets`), placed **next to the manifest**. Because each package owns its own manifest, 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.
+- **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, a mapping with a string value `SOURCE: TARGET` is an alias, and a mapping 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"
-  ]
-}
+```yaml
+# apps/web/secrets.yaml — a client package
+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"
-  ]
-}
+```yaml
+# apps/web/secrets.yaml — client package, strict wire-level least privilege
+fetch: keys
+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 +230,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 +278,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,12 +309,12 @@ 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
 
-Everything repo-specific lives in `infisicml.config` — package discovery, the project-id source, the OIDC audience, and deploy-time key advertisement are all configuration, so nothing about one repo's layout is baked into the tool. The manifest contract (`secrets.json`) is the stable public interface, versioned via the [published JSON Schema](./schema/secrets.schema.json).
+Everything repo-specific lives in `infisicml.config` — package discovery, the project-id source, the OIDC audience, and deploy-time key advertisement are all configuration, so nothing about one repo's layout is baked into the tool. The manifest contract (`secrets.yaml` or `secrets.json`) is the stable public interface, versioned via the [published JSON Schema](./schema/secrets.schema.json).
 
 ## License
 

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"}