Skip to content

refactor(cli): remove remaining zod usage, migrate to valibot - #1389

Merged
BYK merged 3 commits into
mainfrom
issue-1371-remove-zod-full
Aug 7, 2026
Merged

refactor(cli): remove remaining zod usage, migrate to valibot#1389
BYK merged 3 commits into
mainfrom
issue-1371-remove-zod-full

Conversation

@jared-outpost

@jared-outpost jared-outpost Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

finishes the zod→valibot migration from #1370/#1388 and drops the zod dependency entirely. covers all three coupling categories in #1371 plus the ~13 self-contained schema files that were still on zod.

what changed

  • @sentry/api/zod@sentry/api/valibot (types/sentry.ts, types/feedback.ts): switched to the v*-prefixed SDK schemas and reworked the .pick/.partial/.shape/.element derivations. valibot has no .extend, so extensions are composed via object({ ...Base.entries, ... }).
  • central response validator (lib/api/infrastructure.ts + lib/api/logs.ts): z.ZodType<T>GenericSchema<unknown, T>, schema.safeParse(x)safeParse(schema, x), result.data/result.error.issuesresult.output/result.issues. the Sentry telemetry context key is renamed zod_validationschema_validation (⚠️ see note below).
  • zod-internals introspection (lib/formatters/output.ts): extractSchemaFields/zodTypeToString read zod's _def.typeName/.shape; rewritten against valibot's runtime shape (.entries/.wrapped/.options + getDescription()), including pipe/coercion type resolution and descriptions nested under wrapper schemas.
  • migrated the remaining self-contained z.object schemas (types/conversation, dashboard, replay, seer; lib/api/proguard, code-mappings, chunk-upload, dart-symbols, debug-files, preprod-artifacts, conversations, dashboards), commands/code-mappings/upload.ts, and the affected test suites' schema API usage.
  • dropped zod from packages/cli/package.json + refreshed the lockfile.

testing

  • tsc --noEmit: clean
  • biome check ./src ./test: clean (933 files)
  • generated skill docs regenerate unchanged — confirms the introspection rewrite is output-identical to the zod version
  • full test/lib, test/types, test/commands suites pass (1800+ tests)

notes for reviewers

  • telemetry key rename zod_validationschema_validation in Sentry setContext — if any dashboards/alerts key off zod_validation, they'll need updating.
  • @sentry/api zod peer: @sentry/api@0.256.0 still declares an optional zod: ^3.24.0 peer. with the CLI's direct zod dep removed, transitive zod (from AI SDKs) floats to v4, so pnpm prints a benign unmet-optional-peer warning. install and --frozen-lockfile both succeed; our usage goes through the valibot entrypoint so zod isn't needed at runtime.
  • caught + fixed two migration regressions during self-review via the generated-docs oracle: a dropped nullable on AIConversationDetailsSchema.title, and ReplayViewOutputSchema accidentally spreading the list-item base instead of the details schema (dropping clicks/replay_type).

Closes #1371

Completes the zod→valibot migration started in #1370/#1388 and drops the
`zod` dependency entirely.

Migrated the three coupling categories from #1371:
- `@sentry/api/zod` schemas in types/sentry.ts, types/feedback.ts →
  `@sentry/api/valibot` (v*-prefixed), reworking the .pick/.partial/.shape
  derivations (valibot has no .extend — composed via object spread).
- Central response validator in lib/api/infrastructure.ts + lib/api/logs.ts:
  z.ZodType → GenericSchema, schema.safeParse → safeParse(schema, data),
  result.error.issues → result.issues. Sentry telemetry context renamed
  zod_validation → schema_validation.
- Zod-internals introspection in lib/formatters/output.ts rewritten for
  valibot's runtime shape (.entries/.wrapped/.options + getDescription),
  incl. pipe/coercion type resolution and nested-wrapper descriptions.

Also migrated the ~13 self-contained z.object schema files (types/*,
lib/api/*), commands/code-mappings/upload.ts, and the test suites' schema
API usage.

Verified: tsc clean, biome clean, generated skill docs regenerate
unchanged (introspection parity), full lib/types/commands test suites pass.

Closes #1371
Comment thread packages/cli/src/lib/api/logs.ts
@BYK
BYK marked this pull request as ready for review August 7, 2026 16:43
@github-actions github-actions Bot added the risk: high PR risk score: high label Aug 7, 2026

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 0108cd2. Configure here.

Comment thread packages/cli/src/lib/api/infrastructure.ts
Comment thread packages/cli/src/lib/api/infrastructure.ts
@BYK BYK added the jared Trigger the Jared agent to work on stuff label Aug 7, 2026
@jared-outpost

jared-outpost Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

pushed d03fdb6 — addresses both Warden and Cursor Bugbot findings on the telemetry path: valibot issues are now stripped to {path: [{key, type}], type, message} before Sentry.setContext, so no raw input/value from API responses is attached (in both infrastructure.ts and logs.ts). ci is re-running on the new commit.

holding off on enabling auto-merge myself since this is a large risk: high change touching telemetry and there's no approving review yet — happy to flip it on if you want, or you can merge once ci is green.

@BYK
BYK merged commit f271278 into main Aug 7, 2026
30 of 31 checks passed
@BYK
BYK deleted the issue-1371-remove-zod-full branch August 7, 2026 23:34
BYK pushed a commit that referenced this pull request Aug 11, 2026
…ons, dataset list (#1400)

## Documentation Audit Report (2026-08-10)

Weekly automated audit of the Sentry CLI repository comparing
documentation against implementation.

---

## Changes in This PR

### 1. AGENTS.md — Zod → Valibot migration drift (HIGH IMPACT)

PR #1389 (merged 2026-08-07) removed all remaining Zod usage and
migrated to Valibot. However, AGENTS.md was not updated, leaving AI
agents with incorrect guidance that would produce non-compiling code.

**Fixed:**
- Renamed "Zod Schemas for Validation" → "Valibot Schemas for
Validation"
- Rewrote code examples to use the Valibot API (`object`, `string`,
`optional`, `InferOutput`, `safeParse`)
- Fixed import example from `import { z } from "zod"` → `import {
object, string, optional } from "valibot"`
- Fixed stale import path `../../lib/config.js` → `../../lib/db/auth.js`
for `getAuthToken`
- Updated architecture description ("TypeScript types and Zod schemas" →
"Valibot schemas")
- Updated "No Runtime Dependencies" rule ("redundant Zod schemas" →
"redundant Valibot schemas")

### 2. Version pin examples — 0.40.0 → 0.42.2

The latest release is 0.42.2 (three minor versions ahead of the
documented pin).

**Fixed in:**
- `apps/cli-docs/src/content/docs/getting-started.mdx` —
`SENTRY_VERSION=0.40.0` → `0.42.2`
- `packages/cli/install` — help text and examples updated from `0.40.0`
→ `0.42.2`

### 3. agent-guidance.md — Stale dashboard dataset list

The documented dataset list used internal API names (`tracemetrics`,
`error-events`) instead of user-facing aliases. Also missing
`transactions` alias.

**Fixed:** Updated to show user-facing names: `spans` (default),
`errors`, `transactions`, `metrics`, `issue`, `logs`.

---

## Full Gap Report

### A. Undocumented or missing commands/subcommands

**No gaps.** All commands in `src/commands/` have corresponding doc
fragments in `apps/cli-docs/src/fragments/commands/`. Command docs are
auto-generated from code metadata + fragments, so coverage is inherently
complete. The new `platform` command (#1366) already has its fragment.

### B. Undocumented flags

**No gaps.** Non-hidden flags are auto-generated into Options tables by
the doc generator (`script/generate-command-docs.ts`). This was verified
by checking the generated output for recent additions.

### C. Missing usage examples

All command groups have bash examples in their fragments. Lower-priority
gaps:
- `sentry help --json` (new in #1337) has no dedicated example in the
help fragment (only available via `--help`)
- `sentry cli fix` fragment exists but is minimal

### D. Stale descriptions

**No gaps found.** The `brief` strings in code match the generated doc
descriptions.

### E. Missing route mappings in skill generator

**Not applicable.** `ROUTE_TO_REFERENCE` was removed in favor of
automatic 1:1 mapping via `groupRoutesByReference()`. All routes are
automatically covered.

### F. Installation / distribution gaps

| Gap | Source | Doc |
|-----|--------|-----|
| Install script `--no-modify-path` / `--no-completions` flags |
`packages/cli/install` | Not in `getting-started.mdx` (available via
`--help`) |
| Two install URLs coexist: `cli.sentry.dev/install` vs
`sentry.io/get-cli/` | redirect config | Not documented (redirect is
transparent) |
| **Version pin examples stale (0.40.0)** | install script,
getting-started.mdx | **Fixed in this PR** |

### G. Undocumented environment variables

**No gaps.** `configuration.md` is generated from
`src/lib/env-registry.ts`, which is the single source of truth.
Internal-only variables (`SENTRY_PIPELINE`, `SENTRY_MONITOR_SLUG`, etc.)
are intentionally excluded.

### H. Auth / self-hosted gaps

**No new gaps.** Self-hosted docs (26.1.0+ OAuth requirement,
`SENTRY_CLIENT_ID`, trust anchors) are accurate. The new `sentry auth`
smart default (login when logged out, status when logged in, PR #1380)
is already documented in the auth fragment.

### I. Plugin/skills gaps

Low-priority items (unchanged from prior audit):
- `agent-skills.ts` only installs to `.claude` and `.agents` directories
— other detected agents (Windsurf, Copilot, etc.) are detected for
telemetry only, not skill installation
- This is technically accurate in `agentic-usage.md` ("Skills are also
refreshed... skill files are embedded in the binary") but could be
clearer about which agents get auto-installed skills vs. which are only
detected

### J. README / DEVELOPMENT.md drift

| Gap | Source | Doc |
|-----|--------|-----|
| **AGENTS.md references Zod throughout** | `src/types/` uses Valibot
after #1389 | **Fixed in this PR** |
| AGENTS.md import example uses stale path `lib/config.js` |
`getAuthToken` is in `lib/db/auth.js` | **Fixed in this PR** |

---

## Top 5 Most Impactful Fixes (Prioritized)

1. **✅ AGENTS.md Zod → Valibot** — AI agents will write non-compiling
code using `import { z } from "zod"` because AGENTS.md instructs them
to. This causes immediate build failures for any AI-assisted
contribution.

2. **✅ Version pin examples** — Users following the install docs will
pin to a version 3 releases behind, potentially missing security fixes
and new features.

3. **✅ Dashboard dataset aliases** — Agents using the documented
`tracemetrics` or `error-events` names work, but the user-facing aliases
(`metrics`, `errors`) are more discoverable and match `--help` output.

4. **Low priority: `--no-modify-path` / `--no-completions` installer
flags** — Power users in CI/Docker may want these, but they're available
via `--help` on the script itself.

5. **Low priority: Skill install target clarification** — Only `.claude`
and `.agents` get auto-installed skills; other agents are detected for
telemetry only. This is technically correct in the docs but could be
made more explicit.

<div><a
href="https://cursor.com/agents/bc-e1379371-9ad9-4d53-8665-bb60c5e961e0?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/automations/8b0c0f35-da5e-409d-984c-5e39518ffb8a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/view-automation-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/view-automation-light.png"><img
alt="View Automation" width="141" height="28"
src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
jared-outpost Bot added a commit that referenced this pull request Aug 25, 2026
…missing env vars, new commands (#1461)

## Documentation Audit Report (2026-08-24)

Weekly automated audit comparing the CLI implementation against its
documentation. Changes since the last merged audit (PR #1400,
2026-08-11) include: the `sentry cli completion` command (#1427), sixel
dashboard rendering (#1410), the `--environment` explore fix (#1442),
and the 0.43.0 release.

---

## Findings & Fixes

### A. Undocumented or missing commands/subcommands

| Command | Source | Expected doc location | Status |
|---------|--------|----------------------|--------|
| `sentry cli completion` | `src/commands/cli/completion.ts` (added in
#1427) | `apps/cli-docs/src/fragments/commands/cli.md` | **Fixed** —
added examples for bash, zsh, fish |

All other commands in `src/commands/` have corresponding fragment files.
Hidden backward-compat aliases (`send-event`, `send-envelope`,
`bash-hook`, `whoami`, plural aliases) are correctly excluded from docs.

### B. Undocumented flags

| Flag | Command | Source | Doc file | Status |
|------|---------|--------|----------|--------|
| `--sixel` / `-s` | `sentry dashboard view` |
`src/commands/dashboard/view.ts` | `fragments/commands/dashboard.md` |
**Fixed** — added example |

All other non-hidden flags are auto-generated into the command docs via
`generate-command-docs.ts`.

### C. Missing usage examples

No new gaps. The `sentry cli completion` command was the only command
without examples, now fixed.

### D. Stale descriptions

| Command/Flag | Code brief | Doc description | Status |
|-------------|-----------|-----------------|--------|
| `sentry explore --environment` | Was: "Replay environment filter for
--dataset replays" | Now works for all datasets (fixed in #1442) |
**Fixed** — updated brief to "Environment filter" |

### E. Missing route mappings in skill generator

**N/A** — `ROUTE_TO_REFERENCE` was removed and replaced with automatic
1:1 route-to-reference mapping via `groupRoutesByReference()` in
`script/generate-skill.ts`. No manual mapping to go stale.

### F. Installation / distribution gaps

No new gaps. Install script flags (`--no-modify-path`,
`--no-completions`, `--no-agent-skills`) and env vars
(`SENTRY_INSTALL_DIR`, `SENTRY_VERSION`, `SENTRY_INIT`) are documented
in `getting-started.mdx`. Platform support table matches `.craft.yml`
targets (macOS x64/arm64, Linux x64/arm64, Windows x64).

### G. Undocumented environment variables

| Variable | Referenced in | Expected doc | Status |
|----------|-------------|-------------|--------|
| `DO_NOT_TRACK` | `src/lib/telemetry.ts` | `configuration.md`
(generated from env-registry) | **Fixed** — added to env-registry.ts |
| `SENTRY_PIPELINE` | `src/commands/build/upload.ts`,
`src/lib/build/index.ts` | `configuration.md` | **Fixed** — added to
env-registry.ts |

Remaining niche/internal vars NOT added (intentionally excluded from
user-facing docs):
- `SENTRY_ENVIRONMENT` — bash-hook template only
- `SENTRY_CLI_NO_EXIT_TRAP` — bash-hook template internal
- `SENTRY_SCAN_DISABLE_WORKERS` — internal performance tuning
- `SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE` — test-only
- `SENTRY_RN_*` — internal react-native wrapper vars
- `SENTRY_TRACES_SAMPLE_RATE` — inherited from SDK, not a CLI config

### H. Auth / self-hosted gaps

No new gaps. OAuth scopes in `self-hosted.md` and `DEVELOPMENT.md` are
auto-generated (`GENERATED:START oauth-scopes`). The `--url` flag for
`auth login` and `SENTRY_HOST`/`SENTRY_URL` behavior are documented.
Token priority (OAuth > env token unless `SENTRY_FORCE_ENV_TOKEN`) is
correct.

### I. Plugin/skills gaps

No new gaps since the last audit. Skills install to `~/.claude` and
`~/.agents` only. The `agentic-usage.md` correctly states this.
Detection of other agents (Cursor, Windsurf, Copilot, etc.) is for
telemetry and the docs correctly list them as "supported" agents (they
can use the CLI, just not via auto-installed skills).

### J. README / DEVELOPMENT.md / contributing.md drift

| File | Claim | Reality | Status |
|------|-------|---------|--------|
| `script/generate-docs-sections.ts` line 210 | "TypeScript types and
Zod schemas" | Migrated to Valibot in #1389 (merged Aug 7) | **Fixed** |
| `apps/cli-docs/src/content/docs/features.md` | DSN detection table
lists 6 languages with specific `Sentry.init()` patterns | Scanner uses
a universal DSN URL regex across 30+ file extensions | **Fixed** —
updated table to match actual TEXT_EXTENSIONS set |

Node.js version claims (v22.15+ for dev, >=20 for runtime) are correct.
Build commands, test commands, and license (`FSL-1.1-Apache-2.0`) are
all accurate.

---

## Top 5 Most Impactful Fixes (prioritized)

1. **DSN detection language table overhaul** (`features.md`) — The
previous table implied language-specific `Sentry.init()` pattern
matching, which is misleading. The universal regex approach supports 30+
file extensions. Users of Kotlin, Rust, Swift, Dart, C#, etc. would not
have known their DSNs are detected.

2. **Missing `sentry cli completion` docs** (`cli.md` fragment) — New
command from #1427 with no usage examples. Users discovering shell
completions would miss this standalone alternative to `sentry cli
setup`.

3. **Stale `--environment` flag brief** (`explore.ts`) — After #1442
fixed `--environment` to work for all datasets, the flag's `brief`
string still said "Replay environment filter". Users would think it only
applies to replays.

4. **Missing env vars in registry** (`env-registry.ts`) — `DO_NOT_TRACK`
(industry-standard telemetry opt-out) and `SENTRY_PIPELINE` (build
plugin identification) were referenced in code but absent from the
generated configuration page.

5. **Zod→Valibot drift in project structure**
(`generate-docs-sections.ts`) — The auto-generated project structure
tree in `contributing.md` still said "Zod schemas" despite the migration
to Valibot in #1389. Contributors would be confused about which
validation library to use.

<div><a
href="https://cursor.com/agents/bc-2961de96-bee8-48d4-becb-d403a42a7cb6?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/automations/8b0c0f35-da5e-409d-984c-5e39518ffb8a"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/view-automation-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/view-automation-light.png"><img
alt="View Automation" width="141" height="28"
src="https://cursor.com/assets/images/view-automation-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: jared-outpost[bot] <jared-outpost[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

jared Trigger the Jared agent to work on stuff risk: high PR risk score: high

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor: remove remaining Zod usage after valibot migration

1 participant