feat: add privacy-safe crash reporting

[altaywtf]

Summary

Closes #61.

Adds bounded, privacy-safe crash reporting for unexpected CLI failures. Official releases enable reporting by default with one durable local control: putio telemetry disable|status|enable.

Changed

• added the dedicated US-hosted putio/putio-cli Sentry integration and release/environment tagging
• injects a schema-validated public DSN from the protected GitHub release Environment into npm and standalone artifacts; no production DSN remains in tracked source
• release builds fail if DSN configuration is missing or invalid, while local and pull-request builds remain network-free
• added a persisted telemetry_disabled preference loaded before Sentry initialization
• captures at most one unexpected Effect defect, uncaught exception, or unhandled rejection
• reconstructs the serialized Sentry envelope from a fixed synthetic allowlist at the transport boundary
• blocks redirects, retries, SDK-internal events, malformed envelopes, and original error data
• preserves stdout, stderr, exit status, signal behavior, Node rejection modes, and offline operation

Risks

• crash events intentionally contain no original message, stack, path, URL, arguments, payload, token, user, or device data, so diagnosis relies on release plus one of three failure categories
• protected release jobs cannot run on pull requests; injected npm and macOS SEA artifacts were built and verified locally with the configured DSN
• no production test event was sent

Verification

• pnpm exec vp run verify — 33 files, 339 tests, 89.81% statement coverage
• actionlint .github/workflows/ci.yml .github/workflows/backfill-release-assets.yml
• local build without DSN reports build_configuration_unavailable
• required release build without DSN fails closed
• injected npm and macOS SEA artifacts report crash reporting enabled
• hosted Verify CLI — passed
• Codex autoreview — clean, zero findings

Complexity

Preference loading, build configuration, Sentry initialization, event construction, final envelope serialization, bounded transport, and fatal replay are separate fail-closed stages so reporting cannot replace or leak the original command failure.

[Copilot]

Pull request overview

This PR introduces bounded, privacy-safe crash reporting for unexpected putio CLI failures, backed by a persisted user preference (telemetry_disabled) and exposed through new putio telemetry commands. It integrates a minimal Sentry transport that rebuilds envelopes from an allowlist to avoid leaking original error details, while documenting the policy and operational boundaries.

Changes:

• Add crash reporting bootstrap + process-level crash boundary for uncaught exceptions, unhandled rejections, and Effect defects (captured once, bounded flush).
• Add persisted telemetry preference (telemetry_disabled) with CLI commands: telemetry status|disable|enable, plus metadata exposure via putio describe.
• Add extensive unit + process-boundary test coverage and update user/agent/architecture documentation.

Reviewed changes

Copilot reviewed 30 out of 31 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/test-support/crash-process.mjs	Adds a fixture process to exercise crash boundary behavior end-to-end.
src/sea.ts	Bootstraps crash reporting and wires crash reporter into the app layer for SEA entrypoint.
src/internal/state.ts	Persists telemetry_disabled and adds state APIs to read/update telemetry preference.
src/internal/state.test.ts	Adds tests ensuring telemetry preference persists without affecting auth state.
src/internal/metadata.ts	Extends describe metadata contract with crashReporting and telemetry_disabled config field.
src/internal/metadata.test.ts	Verifies new crashReporting metadata shape and telemetry command presence.
src/internal/main.ts	Captures Effect defects via the crash reporter from the CLI error handler.
src/internal/main.test.ts	Adds coverage ensuring defects still render stderr-only and invoke crash capture.
src/internal/crash-reporting.ts	Implements Sentry integration with allowlisted event/envelope sanitation and bounded transport.
src/internal/crash-reporting.test.ts	Adds thorough tests for preference loading, event/envelope sanitation, and transport guarantees.
src/internal/crash-boundary.ts	Adds process-level handlers for uncaught exceptions/unhandled rejections and fatal replay logic.
src/internal/crash-boundary.test.ts	Tests crash boundary installs/removes handlers and captures exactly once.
src/internal/crash-boundary-process.test.ts	Process-boundary tests verifying stdout purity, exit semantics, and Node rejection modes.
src/internal/crash-bootstrap.ts	Adds early preference loading + crash reporter creation + handler installation bootstrap.
src/internal/crash-bootstrap.test.ts	Tests opt-out prevents initialization/handler installation and fail-closed behavior.
src/internal/config.ts	Exposes resolved config path as a service effect for reuse by telemetry/state.
src/internal/cli-contract.ts	Registers new telemetry command specs in the command catalog.
src/internal/app-layer.ts	Wires the crash reporter service into the application layer.
src/index.ts	Updates public exports for state-related schemas and new telemetry helpers.
src/i18n/catalog/en.ts	Adds English strings for telemetry subcommands/status rendering.
src/commands/telemetry.ts	Introduces `putio telemetry status
src/cli.ts	Adds telemetry command to CLI and includes crashReporting decision in describe output.
src/cli.test.ts	Adds CLI-level tests for telemetry disable (including with invalid API env config).
src/bin.ts	Bootstraps crash reporting and wires crash reporter into the app layer for main entrypoint.
skills/putio-cli/SKILL.md	Documents telemetry opt-out/status/enable in the consumer skill guidance.
skills/putio-cli/references/guardrails.md	Adds guardrail note about respecting telemetry preference state.
skills/putio-cli/references/discovery.md	Documents crashReporting metadata as part of automation discovery.
README.md	Adds a new Crash Reporting and Diagnostics section describing policy and usage.
pnpm-lock.yaml	Adds locked dependency entries for @sentry/core.
package.json	Adds @sentry/core dependency.
docs/ARCHITECTURE.md	Documents crash-reporting policy, boundaries, and data-handling guarantees.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[putio-releaser]

🎉 This PR is included in version 1.6.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀