prepare for production (#30)

Author: w01fgang

.changeset/README.md

@@ -0,0 +1,4 @@
+# Changesets
+
+This folder stores changeset entries used for versioning and changelogs.
+See https://github.com/changesets/changesets for details.

.changeset/cold-olives-cry.md

@@ -0,0 +1,48 @@
+# @power-rent/try-catch
+
+## What This Is
+
+A TypeScript utility library for full-stack teams to handle async errors with a fluent Try API and optional Sentry reporting via `report()`. It supports Node, browser, and Next.js entry points with consistent behavior across environments.
+
+## Core Value
+
+A fluent Try API that never hides errors.
+
+## Requirements
+
+### Validated
+
+- ✓ Developers can run functions via `Try` and choose `.value()`, `.default()`, `.error()`, or `.unwrap()` for clear outcomes — existing
+- ✓ Developers can send errors to Sentry using `.report(message)` with tags and breadcrumbs — existing
+- ✓ Developers can use environment-specific entry points (`/node`, `/browser`, `/nextjs`) — existing
+
+### Active
+
+- [ ] Documentation aligns with real usage patterns, especially `report()` behavior and error outcomes
+- [ ] Type safety is preserved across sync/async functions and all execution paths
+- [ ] Core error-handling flows are well tested (value/default/error/unwrap + reporting)
+
+### Out of Scope
+
+- New runtimes (Deno/Bun/Cloudflare) — keep focus on current environments
+
+## Context
+
+- Existing codebase with a modular core Try class, reporter abstraction, and platform adapters
+- Sentry integration is opt-in via `.report()`; reporting uses adapters per environment
+
+## Constraints
+
+- **Quality**: Type-safe API and strong test coverage — required
+- **Runtime**: Node.js >= 20 — current support target
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Target both server and browser usage | Library is meant to be shared across environments | — Pending |
+| Reporting via explicit `.report()` | Keeps error handling intentional and opt-in | — Pending |
+| No new runtimes in v1 | Reduce scope and keep focus on current adapters | — Pending |
+
+---
+*Last updated: 2026-01-30 after initialization*

.planning/PROJECT.md

@@ -0,0 +1,87 @@
+# Requirements: @power-rent/try-catch
+
+**Defined:** 2026-01-31
+**Core Value:** A fluent Try API that never hides errors.
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Core Try API
+
+- [ ] **TRY-01**: User can wrap sync functions with `new Try(fn, ...args)` and execute via `.value()`, `.error()`, or `.unwrap()`
+- [ ] **TRY-02**: User can wrap async functions with the same fluent API and preserve type inference
+- [ ] **TRY-03**: User can provide a fallback via `.default(value)` and receive it on error
+- [ ] **TRY-04**: Error channel is type-safe across all execution paths
+
+### Sentry Reporting
+
+- [ ] **SENT-01**: User can call `.report(message)` to capture the error via Sentry
+- [ ] **SENT-02**: User can attach tags and breadcrumbs to reported events via fluent chain
+- [ ] **SENT-03**: Errors are reported only when `.report()` is explicitly called, but breadcrumbs are always recorded when `.breadcrumbs()` is used
+- [ ] **SENT-04**: Breadcrumbs configuration is type-safe and matches README examples
+
+### Entry Points
+
+- [ ] **ENTRY-01**: Node entry point available at `@power-rent/try-catch/node`
+- [ ] **ENTRY-02**: Browser entry point available at `@power-rent/try-catch/browser`
+- [ ] **ENTRY-03**: Next.js entry point available at `@power-rent/try-catch/nextjs`
+
+### Diagnostics
+
+- [ ] **DIAG-01**: Non-Error throws are normalized into an Error before reporting
+- [ ] **DIAG-02**: Debug mode allows local error logging without Sentry
+
+### Developer Experience
+
+- [ ] **DX-01**: Documentation and examples read like native English error handling
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### Sentry Reporting
+
+- **SENT-05**: Scoped metadata isolation per call to prevent cross-request bleed
+- **SENT-06**: Zero runtime dependency when Sentry is unused
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| New runtimes (Deno/Bun/Cloudflare) | Focus on current environments for v1 |
+| Result-style combinators (combine/all/partition) | Scope creep beyond focused Try API |
+| Lint plugin for “must handle” semantics | Likely separate package later |
+| Auto-report all errors by default | Creates Sentry noise; report is explicit |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| TRY-01 | Phase 1 | Pending |
+| TRY-02 | Phase 1 | Pending |
+| TRY-03 | Phase 1 | Pending |
+| TRY-04 | Phase 1 | Pending |
+| SENT-01 | Phase 2 | Pending |
+| SENT-02 | Phase 2 | Pending |
+| SENT-03 | Phase 2 | Pending |
+| SENT-04 | Phase 2 | Pending |
+| ENTRY-01 | Phase 2 | Pending |
+| ENTRY-02 | Phase 2 | Pending |
+| ENTRY-03 | Phase 2 | Pending |
+| DIAG-01 | Phase 2 | Pending |
+| DIAG-02 | Phase 2 | Pending |
+| DX-01 | Phase 3 | Pending |
+
+**Coverage:**
+- v1 requirements: 14 total
+- Mapped to phases: 14
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-01-31*
+*Last updated: 2026-01-31 after initial definition*

.planning/REQUIREMENTS.md

@@ -0,0 +1,71 @@
+# Roadmap: @power-rent/try-catch
+
+## Overview
+
+This roadmap delivers a fluent, type-safe Try API first, then layers in Sentry reporting with runtime entry points and diagnostics. Documentation comes last to ensure examples reflect the real behavior users will see.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: Core Try Semantics** - Users can handle sync/async errors with typed outcomes.
+- [ ] **Phase 2: Reporting + Runtime Entry Points** - Users can report errors with Sentry across environments, with diagnostics.
+- [ ] **Phase 3: Documentation & Examples** - Users can follow clear docs that match real behavior.
+
+## Phase Details
+
+### Phase 1: Core Try Semantics
+**Goal**: Users can handle sync/async errors with a type-safe Try API.
+**Depends on**: Nothing (first phase)
+**Requirements**: TRY-01, TRY-02, TRY-03, TRY-04
+**Success Criteria** (what must be TRUE):
+  1. User can wrap sync functions with `new Try(fn, ...args)` and retrieve outcomes via `.value()`, `.error()`, or `.unwrap()`.
+  2. User can wrap async functions with the same API and retain correct TypeScript inference for success and error channels.
+  3. User can supply a fallback via `.default(value)` and receive it on error.
+**Plans**: TBD
+
+Plans:
+- [ ] 01-01: TBD
+
+### Phase 2: Reporting + Runtime Entry Points
+**Goal**: Users can report errors with Sentry across runtimes, with clear diagnostics.
+**Depends on**: Phase 1
+**Requirements**: SENT-01, SENT-02, SENT-03, SENT-04, ENTRY-01, ENTRY-02, ENTRY-03, DIAG-01, DIAG-02
+**Success Criteria** (what must be TRUE):
+  1. User can call `.report(message)` to send the current error to Sentry.
+  2. User can attach tags and breadcrumbs in the fluent chain before reporting.
+  3. Reporting defaults avoid noisy handled errors unless explicitly requested.
+  4. User can import runtime-specific entry points (`/node`, `/browser`, `/nextjs`) with consistent reporting behavior.
+  5. Breadcrumbs configuration is type-safe and matches README examples.
+  6. Non-Error throws are normalized to Error before reporting, and debug mode logs locally without Sentry.
+**Plans**: TBD
+
+Plans:
+- [ ] 02-01: TBD
+
+### Phase 3: Documentation & Examples
+**Goal**: Users can rely on docs/examples that reflect real Try and reporting behavior.
+**Depends on**: Phase 2
+**Requirements**: DX-01
+**Success Criteria** (what must be TRUE):
+  1. User can follow docs/examples for core Try usage that read like native English error handling and match actual outcomes.
+  2. User can follow docs/examples for reporting and entry points that reflect real `report()` behavior and configuration.
+**Plans**: TBD
+
+Plans:
+- [ ] 03-01: TBD
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Core Try Semantics | 0/TBD | Not started | - |
+| 2. Reporting + Runtime Entry Points | 0/TBD | Not started | - |
+| 3. Documentation & Examples | 0/TBD | Not started | - |

.planning/ROADMAP.md

@@ -0,0 +1,69 @@
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-01-31)
+
+**Core value:** A fluent Try API that never hides errors.
+**Current focus:** Phase 1 — Core Try Semantics
+
+## Current Position
+
+Phase: 1 of 3 (Core Try Semantics)
+Plan: 0 of TBD in current phase
+Status: Ready to plan
+Last activity: 2026-01-31 - Completed quick task 001: write tests that verify type safety accoriding to the use cases covered in Readme.md
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 1
+- Average duration: 2m 41s
+- Total execution time: 2m 41s
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| Quick | 1 | 2m 41s | 2m 41s |
+
+**Recent Trend:**
+- Last 5 plans: -
+- Trend: -
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- None yet.
+
+### Pending Todos
+
+[From .planning/todos/pending/ — ideas captured during sessions]
+
+None yet.
+
+### Blockers/Concerns
+
+[Issues that affect future work]
+
+None yet.
+
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+| 001 | write tests that verify type safety accoriding to the use cases covered in Readme.md | 2026-01-31 | 9595583 | [001-write-tests-that-verify-type-safety-acco](./quick/001-write-tests-that-verify-type-safety-acco/) |
+
+## Session Continuity
+
+Last session: 2026-01-31 14:21 UTC
+Stopped at: Completed quick-001 type-safety-tests plan 001
+Resume file: None