@theholocron/holocron-plugin-sentry 5.0.0-alpha.44 → 5.0.0-alpha.442

package/README.md

@@ -21,7 +21,7 @@ Token resolution order:
 2. `HOLOCRON_SENTRY_TOKEN` env var
 3. `SENTRY_AUTH_TOKEN` env var (the standard Sentry variable name)
 4. Keyring `sentry.<org>` — tried first when an org is active via `--org`, `HOLOCRON_ORG`, or `org` in `holocron.config.ts`
-5. Keyring `sentry` — unnamespaced fallback; set via `holocron auth set sentry <token>`
+5. Keyring `sentry` — unnamespaced fallback; set via `holocron new token sentry <token>`
 
 Generate an auth token at **sentry.io/settings/account/api/auth-tokens/**
 with `org:read`, `project:read`, and `project:write` scopes. Both
@@ -47,12 +47,15 @@ user-owned and org-owned tokens are accepted.
 
 | Method          | What it does                                                                                                                                                 |
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `describe`      | Returns `{ provider: "sentry", envKeys: ["SENTRY_DSN", "NEXT_PUBLIC_SENTRY_DSN"] }` — the env vars the app reads at runtime.                                 |
+| `describe`      | Returns `{ provider: "sentry", envKeys: ["SENTRY_DSN"], frameworkEnvKeys: { next: ["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. |
 
 A provider entry in `holocron.config` is only needed to enable `holocron
-setup` provisioning (`ensureProject` + pushing `SENTRY_DSN` /
-`NEXT_PUBLIC_SENTRY_DSN` to Secrets) and `holocron doctor` connectivity
+setup` provisioning (`ensureProject` + pushing `SENTRY_DSN` to Secrets, and
+`NEXT_PUBLIC_SENTRY_DSN` too when Next.js is detected: the root `package.json`
+or any workspace package's lists `next`) and `holocron doctor` connectivity
 checks — not for runtime error reporting, which the CLI activates directly
-from `HOLOCRON_SENTRY_DSN` (fallback `SENTRY_DSN`).
+from `HOLOCRON_SENTRY_DSN` (fallback `SENTRY_DSN`). A DSN is built to be embedded in
+client code, so it is not a true secret.
+Setup never removes `NEXT_PUBLIC_SENTRY_DSN`: a repo that drops Next.js deletes that secret by hand.

package/dist/index.d.mts

@@ -1,28 +1,55 @@
-import { AuthError, Errors, ResolveTokenInput } from "@theholocron/cli";
+import { AuthError, EnsureRelayInput, EnsureRelayResult, Errors, InspectRelayInput, PluginToken, RelayState, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } 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/errors.d.ts
+/** Resolves the Sentry token from `--token`, `HOLOCRON_SENTRY_TOKEN`, `SENTRY_AUTH_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
+export declare const resolveToken: import("@theholocron/cli").TokenResolver;
+/**
+ * The token for the Comlink relay: an integration, its client secret and an alert rule need more than the general token
+ * (`alerts:write`, `org:write`, `event:read`), so it has its own.
+ */
+export declare const resolveComlinkToken: import("@theholocron/cli").FeatureResolver;
+/**
+ * The token for the relay: the Comlink one when there is one, else the general Sentry token as the last resort. The
+ * fallback only helps if the general token happens to carry the scopes; otherwise Sentry's answer names what is missing.
+ */
+export declare function resolveRelayToken(input?: ResolveTokenInput): string;
+/**
+ * Every token this plugin takes, for `holocron doctor secrets --verify`, each with what its layer's token must and must not be
+ * able to do: the general one, the Comlink relay's own and the CI release token.
+ */
+export declare const tokens: PluginToken[];
+/** Options for the Sentry `errors` capability. */
 interface SentryErrorsOptions {
   /** Sentry organization slug. Required for `whoami` and `ensureProject`. */
   org?: string;
   /** Default team slug for project creation. Defaults to org slug. */
   team?: string;
 }
-declare class SentryErrors implements Errors {
+/** The `errors` capability for Sentry: finds or creates a project and reports its DSN, and manages the Comlink relay. */
+export declare class SentryErrors implements Errors {
   private readonly client;
   private readonly opts;
+  /** The client for the relay, made with the Comlink token (see `resolveRelayToken`). */
+  private readonly relayClient;
+  /** The capability key, always `errors`. */
   readonly key: "errors";
+  /** The provider name, `sentry`. */
   readonly providerName = "sentry";
-  constructor(client: () => SentryClient, opts: SentryErrorsOptions);
+  constructor(client: () => SentryClient, opts: SentryErrorsOptions,
+  /** The client for the relay, made with the Comlink token (see `resolveRelayToken`). */
+  relayClient?: () => SentryClient);
+  ensureRelay(input: EnsureRelayInput): Promise<EnsureRelayResult>;
+  inspectRelay(input: InspectRelayInput): Promise<RelayState>;
   describe(): Promise<{
     provider: string;
     envKeys: string[];
+    frameworkEnvKeys: {
+      next: string[];
+    };
   }>;
   whoami(): Promise<{
     org: string;
-  }>;
+  } | null>;
+  /** Returns the public DSN of the project named `input.name` (matched by its slug), creating it when missing; needs `org`, and the new project uses `team` (default the org slug) and `platform` (default `node`). */
   ensureProject(input: {
     name: string;
     platform?: string;
@@ -37,25 +64,14 @@ declare class SentryErrors implements Errors {
    */
   private requireOrg;
 }
-//#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, SentryErrorsOptions {
+/** Checks a Sentry token by listing its organizations; the success subject is `org:` and the first organization's slug, the failure carries the error message. */
+export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
+/** Options for the Sentry plugin: token resolution, the organization and team, and test overrides. */
+export interface SentryPluginOptions extends ResolveTokenInput, SentryErrorsOptions {
   /**
    * Sentry organization slug. Optional at load time — the `errors` capability
    * activates from env vars alone — but required for `whoami` / `ensureProject`
@@ -64,20 +80,33 @@ interface SentryPluginOptions extends ResolveTokenInput, SentryErrorsOptions {
   org?: string;
   /** Override base URL for tests. */
   baseUrl?: string;
+  /** Override `fetch` for tests. */
   fetch?: typeof fetch;
 }
-interface PluginContext {
+/** What the plugin's capabilities share: the options and two lazily built clients. */
+export interface PluginContext {
+  /** The options the plugin was created with. */
   options: SentryPluginOptions;
+  /** Builds the Sentry client on first call and reuses it; the token is resolved then, not at plugin load. */
   client: () => SentryClient;
+  /** The client for the Comlink relay: its own token (`sentry.comlink`), the general one only as a last resort. */
+  relayClient: () => SentryClient;
 }
-declare function createContext(options: SentryPluginOptions): PluginContext;
-declare function errors(ctx: PluginContext): Errors;
-declare function createPlugin(options: SentryPluginOptions): {
+/** Creates the shared context for the given options; no token is resolved until a client is first called. */
+export declare function createContext(options: SentryPluginOptions): PluginContext;
+/** Builds the `errors` capability from a plugin context, using the relay client for the Comlink relay. */
+export declare function errors(ctx: PluginContext): Errors;
+/** Creates the Sentry plugin: its probes, a `connection` probe and the `errors` capability. */
+export declare function createPlugin(options: SentryPluginOptions): {
   name: string;
+  probes: {
+    token: import("@theholocron/cli").Probe;
+    connection: import("@theholocron/cli").Probe;
+  };
   capabilities: {
     errors: () => Errors;
   };
 };
-declare const AUTH_HINT: string;
-//#endregion
-export { AUTH_HINT, AuthError, PluginContext, type ResolveTokenInput, type SentryClient, type SentryClientOptions, SentryErrors, type SentryErrorsOptions, SentryPluginOptions, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, createSentryClient, errors, resolveToken, verifyToken };
+/** One-line hint shown by `holocron new token sentry` when no token is given or the token is rejected. */
+export declare const AUTH_HINT: string;
+export { AuthError, type ResolveTokenInput, type SentryClient, type SentryClientOptions, type SentryErrorsOptions, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createSentryClient };

package/dist/index.mjs

@@ -1,32 +1,366 @@
-import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
+import { AuthError, ProviderApiError, connectionProbe, createFeatureResolver, createResolveToken, tokenExpectations } from "@theholocron/cli";
+import { createEnvLookup, holocronEnv } from "@theholocron/env-utils/lookup";
+import { randomUUID } from "node:crypto";
+import { errorMessage } from "@theholocron/misc-utils";
 import { createSentryClient } from "@theholocron/sentry-client";
-//#region src/auth.ts
+// src/probes/token/expectations.ts
+const READS = {
+	org: "required",
+	projects: "required"
+};
+/**
+* The general token provisions projects and their DSNs and lives on a laptop (`local` inherits `dev`): it needs
+* `org:read` and `project:read`. `project:write` has no read that proves it, so it is not probed; the permission table
+* in `docs/src/content/docs/tokens.mdx` lists it. This is the plugin's `tokens` declaration, read through
+* `tokenExpectations()`; change it and that table together.
+*/
+const GENERAL = { permissions: {
+	local: READS,
+	dev: READS
+} };
+const RELAY_READS = {
+	org: "required",
+	projects: "required",
+	alerts: "required"
+};
+/**
+* The Comlink relay's token makes an integration and an alert rule, so on top of the general token's reads it needs
+* `alerts:read`. Its write scopes (`org:write`, `alerts:write`) and `event:read` are not probed, as no read proves them.
+*/
+const COMLINK = { permissions: {
+	local: RELAY_READS,
+	dev: RELAY_READS
+} };
+/**
+* The release token only creates a release and uploads sourcemaps (an organization token with `org:ci`), so it must not
+* read the organization, its projects or its alert rules: a leak from CI cannot reach them.
+*/
+const RELEASE = { permissions: { ci: {
+	org: "absent",
+	projects: "absent",
+	alerts: "absent"
+} } };
+// src/auth.ts
+/** Resolves the Sentry token from `--token`, `HOLOCRON_SENTRY_TOKEN`, `SENTRY_AUTH_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
 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>"
+	errorMessage: "no Sentry auth token found. Pass --token <TOKEN>, set HOLOCRON_SENTRY_TOKEN / SENTRY_AUTH_TOKEN, or run: holocron new token sentry <TOKEN>"
 });
-//#endregion
-//#region src/capabilities/errors.ts
+/**
+* The token for the Comlink relay: an integration, its client secret and an alert rule need more than the general token
+* (`alerts:write`, `org:write`, `event:read`), so it has its own.
+*/
+const resolveComlinkToken = createFeatureResolver({
+	envName: "HOLOCRON_SENTRY_COMLINK_TOKEN",
+	keyringKey: "sentry.comlink",
+	vendor: "Sentry"
+});
+/**
+* The token for the relay: the Comlink one when there is one, else the general Sentry token as the last resort. The
+* fallback only helps if the general token happens to carry the scopes; otherwise Sentry's answer names what is missing.
+*/
+function resolveRelayToken(input = {}) {
+	try {
+		return resolveComlinkToken(input);
+	} catch (err) {
+		if (!(err instanceof AuthError)) throw err;
+		return resolveToken(input);
+	}
+}
+/**
+* The token only `release.yml` reads (sentry-cli makes the release and uploads sourcemaps): an organization token with
+* `org:ci` held in the `ci` layer. The plugin never resolves it, so it is `optional` and `verifiable: false` (the
+* plugin's `verifyToken` lists organizations, which this token must not be able to do); it is declared so the probe and
+* `holocron probe sentry token --environment ci` can find it and check that it reaches nothing else.
+*/
+const releaseToken = {
+	envName: "HOLOCRON_SENTRY_RELEASE_TOKEN",
+	keyringKey: "sentry.release",
+	optional: true,
+	verifiable: false,
+	expect: RELEASE
+};
+/**
+* Every token this plugin takes, for `holocron doctor secrets --verify`, each with what its layer's token must and must not be
+* able to do: the general one, the Comlink relay's own and the CI release token.
+*/
+const tokens = [
+	{
+		...resolveToken.token,
+		expect: GENERAL
+	},
+	{
+		...resolveComlinkToken.token,
+		expect: COMLINK
+	},
+	releaseToken
+];
+// src/capabilities/relay.ts
+/** What the integration needs to read: the alert's event. It is also why reading its secret needs the same scope. */
+const INTEGRATION_SCOPES = ["event:read"];
+const DEFAULT_FREQUENCY = 5;
+/**
+* The alert action that sends through an integration, in the shape Sentry's own page writes when "Send a notification via
+* an integration" is picked: a `webhook` action named by the integration's slug. (A `sentry_app` action with the numeric
+* id is accepted too, but the page shows it as an unknown integration.)
+*/
+const integrationAction = (slug) => ({
+	type: "webhook",
+	config: {
+		targetType: null,
+		targetDisplay: null,
+		targetIdentifier: slug
+	},
+	data: {}
+});
+const sendsThrough = (action, slug) => action.type === "webhook" && action.config["targetIdentifier"] === slug;
+/** The `sentry_app` form an earlier version wrote for this integration, which the page cannot name. */
+const isLegacyAction = (action, appId) => action.type === "sentry_app" && String(action.config["targetIdentifier"]) === String(appId);
+/** A workflow as Sentry returned it, as the body to send back (the nested ids are not part of an update). */
+function toInput(wf) {
+	return {
+		name: wf.name,
+		enabled: wf.enabled,
+		environment: wf.environment,
+		config: wf.config,
+		detectorIds: wf.detectorIds,
+		triggers: {
+			logicType: wf.triggers.logicType,
+			conditions: wf.triggers.conditions.map((c) => ({
+				type: c.type,
+				comparison: c.comparison,
+				conditionResult: c.conditionResult
+			}))
+		},
+		actionFilters: wf.actionFilters.map((f) => ({
+			logicType: f.logicType,
+			conditions: f.conditions.map((c) => ({
+				type: c.type,
+				comparison: c.comparison,
+				conditionResult: c.conditionResult
+			})),
+			actions: f.actions.map((a) => ({
+				type: a.type,
+				config: a.config,
+				data: a.data
+			}))
+		}))
+	};
+}
+/** Sentry's own "high priority issues" rule, which is the default for a new alert. */
+function newWorkflow(name, frequency, detectorIds, slug) {
+	return {
+		name,
+		enabled: true,
+		environment: null,
+		config: { frequency },
+		detectorIds,
+		triggers: {
+			logicType: "any-short",
+			conditions: [{
+				type: "new_high_priority_issue",
+				comparison: true,
+				conditionResult: true
+			}, {
+				type: "existing_high_priority_issue",
+				comparison: true,
+				conditionResult: true
+			}]
+		},
+		actionFilters: [{
+			logicType: "all",
+			conditions: [],
+			actions: [integrationAction(slug)]
+		}]
+	};
+}
+/** The integration: found by name, made if missing, and its webhook and alert action brought in line. */
+async function ensureIntegration(client, org, input) {
+	const existing = (await client.sentryApps.list(org)).find((a) => a.name === input.name);
+	if (!existing) return {
+		app: await client.sentryApps.create(org, {
+			name: input.name,
+			scopes: INTEGRATION_SCOPES,
+			webhookUrl: input.webhookUrl,
+			isAlertable: true
+		}),
+		created: true,
+		updated: []
+	};
+	const updated = [];
+	if (existing.webhookUrl !== input.webhookUrl) updated.push("webhook URL");
+	if (!existing.isAlertable) updated.push("alert action");
+	const scopes = [.../* @__PURE__ */ new Set([...existing.scopes, ...INTEGRATION_SCOPES])];
+	if (scopes.length !== existing.scopes.length) updated.push("scopes");
+	if (updated.length === 0) return {
+		app: existing,
+		created: false,
+		updated
+	};
+	return {
+		app: await client.sentryApps.update(existing.slug, {
+			name: existing.name,
+			scopes,
+			webhookUrl: input.webhookUrl,
+			isAlertable: true
+		}),
+		created: false,
+		updated
+	};
+}
+/** The issue stream detector of each project, so a wrong project fails before anything is changed. */
+async function detectorsFor(client, org, slugs) {
+	const [projects, detectors] = await Promise.all([client.projects.list(org), client.workflows.detectors(org)]);
+	return slugs.map((slug) => {
+		const project = projects.find((p) => p.slug === slug);
+		if (!project) throw new Error(`Sentry project \`${slug}\` was not found in ${org}`);
+		const detector = detectors.find((d) => d.projectId === project.id && d.type === "issue_stream");
+		if (!detector) throw new Error(`Sentry project \`${slug}\` has no issue stream detector to attach an alert to`);
+		return detector.id;
+	});
+}
+/** The alert rule: one workflow for every project, found by name, made if missing, reconciled if not. */
+async function ensureRule(client, org, input, install, detectorIds) {
+	const workflows = await client.workflows.list(org);
+	const frequency = input.rule.frequency ?? DEFAULT_FREQUENCY;
+	const existing = workflows.find((w) => w.name === input.rule.name);
+	if (!existing) {
+		await client.workflows.create(org, newWorkflow(input.rule.name, frequency, detectorIds, install.slug));
+		return {
+			created: true,
+			updated: []
+		};
+	}
+	const next = toInput(existing);
+	const updated = [];
+	if (!existing.enabled) {
+		next.enabled = true;
+		updated.push("enabled");
+	}
+	if (input.rule.frequency !== void 0 && existing.config.frequency !== input.rule.frequency) {
+		next.config = {
+			...existing.config,
+			frequency: input.rule.frequency
+		};
+		updated.push("frequency");
+	}
+	const missing = detectorIds.filter((id) => !existing.detectorIds.includes(id));
+	if (missing.length > 0) {
+		next.detectorIds = [...existing.detectorIds, ...missing];
+		updated.push("projects");
+	}
+	const sends = existing.actionFilters.some((f) => f.actions.some((a) => sendsThrough(a, install.slug)));
+	const legacy = existing.actionFilters.some((f) => f.actions.some((a) => isLegacyAction(a, install.appId)));
+	if (legacy) for (const f of next.actionFilters) f.actions = f.actions.filter((a) => !isLegacyAction(a, install.appId));
+	if (!sends) {
+		const open = next.actionFilters.find((f) => f.conditions.length === 0);
+		if (open) open.actions.push(integrationAction(install.slug));
+		else next.actionFilters.push({
+			logicType: "all",
+			conditions: [],
+			actions: [integrationAction(install.slug)]
+		});
+	}
+	if (legacy || !sends) updated.push("action");
+	if (updated.length === 0) return {
+		created: false,
+		updated
+	};
+	await client.workflows.update(org, existing.id, next);
+	return {
+		created: false,
+		updated
+	};
+}
+/** The signing secret, if the token may see it: a new integration's answer omits it, so it is read again. */
+async function secretOf(client, app) {
+	if (app.clientSecret) return app.clientSecret;
+	return (await client.sentryApps.get(app.slug)).clientSecret || void 0;
+}
+async function ensureSentryRelay(client, org, input) {
+	if (input.projects.length === 0) throw new Error("relay needs at least one Sentry project to alert on");
+	const detectorIds = await detectorsFor(client, org, input.projects);
+	const integration = await ensureIntegration(client, org, input);
+	const install = (await client.sentryApps.installations(org)).find((i) => i.app.slug === integration.app.slug);
+	if (!install) throw new Error(`the integration \`${integration.app.name}\` is not installed on ${org}`);
+	const rule = await ensureRule(client, org, input, {
+		slug: install.app.slug,
+		appId: install.app.sentryAppId
+	}, detectorIds);
+	const clientSecret = await secretOf(client, integration.app);
+	return {
+		integration: {
+			created: integration.created,
+			updated: integration.updated
+		},
+		rule,
+		...clientSecret ? { clientSecret } : {}
+	};
+}
+/**
+* Read the integration and the alert rule back, changing nothing. The integration's signing secret is not read: the
+* list answer is used as it is and `get`, which returns the secret, is never called.
+*/
+async function inspectSentryRelay(client, org, input) {
+	const apps = await client.sentryApps.list(org);
+	const projects = await client.projects.list(org);
+	const detectors = await client.workflows.detectors(org);
+	const workflows = await client.workflows.list(org);
+	const app = apps.find((a) => a.name === input.name);
+	const rule = workflows.find((w) => w.name === input.rule.name);
+	return {
+		...app ? { integration: {
+			webhookUrl: app.webhookUrl,
+			alertAction: app.isAlertable
+		} } : {},
+		rules: rule ? input.projects.flatMap((slug) => {
+			const project = projects.find((p) => p.slug === slug);
+			const detector = project && detectors.find((d) => d.projectId === project.id && d.type === "issue_stream");
+			if (!detector || !rule.detectorIds.includes(detector.id)) return [];
+			const sends = app !== void 0 && rule.actionFilters.some((f) => f.actions.some((a) => sendsThrough(a, app.slug)));
+			return [{
+				project: slug,
+				enabled: rule.enabled,
+				sends
+			}];
+		}) : []
+	};
+}
+// src/capabilities/errors.ts
+/** The `errors` capability for Sentry: finds or creates a project and reports its DSN, and manages the Comlink relay. */
 var SentryErrors = class {
 	client;
 	opts;
+	relayClient;
+	/** The capability key, always `errors`. */
 	key = "errors";
+	/** The provider name, `sentry`. */
 	providerName = "sentry";
-	constructor(client, opts) {
+	constructor(client, opts, relayClient = client) {
 		this.client = client;
 		this.opts = opts;
+		this.relayClient = relayClient;
+	}
+	async ensureRelay(input) {
+		return ensureSentryRelay(this.relayClient(), this.requireOrg(), input);
+	}
+	async inspectRelay(input) {
+		return inspectSentryRelay(this.relayClient(), this.requireOrg(), input);
 	}
 	async describe() {
 		return {
 			provider: "sentry",
-			envKeys: ["SENTRY_DSN", "NEXT_PUBLIC_SENTRY_DSN"]
+			envKeys: ["SENTRY_DSN"],
+			frameworkEnvKeys: { next: ["NEXT_PUBLIC_SENTRY_DSN"] }
 		};
 	}
 	async whoami() {
-		return { org: (await this.client().auth.getOrg(this.requireOrg())).slug };
+		if (!this.opts.org) return null;
+		return { org: (await this.client().auth.getOrg(this.opts.org)).slug };
 	}
+	/** Returns the public DSN of the project named `input.name` (matched by its slug), creating it when missing; needs `org`, and the new project uses `team` (default the org slug) and `platform` (default `node`). */
 	async ensureProject(input) {
 		const org = this.requireOrg();
 		const slug = toSlug(input.name);
@@ -68,8 +402,401 @@ var SentryErrors = class {
 function toSlug(name) {
 	return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
-//#endregion
-//#region src/verify-token.ts
+// src/probes/probe-deps.type.ts
+function requireOrg(deps) {
+	if (!deps.org) throw new Error("the Sentry probes need `org` in the sentry provider's options");
+	return deps.org;
+}
+// src/probes/integrations.ts
+/** Where a webhook points, without a query string that could carry a token. */
+function where(url) {
+	if (!url) return "no webhook";
+	try {
+		const u = new URL(url);
+		return `${u.host}${u.pathname}`;
+	} catch {
+		return "an unreadable URL";
+	}
+}
+function integrationsProbe(deps) {
+	return {
+		summary: "List the custom integrations: scopes, alert action, webhook, and whether the client secret is visible.",
+		writes: false,
+		async run(probe) {
+			const apps = await deps.client().sentryApps.list(requireOrg(deps));
+			if (apps.length === 0) probe.say({
+				status: "info",
+				label: "no custom integrations"
+			});
+			for (const app of apps) {
+				probe.secret(app.clientSecret);
+				probe.say({
+					status: "ok",
+					label: `${app.name} (${app.slug})`,
+					detail: [
+						`scopes: ${app.scopes.join(", ") || "none"}`,
+						`alert action: ${app.isAlertable ? "on" : "off"}`,
+						`webhook: ${where(app.webhookUrl)}`,
+						`secret visible: ${app.clientSecret ? "yes" : "no"}`
+					].join(" | ")
+				});
+			}
+		}
+	};
+}
+// src/probes/rule-update.ts
+const FROM = 5;
+const TO = 10;
+/** The detector the throwaway rule hangs on: the issue stream of `HOLOCRON_SENTRY_PROBE_PROJECT`, else of any project. */
+async function detectorFor(deps, org) {
+	const client = deps.client();
+	const slug = createEnvLookup(deps.env).get("HOLOCRON_SENTRY_PROBE_PROJECT");
+	const [detectors, projects] = await Promise.all([client.workflows.detectors(org), slug ? client.projects.list(org) : Promise.resolve([])]);
+	const streams = detectors.filter((d) => d.type === "issue_stream");
+	if (slug) {
+		const project = projects.find((p) => p.slug === slug);
+		if (!project) throw new Error(`Sentry project \`${slug}\` was not found in ${org}`);
+		const own = streams.find((d) => d.projectId === project.id);
+		if (!own) throw new Error(`Sentry project \`${slug}\` has no issue stream detector`);
+		return own.id;
+	}
+	const any = streams[0];
+	if (!any) throw new Error("no project has an issue stream detector to attach a throwaway rule to");
+	return any.id;
+}
+function ruleUpdateProbe(deps) {
+	return {
+		summary: "Make a disabled throwaway alert rule, change it the way the relay's adopt path does, read it back, delete it.",
+		writes: true,
+		async run(probe) {
+			const org = requireOrg(deps);
+			const client = deps.client();
+			const detectorId = await detectorFor(deps, org);
+			const body = {
+				name: `Holocron probe: throwaway rule (${(/* @__PURE__ */ new Date()).toISOString()})`,
+				enabled: false,
+				environment: null,
+				config: { frequency: FROM },
+				detectorIds: [detectorId],
+				triggers: {
+					logicType: "any-short",
+					conditions: [{
+						type: "new_high_priority_issue",
+						comparison: true,
+						conditionResult: true
+					}]
+				},
+				actionFilters: [{
+					logicType: "all",
+					conditions: [],
+					actions: []
+				}]
+			};
+			const created = await probe.write("create a disabled throwaway alert rule", async () => {
+				const wf = await client.workflows.create(org, body);
+				probe.cleanup(`the throwaway rule ${wf.id}`, () => client.workflows.delete(org, wf.id));
+				return wf;
+			});
+			if (!created) {
+				probe.say({
+					status: "info",
+					label: `would then change its frequency ${FROM} to ${TO} with PUT, read it back, and delete it`
+				});
+				return;
+			}
+			probe.say({
+				status: "ok",
+				label: "created",
+				detail: `rule ${created.id}, disabled`
+			});
+			const next = toInput(created);
+			next.config = {
+				...created.config,
+				frequency: TO
+			};
+			await client.workflows.update(org, created.id, next);
+			probe.say({
+				status: "ok",
+				label: "PUT accepted"
+			});
+			const read = await client.workflows.get(org, created.id);
+			const kept = !read.enabled && read.detectorIds.includes(detectorId);
+			probe.say(read.config.frequency === TO && kept ? {
+				status: "ok",
+				label: "read back",
+				detail: `frequency ${read.config.frequency}, still disabled and attached`
+			} : {
+				status: "fail",
+				label: "read back differs",
+				detail: `frequency ${read.config.frequency} (sent ${TO}), enabled ${read.enabled}, detectors ${read.detectorIds.join(",")}`
+			});
+		}
+	};
+}
+// src/probes/rules.ts
+function rulesProbe(deps) {
+	return {
+		summary: "List the alert rules: enabled, projects attached, and what each action sends to.",
+		writes: false,
+		async run(probe) {
+			const org = requireOrg(deps);
+			const client = deps.client();
+			const [workflows, apps] = await Promise.all([client.workflows.list(org), client.sentryApps.list(org)]);
+			const alertable = new Set(apps.filter((a) => a.isAlertable).map((a) => a.slug));
+			if (workflows.length === 0) probe.say({
+				status: "info",
+				label: "no alert rules"
+			});
+			for (const wf of workflows) {
+				const actions = wf.actionFilters.flatMap((f) => f.actions);
+				const described = actions.map((a) => {
+					const target = String(a.config["targetIdentifier"] ?? a.config["targetType"] ?? "");
+					return target ? `${a.type} ${target}` : a.type;
+				});
+				const problems = actions.flatMap((a) => {
+					if (a.type === "sentry_app") return [`a sentry_app action shows as an unknown integration`];
+					if (a.type === "webhook" && !alertable.has(String(a.config["targetIdentifier"]))) return [`webhook ${String(a.config["targetIdentifier"])} is not an alertable integration`];
+					return [];
+				});
+				probe.say({
+					status: problems.length > 0 || !wf.enabled ? "fail" : "ok",
+					label: wf.name,
+					detail: [
+						wf.enabled ? "enabled" : "DISABLED",
+						`detectors: ${wf.detectorIds.length}`,
+						`actions: ${described.join(", ") || "none"}`,
+						...problems
+					].join(" | ")
+				});
+			}
+		}
+	};
+}
+// src/probes/send-error.ts
+/** Which DSN to send to: `HOLOCRON_SENTRY_DSN`, else `SENTRY_DSN`, else the first client key of the project named in `HOLOCRON_SENTRY_PROBE_PROJECT`. */
+async function dsnFor(deps) {
+	const env = holocronEnv(deps.env);
+	const configured = env.get("SENTRY_DSN");
+	if (configured) return configured;
+	const project = env.get("HOLOCRON_SENTRY_PROBE_PROJECT");
+	if (!project) throw new Error("set SENTRY_DSN, or HOLOCRON_SENTRY_PROBE_PROJECT to a project slug, to say where to send the error");
+	const dsn = (await deps.client().projects.keys(requireOrg(deps), project))[0]?.dsn.public;
+	if (!dsn) throw new Error(`project \`${project}\` has no client key`);
+	return dsn;
+}
+function sendErrorProbe(deps) {
+	return {
+		summary: "Send one labelled test error to a project, to follow it through the alert rule to Discord.",
+		writes: true,
+		async run(probe) {
+			const dsn = new URL(await dsnFor(deps));
+			probe.secret(dsn.username);
+			const projectId = dsn.pathname.replace(/^\/+/, "");
+			const eventId = randomUUID().replaceAll("-", "");
+			const message = `Holocron probe: sent on purpose (${(/* @__PURE__ */ new Date()).toISOString()})`;
+			const envelope = [
+				JSON.stringify({
+					event_id: eventId,
+					sent_at: (/* @__PURE__ */ new Date()).toISOString()
+				}),
+				JSON.stringify({ type: "event" }),
+				JSON.stringify({
+					event_id: eventId,
+					level: "error",
+					platform: "node",
+					environment: "holocron-probe",
+					message: { formatted: message },
+					exception: { values: [{
+						type: "HolocronProbeError",
+						value: message
+					}] },
+					tags: { probe: "sentry.send-error" }
+				})
+			].join("\n");
+			if (await probe.write("send a test error", async () => {
+				const res = await (deps.fetch ?? fetch)(`${dsn.protocol}//${dsn.host}/api/${projectId}/envelope/?sentry_version=7&sentry_key=${dsn.username}&sentry_client=holocron-probe/1`, {
+					method: "POST",
+					headers: { "content-type": "application/x-sentry-envelope" },
+					body: envelope
+				});
+				if (!res.ok) throw new Error(`Sentry answered ${res.status}`);
+				return true;
+			})) probe.say({
+				status: "ok",
+				label: "sent HolocronProbeError",
+				detail: "look for it in the project's issues and, through the rule, in #errors; resolve the issue by hand (a probe cannot delete it)"
+			});
+		}
+	};
+}
+// src/probes/index.ts
+function sentryProbes(deps) {
+	return {
+		integrations: integrationsProbe(deps),
+		rules: rulesProbe(deps),
+		"rule-update": ruleUpdateProbe(deps),
+		"send-error": sendErrorProbe(deps)
+	};
+}
+// src/probes/token/parse-token-args.ts
+/** Reads `--layer <word>` and `--token-name <VAR>` (either spelling). Anything else, and a flag with no value, is ignored. */
+function parseTokenArgs(args) {
+	let layer;
+	let tokenName;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--layer") layer = args[++i];
+		else if (arg.startsWith("--layer=")) layer = arg.slice(8);
+		else if (arg === "--token-name") tokenName = args[++i];
+		else if (arg.startsWith("--token-name=")) tokenName = arg.slice(13);
+	}
+	return {
+		...layer ? { layer } : {},
+		...tokenName ? { tokenName } : {}
+	};
+}
+// src/probes/token/token.ts
+/** How many names to show before "(+N more)". */
+const SHOWN = 5;
+/** `a, b, c (+2 more)`. */
+function summarise(names) {
+	return names.length <= SHOWN ? names.join(", ") : `${names.slice(0, SHOWN).join(", ")} (+${names.length - SHOWN} more)`;
+}
+/**
+* Reads one list and says what came back. Sentry answers a token without the scope with a 401 or 403, and an empty
+* list may only mean there are none, so an empty list is `none` too. Any other failure (the network, a 404, a 5xx) is an
+* `error`.
+*/
+async function reach(read, noun) {
+	try {
+		const items = await read();
+		if (items.length === 0) return {
+			kind: "none",
+			detail: `no ${noun} visible (none exist, or the token cannot see them)`
+		};
+		const names = items.map((i) => i.slug ?? i.name).filter((n) => typeof n === "string");
+		return {
+			kind: "has",
+			detail: names.length > 0 ? `${items.length} ${noun}: ${summarise(names)}` : `${items.length} ${noun}`
+		};
+	} catch (err) {
+		if (err instanceof ProviderApiError && (err.status === 401 || err.status === 403)) return {
+			kind: "none",
+			detail: `no access (${err.status})`
+		};
+		return {
+			kind: "error",
+			detail: errorMessage(err)
+		};
+	}
+}
+/**
+* One row for what was tried. With no rule it only describes (`ok` for access, `info` for none). Under a layer's rule it
+* judges: a required permission the token lacks fails, and one the layer must not have fails when the token has it; a
+* permission that is rightly absent is a bare `ok`.
+*/
+function rowFor({ label, outcome }, rule) {
+	if (outcome.kind === "error") return {
+		status: "fail",
+		label,
+		detail: outcome.detail
+	};
+	const has = outcome.kind === "has";
+	if (rule === "required") return has ? {
+		status: "ok",
+		label,
+		detail: outcome.detail
+	} : {
+		status: "fail",
+		label,
+		detail: outcome.detail
+	};
+	if (rule === "absent") return has ? {
+		status: "fail",
+		label,
+		detail: outcome.detail
+	} : {
+		status: "ok",
+		label
+	};
+	return {
+		status: has ? "ok" : "info",
+		label,
+		detail: outcome.detail
+	};
+}
+/**
+* The `token` probe: reads what Holocron reads from Sentry (the organizations, the projects and the alert rules) with a
+* token and reports which of them it reaches. It only reads, so it changes nothing. The token is the one the plugin
+* resolves, so `--token sentry=<token>` or `--environment <layer>` checks another one; the organization is the
+* provider's `org` option. A write scope (`project:write`, `org:write`, `alerts:write`) has no read that proves it, so it
+* is not probed.
+*
+* A token with no layer is only described. When the CLI passes `--layer` (because `--environment` named `ci`, `dev` or
+* `local`), the results are judged against what that layer's token is meant to carry (the plugin's `tokens`
+* declaration, read with `tokenExpectations()` and narrowed to the token `--token-name` names, which the CLI passes for
+* each declared token the Environment holds) and shown in two groups, what it should have and what it should not, where
+* a missing or extra permission fails.
+*/
+function tokenProbe(ctx) {
+	return {
+		summary: "Try each Sentry read Holocron uses (organizations, projects, alert rules) with a token and report which it reaches; for a ci or dev Environment, check it against what that layer should carry. Read-only.",
+		writes: false,
+		acceptsToken: true,
+		async run(probe) {
+			const { layer, tokenName } = parseTokenArgs(probe.args ?? []);
+			const token = ctx.token();
+			probe.secret(token);
+			const client = ctx.client();
+			const rules = layer ? tokenExpectations(tokens, {
+				layer,
+				...tokenName ? { envName: tokenName } : {}
+			})[0]?.rules : void 0;
+			if (layer && !rules) probe.say({
+				status: "info",
+				label: layer,
+				detail: "no expectations are declared for it, so the token is only described"
+			});
+			const tried = [{
+				label: "Organizations: Read",
+				permission: "org",
+				outcome: await reach(() => client.auth.organizations(), "organizations")
+			}];
+			const org = ctx.org;
+			if (org) {
+				tried.push({
+					label: "Projects: Read",
+					permission: "projects",
+					outcome: await reach(() => client.projects.list(org), "projects")
+				});
+				tried.push({
+					label: "Alert rules: Read",
+					permission: "alerts",
+					outcome: await reach(() => client.workflows.list(org), "alert rules")
+				});
+			} else probe.say({
+				status: rules ? "fail" : "info",
+				label: "projects and alert rules",
+				detail: "no org: set `org` in the sentry provider's options to check them"
+			});
+			if (!rules) {
+				for (const t of tried) probe.say(rowFor(t, void 0));
+				return;
+			}
+			for (const [heading, rule] of [["Should have", "required"], ["Should not have", "absent"]]) {
+				const inGroup = tried.filter((t) => rules[t.permission] === rule);
+				if (inGroup.length === 0) continue;
+				probe.say({
+					status: "heading",
+					label: heading
+				});
+				for (const t of inGroup) probe.say(rowFor(t, rule));
+			}
+		}
+	};
+}
+// src/verify-token.ts
+/** Checks a Sentry token by listing its organizations; the success subject is `org:` and the first organization's slug, the failure carries the error message. */
 async function verifyToken(token, opts = {}) {
 	const client = createSentryClient({
 		token,
@@ -84,36 +811,66 @@ async function verifyToken(token, opts = {}) {
 	} catch (err) {
 		return {
 			ok: false,
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 }
-//#endregion
-//#region src/index.ts
+// src/index.ts
+/** Creates the shared context for the given options; no token is resolved until a client is first called. */
 function createContext(options) {
 	let client;
+	let relayClient;
 	return {
 		options,
 		client: () => client ??= createSentryClient({
 			token: resolveToken(options),
 			baseUrl: options.baseUrl,
 			fetch: options.fetch
+		}),
+		relayClient: () => relayClient ??= createSentryClient({
+			token: resolveRelayToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
 		})
 	};
 }
+/** Builds the `errors` capability from a plugin context, using the relay client for the Comlink relay. */
 function errors(ctx) {
 	return new SentryErrors(ctx.client, {
 		org: ctx.options.org,
 		team: ctx.options.team
-	});
+	}, ctx.relayClient);
 }
+/** Creates the Sentry plugin: its probes, a `connection` probe and the `errors` capability. */
 function createPlugin(options) {
 	const ctx = createContext(options);
 	return {
 		name: "@theholocron/holocron-plugin-sentry",
+		probes: {
+			...sentryProbes({
+				org: options.org,
+				client: ctx.relayClient,
+				fetch: options.fetch
+			}),
+			token: tokenProbe({
+				org: options.org,
+				client: ctx.client,
+				token: () => resolveToken(options)
+			}),
+			connection: connectionProbe({
+				provider: "Sentry",
+				url: options.baseUrl ?? "https://sentry.io",
+				fetch: options.fetch,
+				token: () => resolveToken(options),
+				verify: (token) => verifyToken(token, {
+					baseUrl: options.baseUrl,
+					fetch: options.fetch
+				})
+			})
+		},
 		capabilities: { errors: () => errors(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, SentryErrors, createContext, createPlugin, createSentryClient, errors, resolveToken, verifyToken };
+/** One-line hint shown by `holocron new token sentry` when no token is given or the token is rejected. */
+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 new token sentry <TOKEN>";
+export { AUTH_HINT, AuthError, SentryErrors, createContext, createPlugin, createSentryClient, errors, resolveComlinkToken, resolveRelayToken, resolveToken, tokens, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-sentry",
-  "version": "5.0.0-alpha.44",
+  "version": "5.0.0-alpha.442",
   "description": "Holocron plugin for Sentry. Implements the errors capability against Sentry's management API — project provisioning and DSN retrieval.",
   "keywords": [
     "errors",
@@ -8,12 +8,12 @@
     "plugin",
     "sentry"
   ],
-  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-sentry#readme",
+  "homepage": "https://docs.theholocron.dev/holocron/plugins/sentry/",
   "bugs": "https://github.com/theholocron/holocron/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/theholocron/holocron.git",
-    "directory": "packages/holocron-plugin-sentry"
+    "directory": "plugins/holocron-plugin-sentry"
   },
   "license": "MIT",
   "author": "Newton Koumantzelis",
@@ -29,29 +29,34 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@theholocron/env-utils": "^1.17.0-alpha.4"
+  },
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.4.5",
-    "@theholocron/http-client": "^1.25.0",
-    "@theholocron/sentry-client": "^1.25.0",
-    "@theholocron/tsconfig": "^8.4.5",
-    "@theholocron/tsdown-config": "^8.4.5",
-    "@theholocron/vitest-config": "^8.4.5",
     "@types/node": "^26",
-    "@vitest/coverage-v8": "^4.1.11",
-    "@vitest/eslint-plugin": "^1.6.27",
-    "chalk": "^6.0.0",
-    "eslint": "^10.8.1",
-    "eslint-plugin-n": "^18.3.0",
-    "globals": "^17.11.0",
-    "tsdown": "^0.22.14",
-    "tsx": "4.23.12",
+    "@vitest/coverage-v8": "^5.1.0",
+    "@vitest/eslint-plugin": "^1.6.28",
+    "chalk": "^6.0.1",
+    "eslint": "^10.14.0",
+    "eslint-plugin-n": "^18.5.0",
+    "globals": "^17.14.0",
+    "tsdown": "^0.23.5",
+    "tsx": "4.23.15",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.44"
+    "vitest": "^5.1.0",
+    "@theholocron/cli": "5.0.0-alpha.442",
+    "@theholocron/eslint-config": "^8.9.0-alpha.17",
+    "@theholocron/http-client": "^1.58.0-alpha.32",
+    "@theholocron/misc-utils": "^1.17.0-alpha.4",
+    "@theholocron/sentry-client": "^1.58.0-alpha.32",
+    "@theholocron/tsconfig": "^8.9.0-alpha.17",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.17",
+    "@theholocron/vitest-config": "^8.9.0-alpha.17"
   },
   "peerDependencies": {
-    "@theholocron/sentry-client": "^1.25.0",
-    "@theholocron/cli": "5.0.0-alpha.44"
+    "@theholocron/misc-utils": "^1.16.0",
+    "@theholocron/sentry-client": "^1.56.0",
+    "@theholocron/cli": "5.0.0-alpha.442"
   },
   "peerDependenciesMeta": {
     "@theholocron/sentry-client": {}
@@ -63,11 +68,11 @@
     "access": "public"
   },
   "scripts": {
-    "delivery.build": "tsdown",
-    "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
+    "build": "tsdown",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest",
-    "validate": "tsx scripts/validate.mjs",
-    "verification.typeSafety": "holocron run verification.typeSafety --",
-    "verification.unitTests": "holocron run verification.unitTests --"
+    "typecheck": "tsc --noEmit",
+    "validate:plugin": "tsx scripts/validate.mjs"
   }
 }