@super-repo/envx 0.4.0 → 0.4.1-b.2

package/docs/plugins/overview.md

@@ -0,0 +1,96 @@
+# @super-repo/envx/plugins
+
+> Secret-provider plugins for envx — `${aws-secrets:my-db}` and `${vault:prod/api}` style refs that resolve at load time from real backends.
+
+[![NPM](https://nodei.co/npm/@super-repo/envx/plugins.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/@super-repo/envx/plugins)
+
+[![npm version](https://img.shields.io/npm/v/@super-repo/envx/plugins.svg)](https://www.npmjs.com/package/@super-repo/envx/plugins)
+[![npm downloads](https://img.shields.io/npm/dm/@super-repo/envx/plugins.svg)](https://www.npmjs.com/package/@super-repo/envx/plugins)
+[![license](https://img.shields.io/npm/l/@super-repo/envx/plugins.svg)](./LICENSE)
+
+`.env*` files are great until the secrets in them shouldn't sit on disk. envx-plugins lets you write `${aws-secrets:prod/db}` (or vault, 1Password, Doppler, …) directly in `.env*` and have envx resolve those refs against the real backend at load time. Each plugin returns a `SecretProvider` you wire into [envx's](https://www.npmjs.com/package/@super-repo/envx) `resolvers:` config.
+
+The package itself has zero runtime SDK dependencies. Each plugin lazy-loads its provider's SDK on first use, so you only install the SDKs you actually reference.
+
+## Getting started
+
+```sh
+pnpm add @super-repo/envx/plugins
+```
+
+```ts
+// bootstrap.ts
+import envx from "@super-repo/envx";
+import { awsSecrets, autoPreload, asResolvers } from "@super-repo/envx/plugins";
+
+const aws = awsSecrets({ region: "us-east-1" });
+
+await autoPreload([aws], { envFiles: [".env"] });
+
+envx({
+  resolvers: asResolvers([aws]),
+});
+```
+
+```
+# .env
+DATABASE_URL=${aws-secrets:prod/db}
+API_KEY=${aws-secrets:prod/api-key}
+```
+
+For the all-seven-providers wiring, per-provider auth, edge-runtime usage, and custom backends, see [Docs](#docs).
+
+## Features
+
+| provider               | edge-runtime | reference syntax                                  |
+| ---------------------- | :----------: | ------------------------------------------------- |
+| **AWS Secrets Manager** | ⚠            | `${aws-secrets:<name>}` (`@v3` for version pin)   |
+| **GCP Secret Manager**  | ⚠            | `${gcp-secrets:<name>}` (`@3` for version pin)    |
+| **Azure Key Vault**     | ⚠            | `${azure-keyvault:<name>}` (`@<version>` for pin) |
+| **HashiCorp Vault**     | ✓            | `${vault:<path>}` (`#<field>` for JSON field)     |
+| **1Password (CLI)**     | ✗            | `${op:op://vault/item/field}`                     |
+| **1Password (SDK)**     | depends      | `${op:op://vault/item/field}`                     |
+| **Doppler**             | ✓            | `${doppler:<NAME>}`                               |
+| **Infisical**           | ✓            | `${infisical:<NAME>}`                             |
+
+✓ = native `fetch`, runs in Workers / Edge / Deno. ⚠ = needs Node-compatible runtime (Lambda, Cloud Run, Node). ✗ = spawns a child process. Full table with caveats: [docs/runtime.md](./docs/runtime.md#edge-runtime-compatibility-per-provider).
+
+Beyond the per-provider plugins:
+
+- **`autoPreload`** — scans your `envFiles` first, only invokes providers that actually appear, and runs them in parallel.
+- **`asResolvers`** — turns a provider list into the `{ name → resolve }` map envx expects.
+- **`buildProvider`** — wrap any async `(id) => Promise<string>` fetcher into a first-class `SecretProvider` for in-house backends.
+- **`createSecretRuntime`** (`/runtime` subpath) — V8-isolate-safe, TTL-cached, single-flight async fetch for edge / serverless.
+
+## Comparison
+
+| feature                                | `@super-repo/envx/plugins` | `dotenv-vault`     | direct vendor SDKs |
+| -------------------------------------- | :------------------------: | :----------------: | :----------------: |
+| `${ref}` interpolation in `.env*`      | ✓                          | ✗                  | ✗                  |
+| Pluggable, multi-vendor in one config  | ✓                          | ✗ (one backend)    | n/a                |
+| Lazy SDK install per provider          | ✓                          | n/a                | ✗                  |
+| Edge-runtime entry (V8-isolate-safe)   | ✓                          | ✗                  | varies             |
+| Works without leaving envx's pipeline  | ✓                          | replaces dotenv    | replaces dotenv    |
+
+`dotenv-vault` and the official Doppler / Infisical CLIs each take over the entire env story. envx-plugins keeps envx as the loader and adds vendor-backed `${ref}` resolution as a layer on top — so one repo can mix AWS for DB credentials, Vault for service tokens, and 1Password for developer secrets without three different bootstrap shapes.
+
+## Docs
+
+Deep references and worked examples live alongside this package in [./docs/](./docs/):
+
+- **[providers.md](./docs/providers.md)** — per-provider auth, options, and `${ref}` syntax for AWS, GCP, Azure, Vault, 1Password (CLI + SDK), Doppler, Infisical.
+- **[recipes.md](./docs/recipes.md)** — the all-seven-providers bootstrap, plus the SDK install matrix.
+- **[runtime.md](./docs/runtime.md)** — `createSecretRuntime` for edge / serverless: TTL caching, single-flight, failure modes, edge-compat table.
+- **[custom-providers.md](./docs/custom-providers.md)** — wrap any backend with `buildProvider`.
+- **[library-api.md](./docs/library-api.md)** — `SecretProvider` shape, `autoPreload`, `asResolvers`, `buildProvider`, `MissingSdkError`, subpath imports.
+
+## References
+
+- [`@super-repo/envx`](../core) — the loader these plugins plug into. envx-plugins has no purpose without it; the two are designed to be used together.
+- [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/) · [GCP Secret Manager](https://cloud.google.com/secret-manager/docs) · [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/) · [HashiCorp Vault KV](https://developer.hashicorp.com/vault/docs/secrets/kv)
+- [1Password Service Accounts](https://developer.1password.com/docs/service-accounts) · [Doppler API](https://docs.doppler.com/reference) · [Infisical API](https://infisical.com/docs/api-reference/overview/introduction)
+- [Project README](../../../README.md)
+
+## License
+
+MIT © Super-Repo contributors. See [LICENSE](./LICENSE).

package/docs/plugins/providers.md

@@ -0,0 +1,149 @@
+# Per-provider setup
+
+Each plugin has its own auth surface and `${ref}` syntax. All return the same `SecretProvider` shape, so they compose together inside one `asResolvers([...])` / `autoPreload([...])` call (see [Quick start](../README.md#getting-started) and [recipes.md](./recipes.md)).
+
+## AWS Secrets Manager
+
+```ts
+import { awsSecrets } from "@super-repo/envx/plugins/aws";
+
+const aws = awsSecrets({ region: "us-east-1" });
+await aws.preload(["prod/db", "prod/api-key"]);
+```
+
+```
+DATABASE_URL=${aws-secrets:prod/db}
+API_KEY=${aws-secrets:prod/api-key}
+```
+
+Multiple regions? Give each its own provider name and reference accordingly:
+
+```ts
+const awsUs = awsSecrets({ region: "us-east-1", name: "aws-us" });
+const awsEu = awsSecrets({ region: "eu-west-1", name: "aws-eu" });
+```
+
+```
+DB_US=${aws-us:prod/db}
+DB_EU=${aws-eu:prod/db}
+```
+
+## GCP Secret Manager
+
+```ts
+import { gcpSecrets } from "@super-repo/envx/plugins/gcp";
+
+const gcp = gcpSecrets({ projectId: "acme-prod" });
+await gcp.preload(["prod-db", "prod-api"]);
+```
+
+```
+DB_URL=${gcp-secrets:prod-db}
+API_KEY=${gcp-secrets:prod-api@3}    # pin to version 3
+```
+
+## Azure Key Vault
+
+```ts
+import { azureKeyVault } from "@super-repo/envx/plugins/azure";
+
+const az = azureKeyVault({
+  vaultUrl: "https://my-vault.vault.azure.net",
+});
+await az.preload(["prod-db", "prod-jwt-signing"]);
+```
+
+```
+DB_URL=${azure-keyvault:prod-db}
+JWT_SECRET=${azure-keyvault:prod-jwt-signing@<version>}
+```
+
+Credentials come from `DefaultAzureCredential` by default (env vars → managed identity → Azure CLI → VS Code, in that order). Pass `credential:` to override.
+
+## HashiCorp Vault (KV v1 / v2)
+
+```ts
+import { hcVault } from "@super-repo/envx/plugins/vault";
+
+const vault = hcVault({
+  endpoint: process.env.VAULT_ADDR!,
+  token: process.env.VAULT_TOKEN!,
+  mount: "secret",
+});
+await vault.preload(["prod/db", "prod/api"]);
+```
+
+```
+DB_URL=${vault:prod/db}             # reads `data.value` field by default
+USERNAME=${vault:prod/db#username}  # specific JSON field
+```
+
+KV v1? Pass `kvVersion: 1`.
+
+## 1Password — CLI mode (developer machines)
+
+If `op` is signed in on your machine, no token / SDK is required:
+
+```ts
+import { onePassword } from "@super-repo/envx/plugins/op";
+
+const op = onePassword();
+await op.preload([
+  "op://prod/Database/url",
+  "op://prod/API/key",
+]);
+```
+
+```
+DB_URL=${op:op://prod/Database/url}
+API_KEY=${op:op://prod/API/key}
+```
+
+## 1Password — SDK mode (CI / containers)
+
+Use a service-account token in environments without an interactive `op signin`:
+
+```ts
+const op = onePassword({
+  token: process.env.OP_SERVICE_ACCOUNT_TOKEN!,
+});
+```
+
+The plugin lazy-loads `@1password/sdk` only in this mode.
+
+## Doppler
+
+```ts
+import { doppler } from "@super-repo/envx/plugins/doppler";
+
+const dop = doppler({ token: process.env.DOPPLER_TOKEN! });
+await dop.preload(["DATABASE_URL", "API_KEY"]);
+```
+
+```
+DATABASE_URL=${doppler:DATABASE_URL}
+API_KEY=${doppler:API_KEY}
+```
+
+Service tokens scope to one project + config, so you typically don't pass project/config explicitly.
+
+## Infisical
+
+```ts
+import { infisical } from "@super-repo/envx/plugins/infisical";
+
+const inf = infisical({
+  token: process.env.INFISICAL_TOKEN!,
+  projectId: "proj-1",
+  environment: "prod",
+  secretPath: "/services/api",   // optional
+});
+await inf.preload(["DATABASE_URL", "API_KEY"]);
+```
+
+```
+DATABASE_URL=${infisical:DATABASE_URL}
+API_KEY=${infisical:API_KEY}
+```
+
+Self-hosted? Pass `endpoint: "https://infisical.example.com"`.

package/docs/plugins/recipes.md

@@ -0,0 +1,77 @@
+# Recipes
+
+End-to-end worked example wiring all seven providers into one envx bootstrap.
+
+## All 7 providers in one bootstrap
+
+```ts
+// bootstrap.ts
+import envx from "@super-repo/envx";
+import {
+  awsSecrets,
+  gcpSecrets,
+  azureKeyVault,
+  hcVault,
+  onePassword,
+  doppler,
+  infisical,
+  autoPreload,
+  asResolvers,
+} from "@super-repo/envx/plugins";
+
+const aws = awsSecrets({ region: "us-east-1" });
+const gcp = gcpSecrets({ projectId: "acme-prod" });
+const azure = azureKeyVault({ vaultUrl: "https://acme.vault.azure.net" });
+const vault = hcVault({
+  endpoint: process.env.VAULT_ADDR!,
+  token: process.env.VAULT_TOKEN!,
+});
+const op = onePassword({ token: process.env.OP_SERVICE_ACCOUNT_TOKEN });
+const dop = doppler({ token: process.env.DOPPLER_TOKEN! });
+const inf = infisical({
+  token: process.env.INFISICAL_TOKEN!,
+  projectId: "proj-1",
+  environment: "prod",
+});
+
+// One call, per-file scan, parallel resolution.
+await autoPreload([aws, gcp, azure, vault, op, dop, inf], {
+  envFiles: [".env", "vault/.env.prod"],
+});
+
+envx({
+  // `asResolvers([...])` builds the { name → resolve } map for you.
+  resolvers: asResolvers([aws, gcp, azure, vault, op, dop, inf]),
+});
+```
+
+In your `.env*` files:
+
+```
+DATABASE_URL=${aws-secrets:prod/db}
+CACHE_URL=${gcp-secrets:cache-host}
+JWT_SECRET=${azure-keyvault:prod-jwt-signing@v3}
+ROOT_TOKEN=${vault:prod/admin#token}
+GITHUB_PAT=${op:op://prod/GitHub/personal-access-token}
+SENDGRID_KEY=${doppler:SENDGRID_KEY}
+STRIPE_KEY=${infisical:STRIPE_LIVE_KEY}
+```
+
+Only the providers actually referenced in those files get pre-loaded — `autoPreload` scans the files first and skips providers with zero hits.
+
+## SDK install matrix
+
+The plugins package itself has zero runtime SDK dependencies. Each plugin lazy-loads its provider's SDK on first use; install only the SDKs you actually need:
+
+| provider           | install                                                                     |
+| ------------------ | --------------------------------------------------------------------------- |
+| AWS Secrets Manager | `pnpm add @aws-sdk/client-secrets-manager`                                  |
+| GCP Secret Manager  | `pnpm add @google-cloud/secret-manager`                                     |
+| Azure Key Vault     | `pnpm add @azure/keyvault-secrets @azure/identity`                          |
+| HashiCorp Vault     | _(no SDK — uses native `fetch`)_                                            |
+| 1Password (SDK)     | `pnpm add @1password/sdk`                                                   |
+| 1Password (CLI)     | install `op` via [1Password's docs](https://developer.1password.com/docs/cli) |
+| Doppler             | _(no SDK — uses native `fetch`)_                                            |
+| Infisical           | _(no SDK — uses native `fetch`)_                                            |
+
+If a provider's SDK isn't installed when you call its `preload`/`fetch`, the plugin throws `MissingSdkError` with the install command — see [library-api.md](./library-api.md).

package/docs/plugins/runtime.md

@@ -0,0 +1,88 @@
+# Runtime / edge — secrets that never leave the source
+
+For the "secrets never touch disk, fetched on demand" model, use `createSecretRuntime` from the `/runtime` subpath. Async-first, TTL-cached, V8-isolate-safe — works in Cloudflare Workers, Vercel Edge, Deno Deploy, AWS Lambda, Bun, Node.
+
+```ts
+// src/secrets.ts — module-level singleton, one instance per worker / process
+import { createSecretRuntime } from "@super-repo/envx/plugins/runtime";
+import { hcVault } from "@super-repo/envx/plugins/vault";
+
+export const secrets = createSecretRuntime({
+  providers: [
+    hcVault({
+      endpoint: env.VAULT_ADDR,
+      token: env.VAULT_TOKEN,
+    }),
+  ],
+  ttl: 300,                 // refresh after 5 min
+  onFailure: "cache-stale", // serve stale on transient backend failures
+});
+```
+
+```ts
+// Cloudflare Worker, Vercel Edge, Lambda, Deno Deploy — same handler shape
+import { secrets } from "./secrets";
+
+export default async function handler(req: Request): Promise<Response> {
+  const dbUrl = await secrets.get("vault:prod/db");
+  const apiKey = await secrets.get("vault:prod/api");
+  return new Response(JSON.stringify({ dbUrl, apiKey }));
+}
+```
+
+## Behavior
+
+- **Lazy fetch** — first read triggers the network call. Subsequent reads inside the TTL window hit the in-memory cache.
+- **Single-flight** — N concurrent reads of the same ref coalesce to one fetch. Edge functions handling a request burst don't fan out N parallel calls to your secret store.
+- **TTL refresh** — values older than `ttl` seconds are refetched on next read.
+- **Failure modes** — `"throw"` (default), `"cache-stale"` (serve previous value, log warn), `"cache-error"` (cache the failure for `errorTtl` seconds so a flaky backend doesn't get hammered).
+- **No fs / child_process imports** — the runtime entry is V8-isolate-safe.
+
+## API
+
+```ts
+interface SecretRuntime {
+  get(ref: string): Promise<string>;             // throws on miss / unknown provider / failed fetch
+  tryGet(ref: string): Promise<string | undefined>; // never throws
+  invalidate(ref: string): Promise<string>;      // force-refresh a specific ref
+  clear(): void;                                  // drop all cached entries
+  readonly stats: () => { cached: number; inflight: number; errors: number };
+}
+
+interface SecretRuntimeOptions {
+  readonly providers: readonly SecretProvider[];
+  readonly ttl?: number;                          // default 300 (5min). 0 = no cache. Infinity = forever.
+  readonly onFailure?: "throw" | "cache-stale" | "cache-error";
+  readonly errorTtl?: number;                     // for "cache-error" mode. default 30
+  readonly logger?: { warn(msg: string): void };
+}
+```
+
+## Edge-runtime compatibility per provider
+
+| provider              | Cloudflare Workers / Vercel Edge / Deno | Lambda / Cloud Run / Node | reason                       |
+| --------------------- | --------------------------------------- | ------------------------- | ---------------------------- |
+| `hcVault`             | ✓                                       | ✓                         | native `fetch`                |
+| `doppler`             | ✓                                       | ✓                         | native `fetch`                |
+| `infisical`           | ✓                                       | ✓                         | native `fetch`                |
+| `awsSecrets`          | ⚠                                       | ✓                         | Node streams in the SDK       |
+| `gcpSecrets`          | ⚠                                       | ✓                         | gRPC in the SDK               |
+| `azureKeyVault`       | ⚠                                       | ✓                         | `@azure/identity` token chain |
+| `onePassword` (CLI)   | ✗                                       | ✓ (with `op` on PATH)      | spawns a child process        |
+| `onePassword` (SDK)   | depends on `@1password/sdk`              | ✓                         | SDK's own constraints         |
+| custom `buildProvider`| depends on what your fetcher does        | ✓                         | usually fine if you use `fetch` |
+
+For maximum portability across edges, prefer Vault / Doppler / Infisical, or write your own provider with `buildProvider` (see [custom-providers.md](./custom-providers.md)):
+
+```ts
+import { buildProvider } from "@super-repo/envx/plugins";
+
+const myProvider = buildProvider("internal", async (id) => {
+  const r = await fetch(`https://internal.example.com/secrets/${id}`, {
+    headers: { Authorization: `Bearer ${env.MY_TOKEN}` },
+  });
+  return (await r.json()).value;
+});
+```
+
+That single-file plugin works in every JS runtime that has `fetch`.

package/docs/security-models.md

@@ -48,12 +48,12 @@ envx bake --public-only --out .env.resolved && pnpm vite build
 
 ## Runtime fetch — edge / serverless
 
-For the "secrets never leave the source-of-truth" model, use `createSecretRuntime` from `@super-repo/envx-plugins/runtime`. Async-first, TTL caching, no `fs` / `child_process` dependencies — works in Cloudflare Workers, Vercel Edge, Deno Deploy, AWS Lambda, Bun, Node.
+For the "secrets never leave the source-of-truth" model, use `createSecretRuntime` from `@super-repo/envx/plugins/runtime`. Async-first, TTL caching, no `fs` / `child_process` dependencies — works in Cloudflare Workers, Vercel Edge, Deno Deploy, AWS Lambda, Bun, Node.
 
 ```ts
 // src/secrets.ts — module-level singleton, one per worker
-import { createSecretRuntime } from "@super-repo/envx-plugins/runtime";
-import { hcVault } from "@super-repo/envx-plugins/vault";
+import { createSecretRuntime } from "@super-repo/envx/plugins/runtime";
+import { hcVault } from "@super-repo/envx/plugins/vault";
 
 export const secrets = createSecretRuntime({
   providers: [

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@super-repo/envx",
   "description": "A global executable to run applications with the ENV variables witin a monorepo loaded by dotenvx",
-  "version": "0.4.0",
+  "version": "0.4.1-b.2",
   "type": "module",
   "bin": {
-    "envx": "./dist/cli.js",
-    "dotenvx-proxy": "./dist/bin/dotenvx.js"
+    "envx": "./dist/cli.js"
   },
   "exports": {
     ".": {
@@ -23,6 +22,50 @@
     "./commands": {
       "types": "./dist/commands/index.d.ts",
       "default": "./dist/commands/index.js"
+    },
+    "./libs": {
+      "types": "./dist/libs/index.d.ts",
+      "default": "./dist/libs/index.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.ts",
+      "default": "./dist/plugins/index.js"
+    },
+    "./plugins/aws": {
+      "types": "./dist/plugins/aws.d.ts",
+      "default": "./dist/plugins/aws.js"
+    },
+    "./plugins/gcp": {
+      "types": "./dist/plugins/gcp.d.ts",
+      "default": "./dist/plugins/gcp.js"
+    },
+    "./plugins/azure": {
+      "types": "./dist/plugins/azure.d.ts",
+      "default": "./dist/plugins/azure.js"
+    },
+    "./plugins/vault": {
+      "types": "./dist/plugins/vault.d.ts",
+      "default": "./dist/plugins/vault.js"
+    },
+    "./plugins/op": {
+      "types": "./dist/plugins/op.d.ts",
+      "default": "./dist/plugins/op.js"
+    },
+    "./plugins/doppler": {
+      "types": "./dist/plugins/doppler.d.ts",
+      "default": "./dist/plugins/doppler.js"
+    },
+    "./plugins/infisical": {
+      "types": "./dist/plugins/infisical.d.ts",
+      "default": "./dist/plugins/infisical.js"
+    },
+    "./plugins/runtime": {
+      "types": "./dist/plugins/runtime.d.ts",
+      "default": "./dist/plugins/runtime.js"
+    },
+    "./plugins/auto-preload": {
+      "types": "./dist/plugins/auto-preload.d.ts",
+      "default": "./dist/plugins/auto-preload.js"
     }
   },
   "files": [
@@ -46,23 +89,20 @@
     }
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.49.1",
     "eciesjs": "^0.4.10",
     "ignore": "^5.3.2",
     "yargs": "^17.7.0",
-    "zod": "^3.25.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
+    "@types/node": "^25.8.0",
     "@types/yargs": "^17.0.33",
     "tsc-alias": "^1.8.16",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.11",
     "vite-plugin-dts": "^5.0.0",
-    "vitest": "^4.1.5",
-    "@super-repo/cli": "0.4.0",
-    "@super-repo/envx-libs": "0.0.1",
-    "@super-repo/envx-common": "0.0.1"
+    "vitest": "^4.1.6",
+    "@super-repo/common": "0.0.1"
   }
 }

package/dist/bin/dotenvx.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=dotenvx.d.ts.map

package/dist/bin/dotenvx.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dotenvx.d.ts","sourceRoot":"","sources":["../../src/bin/dotenvx.ts"],"names":[],"mappings":"AAQA,OAAO,kBAAkB,CAAC"}

package/dist/bin/dotenvx.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import "@dotenvx/dotenvx";