@sentry/junior-sentry 0.31.0 → 0.32.0

package/README.md

@@ -1,6 +1,6 @@
 # @sentry/junior-sentry
 
-`@sentry/junior-sentry` adds Sentry issue workflows to Junior via per-user OAuth.
+`@sentry/junior-sentry` adds read-only Sentry investigation workflows to Junior via per-user OAuth.
 
 Install it alongside `@sentry/junior`:
 
@@ -8,4 +8,18 @@ Install it alongside `@sentry/junior`:
 pnpm add @sentry/junior @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.
+
+As of 2026-04-30, `sentry@latest` is `0.30.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>`
+
+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`.
+
 Full setup guide: https://junior.sentry.dev/extend/sentry-plugin/

package/package.json

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

package/skills/sentry/SKILL.md

@@ -1,18 +1,24 @@
 ---
 name: sentry
-description: Query live Sentry telemetry (issues, events, replays, traces) and generate deep links scoped to users or timeframes. Use this skill when users ask to investigate live Sentry data, search errors, find replays, inspect traces, or look up Sentry issues/events. Do not use it for repository/source-code/PR tasks, even when the topic concerns Sentry products.
+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, or authenticated Sentry API data. Do not use it for repository/source-code/PR tasks, even when the topic concerns Sentry products.
 allowed-tools: bash
 ---
 
 # Sentry Operations
 
-Use this skill for Sentry investigation workflows in the harness.
+Use this skill for live Sentry investigation workflows in the harness.
+
+Before declaring a Sentry data surface unavailable, verify the current CLI help:
+
+- Run `sentry --help` for top-level command groups.
+- Run `sentry <command> --help` or `sentry help <command>` before using a command shape from memory.
+- If a remembered plural command fails, check for the current singular command group before blocking. Prefer canonical forms such as `sentry issue list`, `sentry org list`, `sentry log list`, and `sentry trace list`.
 
 ## Workflow
 
 1. Confirm operation and target:
 
-- Determine operation: `issue list`, `deep-link`, or general query.
+- Determine operation: issue, event, log, trace, org, project, replay/deep-link, 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.
@@ -21,8 +27,10 @@ Use this skill for Sentry investigation workflows in the harness.
 
 - Use `sentry <command>` for structured queries.
 - The runtime injects `SENTRY_AUTH_TOKEN` automatically for authenticated `sentry` CLI commands in this skill.
-- Read [references/cli-commands.md](references/cli-commands.md) for command shapes and flags.
+- 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 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.
@@ -41,7 +49,7 @@ Use this skill for Sentry investigation workflows in the harness.
 ## Guardrails
 
 - Read-only operations only (MVP scope).
-- Avoid speculative or experimental Sentry CLI subcommands that are not listed in the bundled references.
+- 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.
 - Prefer deep links over raw data dumps when linking to Sentry web UI.

package/skills/sentry/SOURCES.md

@@ -0,0 +1,48 @@
+# Sentry Skill Sources
+
+Last updated: 2026-04-30
+
+## Source inventory
+
+| Source                                                          | Trust tier | Confidence | Contribution                                                                                                          | Usage constraints                                                   |
+| --------------------------------------------------------------- | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `https://github.com/getsentry/junior/issues/271`                | canonical  | high       | Regression report: Junior tried stale `sentry organizations list` and should verify current CLI help before blocking. | Use as issue context, not as a full command reference.              |
+| `https://cli.sentry.dev/commands/issue/`                        | canonical  | high       | Current `sentry issue list`, target syntax, issue subcommands, and JSON support.                                      | Verify live help when runtime CLI differs.                          |
+| `https://cli.sentry.dev/commands/org/`                          | canonical  | high       | Current `sentry org list` and `sentry org view` commands.                                                             | Verify live help when runtime CLI differs.                          |
+| `https://cli.sentry.dev/commands/log/`                          | canonical  | high       | Current `sentry log list` and `sentry log view` commands, trace filtering, and log query flags.                       | Verify live help when runtime CLI differs.                          |
+| `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.                               |
+| `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.                                                |
+| `packages/junior/src/chat/sandbox/eval-sentry-stub.ts`          | canonical  | medium     | Eval-only shim needed to avoid preserving stale command forms in tests.                                               | Not a production CLI source.                                        |
+
+## Decisions
+
+| Decision                                                   | Status   | Rationale                                                                                               |
+| ---------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| Use singular canonical command groups in runtime guidance. | adopted  | Current docs and latest executable help use `issue`, `org`, `log`, and `trace`.                         |
+| Add a live-help verification gate before blocking.         | adopted  | Issue 271 showed a stale remembered command produced a false blocked answer.                            |
+| Keep `sentry api <endpoint>` as a read-only fallback.      | adopted  | Current CLI exposes an authenticated API escape hatch for resources not covered by high-level commands. |
+| Prefer `--json` and optional `--fields` for parsing.       | adopted  | Current CLI supports machine-readable output across command groups.                                     |
+| 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`.                     |
+
+## 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.                                  |
+| 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.                             |
+| Known issues/workarounds           | complete        | `cli-commands.md` troubleshooting covers stale plural commands, target syntax, JSON parsing, cache, auth, scope, and access failures. |
+| Version/migration variance         | complete        | The skill now treats live CLI help as final when references and installed CLI disagree.                                               |
+
+## 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`.
+
+## Changelog
+
+- 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

@@ -0,0 +1,95 @@
+# Sentry Skill Specification
+
+## 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.
+
+## Scope
+
+In scope:
+
+- Listing and viewing Sentry issues, issue events, logs, traces, organizations, and related read-only data.
+- Using `sentry api <endpoint>` for authenticated read-only requests when no high-level command exists.
+- 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.
+- 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".
+- 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.
+- 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.
+- 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`.
+- 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.
+
+## Source And Evidence Model
+
+Authoritative sources:
+
+- Current Sentry CLI docs and live `sentry --help` output.
+- The Sentry plugin manifest and Junior runtime contracts.
+- GitHub issues or PRs that document observed skill failures.
+
+Useful improvement sources:
+
+- positive examples: successful Sentry investigations with exact command choices.
+- negative examples: false blocked answers, stale CLI command forms, or incorrect auth/scope recovery.
+- commit logs/changelogs: Sentry CLI command migrations and Junior plugin runtime changes.
+- issue or PR feedback: reports like issue 271.
+- eval results: targeted Slack/harness evals for command selection and credential injection.
+
+Data that must not be stored:
+
+- secrets
+- customer data
+- private Sentry URLs or identifiers that are not needed for reproduction
+
+## Reference Architecture
+
+- `SKILL.md` contains activation, workflow routing, and non-negotiable guardrails.
+- `SOURCES.md` contains provenance, decisions, coverage, gaps, and changelog.
+- `references/cli-commands.md` contains command selection, flags, use cases, and troubleshooting.
+- `references/deep-link-patterns.md` contains URL templates and link-generation rules.
+- `references/sandbox-runtime.md` contains harness runtime and credential injection guidance.
+- `references/evidence/`, `scripts/`, and `assets/` are currently unused.
+
+## 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.
+- 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.
+
+## Known Limitations
+
+- The skill depends on the runtime-installed npm `sentry` package, which may change independently of this repository.
+- The eval shim is intentionally narrow and is not a full Sentry CLI replacement.
+- Some live Sentry requests require org/project context or product access that the current user may not have.
+
+## Maintenance Notes
+
+- When to update `SKILL.md`: trigger language, workflow order, or global guardrails change.
+- When to update `SOURCES.md`: command surfaces, docs, issue evidence, or runtime dependency behavior changes.
+- When to update `README.md` and this `SPEC.md`: verified Sentry CLI version, canonical command groups, or migration/fallback rules change.
+- When to update `references/cli-commands.md`: any Sentry CLI command, flag, target syntax, or fallback behavior changes.
+- When to update `references/evidence/`: store durable examples of repeated false positives, false blocks, or corrected investigations.

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

@@ -1,35 +1,128 @@
 # Sentry CLI Command Reference
 
+Open this file when selecting a Sentry CLI command, checking target syntax, or diagnosing an unknown-command failure.
+
 All commands use `sentry` and read `SENTRY_AUTH_TOKEN` from environment.
+The npm `sentry` package is intentionally installed at runtime from the plugin manifest, so verify live help before blocking on a missing command.
+
+## Command selection rules
+
+1. Prefer current canonical singular command groups: `issue`, `org`, `log`, `trace`, and `api`.
+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.
 
 ## Issue commands
 
 ### List issues
 
 ```bash
-sentry issues list --org ORG [--project PROJECT] [--query QUERY] [--json]
+sentry issue list [ORG/PROJECT|ORG/|PROJECT] [--query QUERY] [--period PERIOD] [--sort SORT] [--limit N] [--json]
 ```
 
-- `--org`: Organization slug (required).
-- `--project`: Project slug (optional, omit for org-wide).
+- `ORG/PROJECT`: Explicit organization and project.
+- `ORG/`: All projects in an organization. The trailing slash is significant.
+- `PROJECT`: Search for a project by name across accessible organizations.
 - `--query`: Sentry search query (e.g., `user.email:alice@example.com`, `is:unresolved`).
+- `--period`: Time range such as `24h`, `7d`, or an absolute range.
+- `--sort`: `date`, `new`, `freq`, or `user`.
+- `--limit`: Maximum result count.
 - `--json`: Output as JSON for structured parsing.
 
+Use `sentry issue view ISSUE`, `sentry issue events ISSUE`, `sentry issue explain ISSUE`, or `sentry issue plan ISSUE` when the user asks for a specific issue, its events, root cause, or a fix plan.
+
 ## Organization commands
 
 ### List organizations
 
 ```bash
-sentry organizations list [--json]
+sentry org list [--limit N] [--json]
 ```
 
 Lists organizations accessible with current token.
 
+### View organization
+
+```bash
+sentry org view ORG [--json]
+```
+
+Views one organization.
+
+## Log commands
+
+### List logs
+
+```bash
+sentry log list [ORG/PROJECT|PROJECT|TRACE_ID|ORG/TRACE_ID] [--query QUERY] [--period PERIOD] [--limit N] [--json]
+```
+
+- `ORG/PROJECT`: Explicit project target.
+- `PROJECT`: Search for a project by name.
+- `TRACE_ID` or `ORG/TRACE_ID`: Filter logs by trace.
+- `--query`: Filter query such as `level:error` or `project:[frontend,backend]`.
+- `--period`: Time range.
+- `--limit`: Maximum result count.
+
+Use `sentry log view [ORG/PROJECT] LOG_ID...` after `log list` returns IDs.
+
+## Trace commands
+
+### List traces
+
+```bash
+sentry trace list [ORG/PROJECT|PROJECT] [--query QUERY] [--period PERIOD] [--sort SORT] [--limit N] [--json]
+```
+
+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.
+
+## 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.
+
 ## Common flags
 
 - `--json`: Structured JSON output (preferred for parsing).
-- `--org ORG`: Organization slug.
-- `--project PROJECT`: Project slug.
-- `--log-level`: `debug`, `info`, `warn`, `error`.
+- `--fields`: Comma-separated JSON fields to include.
+- `--fresh`: Bypass local CLI caches and re-detect projects.
+- `--log-level`: `error`, `warn`, `log`, `info`, `debug`, or `trace`.
+
+## Common use cases
+
+| User request                                          | Command pattern                                                     |
+| ----------------------------------------------------- | ------------------------------------------------------------------- |
+| "List my orgs"                                        | `sentry org list --json`                                            |
+| "Show issues in frontend"                             | `sentry issue list ORG/frontend --json`                             |
+| "Show unresolved errors across the org"               | `sentry issue list ORG/ --query "is:unresolved level:error" --json` |
+| "Inspect this issue"                                  | `sentry issue view ISSUE --json`                                    |
+| "Show events for this issue"                          | `sentry issue events ISSUE --json`                                  |
+| "Find error logs"                                     | `sentry log list ORG/PROJECT --query "level:error" --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`                                  |
+
+## Troubleshooting
+
+| Symptom                                                             | Likely cause                               | Remedy                                                                                        |
+| ------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `organizations list` is unavailable                                 | Stale plural command shape                 | Use `sentry org list`; verify with `sentry org list --help`.                                  |
+| `issues list --org ORG` is unavailable                              | Stale flag-based command shape             | Use `sentry issue list ORG/` for org-wide or `sentry issue list ORG/PROJECT` for one project. |
+| Bare org slug returns project-search behavior                       | Missing org-wide trailing slash            | Use `ORG/` for all projects in an org.                                                        |
+| Command group is not remembered                                     | CLI surface may have changed               | Run `sentry --help`, then `sentry <group> --help`.                                            |
+| High-level command does not expose the requested read-only resource | CLI command coverage gap                   | Use `sentry api <endpoint>` with a read-only endpoint.                                        |
+| Result parsing is brittle                                           | Human table output                         | Add `--json`, and optionally `--fields`.                                                      |
+| Results look stale or target detection is wrong                     | Local CLI cache or auto-detection          | Add `--fresh` or pass an explicit `ORG/PROJECT` target.                                       |
+| 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.               |
 
-Only use commands listed in this reference during normal skill execution. If a command reports expired, revoked, or invalid authorization, reconnect the Sentry account and retry. Treat generic permission or org/project access errors as access problems rather than reconnect signals.
+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.