@sentry/junior-sentry 0.101.0 → 0.102.1

package/README.md

@@ -1,6 +1,6 @@
 # @sentry/junior-sentry
 
-`@sentry/junior-sentry` adds read-only Sentry investigation workflows to Junior via per-user OAuth.
+`@sentry/junior-sentry` adds Sentry investigation workflows and explicitly requested alert/monitor creation to Junior via per-user OAuth.
 
 Install it alongside `@sentry/junior`:
 
@@ -18,15 +18,16 @@ export const plugins = defineJuniorPlugins(["@sentry/junior-sentry"]);
 
 ## Sentry CLI Surface
 
-The plugin installs the npm `sentry` package as a runtime dependency and injects the current user's OAuth token as `SENTRY_AUTH_TOKEN` for Sentry skill commands.
+The plugin installs the npm `sentry` package as a runtime dependency and injects the current user's OAuth token as `SENTRY_AUTH_TOKEN` for Sentry skill commands. The OAuth grant includes `alerts:write`; existing connections must reconnect after upgrading to grant it.
 
-As of 2026-04-30, `sentry@latest` is `0.30.0`. The verified command groups used by the bundled skill are:
+As of 2026-07-13, `sentry@latest` is `0.38.0`. The verified command groups used by the bundled skill are:
 
 - `sentry issue list|events|explain|plan|view`
 - `sentry org list|view`
 - `sentry log list|view`
 - `sentry trace list|view|logs`
-- `sentry api <endpoint>`
+- `sentry alert metrics list|view|create|edit|delete`
+- `sentry api <endpoint>` as a fallback when no first-class command covers the request
 
 The skill must verify live `sentry --help` output before declaring a Sentry data surface unavailable. Prefer singular command groups such as `sentry org list`; do not use stale forms such as `sentry organizations list`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-sentry",
-  "version": "0.101.0",
+  "version": "0.102.1",
   "private": false,
   "publishConfig": {
     "access": "public"

package/plugin.yaml

@@ -23,7 +23,7 @@ oauth:
   client-secret-env: SENTRY_CLIENT_SECRET
   authorize-endpoint: https://sentry.io/oauth/authorize/
   token-endpoint: https://sentry.io/oauth/token/
-  scope: "event:read org:read project:read team:read"
+  scope: "alerts:write event:read org:read project:read team:read"
 
 runtime-dependencies:
   - type: npm

package/skills/sentry/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sentry
-description: Query live Sentry telemetry with the Sentry CLI and generate Sentry deep links. Use when users ask to investigate Sentry issues, events, logs, traces, organizations, projects, replays, product feature usage, Sentry's own product telemetry, or authenticated Sentry API data. Do not use it for repository/source-code/PR tasks, even when the topic concerns Sentry products.
+description: Query live Sentry telemetry, create explicitly requested Sentry alerts and monitors, and generate Sentry deep links. Use when users ask to investigate Sentry issues, events, logs, traces, organizations, projects, replays, product feature usage, Sentry's own product telemetry, authenticated Sentry API data, or to create alerting. Do not use it for repository/source-code/PR tasks, even when the topic concerns Sentry products.
 allowed-tools: bash
 ---
 
@@ -18,7 +18,7 @@ Before declaring a Sentry data surface unavailable, verify the current CLI help:
 
 1. Confirm operation and target:
 
-- Determine operation: issue, event, log, trace, org, project, replay/deep-link, Sentry product feature usage, or API query.
+- Determine operation: issue, event, log, trace, org, project, replay/deep-link, Sentry product feature usage, alert/monitor creation, or API query.
 - Resolve org from channel config: `jr-rpc config get sentry.org`
 - Resolve project from channel config: `jr-rpc config get sentry.project` (optional — many queries span multiple projects).
 - If org is missing and needed, ask the user.
@@ -31,7 +31,9 @@ Before declaring a Sentry data surface unavailable, verify the current CLI help:
 - Read [references/cli-commands.md](references/cli-commands.md) when choosing command shapes, target formats, flags, API fallback, or troubleshooting behavior.
 - Read [references/sandbox-runtime.md](references/sandbox-runtime.md) before relying on sandbox credentials.
 - Prefer `--json` when parsing or summarizing results.
-- If no high-level CLI command covers the requested read-only data, use `sentry api <endpoint>` before claiming the workflow is blocked.
+- If no high-level CLI command covers the request, use `sentry api <endpoint>` before claiming the workflow is blocked.
+- Create alerts only when the user explicitly asks. Prefer `sentry alert metrics` for metric-alert list/view/create/edit/delete; before writing, resolve the exact target, check duplicates, run the complete command with `--dry-run`, then execute once and report the created rule URL.
+- Use `sentry api` only when live CLI help confirms the first-class command cannot express the requested alert behavior, such as dynamic anomaly detection.
 - If a Sentry API call returns `401`, or clearly says the token is invalid, expired, revoked, or unauthorized, rerun the real Sentry command once and let the runtime trigger a reconnect flow when needed.
 - If a Sentry API call explicitly says `missing scope`, `missing scopes`, or `insufficient scope`, rerun the real Sentry command once and let the runtime trigger a reconnect flow when needed.
 - If a Sentry API call returns a generic `403`, `permission denied`, or otherwise indicates missing org/project access without naming missing scopes, stop and tell the user the current Sentry connection could not access the requested Sentry data.
@@ -49,7 +51,7 @@ Before declaring a Sentry data surface unavailable, verify the current CLI help:
 
 ## Guardrails
 
-- Read-only operations only (MVP scope).
+- Default to read-only operations. Only create, edit, or delete alerting resources when the user explicitly requests that exact action and a documented first-class CLI command supports it. Use API fallback only for explicitly requested alert behavior that live CLI help confirms is unsupported.
 - Avoid speculative Sentry CLI subcommands. Use bundled references plus live `sentry --help` output to verify current commands.
 - Do not print credential values.
 - If org is missing and needed, ask the user.

package/skills/sentry/SOURCES.md

@@ -1,6 +1,6 @@
 # Sentry Skill Sources
 
-Last updated: 2026-06-18
+Last updated: 2026-07-13
 
 ## Source inventory
 
@@ -13,10 +13,13 @@ Last updated: 2026-06-18
 | `https://cli.sentry.dev/commands/trace/`                        | canonical  | high       | Current `sentry trace list`, `view`, and `logs` commands.                                                                                          | Verify live help when runtime CLI differs.                          |
 | `https://cli.sentry.dev/commands/api/`                          | canonical  | high       | Authenticated `sentry api <endpoint>` fallback and request flags.                                                                                  | Use read-only requests unless the user asks for mutation.           |
 | `https://cli.sentry.dev/configuration/`                         | canonical  | high       | `SENTRY_AUTH_TOKEN`, JSON/global flags, cache controls, and runtime configuration behavior.                                                        | Junior injects credentials; do not persist or print tokens.         |
-| `pnpm view sentry version dist-tags description bin repository` | canonical  | high       | Confirmed npm package `sentry` latest is `0.30.0` and exposes `sentry` binary.                                                                     | Package metadata only; command behavior still comes from help/docs. |
-| `pnpm dlx sentry@latest --help` and subcommand help             | canonical  | high       | Confirmed executable help lists org list/view, issue list/events/view, log list/view, trace list/view/logs, and api.                               | Re-run when updating for a newer CLI.                               |
+| `pnpm view sentry version dist-tags description bin repository` | canonical  | high       | Confirmed npm package `sentry` latest is `0.38.0` and exposes the `sentry` binary.                                                                   | Package metadata only; command behavior still comes from help/docs. |
+| `pnpm dlx sentry@latest --help` and subcommand help             | canonical  | high       | Confirmed `alert metrics list|view|create|edit|delete`, including triggers and dry-run, plus the existing investigation commands.                   | Re-run when updating for a newer CLI.                               |
 | `packages/junior-sentry/plugin.yaml`                            | canonical  | high       | Confirms runtime dependency is the npm `sentry` package and auth token env is `SENTRY_AUTH_TOKEN`.                                                 | Local repo contract.                                                |
 | `https://github.com/getsentry/junior/issues/615`                | canonical  | high       | Regression report: Sentry product feature usage routed to Hex, then an explicit "use Sentry telemetry" redirect was ignored after Hex auth paused. | Use as routing evidence, not as command reference.                  |
+| `https://docs.sentry.io/api/monitors/create-a-monitor-for-a-project/` | canonical | high | Current public monitor creation endpoint, payload fields, and metric monitor examples. | Alerting API may evolve; verify live docs before writes. |
+| `https://docs.sentry.io/api/monitors/create-an-alert-for-an-organization/` | canonical | high | Current public alert workflow endpoint, connection fields, conditions, and actions. | Resolve integration and target IDs; never guess action identifiers. |
+| `getsentry/sentry` workflow engine endpoint and frontend form sources | canonical | high | Confirms `alerts:write`, `detectors`/`workflows` paths, dynamic anomaly payload shape, and legacy alert-rule deprecation. | Source-backed implementation detail; public API docs remain the user-facing contract. |
 
 ## Decisions
 
@@ -29,12 +32,15 @@ Last updated: 2026-06-18
 | Treat Sentry product feature usage and explicit Sentry telemetry redirects as Sentry skill triggers. | adopted  | Issue 615 showed the previous trigger language under-specified product-introspection queries and let Hex win. |
 | Preserve stale plural subcommands as recommended forms.                                              | rejected | `organizations list` was the root failure; aliases should not be taught as canonical command shapes.          |
 | Create a broad new troubleshooting reference.                                                        | deferred | Current failure modes fit in the focused CLI reference without crowding `SKILL.md`.                           |
+| Permit explicitly requested alert/monitor writes only.                                               | adopted  | `alerts:write` is intentionally narrow; unrelated Sentry mutations remain out of scope.                       |
+| Prefer first-class `sentry alert metrics` commands.                                                    | adopted  | CLI `0.38.0` supports list, view, create, edit, delete, triggers, and dry-run.                                 |
+| Keep API fallback for dynamic anomaly detection.                                                       | adopted  | The current CLI create flags expose threshold triggers but no dynamic/anomaly configuration.                  |
 
 ## Coverage matrix
 
 | Dimension                          | Coverage status | Evidence                                                                                                                                                                                                 |
 | ---------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| API surface and behavior contracts | complete        | `cli-commands.md` covers issue, org, log, trace, and API command shapes plus live help verification.                                                                                                     |
+| API surface and behavior contracts | complete        | `cli-commands.md` covers issue, org, log, trace, first-class metric-alert commands, and API fallback plus live help verification.                                                                        |
 | Config/runtime options             | complete        | `sandbox-runtime.md`, `plugin.yaml`, and CLI configuration docs cover injected auth and runtime package installation.                                                                                    |
 | Common use cases                   | complete        | `cli-commands.md` maps org listing, issue search/view/events, logs, traces, trace logs, and API fallback.                                                                                                |
 | Product telemetry routing          | documented      | `SKILL.md` and `SPEC.md` cover Sentry product feature usage and explicit "Sentry telemetry" redirects after an unrelated auth pause. A dedicated eval should wait for the eval harness boundary cleanup. |
@@ -43,9 +49,10 @@ Last updated: 2026-06-18
 
 ## Open gaps
 
-- Review the Sentry CLI docs and rerun `pnpm dlx sentry@latest --help` when the plugin pins or upgrades beyond npm `sentry@0.30.0`.
+- Review the Sentry CLI docs and rerun `pnpm dlx sentry@latest --help` when the plugin pins or upgrades beyond npm `sentry@0.38.0`.
 
 ## Changelog
 
+- 2026-07-13: Added CLI-first `sentry alert metrics` guidance, explicit-write and duplicate safeguards, API fallback for unsupported anomaly configuration, and `alerts:write` scope behavior.
 - 2026-06-18: Expanded trigger language for Sentry product telemetry and feature usage, and recorded issue 615 routing evidence.
 - 2026-04-30: Reconciled skill guidance with Sentry CLI `0.30.0`, replaced stale plural command forms, added live-help verification, expanded log/trace/API guidance, updated eval smoke artifacts, and added an org-list command-selection eval.

package/skills/sentry/SPEC.md

@@ -2,8 +2,8 @@
 
 ## Intent
 
-The Sentry skill helps agents investigate live Sentry telemetry through the Sentry CLI using per-user credentials injected by Junior.
-It should produce useful read-only investigation results or Sentry web links without exposing credentials.
+The Sentry skill helps agents investigate live Sentry telemetry and create explicitly requested alerts and monitors through the Sentry CLI using per-user credentials injected by Junior.
+It should produce useful investigation results, safe alerting mutations, or Sentry web links without exposing credentials.
 
 ## Scope
 
@@ -11,37 +11,39 @@ In scope:
 
 - Listing and viewing Sentry issues, issue events, logs, traces, organizations, and related read-only data.
 - Investigating Sentry's own product telemetry and product feature usage through Sentry CLI/API data surfaces.
-- Using `sentry api <endpoint>` for authenticated read-only requests when no high-level command exists.
+- Using `sentry api <endpoint>` for authenticated requests when no high-level command exists.
+- Creating explicitly requested metric alerts through `sentry alert metrics` after duplicate checks and dry-run validation, with API fallback only for unsupported alert behavior.
 - Generating Sentry deep links for user-scoped or entity-specific views.
 - Diagnosing auth, scope, and access failures without guessing missing scopes.
 
 Out of scope:
 
 - Repository, code search, commit, branch, and pull-request work.
-- Mutating Sentry data unless the user explicitly asks for a write action.
+- Mutating Sentry data outside explicitly requested alert or monitor operations.
 - Persisting, printing, or transforming Sentry credentials.
 
 ## Users And Trigger Context
 
 - Primary users: Junior users asking Slack or harness agents to investigate Sentry data.
-- Common user requests: "list my Sentry issues", "show error logs", "inspect this trace", "which orgs can I access", "open the issue in Sentry", "use Sentry telemetry", and "how much is this Sentry feature used".
+- Common user requests: "list my Sentry issues", "show error logs", "inspect this trace", "which orgs can I access", "open the issue in Sentry", "use Sentry telemetry", "create a metric alert", and "notify this channel when this monitor fires".
 - Should not trigger for: source-code tasks, GitHub PRs, repository searches, or generic questions about Sentry SDK implementation.
 
 ## Runtime Contract
 
 - Required first actions: classify the Sentry operation, resolve configured org/project when needed, and verify current CLI help before blocking on an unknown command.
-- Required outputs: concise findings, relevant Sentry URLs or deep links, and clear access/auth failure messages.
-- Non-negotiable constraints: do not print credentials; prefer read-only commands; use canonical current CLI command groups; use `sentry api` before claiming a read-only surface is unavailable.
+- Required outputs: concise findings, relevant Sentry URLs or deep links, created alerting resource URLs, and clear access/auth failure messages.
+- Non-negotiable constraints: do not print credentials; default to read-only commands; only perform explicitly requested alerting mutations; check duplicates and dry-run before writing; use canonical current CLI command groups; use `sentry api` before claiming a surface is unavailable.
 - Expected bundled files loaded at runtime: `references/cli-commands.md`, `references/deep-link-patterns.md`, and `references/sandbox-runtime.md`.
 
 ## Current CLI Data
 
-- Verified date: 2026-04-30.
-- Verified npm package: `sentry@0.30.0`, installed from the plugin `runtime-dependencies` entry.
+- Verified date: 2026-07-13.
+- Verified npm package: `sentry@0.38.0`, installed from the plugin `runtime-dependencies` entry.
 - Auth model: Junior injects `SENTRY_AUTH_TOKEN` for authenticated Sentry commands during the requesting user's turn.
-- Canonical command groups: `sentry issue`, `sentry org`, `sentry log`, `sentry trace`, and `sentry api`.
+- Canonical command groups: `sentry issue`, `sentry org`, `sentry log`, `sentry trace`, `sentry alert metrics`, and `sentry api`.
 - Required migration rule: prefer singular command groups such as `sentry org list`; do not teach stale plural command forms such as `sentry organizations list`.
-- Required fallback rule: use `sentry api <endpoint>` for read-only data when no high-level CLI command covers the requested surface.
+- Required fallback rule: use `sentry api <endpoint>` when no high-level CLI command covers the requested surface.
+- Alerting write rule: prefer `sentry alert metrics`; use the API fallback only when live CLI help confirms the requested behavior is unsupported.
 
 ## Source And Evidence Model
 
@@ -77,9 +79,9 @@ Data that must not be stored:
 ## Evaluation
 
 - Lightweight validation: run skill validation and grep for stale command forms after CLI updates.
-- Deeper evaluation: add Slack/harness evals for org listing, issue search, log search, trace lookup, API fallback, and auth recovery.
+- Deeper evaluation: add Slack/harness evals for org listing, issue search, log search, trace lookup, API fallback, auth recovery, explicit alert creation, duplicate prevention, and refusal of unrelated mutations.
 - Holdout examples: requests that mention "organizations list", "orgs", "logs for this trace", and "use the API".
-- Acceptance gates: command guidance matches latest CLI help, stale plural forms are not canonical, read-only fallback is available, and credential handling remains private.
+- Acceptance gates: command guidance matches latest CLI help, stale plural forms are not canonical, read-only fallback is available, alerting writes require explicit intent plus duplicate and dry-run checks, unrelated mutations remain blocked, and credential handling remains private.
 
 ## Known Limitations
 

package/skills/sentry/references/cli-commands.md

@@ -11,7 +11,7 @@ The npm `sentry` package is intentionally installed at runtime from the plugin m
 2. Do not use stale plural subcommands such as `sentry organizations list`.
 3. If a command errors as unknown, run `sentry --help` and the nearest subcommand help before declaring the surface unavailable.
 4. Prefer `--json` and, when useful, `--fields` for structured parsing.
-5. Use `sentry api <endpoint>` for authenticated read-only API calls when a high-level command does not cover the requested data.
+5. Use `sentry api <endpoint>` for authenticated API calls when a high-level command does not cover the request. Default to `GET`; only perform documented alert or monitor mutations when explicitly requested.
 
 ## Issue commands
 
@@ -78,16 +78,53 @@ sentry trace list [ORG/PROJECT|PROJECT] [--query QUERY] [--period PERIOD] [--sor
 Use `sentry trace view [ORG/PROJECT/]TRACE_ID` for trace details.
 Use `sentry trace logs [ORG/]TRACE_ID` when the user asks for logs associated with a trace.
 
+## Metric alert commands
+
+Use the first-class CLI surface for metric alerts:
+
+```bash
+sentry alert metrics list ORG/ [--query NAME] [--fresh] [--json]
+sentry alert metrics view ORG/RULE_ID_OR_NAME [--json]
+sentry alert metrics create ORG --name NAME --query QUERY --aggregate AGGREGATE \
+  --dataset DATASET --time-window MINUTES --trigger TRIGGER_JSON \
+  [--project PROJECT]... [--environment ENVIRONMENT] [--owner OWNER] [--dry-run] [--json]
+sentry alert metrics edit ORG/RULE_ID_OR_NAME [OPTIONS]
+sentry alert metrics delete ORG/RULE_ID_OR_NAME [--dry-run]
+```
+
+Before creating a rule:
+
+- Run `sentry alert metrics create --help` and treat live help as authoritative.
+- Resolve the exact org, project, owner, integration, and notification target IDs.
+- List existing rules and stop on a likely duplicate unless the user explicitly asks for another.
+- Run the complete create command with `--dry-run`, then execute it once without `--dry-run`.
+- Pass each trigger as JSON with `--trigger`; do not guess action IDs or target identifiers.
+
+Example static error-volume rule:
+
+```bash
+sentry alert metrics create ORG \
+  --name 'Non-Zod error spike' \
+  --query '!error.type:ZodError' \
+  --aggregate 'count()' \
+  --dataset errors \
+  --time-window 60 \
+  --project PROJECT \
+  --environment production \
+  --owner 'team:TEAM_ID' \
+  --trigger '{"alertThreshold":50,"actions":[...]}' \
+  --dry-run
+```
+
+The current CLI create command exposes threshold triggers but no dynamic/anomaly detection flags. If the user explicitly needs anomaly detection, verify live CLI help first; when still unsupported, use `sentry api` with the current public monitor/alert API rather than inventing CLI flags.
+
 ## API fallback
 
 ```bash
 sentry api ENDPOINT [--method METHOD] [--field KEY=VALUE] [--data JSON] [--json]
 ```
 
-- `ENDPOINT` is relative to `/api/0/`, for example `organizations/` or `issues/123456789/`.
-- Use read-only `GET` requests by default.
-- Do not use API write methods unless the user explicitly asks for a mutating Sentry action.
-- Use `--dry-run` when verifying a complex endpoint or request body.
+Use `sentry api` only when no first-class CLI command covers the requested operation. Default to read-only `GET` requests. For an explicitly requested alerting write, validate with `--dry-run` and verify the current API schema before executing. Do not mutate unrelated Sentry resources.
 
 ## Common flags
 
@@ -109,6 +146,8 @@ sentry api ENDPOINT [--method METHOD] [--field KEY=VALUE] [--data JSON] [--json]
 | "Inspect a trace"                                     | `sentry trace view ORG/PROJECT/TRACE_ID --json`                     |
 | "Show logs for a trace"                               | `sentry trace logs ORG/TRACE_ID --json`                             |
 | "Call an endpoint not covered by high-level commands" | `sentry api organizations/ --json`                                  |
+| "Create a static metric alert"                       | `sentry alert metrics create ... --dry-run`, then execute           |
+| "Create a dynamic anomaly alert"                     | Verify CLI help; use API fallback only if still unsupported         |
 
 ## Troubleshooting
 
@@ -124,5 +163,8 @@ sentry api ENDPOINT [--method METHOD] [--field KEY=VALUE] [--data JSON] [--json]
 | API returns `401` or invalid/expired/revoked token text             | Stale or missing credential                | Rerun the real command once so the runtime can trigger reconnect.                             |
 | API returns explicit missing scope text                             | OAuth grant lacks a named scope            | Rerun the real command once so the runtime can trigger reconnect.                             |
 | API returns generic `403` or permission denied                      | Connected account lacks org/project access | Stop and tell the user the current connection cannot access the requested data.               |
+| Alert write returns an explicit missing-scope error                  | OAuth grant predates alert writes         | Rerun once to trigger reconnect; the connection needs `alerts:write`.                          |
+| Static metric alert requested                                       | First-class CLI command is available       | Use `sentry alert metrics create`; do not drop directly to `sentry api`.                        |
+| Dynamic/anomaly alert flags are unavailable                         | CLI coverage gap                          | Verify live help, then use the current API fallback if needed.                                 |
 
 Use these command shapes during normal skill execution, but treat live CLI help as the final source when this reference and the installed CLI disagree.