statuspro-openapi-client 0.1.0__tar.gz

statuspro_openapi_client-0.1.0/.claude/agents/code-modernizer.md

@@ -0,0 +1,96 @@
+# Code Modernizer
+
+Simplify and modernize editable code while respecting this repo's generated file
+boundaries and established patterns.
+
+## Mission
+
+Find and fix outdated patterns, anti-patterns, and unnecessarily complex code in
+editable files. This agent has repo-specific knowledge that the generic `/simplify`
+skill lacks.
+
+## File Boundaries
+
+**ONLY touch editable files.** NEVER modify generated files:
+
+- SKIP: `statuspro_public_api_client/api/**/*.py`
+- SKIP: `statuspro_public_api_client/models/**/*.py`
+- SKIP: `statuspro_public_api_client/client.py`
+- SCAN: `statuspro_public_api_client/` (excluding above), `statuspro_mcp_server/`, `tests/`,
+  `scripts/`
+
+## Detection Rules
+
+### UNSET Sentinel Misuse
+
+```python
+# BAD: raw isinstance check
+if not isinstance(value, type(UNSET)):
+    use(value)
+
+# GOOD: use unwrap_unset
+use(unwrap_unset(value, default))
+```
+
+```python
+# BAD: manual None-to-UNSET conversion
+value if value is not None else UNSET
+
+# GOOD: use to_unset
+to_unset(value)
+```
+
+### Response Handling
+
+```python
+# BAD: manual status code check
+if response.status_code == 200:
+    result = response.parsed
+
+# GOOD: use helpers
+result = unwrap_as(response, ExpectedType)
+items = unwrap_data(response, default=[])
+if is_success(response): ...
+```
+
+### Architecture Violations
+
+- Wrapping API methods with retry logic (resilience is at the transport layer)
+- `hasattr` checks on attrs-defined fields (they always exist, may be UNSET)
+- Broad `except Exception` without re-raise or logging
+
+### Code Complexity
+
+- Functions with too many parameters (extract a dataclass)
+- Names that shadow builtins (rename them)
+- Deeply nested conditionals (extract early returns or helper functions)
+- Duplicate logic across test fixtures (consolidate into `conftest.py`)
+
+## Process
+
+1. Scan editable files for each detection rule category
+1. Before rewriting a suspected anti-pattern, verify with the LSP:
+   - `hasattr` flag: run `LSP hover` on the attribute. If the type points into an
+     attrs-generated model (fields carry `Unset | T`), the rewrite to `unwrap_unset` is
+     safe. If hover shows a plain Python class, it may be a real `hasattr` check — leave
+     it alone.
+   - Dead-code flag: run `LSP findReferences` on the symbol definition. Zero references
+     means safe to delete; any reference means it's still wired up.
+1. For each confirmed finding, report the file, line, current pattern, and fix
+1. Apply fixes incrementally (one category at a time)
+1. After each batch of changes, run `uv run poe agent-check` to verify
+1. Summarize all changes made
+
+## Constraints
+
+- Do not add unnecessary abstractions for one-time patterns
+- Do not add docstrings or type annotations to code you didn't otherwise change
+- Preserve existing test behavior - modernize structure, not assertions
+- If a fix would require changing generated files, note it but skip it
+
+## Relationship to /techdebt
+
+`/techdebt` is a broad scanner that reports findings across 5 categories (dead code,
+duplication, smells, etc.) without applying fixes. This agent is narrower: it focuses on
+repo-specific anti-patterns and actively applies fixes. Use `/techdebt` to survey, use
+this agent to remediate.

statuspro_openapi_client-0.1.0/.claude/agents/pr-preparer.md

@@ -0,0 +1,84 @@
+# PR Preparer
+
+Mechanical readiness checklist for pull requests. Focuses on process compliance (commit
+format, generated file integrity, coverage thresholds) rather than code quality analysis
+(which `/review` handles). Use this agent for the "is the branch shippable?" question,
+not "is the code good?"
+
+## Mission
+
+Run a comprehensive readiness assessment and produce a pass/fail report. This is the
+process gate before opening a PR.
+
+## Readiness Checks
+
+### 1. Validation Suite
+
+Run `uv run poe check` (Tier 3 validation - format, lint, type check, tests). All checks
+must pass clean with zero warnings.
+
+### 2. Commit Standards
+
+Review all commits on this branch (vs main) for:
+
+- Conventional commit format: `type(scope): description`
+- Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `build`,
+  `ci`, `perf`
+- Valid scopes: `client`, `mcp`, or no scope for cross-cutting changes
+- Breaking changes marked with `!`: `feat(client)!: description`
+- Concise, meaningful descriptions (not "fix stuff" or "updates")
+
+### 3. Generated File Integrity
+
+- If generated files (`api/**/*.py`, `models/**/*.py`, `client.py`) appear in the diff,
+  verify they came from regeneration (spec change + `uv run poe regenerate-client`), not
+  manual edits
+- If `docs/statuspro-openapi.yaml` was modified, verify that client was regenerated AND
+  pydantic models were regenerated (`uv run poe generate-pydantic`)
+
+### 4. Coverage Check
+
+- Run `uv run poe test-coverage` and verify core logic maintains 87%+ coverage
+- New code has test coverage for both success and error paths
+- No test files with only happy-path assertions
+
+### 5. Documentation
+
+- Public functions/classes added or modified have docstrings
+- If an architectural decision was made, check for a corresponding ADR in `docs/adr/`
+- If new patterns or pitfalls were discovered, verify CLAUDE.md was updated
+- If MCP tools were added/modified, verify help resource in
+  `statuspro_mcp_server/.../resources/help.py` is in sync
+
+### 6. Anti-Pattern Scan
+
+Quick scan of the diff for anti-patterns listed in CLAUDE.md's "Known Pitfalls" and
+"Anti-Patterns to Avoid" sections.
+
+## Output Format
+
+```
+## PR Readiness Report
+
+### Status: [READY | NOT READY]
+
+### Checks
+- [ ] Validation suite: [PASS/FAIL - details]
+- [ ] Commit standards: [PASS/FAIL - details]
+- [ ] Generated files: [PASS/FAIL - details]
+- [ ] Coverage: [PASS/FAIL - N%]
+- [ ] Documentation: [PASS/FAIL - details]
+- [ ] Anti-patterns: [PASS/FAIL - details]
+
+### Blocking Issues
+[List of issues that must be fixed before PR]
+
+### Suggestions
+[Non-blocking improvements noticed during review]
+```
+
+## Important
+
+- Run real commands for every check - do not assume anything passes
+- If `uv run poe check` fails, list specific failures as blocking issues
+- Never suggest `--no-verify` or skipping any check

statuspro_openapi_client-0.1.0/.claude/agents/spec-auditor.md

@@ -0,0 +1,64 @@
+# Spec Auditor
+
+Audit the local OpenAPI spec against the upstream StatusPro API to detect drift, missing
+endpoints, field mismatches, and type discrepancies.
+
+## Mission
+
+Compare `docs/statuspro-openapi.yaml` (our local spec) against the upstream StatusPro
+spec and identify any differences that need resolution.
+
+**Note on upstream source**: StatusPro does not appear to publish their OpenAPI spec at
+a public URL. Until an upstream source is confirmed, treat this agent as operating in
+**local-only mode** — verify internal consistency, cross-check against API behavior
+observed in tests, and flag anything that looks out-of-date. If/when the user provides
+an upstream URL, update this file with the URL and switch to full drift-detection mode.
+
+## Knowledge
+
+- Local spec lives at `docs/statuspro-openapi.yaml`
+- Generated files (`api/**/*.py`, `models/**/*.py`, `client.py`) are derived from the
+  spec via `uv run poe regenerate-client` followed by `uv run poe generate-pydantic`
+- Pydantic models inherit from `StatusProPydanticBase`, which uses `extra="forbid"`;
+  the attrs models tolerate unknown fields via `additional_properties`
+- Most list endpoints wrap data in `{"data": [...], "meta": {...}}` (page/per_page
+  pagination). Two endpoints return raw arrays: `GET /statuses` and
+  `GET /orders/{id}/viable-statuses`
+
+## Audit Process
+
+1. **If an upstream URL is known**, fetch it and diff paths + schemas. Otherwise,
+   skip this step and audit internal consistency only.
+1. **Compare paths**: identify endpoints in upstream but missing locally, and vice versa
+1. **Compare schemas**: for shared endpoints, diff request/response schemas for field
+   additions, removals, type changes, and nullable mismatches
+1. **Internal consistency**: every `$ref` resolves; every path referenced in tool or
+   helper code exists in the spec
+1. **Check parameter alignment**: path params, query params, request bodies
+
+## Output Format
+
+```
+## Spec Audit Report
+
+### Path Comparison
+- Upstream paths: N (or "upstream not available")
+- Local paths: N
+- Missing locally: [list]
+- Extra locally: [list]
+
+### Schema Differences
+For each endpoint with differences:
+- **[METHOD /path]**: [description of difference]
+
+### Recommended Actions
+1. [Specific changes to make to docs/statuspro-openapi.yaml]
+2. [Whether regeneration is needed]
+```
+
+## Important
+
+- NEVER edit generated files directly — only modify `docs/statuspro-openapi.yaml`
+- After spec changes, the pipeline is: edit spec → `uv run poe regenerate-client` →
+  `uv run poe generate-pydantic` → `uv run poe agent-check`
+- Never include real user names or emails from API responses in reports or examples

statuspro_openapi_client-0.1.0/.claude/commands/generate-docs.md

@@ -0,0 +1,116 @@
+# Generate Documentation
+
+Generate or update documentation for the specified code, feature, or architectural
+decision. If no target is specified, identify documentation gaps and address them.
+
+## Documentation Types
+
+### 1. Docstrings (Google Style)
+
+Required for all public functions, classes, and modules:
+
+```python
+def unwrap_as(response: Response, expected_type: type[T]) -> T:
+    """Extract and validate a parsed response as the expected type.
+
+    Args:
+        response: The HTTP response to unwrap.
+        expected_type: The type to validate the parsed response against.
+
+    Returns:
+        The parsed response cast to the expected type.
+
+    Raises:
+        AuthenticationError: If the response is 401 Unauthorized.
+        ValidationError: If the response is 422 Unprocessable Entity.
+        APIError: For other non-success status codes.
+    """
+```
+
+### 2. Architecture Decision Records (ADRs)
+
+For architectural decisions, create an ADR in `docs/adr/`:
+
+- Numbering: 4-digit sequential (`0001`, `0002`, etc.)
+- Find next number: `ls docs/adr/*.md | grep -o '[0-9]\{4\}' | sort -n | tail -1`
+- Use the template at `docs/adr/template.md`
+- Update `docs/adr/README.md` index after creating
+
+### 3. README Structure Template
+
+When creating a new README or major documentation page:
+
+```markdown
+# Project/Package Name
+
+Brief description of what this does and why it exists.
+
+## Installation
+
+How to install or set up.
+
+## Quick Start
+
+Minimal working example to get started fast.
+
+## Usage
+
+Detailed usage patterns with examples.
+
+## API Reference
+
+Key functions/classes with signatures and descriptions.
+
+## Configuration
+
+Environment variables, config files, options.
+
+## Contributing
+
+How to contribute (or link to CONTRIBUTING.md).
+```
+
+### 4. Cookbook Recipes
+
+For new usage patterns, add to `docs/COOKBOOK.md`:
+
+```markdown
+### Recipe: [What You Want to Do]
+
+**When to use**: [Scenario description]
+
+\`\`\`python
+# Working, tested code example
+\`\`\`
+
+**Notes**: [Gotchas, alternatives, related recipes]
+```
+
+### 5. User Guides
+
+For complex features, create or update guides in `docs/`:
+
+- Step-by-step instructions
+- Working code examples (tested)
+- Common pitfalls and solutions
+- Links to related documentation
+
+## Standards
+
+See CLAUDE.md's "Detailed Documentation" table for project doc structure. Format
+markdown with `uv run poe format` (88 char line length, ATX headers).
+
+## Process
+
+1. Read the target code or feature thoroughly
+1. Identify which documentation type(s) are needed
+1. Write documentation following the templates above
+1. Verify all code examples are correct and tested
+1. Run `uv run poe format` to format markdown
+1. If updating MkDocs content, run `uv run poe docs-build` to verify
+
+## Self-Improvement
+
+If you notice that existing documentation is wrong, incomplete, or misleading while
+generating new docs, fix it. Don't just document new things - improve what's already
+there.

statuspro_openapi_client-0.1.0/.claude/commands/pre-commit.md

@@ -0,0 +1,65 @@
+# Pre-Commit Check
+
+Quick pre-flight validation of staged and unstaged changes before committing. Lighter
+than `/review` (which reviews the whole branch) - this focuses on catching common
+mistakes in the current changeset.
+
+## Process
+
+### 1. Run Tier 2 Validation
+
+```bash
+uv run poe agent-check
+```
+
+If this fails, report the failures and stop. Fix before committing.
+
+### 2. Scan the Diff for Anti-Patterns
+
+Review the output of `git diff` and `git diff --cached` for:
+
+- **Generated file modifications**: any changes to `api/**/*.py`, `models/**/*.py`, or
+  `client.py` that didn't come from regeneration
+- Anti-patterns listed in CLAUDE.md's "Known Pitfalls" and "Anti-Patterns to Avoid"
+  sections
+
+### 3. Verify Test Coverage
+
+If new or changed code is in the diff:
+
+- Check that corresponding test files were also modified or created
+- Flag any new functions without test coverage
+
+### 4. Check Commit Message Format
+
+If a commit message is provided or can be inferred, verify it follows:
+
+- Conventional commit format: `type(scope): description`
+- Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `build`,
+  `ci`, `perf`
+- Valid scopes: `client`, `mcp`, or none for cross-cutting changes
+
+## Output Format
+
+```
+## Pre-Commit Report
+
+### Status: [PASS | FAIL]
+
+### Validation: [PASS/FAIL]
+[Details if failed]
+
+### Anti-Pattern Scan: [PASS/FAIL]
+[List of findings, if any]
+
+### Test Coverage: [PASS/FAIL]
+[Uncovered changes, if any]
+
+### Commit Format: [PASS/FAIL]
+[Issues with message format, if any]
+```
+
+## Key Principle
+
+This check should be fast. If it passes, you can commit with confidence. If it fails,
+fix the issues first - never use `--no-verify`.

statuspro_openapi_client-0.1.0/.claude/commands/review.md

@@ -0,0 +1,101 @@
+# Code Review
+
+Review the current branch's changes against main for quality, correctness, and project
+standards.
+
+## Review Process
+
+### Step 1: Initial Classification
+
+Before diving into details, classify the change:
+
+- **Type**: Feature / Bug Fix / Refactor / Spec Change / Config / Docs
+- **Risk**: Low (cosmetic, docs) / Medium (new feature, test changes) / High (spec
+  changes, transport layer, auth, breaking changes)
+- **Affected packages**: client / mcp / typescript / cross-cutting
+
+This classification guides where to focus review attention.
+
+### Step 2: Full Context Review
+
+1. Identify the diff: `git diff main...HEAD`
+1. Read every changed file in full context (not just the diff lines)
+1. Check surrounding code for broken assumptions - changes may invalidate logic in
+   adjacent functions or callers that aren't in the diff
+1. For every function whose signature or behavior changed, run `LSP findReferences` (or
+   `LSP incomingCalls`) to enumerate callers. Read each caller and confirm it still
+   works with the new semantics. This catches ripple effects that a diff-only review
+   misses — a diff only shows what changed, not what depends on it.
+1. Run `uv run poe check` to verify everything passes
+1. Produce the structured review below
+
+## Review Dimensions (Priority Order)
+
+Focus review effort in this order - higher priorities get more scrutiny:
+
+1. **Correctness** - Does the code do what it claims? Edge cases handled? Bugs?
+1. **Security** - Input validation, auth checks, no secrets in code, safe API handling
+1. **Architecture** - Respects generated file boundaries, transport-layer resilience
+   pattern, UNSET/response helper conventions
+1. **Completeness** - All requirements met, tests cover success + error paths, docs
+   updated
+1. **Readability** - Clear naming, appropriate abstractions, maintainable
+1. **Performance** - Efficient patterns, no N+1 queries, appropriate pagination
+
+## Output Format
+
+### Classification
+
+Type, risk level, and affected packages (from Step 1).
+
+### Summary
+
+One paragraph describing what the changes do, their scope, and overall assessment.
+
+### Strengths
+
+Bullet list of things done well - good patterns, clean code, thorough tests.
+
+### Issues
+
+Each issue gets a severity tag:
+
+- **[BLOCKING]** - Must fix before merge. Bugs, security issues, broken tests,
+  architecture violations.
+- **[SUGGESTION]** - Recommended improvement. Better patterns, missing edge cases,
+  unclear naming.
+- **[NITPICK]** - Minor style or preference. Take it or leave it.
+
+Format each issue as:
+
+```
+**[SEVERITY]** `file:line` - Brief description
+Explanation of the problem and suggested fix.
+```
+
+### Questions
+
+Anything unclear about intent, design choices, or missing context. Questions are not
+criticisms.
+
+## Project-Specific Checklist
+
+Verify these for every review (see CLAUDE.md for details on each):
+
+- [ ] Generated files not manually edited; pydantic models regenerated if the OpenAPI
+  client was regenerated
+- [ ] Resilience at transport layer, not wrapping API methods
+  ([ADR-001](statuspro_public_api_client/docs/adr/0001-transport-layer-resilience.md))
+- [ ] Full type annotations; UNSET/response handling per CLAUDE.md patterns
+- [ ] New functionality has tests (success + error paths, 87%+ coverage)
+- [ ] Public APIs have docstrings; ADR created for architectural decisions
+
+## Verification
+
+Before approving, confirm `uv run poe check` passes clean. If it doesn't, list the
+failures as `[BLOCKING]` issues.
+
+## Self-Improvement
+
+If the review reveals a pattern worth codifying (new anti-pattern, missing convention,
+or a pitfall that tripped up the author), update CLAUDE.md so future work benefits.

statuspro_openapi_client-0.1.0/.claude/commands/techdebt.md

@@ -0,0 +1,95 @@
+# Tech Debt Scanner
+
+Scan the codebase for tech debt, anti-patterns, and improvement opportunities.
+
+## Scope
+
+Only scan **editable** files. NEVER flag or modify generated files:
+
+- SKIP (generated): `statuspro_public_api_client/api/**/*.py`,
+  `statuspro_public_api_client/models/**/*.py`, `statuspro_public_api_client/client.py`
+- SCAN: `statuspro_public_api_client/` (excluding generated paths above),
+  `statuspro_mcp_server/`, `tests/`, `scripts/`
+
+## Categories to Check
+
+### 1. Dead Code
+
+- Unused imports, variables, functions, classes
+- Unreachable code paths
+- Commented-out code blocks
+
+For candidate unused functions/classes, use `LSP findReferences` on the symbol
+definition to confirm zero usages before flagging. Pyright walks the real import graph
+(including `from module import *` and aliased re-exports) that a plain `Grep` can miss,
+so LSP is the authoritative check. If there are no references outside the definition
+itself, the symbol is dead and safe to remove.
+
+### 2. Outdated Patterns (Project-Specific)
+
+Flag anti-patterns from CLAUDE.md's "Known Pitfalls" and "Anti-Patterns to Avoid"
+sections.
+
+### 3. Code Duplication
+
+- Repeated logic that should be extracted into helpers
+- Copy-pasted test setup that should be fixtures
+- Duplicate error handling patterns
+
+### 4. Code Smells
+
+- Overly broad exception handling (`except Exception`)
+- Missing type annotations on public functions
+- Issues listed in CLAUDE.md's "Proper fixes" section (parameter count, shadowing,
+  circular imports)
+
+### 5. Missing Best Practices
+
+- Public functions without docstrings
+- Tests without descriptive names
+- Missing `@pytest.mark.asyncio` on async tests
+- Fixtures that should use `@pytest.fixture(scope="session")`
+
+## Process
+
+1. Run `uv run poe quick-check` to get current lint status
+1. Scan editable files category by category
+1. For each finding, report:
+   - **File and line**: exact location
+   - **Category**: which of the 5 categories above
+   - **Current code**: the problematic pattern
+   - **Suggested fix**: concrete replacement
+   - **Priority**: HIGH (breaks conventions), MEDIUM (code quality), LOW (nice to have)
+1. Run `uv run poe fix` to auto-fix what's possible
+1. Summarize findings by category with counts
+
+## Output Format
+
+```
+## Tech Debt Report
+
+### Summary
+- Dead code: N findings
+- Outdated patterns: N findings
+- Code duplication: N findings
+- Code smells: N findings
+- Missing best practices: N findings
+
+### HIGH Priority
+[findings...]
+
+### MEDIUM Priority
+[findings...]
+
+### LOW Priority
+[findings...]
+
+### Improvements to CLAUDE.md
+[Any new anti-patterns or pitfalls discovered that should be added]
+```
+
+## Self-Improvement
+
+If this scan reveals a recurring anti-pattern not already documented in CLAUDE.md's
+"Known Pitfalls" or "Anti-Patterns to Avoid" sections, add it there so future sessions
+can catch it earlier.