diff --git a/.claude/commands/create-issue.md b/.claude/commands/create-issue.md new file mode 100644 index 0000000..99f918a --- /dev/null +++ b/.claude/commands/create-issue.md @@ -0,0 +1,87 @@ +Create a GitHub issue for the robosystems-python-client repository based on the user's input. + +## Instructions + +1. **Determine Issue Type** - Based on the user's description, determine which type to use: + - **Bug**: Defects or unexpected behavior + - **Task**: Specific, bounded work items that can be completed in one PR + - **Feature**: User-facing feature suggestions + - **Spec**: Features requiring technical design, multiple phases, or architectural changes + - **RFC**: Significant design proposals needing team discussion before implementation + +2. **Gather Context** - If the user provides a file path or references existing code: + - Read the relevant files to understand the current implementation + - Check client methods in `/robosystems_client/` + - Review tests in `/tests/` + +3. **Draft the Issue** - Use the YAML templates in `.github/ISSUE_TEMPLATE/`: + - `bug.yml` - Include reproduction steps, version info + - `task.yml` - Be specific about scope and acceptance criteria + - `feature.yml` - Simple "I wish I could..." format + - `spec.yml` - Fill in all sections with technical detail + - `rfc.yml` - Comprehensive design with alternatives considered + +4. **Sanitize for Public Visibility** - Before creating: + - Remove any internal API details or secrets + - Generalize any sensitive information + - Keep technical implementation details (these are fine to share) + +5. **Create the Issue** - Use `gh issue create` with: + - Clear, concise title (no prefixes like [SPEC] - types handle categorization) + - Well-formatted markdown body matching the template structure + - Appropriate metadata labels (see below) + +6. **Set Issue Type** - After creation, set the issue type via GraphQL: + ```bash + # Get issue ID + gh api graphql -f query='{ repository(owner: "RoboFinSystems", name: "robosystems-python-client") { issue(number: NUMBER) { id } } }' + + # Set type (use correct type ID) + gh api graphql -f query='mutation { updateIssue(input: { id: "ISSUE_ID", issueTypeId: "TYPE_ID" }) { issue { number } } }' + ``` + + Issue Type IDs (org-level, shared across repos): + - Task: `IT_kwDODL_jkM4BnUUo` + - Bug: `IT_kwDODL_jkM4BnUUp` + - Feature: `IT_kwDODL_jkM4BnUUq` + - Spec: `IT_kwDODL_jkM4B0XrY` + - RFC: `IT_kwDODL_jkM4B0XrZ` + +## Labels + +Issue types handle primary categorization. Use labels for metadata. + +**Area** (which part of the client): +- `area:client` - Core client functionality +- `area:api` - API method implementations +- `area:types` - Pydantic models and type definitions +- `area:auth` - Authentication handling +- `area:errors` - Error handling +- `area:testing` - Test coverage +- `area:docs` - Documentation +- `area:packaging` - pyproject.toml, releases +- `area:ci-cd` - Workflows, releases + +**Priority** (when to do it): +- `priority:critical` - Drop everything +- `priority:high` - Next up +- `priority:low` - Backlog + +**Size** (how long): +- `size:small` - < 1 day +- `size:medium` - 1-3 days +- `size:large` - > 3 days + +**Status**: +- `blocked` - Waiting on something +- `needs-review` - Ready for review + +## Output Format + +After creating the issue, provide: +1. The issue URL +2. Brief summary of what was created +3. Issue type and labels applied +4. Any suggested follow-up tasks or related issues to create + +$ARGUMENTS diff --git a/.claude/commands/staged-review.md b/.claude/commands/staged-review.md new file mode 100644 index 0000000..3556b69 --- /dev/null +++ b/.claude/commands/staged-review.md @@ -0,0 +1,42 @@ +Review all staged changes (`git diff --cached`) with focus on these contexts: + +## Client Implementation Context + +**API Methods:** +- Are new methods properly typed with Pydantic models? +- Is error handling consistent? +- Are async/sync variants implemented correctly? + +**Type Definitions:** +- Are Pydantic models properly defined? +- Are types properly exported in `__init__.py`? +- Is backwards compatibility maintained? + +**Code Quality:** +- Does the code follow existing patterns? +- Is the code properly formatted (ruff)? +- Are type hints complete (basedpyright)? + +## Testing Context + +- Do new methods have corresponding tests? +- Are edge cases covered? +- Is test coverage maintained? + +## Documentation Context + +- Is README updated for new features? +- Are docstrings complete? +- Are examples provided for new methods? + +## Packaging Context + +- Is `pyproject.toml` updated if needed? +- Are dependencies properly specified? + +## Output + +Provide a summary with: +1. **Issues**: Problems that should be fixed before commit +2. **Suggestions**: Improvements that aren't blocking +3. **Questions**: Anything unclear that needs clarification diff --git a/.claude/commands/test.md b/.claude/commands/test.md new file mode 100644 index 0000000..266d160 --- /dev/null +++ b/.claude/commands/test.md @@ -0,0 +1,20 @@ +Run `just test-all` and systematically fix all failures to achieve 100% completion. + +## Strategy + +1. **Run full suite first**: `just test-all` to see the full picture +2. **Fix by module**: When errors exist, use `just test` to iterate faster +3. **Fix in order**: Linting/formatting → Type errors → Test failures +4. **Stop when done**: Once `just test-all` passes completely, stop immediately + +## Key Commands + +- `just test-all` - Full suite (tests + lint + format + typecheck) +- `just test` - Run pytest +- `just lint fix` - Auto-fix linting issues +- `just format` - Auto-fix formatting +- `just typecheck` - Run basedpyright + +## Goal + +100% pass rate on `just test-all` with no errors of any kind. diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..b7688ac --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,81 @@ +name: Bug +description: Something isn't working +type: Bug +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug! Please fill out the details below. + + - type: textarea + id: summary + attributes: + label: Summary + description: What's broken? + placeholder: Describe the issue... + validations: + required: true + + - type: dropdown + id: impact + attributes: + label: Impact + options: + - Critical + - High + - Medium + - Low + validations: + required: true + + - type: textarea + id: version + attributes: + label: Version + description: What version are you using? + placeholder: | + robosystems-client version: x.x.x + Python version: x.x.x + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + description: How can we reproduce this? + placeholder: | + 1. + 2. + 3. + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + placeholder: What should happen? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + placeholder: What actually happens? + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Error Messages / Logs + render: shell + placeholder: Paste any relevant error messages or stack traces here + + - type: textarea + id: context + attributes: + label: Additional Context + placeholder: Client configuration, environment, workarounds tried... diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 160740e..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve -title: '' -labels: bug -assignees: '' - ---- - -**Describe the bug** -A clear and concise description of what the bug is. - -**To Reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**Additional context** -Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..46273b8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Discussion + url: https://github.com/orgs/RoboFinSystems/discussions + about: For questions or general discussion, start a GitHub Discussion instead diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..62b284b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,34 @@ +name: Feature +description: I wish I could... +type: Feature +body: + - type: textarea + id: request + attributes: + label: What would you like? + description: A clear description of what you wish you could do. + placeholder: I wish I could... + validations: + required: true + + - type: textarea + id: why + attributes: + label: Why? + description: What problem would this solve for you? + placeholder: This would help because... + validations: + required: true + + - type: textarea + id: ideas + attributes: + label: Any ideas on how? + description: Optional - if you have thoughts on implementation, share them here. + placeholder: One way to do this might be... + + - type: textarea + id: context + attributes: + label: Additional Context + placeholder: Examples, links, or references that help explain the request. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 11fc491..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: enhancement -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml new file mode 100644 index 0000000..12111dc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/rfc.yml @@ -0,0 +1,103 @@ +name: RFC (Design Document) +description: Propose a significant design change for team feedback +type: RFC +body: + - type: textarea + id: summary + attributes: + label: Summary + description: One paragraph explaining the proposal + placeholder: This RFC proposes... + validations: + required: true + + - type: textarea + id: problem + attributes: + label: "Motivation: Problem" + description: What problem does this solve? + placeholder: Currently, we have... + validations: + required: true + + - type: textarea + id: why-now + attributes: + label: "Motivation: Why Now?" + description: Why is this the right time? + placeholder: This is urgent because... + + - type: textarea + id: overview + attributes: + label: "Proposed Design: Overview" + description: High-level approach + placeholder: The proposed solution is to... + validations: + required: true + + - type: textarea + id: detailed-design + attributes: + label: "Proposed Design: Detailed Design" + description: Technical details, architecture, API design + placeholder: | + ## Architecture + + ## API Design + + ## MCP Protocol Considerations + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + placeholder: | + | Alternative | Pros | Cons | + |-------------|------|------| + | Option A | | | + | Option B | | | + + **Why this approach:** + + - type: textarea + id: phases + attributes: + label: "Implementation: Phases" + placeholder: | + 1. **Phase 1:** + 2. **Phase 2:** + + - type: textarea + id: dependencies + attributes: + label: "Implementation: Dependencies" + placeholder: List any dependencies or blockers + + - type: textarea + id: risks + attributes: + label: Risks & Mitigations + placeholder: | + | Risk | Mitigation | + |------|------------| + | | | + + - type: textarea + id: questions + attributes: + label: Open Questions + description: Questions for discussion + placeholder: | + - [ ] + - [ ] + + - type: textarea + id: references + attributes: + label: References + placeholder: | + - Related: # + - External: diff --git a/.github/ISSUE_TEMPLATE/spec.yml b/.github/ISSUE_TEMPLATE/spec.yml new file mode 100644 index 0000000..c346294 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/spec.yml @@ -0,0 +1,143 @@ +name: Technical Specification +description: Detailed design for a feature or system change +type: Spec +body: + - type: textarea + id: summary + attributes: + label: Summary + placeholder: One paragraph summary of the specification + validations: + required: true + + - type: dropdown + id: status + attributes: + label: Status + options: + - Draft + - Review + - Approved + - In Progress + - Complete + validations: + required: true + + - type: textarea + id: current-state + attributes: + label: "Problem Statement: Current State" + placeholder: What exists today? + validations: + required: true + + - type: textarea + id: desired-state + attributes: + label: "Problem Statement: Desired State" + placeholder: What should exist? + validations: + required: true + + - type: textarea + id: why-now + attributes: + label: "Problem Statement: Why Now?" + placeholder: Why is this the right time? + + - type: textarea + id: approach + attributes: + label: "Proposed Solution: Approach" + placeholder: High-level description of the solution + validations: + required: true + + - type: checkboxes + id: components + attributes: + label: Components Affected + options: + - label: Client (`/robosystems_client/`) + - label: API Methods + - label: Type Definitions (Pydantic models) + - label: Authentication + - label: Error Handling + - label: Tests (`/tests/`) + - label: Documentation + - label: CI/CD (`.github/workflows/`) + - label: Packaging (`pyproject.toml`) + + - type: textarea + id: key-changes + attributes: + label: Key Changes + render: text + placeholder: Describe key code changes, new files, or architectural changes + + - type: textarea + id: api-changes + attributes: + label: API Changes + render: python + placeholder: | + # New client methods or type changes + + - type: textarea + id: implementation + attributes: + label: Implementation Plan + placeholder: | + - [ ] **Phase 1:** + - [ ] **Phase 2:** + - [ ] **Phase 3:** + + **Dependencies:** + + **Migration strategy:** + validations: + required: true + + - type: textarea + id: testing + attributes: + label: Testing + placeholder: | + - [ ] Unit tests + - [ ] Integration tests + - [ ] Manual verification + + - type: textarea + id: rollout + attributes: + label: Rollout + placeholder: | + **PyPI version bump:** patch / minor / major + **Breaking changes:** + **Migration guide:** + + - type: textarea + id: success + attributes: + label: Success Criteria + placeholder: | + - [ ] + - [ ] + - [ ] + validations: + required: true + + - type: textarea + id: questions + attributes: + label: Open Questions + placeholder: | + - [ ] + + - type: textarea + id: references + attributes: + label: References + placeholder: | + - Related: # + - Docs: diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml new file mode 100644 index 0000000..b0a65d8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/task.yml @@ -0,0 +1,65 @@ +name: Task +description: A specific work item +type: Task +body: + - type: textarea + id: what + attributes: + label: What + description: What needs to be done? + placeholder: Describe the task... + validations: + required: true + + - type: textarea + id: why + attributes: + label: Why + description: Why is this needed? + placeholder: This is needed because... + validations: + required: true + + - type: textarea + id: affected + attributes: + label: Scope - Affected + description: What areas/files are affected? + placeholder: | + - [ ] + - [ ] + + - type: textarea + id: out-of-scope + attributes: + label: Scope - Out of Scope + description: What's explicitly NOT part of this task? + placeholder: | + - + + - type: textarea + id: acceptance + attributes: + label: Acceptance Criteria + description: How do we know when this is done? + placeholder: | + - [ ] + - [ ] + - [ ] + validations: + required: true + + - type: textarea + id: notes + attributes: + label: Notes + placeholder: Implementation hints or constraints... + + - type: textarea + id: related + attributes: + label: Related Issues + placeholder: | + - Parent: # + - Blocks: # + - Blocked by: # diff --git a/.gitignore b/.gitignore index 8e7a515..df35e9c 100644 --- a/.gitignore +++ b/.gitignore @@ -135,6 +135,9 @@ package-lock.json # npm package files *.tgz -#AI -.claude/ +# AI - Claude Code +.claude/settings.local.json CLAUDE.local.md + +.gemini/ +GEMINI.md