@theholocron/holocron-plugin-sentry 3.24.3

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,54 @@
+<!-- editorconfig-checker-disable-file -->
+
+# `@theholocron/holocron-plugin-sentry`
+
+Sentry plugin for [Holocron](../cli). Implements the `observability`
+capability against the [Sentry management API](https://docs.sentry.io/api/).
+
+## Install
+
+<!-- prettier-ignore -->
+```bash
+pnpm add -D @theholocron/holocron-plugin-sentry
+
+```
+
+## Auth
+
+Token resolution order:
+
+1. `--token <TOKEN>` flag on the holocron invocation
+2. `HOLOCRON_SENTRY_TOKEN` env var
+3. `SENTRY_AUTH_TOKEN` env var (the standard Sentry variable name)
+
+Generate an auth token at **sentry.io/settings/account/api/auth-tokens/**
+with `org:read`, `project:read`, and `project:write` scopes. Both
+user-owned and org-owned tokens are accepted.
+
+## Config
+
+<!-- prettier-ignore -->
+```jsonc
+{
+  "providers": {
+    "observability": ["sentry", { "org": "my-org-slug", "team": "my-team" }],
+  },
+}
+
+```
+
+- `org` (required) — Sentry organization slug.
+- `team` (optional) — team slug for project creation. Defaults to the
+  org slug when omitted.
+
+## What's implemented
+
+| Method          | What it does                                                                                                                                                 |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `describe`      | Returns `{ provider: "sentry", envKeys: ["SENTRY_DSN", "NEXT_PUBLIC_SENTRY_DSN"] }` — the env vars the app reads at runtime.                                 |
+| `whoami`        | Fetches the org by slug to verify the token and confirm the org exists.                                                                                      |
+| `ensureProject` | Looks up the project by slug (derived from `name`); creates it under the configured team if absent. Returns the DSN and an `alreadyExists` flag. Idempotent. |
+
+`holocron setup` calls `ensureProject` and pushes both `SENTRY_DSN` and
+`NEXT_PUBLIC_SENTRY_DSN` to GitHub Secrets (same DSN value, both keys
+required by the Sentry Next.js SDK).

package/dist/index.d.mts

@@ -0,0 +1,71 @@
+import { AuthError, Observability, ResolveTokenInput } from "@theholocron/cli";
+import { SentryClient, SentryClientOptions, createSentryClient } from "@theholocron/sentry-client";
+//#region src/auth.d.ts
+declare const resolveToken: (input?: ResolveTokenInput) => string;
+//#endregion
+//#region src/capabilities/observability.d.ts
+interface SentryObservabilityOptions {
+  /** Sentry organization slug. Required. */
+  org: string;
+  /** Default team slug for project creation. Defaults to org slug. */
+  team?: string;
+}
+declare class SentryObservability implements Observability {
+  private readonly client;
+  private readonly opts;
+  readonly key: "observability";
+  readonly providerName = "sentry";
+  constructor(client: SentryClient, opts: SentryObservabilityOptions);
+  describe(): Promise<{
+    provider: string;
+    envKeys: string[];
+  }>;
+  whoami(): Promise<{
+    org: string;
+  }>;
+  ensureProject(input: {
+    name: string;
+    platform?: string;
+  }): Promise<{
+    dsn: string;
+    alreadyExists: boolean;
+  }>;
+}
+//#endregion
+//#region src/verify-token.d.ts
+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 SentryPluginOptions extends ResolveTokenInput, SentryObservabilityOptions {
+  /** Override base URL for tests. */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: SentryPluginOptions;
+  client: SentryClient;
+}
+declare function createContext(options: SentryPluginOptions): PluginContext;
+declare function observability(ctx: PluginContext): Observability;
+declare function createPlugin(options: SentryPluginOptions): {
+  name: string;
+  capabilities: {
+    observability: () => Observability;
+  };
+};
+declare const AUTH_HINT: string;
+//#endregion
+export { AUTH_HINT, AuthError, PluginContext, type ResolveTokenInput, type SentryClient, type SentryClientOptions, SentryObservability, type SentryObservabilityOptions, SentryPluginOptions, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, createSentryClient, observability, resolveToken, verifyToken };

package/dist/index.mjs

@@ -0,0 +1,110 @@
+import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
+import { createSentryClient } from "@theholocron/sentry-client";
+//#region src/auth.ts
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_SENTRY_TOKEN",
+	vendorEnvName: "SENTRY_AUTH_TOKEN",
+	keyringService: "sentry",
+	errorMessage: "no Sentry auth token found. Pass --token <TOKEN>, set HOLOCRON_SENTRY_TOKEN / SENTRY_AUTH_TOKEN, or run: holocron auth set sentry <TOKEN>"
+});
+//#endregion
+//#region src/capabilities/observability.ts
+var SentryObservability = class {
+	client;
+	opts;
+	key = "observability";
+	providerName = "sentry";
+	constructor(client, opts) {
+		this.client = client;
+		this.opts = opts;
+		if (!opts.org) throw new Error("SentryObservability requires `org` in options");
+	}
+	async describe() {
+		return {
+			provider: "sentry",
+			envKeys: ["SENTRY_DSN", "NEXT_PUBLIC_SENTRY_DSN"]
+		};
+	}
+	async whoami() {
+		return { org: (await this.client.auth.getOrg(this.opts.org)).slug };
+	}
+	async ensureProject(input) {
+		const slug = toSlug(input.name);
+		try {
+			const existing = await this.client.projects.get(this.opts.org, slug);
+			const dsn = (await this.client.projects.keys(this.opts.org, existing.slug))[0]?.dsn.public;
+			/* c8 ignore next */
+			if (!dsn) throw new ProviderApiError(`Sentry project ${slug} has no keys`, 404, void 0);
+			return {
+				dsn,
+				alreadyExists: true
+			};
+		} catch (err) {
+			if (!(err instanceof ProviderApiError) || err.status !== 404) throw err;
+		}
+		const team = this.opts.team ?? this.opts.org;
+		const project = await this.client.projects.create(this.opts.org, team, {
+			name: input.name,
+			platform: input.platform ?? "node"
+		});
+		const dsn = (await this.client.projects.keys(this.opts.org, project.slug))[0]?.dsn.public;
+		/* c8 ignore next */
+		if (!dsn) throw new ProviderApiError(`Sentry project ${project.slug} has no keys after creation`, 500, void 0);
+		return {
+			dsn,
+			alreadyExists: false
+		};
+	}
+};
+function toSlug(name) {
+	return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+//#endregion
+//#region src/verify-token.ts
+async function verifyToken(token, opts = {}) {
+	const client = createSentryClient({
+		token,
+		baseUrl: opts.baseUrl,
+		fetch: opts.fetch
+	});
+	try {
+		return {
+			ok: true,
+			subject: `org: ${(await client.auth.organizations())[0]?.slug ?? "unknown"}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
+function createContext(options) {
+	if (!options.org) throw new Error("@theholocron/holocron-plugin-sentry requires `org` in options");
+	return {
+		options,
+		client: createSentryClient({
+			token: resolveToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		})
+	};
+}
+function observability(ctx) {
+	return new SentryObservability(ctx.client, {
+		org: ctx.options.org,
+		team: ctx.options.team
+	});
+}
+function createPlugin(options) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-sentry",
+		capabilities: { observability: () => observability(ctx) }
+	};
+}
+const AUTH_HINT = "generate an auth token at https://sentry.io/settings/account/api/auth-tokens/ with project:read, project:write, and org:read scopes, then run: holocron auth set sentry <TOKEN>";
+//#endregion
+export { AUTH_HINT, AuthError, SentryObservability, createContext, createPlugin, createSentryClient, observability, resolveToken, verifyToken };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@theholocron/holocron-plugin-sentry",
+  "version": "3.24.3",
+  "description": "Holocron plugin for Sentry. Implements the observability capability against Sentry's management API — project provisioning and DSN retrieval.",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-sentry#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-sentry"
+  },
+  "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/sentry-client": "^1.7.1",
+    "@theholocron/cli": "3.24.4"
+  },
+  "peerDependenciesMeta": {
+    "@theholocron/sentry-client": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@theholocron/sentry-client": "^1.7.1",
+    "@theholocron/eslint-config": "^7.19.1",
+    "@theholocron/tsconfig": "^7.19.1",
+    "@theholocron/tsdown-config": "^7.19.1",
+    "@theholocron/vitest-config": "^7.19.1",
+    "@types/node": "^26",
+    "chalk": "^6.0.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/eslint-plugin": "^1.6.27",
+    "eslint": "^10.8.1",
+    "eslint-plugin-n": "^18.3.0",
+    "globals": "^17.9.0",
+    "tsdown": "^0.22.14",
+    "tsx": "4.22.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@theholocron/cli": "3.24.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "types": "./dist/index.d.mts",
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
+  }
+}