@theholocron/holocron-plugin-doppler 2.0.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+<!-- editorconfig-checker-disable-file -->
+
+# `@theholocron/holocron-plugin-doppler`
+
+Doppler plugin for [Holocron](../cli). Implements the `vault`
+capability against [Doppler's REST API](https://docs.doppler.com/reference/api),
+plus exports `verifyToken` + `AUTH_HINT` for use by `holocron auth`.
+
+## Install
+
+```bash
+pnpm add -D @theholocron/holocron-plugin-doppler@alpha
+```
+
+## Auth
+
+Token resolution order (matches the standard 4-step precedence set by
+`.notes/tech-auth-bootstrap.spec.md`):
+
+1. `--token <TOKEN>` flag on the holocron invocation
+2. `HOLOCRON_DOPPLER_TOKEN` env var (preferred — explicit intent)
+3. `DOPPLER_TOKEN` env var (Doppler-native, works in CI)
+4. **Keyring** — `com.theholocron.cli` service, account `doppler`
+5. `AuthError` naming all four options + the bootstrap hint
+
+## Manual setup (one-time, per operator)
+
+Doppler's free tier does not expose Service Accounts (Team+ only). Use
+a Personal Token or CLI token instead.
+
+```bash
+# 1. Install the Doppler CLI
+brew install dopplerhq/cli/doppler
+
+# 2. Log in (opens a browser). Token lands in ~/.doppler/.doppler.yaml
+#    → OS keychain, managed by the Doppler CLI.
+doppler login
+
+# 3. Hand the token off to holocron's keyring (one-shot). After this,
+#    every plugin call reads the token from the keyring — no env vars
+#    to remember, no dotfiles to sync.
+holocron auth set doppler $(doppler configure get token --plain)
+
+# 4. Verify:
+holocron auth check doppler
+```
+
+**CI**: the keyring is not available in headless containers. Expose
+the token as a GitHub Actions secret and set `HOLOCRON_DOPPLER_TOKEN`
+(or `DOPPLER_TOKEN`) in the workflow env. Steps 1–3 of the auth
+precedence still work; step 4 quietly falls through.
+
+## Config
+
+```jsonc
+{
+	"providers": {
+		"vault": ["doppler", { "project": "my-app", "config": "dev" }],
+	},
+}
+```
+
+- `project` (required) — Doppler project name. `read` / `list` /
+  bootstrap operations default to this project.
+- `config` (required) — Doppler config name (usually `dev`, `stg`, or
+  `prd`). `list()` reads secrets from this config.
+
+Individual `read` / `write` calls take a fully-qualified reference:
+
+```
+doppler://<project>/<config>/<name>
+```
+
+The default project + config in options apply to `list()`,
+`environments()`, and `readEnvironment()` where a three-part
+reference doesn't make sense.
+
+## What's implemented
+
+| Method              | Behavior                                                                                                                  |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `read`              | `GET /v3/configs/config/secret?project&config&name`. Returns `value.computed` when present, else `value.raw`.             |
+| `write`             | `POST /v3/configs/config/secrets` with `{ project, config, secrets: {name: value} }`. Doppler's native upsert — no probe. |
+| `list`              | `GET /v3/configs/config/secrets` on the default project + config.                                                         |
+| `environments`      | `GET /v3/environments?project`. Returns environment slugs (`dev`/`stg`/`prd`).                                            |
+| `readEnvironment`   | `GET /v3/configs/config/secrets/download?format=json` — bulk KEY=VALUE dump for `holocron secrets sync`.                  |
+| `ensureProject`     | `POST /v3/projects`, treats 409/422 "already exists" as idempotent no-op.                                                 |
+| `ensureEnvironment` | `POST /v3/environments`, same idempotency semantics.                                                                      |
+
+Plugin-level exports (not capability methods, per the auth-bootstrap
+convention):
+
+| Export        | Purpose                                                                                     |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| `verifyToken` | `GET /v3/me` — returns `{ok: true, subject: "personal @ acme"}` or `{ok: false, message}`.  |
+| `AUTH_HINT`   | One-line hint printed by `holocron auth set` when no token is supplied or the token is bad. |
+
+## Status
+
+**`v2.0.0-alpha.1`** — published on npm under the `alpha` dist-tag.
+APIs may still shift before stable v2.0.0.

package/dist/index.d.mts

@@ -0,0 +1,131 @@
+import { EnsureResult, Vault } from "@theholocron/cli";
+
+//#region src/auth.d.ts
+/**
+ * Token resolution for the Doppler plugin.
+ *
+ * Resolution order (matches the standard 4-step precedence set by
+ * `.notes/tech-auth-bootstrap.spec.md`):
+ *   1. explicit `cliToken` argument (from `--token` flag)
+ *   2. HOLOCRON_DOPPLER_TOKEN env var (preferred — explicit intent)
+ *   3. DOPPLER_TOKEN env var (Doppler-native, works in CI)
+ *   4. keyring (com.theholocron.cli / "doppler")
+ *   5. AuthError with a hint pointing at `doppler configure`
+ */
+declare class AuthError extends Error {
+  name: string;
+}
+interface ResolveTokenInput {
+  /** From `--token` CLI flag. */
+  cliToken?: string;
+  /** Env vars; passed in for testability. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** Keyring lookup fn; passed in for testability. Defaults to `getToken(provider)`. */
+  keyring?: (provider: string) => string | null;
+}
+declare function resolveToken(input?: ResolveTokenInput): string;
+//#endregion
+//#region src/rest.d.ts
+/**
+ * Thin REST wrapper around api.doppler.com/v3.
+ *
+ * Same pattern as the GitHub / Vercel / Neon REST clients — bearer
+ * auth, JSON-only bodies, transport-failure wrapping with `status: 0`
+ * so the orchestrator's soft-skip path sees a clear "Doppler GET /path
+ * failed" message instead of a generic `TypeError: fetch failed`.
+ */
+interface RestClientOptions {
+  token: string;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+}
+interface RequestOptions {
+  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+  body?: unknown;
+  query?: Record<string, string>;
+  /** Treat this response as void even if 200 is returned. */
+  expectNoContent?: boolean;
+}
+declare class DopplerRestClient {
+  private readonly token;
+  private readonly fetchImpl;
+  readonly baseUrl: string;
+  constructor(opts: RestClientOptions);
+  request<T>(path: string, opts?: RequestOptions): Promise<T>;
+}
+//#endregion
+//#region src/capabilities/vault.d.ts
+interface DopplerVaultOptions {
+  /** Default project — read/list/etc. operate here unless overridden. */
+  project: string;
+  /** Default config name — dev / stg / prd, etc. */
+  config: string;
+}
+declare class DopplerVault implements Vault {
+  private readonly rest;
+  readonly key: "vault";
+  readonly providerName = "doppler";
+  private readonly project;
+  private readonly config;
+  constructor(rest: DopplerRestClient, opts: DopplerVaultOptions);
+  read(reference: string): Promise<string>;
+  write(reference: string, value: string): Promise<void>;
+  list(): Promise<string[]>;
+  environments(): Promise<string[]>;
+  readEnvironment(environmentId: string): Promise<Record<string, string>>;
+  ensureProject(name: string): Promise<EnsureResult>;
+  ensureEnvironment(project: string, name: string): Promise<EnsureResult>;
+}
+//#endregion
+//#region src/verify-token.d.ts
+/**
+ * `verifyToken` — plugin-level export used by `holocron auth set` +
+ * `holocron auth check`. Hits `GET /v3/me` and translates the response
+ * into the normalized `VerifyTokenResult` shape.
+ *
+ * Kept as a standalone function (not a capability method) so the auth
+ * command can call it without initializing the full plugin — plugin
+ * construction requires an already-resolved token, which is exactly
+ * what we don't have yet at bootstrap time.
+ */
+interface VerifyTokenSuccess {
+  ok: true;
+  subject: string;
+}
+interface VerifyTokenFailure {
+  ok: false;
+  message: string;
+}
+type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+interface VerifyTokenOptions {
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+//#endregion
+//#region src/index.d.ts
+interface DopplerPluginOptions extends ResolveTokenInput, DopplerVaultOptions {
+  /** Override base URL for tests. */
+  baseUrl?: string;
+  /** Override `fetch` for tests. */
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: DopplerPluginOptions;
+  rest: DopplerRestClient;
+}
+declare function createContext(options: DopplerPluginOptions): PluginContext;
+declare function vault(ctx: PluginContext): Vault;
+declare function createPlugin(options: DopplerPluginOptions): {
+  name: string;
+  capabilities: {
+    vault: () => Vault;
+  };
+};
+/**
+ * One-line hint shown by `holocron auth set doppler` when no token is
+ * supplied or when the supplied token is rejected.
+ */
+declare const AUTH_HINT: string;
+//#endregion
+export { AUTH_HINT, AuthError, DopplerPluginOptions, DopplerRestClient, DopplerVault, PluginContext, ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, resolveToken, vault, verifyToken };

package/dist/index.mjs

@@ -0,0 +1,288 @@
+import { ProviderApiError, getToken } from "@theholocron/cli";
+//#region src/auth.ts
+/**
+* Token resolution for the Doppler plugin.
+*
+* Resolution order (matches the standard 4-step precedence set by
+* `.notes/tech-auth-bootstrap.spec.md`):
+*   1. explicit `cliToken` argument (from `--token` flag)
+*   2. HOLOCRON_DOPPLER_TOKEN env var (preferred — explicit intent)
+*   3. DOPPLER_TOKEN env var (Doppler-native, works in CI)
+*   4. keyring (com.theholocron.cli / "doppler")
+*   5. AuthError with a hint pointing at `doppler configure`
+*/
+var AuthError = class extends Error {
+	name = "AuthError";
+};
+function resolveToken(input = {}) {
+	const env = input.env ?? process.env;
+	const keyring = input.keyring ?? getToken;
+	const token = input.cliToken || env.HOLOCRON_DOPPLER_TOKEN || env.DOPPLER_TOKEN || keyring("doppler");
+	if (!token) throw new AuthError("no Doppler token found. Pass --token <TOKEN>, set HOLOCRON_DOPPLER_TOKEN / DOPPLER_TOKEN, or run: holocron auth set doppler $(doppler configure get token --plain)");
+	return token;
+}
+//#endregion
+//#region src/capabilities/vault.ts
+/**
+* `vault` capability for Doppler.
+*
+* Reference format: `doppler://<project>/<config>/<name>` — three
+* parts, mirrors 1P's `op://Vault/Item/field`. The plugin options can
+* carry a default project + config so `list()` / `environments()` /
+* `readEnvironment()` don't need a three-part ref.
+*
+* Doppler's data model:
+*   - Projects (top-level)
+*   - Environments — dev / stg / prd (each has a root config with the
+*     same name)
+*   - Configs — the root configs plus optional branch configs (e.g.,
+*     `dev_local`, `dev_ci`). `holocron secrets sync` reads from
+*     configs, not environments.
+*
+* Write semantics: `POST /v3/configs/config/secrets` accepts a
+* `{name: value}` map and upserts. No probe-then-act dance needed.
+*
+* Bootstrap semantics: `ensureProject` / `ensureEnvironment` treat
+* "already exists" (409) as success. Doppler returns 409 with a
+* `messages` array; the plugin's REST client wraps it as
+* ProviderApiError with `status: 409` which we catch and swallow.
+*/
+var DopplerVault = class {
+	rest;
+	key = "vault";
+	providerName = "doppler";
+	project;
+	config;
+	constructor(rest, opts) {
+		this.rest = rest;
+		if (!opts.project) throw new Error("DopplerVault requires `project` in options");
+		if (!opts.config) throw new Error("DopplerVault requires `config` in options");
+		this.project = opts.project;
+		this.config = opts.config;
+	}
+	async read(reference) {
+		const parsed = parseReference(reference);
+		const res = await this.rest.request("/configs/config/secret", { query: {
+			project: parsed.project,
+			config: parsed.config,
+			name: parsed.name
+		} });
+		return res.value?.computed ?? res.value?.raw ?? "";
+	}
+	async write(reference, value) {
+		const parsed = parseReference(reference);
+		await this.rest.request("/configs/config/secrets", {
+			method: "POST",
+			body: {
+				project: parsed.project,
+				config: parsed.config,
+				secrets: { [parsed.name]: value }
+			}
+		});
+	}
+	async list() {
+		const res = await this.rest.request("/configs/config/secrets", { query: {
+			project: this.project,
+			config: this.config
+		} });
+		return Object.keys(res.secrets ?? {});
+	}
+	async environments() {
+		return ((await this.rest.request("/environments", { query: { project: this.project } })).environments ?? []).map((e) => e.slug ?? e.name ?? "").filter(Boolean);
+	}
+	async readEnvironment(environmentId) {
+		const res = await this.rest.request("/configs/config/secrets/download", { query: {
+			project: this.project,
+			config: environmentId,
+			format: "json"
+		} });
+		const out = {};
+		for (const [k, v] of Object.entries(res)) if (typeof v === "string") out[k] = v;
+		return out;
+	}
+	async ensureProject(name) {
+		try {
+			await this.rest.request("/projects", {
+				method: "POST",
+				body: {
+					name,
+					description: `Managed by holocron`
+				}
+			});
+			return { alreadyExists: false };
+		} catch (err) {
+			if (isConflict(err)) return { alreadyExists: true };
+			throw err;
+		}
+	}
+	async ensureEnvironment(project, name) {
+		try {
+			await this.rest.request("/environments", {
+				method: "POST",
+				body: {
+					project,
+					name,
+					slug: name
+				}
+			});
+			return { alreadyExists: false };
+		} catch (err) {
+			if (isConflict(err)) return { alreadyExists: true };
+			throw err;
+		}
+	}
+};
+/**
+* Parse `doppler://project/config/name` into its parts. Throws when
+* the shape doesn't match — surfacing bad inputs at the boundary keeps
+* downstream REST calls from emitting cryptic errors.
+*/
+function parseReference(reference) {
+	if (!reference.startsWith("doppler://")) throw new ProviderApiError(`Doppler references must start with "doppler://": got "${reference}"`, 400, void 0);
+	const parts = reference.slice(10).split("/");
+	if (parts.length < 3) throw new ProviderApiError(`Doppler reference "${reference}" missing parts; expected doppler://project/config/name`, 400, void 0);
+	const [project, config, ...nameParts] = parts;
+	return {
+		project,
+		config,
+		name: nameParts.join("/")
+	};
+}
+/**
+* Doppler returns duplicate-create errors inconsistently across
+* endpoints:
+*
+*   - POST /projects → 409 (or 422 with "already exists" body)
+*   - POST /environments → 400 with body
+*       `{"messages":["Environment with identifier dev already exists"],"success":false}`
+*
+* The REST client wraps all of these as ProviderApiError. We accept 409
+* outright + treat 400/422 as "already exists" when the response body
+* says so — matches Doppler's actual behavior.
+*/
+function isConflict(err) {
+	if (!(err instanceof ProviderApiError)) return false;
+	if (err.status === 409) return true;
+	if ((err.status === 400 || err.status === 422) && hasAlreadyExistsBody(err.details)) return true;
+	return false;
+}
+function hasAlreadyExistsBody(details) {
+	if (typeof details !== "string") return false;
+	return /already exists/i.test(details);
+}
+//#endregion
+//#region src/rest.ts
+/**
+* Thin REST wrapper around api.doppler.com/v3.
+*
+* Same pattern as the GitHub / Vercel / Neon REST clients — bearer
+* auth, JSON-only bodies, transport-failure wrapping with `status: 0`
+* so the orchestrator's soft-skip path sees a clear "Doppler GET /path
+* failed" message instead of a generic `TypeError: fetch failed`.
+*/
+var DopplerRestClient = class {
+	token;
+	fetchImpl;
+	baseUrl;
+	constructor(opts) {
+		this.token = opts.token;
+		this.fetchImpl = opts.fetch ?? globalThis.fetch;
+		let url = opts.baseUrl ?? "https://api.doppler.com/v3";
+		while (url.endsWith("/")) url = url.slice(0, -1);
+		this.baseUrl = url;
+	}
+	async request(path, opts = {}) {
+		const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`);
+		for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
+		const fullUrl = url.toString();
+		const headers = {
+			authorization: `Bearer ${this.token}`,
+			accept: "application/json"
+		};
+		const init = {
+			method: opts.method ?? "GET",
+			headers
+		};
+		if (opts.body !== void 0) {
+			headers["content-type"] = "application/json";
+			init.body = JSON.stringify(opts.body);
+		}
+		let res;
+		try {
+			res = await this.fetchImpl(fullUrl, init);
+		} catch (err) {
+			const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+			throw new ProviderApiError(`Doppler ${init.method} ${path} failed: ${detail}`, 0, void 0);
+		}
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			throw new ProviderApiError(`Doppler ${init.method} ${path} → ${res.status}`, res.status, body);
+		}
+		if (opts.expectNoContent || res.status === 204) return void 0;
+		const text = await res.text();
+		if (!text) return void 0;
+		return JSON.parse(text);
+	}
+};
+//#endregion
+//#region src/verify-token.ts
+/**
+* `verifyToken` — plugin-level export used by `holocron auth set` +
+* `holocron auth check`. Hits `GET /v3/me` and translates the response
+* into the normalized `VerifyTokenResult` shape.
+*
+* Kept as a standalone function (not a capability method) so the auth
+* command can call it without initializing the full plugin — plugin
+* construction requires an already-resolved token, which is exactly
+* what we don't have yet at bootstrap time.
+*/
+async function verifyToken(token, opts = {}) {
+	const restOpts = { token };
+	if (opts.baseUrl !== void 0) restOpts.baseUrl = opts.baseUrl;
+	if (opts.fetch !== void 0) restOpts.fetch = opts.fetch;
+	const rest = new DopplerRestClient(restOpts);
+	try {
+		const me = await rest.request("/me");
+		const workplace = me.workplace?.name ?? me.slug ?? "unknown";
+		return {
+			ok: true,
+			subject: `${me.type ?? "token"} @ ${workplace}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
+function createContext(options) {
+	const restOpts = { token: resolveToken(options) };
+	if (options.baseUrl !== void 0) restOpts.baseUrl = options.baseUrl;
+	if (options.fetch !== void 0) restOpts.fetch = options.fetch;
+	return {
+		options,
+		rest: new DopplerRestClient(restOpts)
+	};
+}
+function vault(ctx) {
+	return new DopplerVault(ctx.rest, {
+		project: ctx.options.project,
+		config: ctx.options.config
+	});
+}
+function createPlugin(options) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-doppler",
+		capabilities: { vault: () => vault(ctx) }
+	};
+}
+/**
+* One-line hint shown by `holocron auth set doppler` when no token is
+* supplied or when the supplied token is rejected.
+*/
+const AUTH_HINT = "install the Doppler CLI (`brew install dopplerhq/cli/doppler`), run `doppler login`, then `holocron auth set doppler $(doppler configure get token --plain)`";
+//#endregion
+export { AUTH_HINT, AuthError, DopplerRestClient, DopplerVault, createContext, createPlugin, resolveToken, vault, verifyToken };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@theholocron/holocron-plugin-doppler",
+  "version": "2.0.0-alpha.5",
+  "description": "Holocron plugin for Doppler. Implements the vault capability against Doppler's REST API — projects, configs, secrets, plus verifyToken + AUTH_HINT for `holocron auth`.",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-doppler#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-doppler"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "@theholocron/cli": "2.0.0-alpha.5"
+  },
+  "devDependencies": {
+    "@theholocron/tsconfig": "^4.1.0",
+    "@tsconfig/node-lts": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.6",
+    "eslint": "^9.36.0",
+    "globals": "^16.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6",
+    "tsdown": "^0.22.3",
+    "tsx": "^4.22.4",
+    "@theholocron/cli": "2.0.0-alpha.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
+  },
+  "types": "./dist/index.d.mts"
+}