From 45955311910400ba18340aa13eb54268b797f7f8 Mon Sep 17 00:00:00 2001 From: "Joseph T. French" Date: Tue, 17 Nov 2026 00:41:30 -0600 Subject: [PATCH] chore(claude): remove the repo's Claude commands The maintainers' Claude Code workflows for this repository now live in one shared set kept outside the individual repositories, so the copies no longer drift apart across the RoboSystems repos. --- .claude/commands/create-issue.md | 99 ----------------------- .claude/commands/create-pr.md | 117 --------------------------- .claude/commands/pr-review.md | 130 ------------------------------ .claude/commands/publish.md | 75 ----------------- .claude/commands/release-notes.md | 65 --------------- .claude/commands/staged-review.md | 78 ------------------ .claude/commands/test.md | 55 ------------- 7 files changed, 619 deletions(-) delete mode 100644 .claude/commands/create-issue.md delete mode 100644 .claude/commands/create-pr.md delete mode 100644 .claude/commands/pr-review.md delete mode 100644 .claude/commands/publish.md delete mode 100644 .claude/commands/release-notes.md delete mode 100644 .claude/commands/staged-review.md delete mode 100644 .claude/commands/test.md diff --git a/.claude/commands/create-issue.md b/.claude/commands/create-issue.md deleted file mode 100644 index 7a60c41d..00000000 --- a/.claude/commands/create-issue.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -description: Create a GitHub issue from the repo's templates, with the right type and labels. -argument-hint: '[what the issue is about]' ---- - -Create a GitHub issue for the current repository based on the user's input. - -## Instructions - -1. **Check you're in the right repo first** - This is a **generated** SDK. `robosystems_client/api/` and `robosystems_client/models/` come from the RoboSystems API's OpenAPI document via `openapi-python-client`, and `robosystems_client/graphql/generated/` comes from `ariadne-codegen` over the checked-in `schema.graphql` plus the operation documents. A large share of apparent SDK bugs are really API bugs. Before filing here, work out which: - - A wrong or missing **type, field, or endpoint** almost always originates in the API's OpenAPI schema — file it in `RoboFinSystems/robosystems`. Regenerating here would only reproduce the same output. - - A bug in the **generation pipeline** — `bin/generate-sdk.sh` and its post-generation patches, `bin/generate-graphql.sh`, `bin/refresh-schema.py`, the `[tool.ariadne-codegen]` config in `pyproject.toml` — belongs here. - - A bug in **hand-written surface** — the typed facades under `robosystems_client/clients/`, `client.py`, `errors.py`, auth and token handling, the dataframe helpers — belongs here. - - A stale **GraphQL schema snapshot** is its own class: `schema.graphql` is checked in, so a drifted snapshot is a repo problem even though the schema itself lives in the API. - - When it's ambiguous, say which layer you think it is and why; a misfiled SDK issue costs a full round trip. - -2. **Determine Issue Type** - Based on the user's description, pick one: - - **Bug**: Defects or unexpected behavior - - **Task**: Specific, bounded work items that can be completed in one PR - - **Feature**: Request a new capability (no design required) - - **RFC**: Propose a design for discussion before implementation - - **Spec**: Approved implementation plan ready for execution - - Confirm what this repo actually offers before assuming — `ls .github/ISSUE_TEMPLATE/` for the templates and `gh issue create --help` for whether `--type` is supported. - -3. **Gather Context** - If the user provides a file path or references existing code: - - Read the relevant files to understand the current implementation - - Check whether the file is generated (`robosystems_client/api/`, `robosystems_client/models/`, `robosystems_client/graphql/generated/`) before proposing a fix in it - - Review any referenced documentation - -4. **Draft the Issue** - Read the matching YAML template in `.github/ISSUE_TEMPLATE/` and mirror its structure. Each template declares its own `type:` in frontmatter and marks which fields are required — read the file rather than guessing the sections. Fill the optional fields too where you have the information; they're the ones that make an issue actionable later. - - Note `gh issue create --title/--body` **bypasses templates entirely** — nothing prefills and nothing validates. That's exactly why the body has to be hand-matched to the template structure. - - For an SDK bug, the reproduction needs what a consumer report usually omits: the **installed version** (`pip show robosystems-client`), the **Python version** (the package supports 3.11–3.13), a **minimal call** showing the arguments passed, and the **actual vs expected** result. Include tracebacks verbatim, and say whether the sync or async path was used — they're separate code paths and a bug in one often isn't in the other. - -5. **Say whether it's a compatibility break** - This package is **post-1.0 and published on PyPI**, so external integrators pin against it. If the issue implies changing an existing signature, model field, or exported name, say so explicitly — that turns the fix into a **major** and forces coordination with the API and every consumer. Issues that quietly imply a break are the expensive ones. - -6. **Sanitize for Public Visibility** - This repo is public and the issue is world-readable immediately. Before creating: - - Remove API keys and JWTs — SDK repro snippets carry credentials more often than any other kind of issue. Check pasted tracebacks and request/response dumps line by line; an httpx traceback can include headers. - - Remove customer names, graph IDs, and real financial payloads; reconstruct with dummy values. - - Remove internal pricing, margins, or cost details. - - For anything security-adjacent, keep the text terse and non-actionable — no exploit mechanics, no endpoint enumerations, no payloads. For coordinated disclosure use a private GitHub Security Advisory, never a public issue. - - Keep ordinary technical implementation details (these are fine to share) - -7. **Create the Issue** - One command, with the type set inline: - - ```bash - gh issue create \ - --type \ - --title "" \ - --body-file /tmp/issue-body.md \ - --label "" - ``` - - No prefixes like `[SPEC]` in the title — the type handles categorization. Write the body to a file rather than inlining it, to avoid shell-escaping problems. - - To change the type on an **existing** issue: `gh issue edit --type ` (or `--remove-type`). - -## Labels - -Issue types handle primary categorization; labels carry the metadata. Always enumerate what actually exists rather than working from memory — and raise the limit, since the default truncates at 30: - -```bash -gh label list --limit 100 -``` - -The families to expect in this repo: - -- **`area:*`** — the primary routing dimension: `client` (the hand-written facades), `api` (the generated endpoint surface), `types`, `auth`, `errors`, `packaging` (build, wheel contents, dependency pins), `docs`, `testing`, `ci-cd`. **Always apply one.** -- **`priority:*`** — when to do it. Note the ladder is `critical` / `high` / `low` — there is **no `priority:medium`**. -- **`size:*`** — rough effort: `small` (< 1 day), `medium` (1–3 days), `large` (> 3 days). -- **Status** — `blocked`, `needs-review`. - -## Questions vs issues - -`.github/ISSUE_TEMPLATE/config.yml` disables blank issues and routes open-ended questions to the org's GitHub Discussions. `gh issue create` bypasses that chooser entirely, so apply the intent yourself: if the user's input is a question ("how do I authenticate?") rather than actionable work, say so and suggest a Discussion instead of filing it. - -## Example Usage - -User: "The graph query response model is missing the row count field" - -Response: Let me check whether that model is generated... - -[Read the model — if it's under `robosystems_client/models/`, it comes from the API's OpenAPI schema, so the fix belongs in robosystems unless the post-generation patches are dropping it] -[Read bug.yml and draft a body matching its structure, with version, Python version, minimal call, and the traceback] -[Create with `gh issue create --type Bug --label area:api,size:small`] - -## 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. Whether the fix implies a semver break, and any companion issue that should be filed against the API - -$ARGUMENTS diff --git a/.claude/commands/create-pr.md b/.claude/commands/create-pr.md deleted file mode 100644 index e9276d95..00000000 --- a/.claude/commands/create-pr.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -description: Open a pull request for the current branch, writing the description from the work actually done. -argument-hint: '[target-branch] [review]' ---- - -Create a GitHub pull request for the current branch, writing the title and description from the actual work done in this session — not reconstructed from the diff. - -## Why this command exists - -The previous flow outsourced PR-description authoring to a GitHub Action that only saw the diff and commit messages. It could not know _why_ the changes were made, so it frequently described things that weren't true. Those inaccurate descriptions then fed `@claude` reviews, compounding the bad information. This command fixes that at the root: **you author the description here, where the full context of what was done and why is available.** - -This is `robosystems-client` — a **published, post-1.0 Python SDK**, largely generated from the RoboSystems API's OpenAPI document and GraphQL schema. Its description is read by integrators deciding whether an upgrade is safe, so precision about the public surface matters more here than in an application repo. - -**This repository is public.** The PR title and body are world-readable the moment they're pushed — and, because publishing happens only when a release is dispatched rather than on merge, the text is often public well before the version that carries it. Treat the description as a publication. - -## Instructions - -### 1. Preflight - -Run these checks before touching anything: - -```bash -# Current and target branches -CURRENT=$(git branch --show-current) -TARGET=${1:-main} # override target via the first argument -``` - -- **Never PR from the default branch.** If `CURRENT` is `main` (or `master`/`staging`), stop and tell the user to switch to a feature branch first. New branches are created via `just create-feature `, not by hand. -- **Never target a release branch.** `release/` is a cut record that `create-release.yml` tags and publishes from; a PR into one changes nothing on `main` and is not a code review. Target `main`. -- **Source ≠ target.** If `CURRENT == TARGET`, stop. -- **Uncommitted changes.** Run `git status --porcelain`. If there are uncommitted/staged changes, surface them and ask whether to commit them (respecting the repo's commit rules — never on `main`, stage files by name, no `git add -A`) or proceed without them. The PR description must reflect committed state. -- **Existing PR.** Check `gh pr list --head "$CURRENT" --base "$TARGET" --json url,number`. If a PR already exists, do **not** create a duplicate — offer to update its title/body with `gh pr edit` instead. -- **Security fixes — check what's published.** A security-fix commit discloses the bug through its diff the moment it's pushed, and the vulnerable version stays installable from PyPI regardless. If this branch carries one, say which published versions are affected so the user can sequence a patch release with the disclosure. -- **Push the branch.** `gh pr create` requires the branch on the remote. Ensure it's pushed: `git push -u origin "$CURRENT"` (the user invoking `/create-pr` is the explicit, in-the-moment request that authorizes pushing _this feature branch_ — never push `main` or `release/*`). - -### 2. Gather the real change context - -This is the whole point — ground the description in what actually happened: - -- **Primary source: this session.** Use what was actually changed and why from the conversation context. This is the information the old GHA workflow never had. -- **Corroborate against the branch:** - ```bash - git log --oneline "$TARGET".."$CURRENT" # commits on this branch - git diff --stat "$TARGET"..."$CURRENT" # files + churn - git diff "$TARGET"..."$CURRENT" # full diff — read it, don't guess - ``` -- **Separate generated churn from real change.** A regeneration touches `robosystems_client/api/`, `robosystems_client/models/`, and `robosystems_client/graphql/generated/` wholesale; the meaningful diff is usually a handful of lines inside it plus whatever was hand-written. Summarize the generated part ("regenerated against API build X; net effect: two new endpoints, one widened union") rather than enumerating it, and never describe generated churn as if it were authored work. -- **Hard rule — no confabulation.** Every claim must be supported by the diff. If you didn't change the public API surface, don't write "new client methods." When the session context and the diff disagree, the diff wins and you investigate the discrepancy. - -### 3. Compose the PR - -- **Type** — derive from the branch prefix (`feature/` → feat, `bugfix/`/`fix/` → fix, `hotfix/` → fix, `chore/` → chore, `refactor/` → refactor). Default to `feat` if unprefixed. -- **Title** — concise (~50–72 chars), conventional-commit style with a scope, matching `git log` (e.g. `feat(ledger): add report bundle download support`, `chore(sdk): regenerate against report-bundle endpoint`). -- **Body** — markdown. **Match the headings in `.github/PULL_REQUEST_TEMPLATE.md`**, because `--body-file` bypasses template prefill entirely and a hand-written body silently drops whatever sections it omits: - - **Summary** — 1–3 sentences: what this PR does and why. - - **Changes** — bullets grouped by area: regenerated SDK vs. hand-written extensions vs. tooling/packaging. - - **Compatibility** — the section that matters most here. See below. - - **Testing** — state truthfully what was run. The gate is `just test-all` (pytest → `ruff format` → `ruff check` → `basedpyright`); `just test`, `just lint`, `just format`, and `just typecheck` run standalone. SDK regeneration needs a reachable API (`just generate-sdk`), so it often isn't runnable in-session — if you couldn't, say so plainly. If nothing was run, say "Not run" — never claim passing tests that weren't executed. - - The template has no Related Issues section — put `Closes #123` / `Fixes #456` as the last line of the Summary. GitHub links it from anywhere in the body. - -- **Compatibility is a required judgment, not an optional section.** This package is post-1.0 with external integrators, so classify the change explicitly and say which it is: - - **Breaking** — a removed or renamed export, a changed signature or return type, a narrowed input type, or changed runtime semantics. This forces a **major** and has to be coordinated with the API and with every consuming app. Say it plainly in the body; don't bury it in a bullet. - - **Additive** — new endpoints, new optional fields, new exports. Free, but worth naming so consumers know what they gain. - - **Internal** — generation tooling, tests, packaging that doesn't alter emitted types. - - A regeneration is not automatically additive: an API schema change can narrow a type or drop a field, and that reaches consumers as a break even though no hand-written line changed. Diff the emitted types before classifying. - -- **Version and publish are not this PR's job.** `create-release.yml` bumps the version on `main` and cuts `release/`, tags it, and publishes from the tag in the same run. Never bump the version in `pyproject.toml` in a feature PR and never imply the PR publishes anything. - -- **Security-fix disclosure.** If the PR fixes a security issue, the prose is often _more_ actionable than the diff — keep it terse and non-actionable. Name the area hardened, never the mechanism. No exploit mechanics, attack scenarios, endpoint enumerations, or payloads. For coordinated disclosure use a private GitHub Security Advisory, never a public issue. - -- **Attribution** — attribute to the user only. Do **not** add a "🤖 Generated with Claude Code" footer or a `Co-Authored-By: Claude` trailer. Include such a line only if the user explicitly asks. - -### 4. Create the PR - -Write the body to a temp file to avoid shell-escaping problems, then: - -```bash -gh pr create \ - --base "$TARGET" \ - --head "$CURRENT" \ - --title "" \ - --body-file /tmp/pr-body.md -``` - -Print the resulting PR URL. - -### 5. Optional Claude review - -Only if the user explicitly asks (e.g. passes `review` / `--review` in arguments), request a review: - -```bash -gh pr comment <number> --body "@claude please review this PR" -``` - -`claude.yml` only fires on an `@claude` mention from an `OWNER`/`MEMBER`/`COLLABORATOR`, so nothing happens automatically. Leave it off by default. - -## Output - -After creating the PR, report: - -1. The PR URL. -2. A one-line summary of the title. -3. Target ← source branches. -4. The compatibility classification (breaking / additive / internal), and if breaking, what a consumer has to change. -5. Whether a Claude review was requested. - -## Arguments - -`$ARGUMENTS` may contain: - -- A target branch (default `main`). -- `review` / `--review` to auto-request a `@claude` review. -- Freeform guidance on what to emphasize in the description. - -$ARGUMENTS diff --git a/.claude/commands/pr-review.md b/.claude/commands/pr-review.md deleted file mode 100644 index 198580f8..00000000 --- a/.claude/commands/pr-review.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -description: Review a pull request — gather metadata, diff, and existing feedback, then give a verdict. -argument-hint: '[pr-number-or-url]' ---- - -Review a pull request by gathering all PR metadata, diff, and review comments, then provide a comprehensive review summary. - -## Instructions - -### 1. Identify the PR - -The user may provide a PR URL, number, or nothing: - -- **URL provided** (e.g., `https://github.com/RoboFinSystems/robosystems-python-client/pull/42`): Extract the repo and PR number -- **Number provided** (e.g., `42`): Use the current repository -- **Nothing provided**: Detect from the current branch using `gh pr view --json number,url` — if no open PR exists for the current branch, ask the user which PR to review - -### 2. Gather PR Data - -Run these `gh` commands to collect all context: - -```bash -# PR metadata + conversation comments in one call -gh pr view <NUMBER> --json number,url,title,body,author,state,isDraft,labels,comments,reviews,reviewDecision,latestReviews,reviewRequests,statusCheckRollup,mergeStateStatus,headRefName,headRefOid,baseRefName,additions,deletions,changedFiles,files,closingIssuesReferences,createdAt,updatedAt - -# PR diff (the actual code changes) -gh pr diff <NUMBER> - -# Inline review comments — no --json equivalent exists, so this call is still required -gh api repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/pulls/<NUMBER>/comments --paginate -``` - -**Field notes:** - -- `reviews` not `reviewers` — `reviewers` is not a valid field and errors. -- `reviewDecision` is the single field that answers "has this been approved." -- `comments` covers the top-level conversation, so no separate `issues/<n>/comments` call is needed. -- `files` is essential here: a regeneration PR is mostly generated churn, and per-file add/delete counts are how you find the few hand-written files worth reading closely. -- Keep `--paginate` **bare**. Adding `-q`/`--jq` makes gh emit one JSON document _per page_ instead of a merged array, and `--slurp` can't be combined with `--jq`. Pipe to `jq` after the call, not through it. - -### 3. Categorize Review Feedback - -Organize all comments and checks into categories: - -- **Human Reviews**: Comments from human reviewers (approve, request changes, general feedback) -- **AI Reviews**: Comments from Claude, Copilot, or other AI review bots -- **Code Quality**: Comments from linters, formatters, type checkers -- **Security**: Findings from security scanners (Dependabot, CodeQL) -- **CI/CD**: Build status, test results - -**How feedback actually arrives in this repo** — don't read the categories too literally: - -- Formal `reviews` and inline `pulls/<n>/comments` are typically **empty**, and `reviewDecision` is usually blank. That's the norm here, not a signal that review was skipped. Don't report "no review feedback" on the strength of an empty `reviews` array. -- **AI review is opt-in.** `claude.yml` only fires on an explicit `@claude` mention from an `OWNER`/`MEMBER`/`COLLABORATOR` — there is no automatic review on PR open. When it has run, the findings are a **bot comment in the conversation `comments`**, not a formal review. -- In `statusCheckRollup`, checks expose `.name` while legacy statuses expose `.context`, and a `conclusion` of `NEUTRAL` or `SKIPPED` is not a failure. Read the conclusion, don't pattern-match on non-`SUCCESS`. -- Note what CI does **not** cover: it cannot regenerate against a live API, so a stale SDK passes every check. Green CI means "this code is internally consistent," not "this matches the API." - -### 4. Review the Diff - -With the full PR diff in hand, perform your own review focusing on: - -- **Compatibility first.** This is a published post-1.0 package with external integrators. Does the diff remove or rename an export, change a signature or return type, narrow an input type, or change runtime semantics? That's a **major** and needs coordination with the API and every consuming app — an uncoordinated break is a blocking issue, not a note. Additive fields and new optional model fields are free. Check the emitted model and signature surface, not just the diff shape: a regeneration can turn an optional field required, or drop one, without a single hand-written line changing. -- **Generated vs. hand-written.** Is anything under `robosystems_client/api/`, `robosystems_client/models/`, or `robosystems_client/graphql/generated/` edited by hand? That's always wrong — the next `just generate-sdk` / `just generate-graphql` erases it. The fix belongs in `bin/generate-sdk.sh`'s post-generation patches, in the `[tool.ariadne-codegen]` config in `pyproject.toml`, or in the API's schema. Flag it as blocking. -- **Schema snapshot drift.** `robosystems_client/graphql/schema.graphql` is a checked-in snapshot that the GraphQL operation tests validate against. If operations changed without a `just refresh-schema`, or the snapshot moved without the operations being re-checked, say so — a stale snapshot makes those tests assert against a schema the API no longer serves. -- **Does the regeneration match a real API state?** A regeneration PR should say what API version or build it was generated against. Types that don't correspond to any deployed API are worse than stale ones. -- **Correctness**: does the code do what the PR description says? -- **Auth and secrets**: token handling, header construction, and anything that could log a credential. A `console.log` of a request object is a credential leak in a consumer's terminal. -- **Error handling**: are API errors mapped to something a consumer can branch on, or swallowed into a generic throw? -- **Exports**: is new surface actually exported from the package `__init__.py` files, and are the models importable from where the README says they are? Unexported surface is invisible to consumers regardless of how well it's written. -- **Sync and async parity**: the client exposes both paths. A fix or a new method applied to only one of them is a half-fix — check that the other got the same treatment and the same test. -- **Packaging**: changes to `pyproject.toml` — dependency pins, optional extras, `requires-python`, included packages, `py.typed` — affect what ships and who can install it. A dropped `py.typed` or a too-narrow `requires-python` breaks consumers in ways no test here catches. -- **Tests**: are changes covered? Read the test, don't trust that it's green — a test that asserts the buggy behavior passes just as happily as a correct one. -- **Disclosure hygiene** (this repo is public): does the PR _text_ over-disclose? A security-fix description should name the area hardened, never the mechanism. Note also that the vulnerable version stays installable from PyPI after the fix merges — flag whether a patch release is needed. -- **Missing changes**: a new endpoint without an export, a new option without a type, a behavior change without a README update. - -### 5. Output Format - -Provide a structured review: - -``` -## PR Summary -**Title**: ... -**Author**: ... | **Branch**: ... → ... -**Status**: ... | **Changes**: +X / -Y across Z files (generated: A / hand-written: B) - -<Brief summary of what the PR does> - -## Compatibility -<BREAKING / ADDITIVE / INTERNAL — and for breaking, exactly what a consumer must change> - -## Existing Review Feedback - -### Human Reviews -<Summarize human reviewer comments and their status> - -### AI Reviews -<Summarize AI review comments — highlight unresolved items> - -### Code Quality -<Summarize code quality bot findings> - -### Security -<Summarize security scanner findings — flag anything critical> - -### CI/CD Status -<Pass/fail status of all checks> - -## My Review - -### Issues (should fix before merge) -<Numbered list of problems found> - -### Suggestions (non-blocking improvements) -<Numbered list of suggestions> - -### Questions -<Anything unclear that needs clarification> - -## Verdict -<APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION — with brief rationale> -``` - -### Notes - -- For a large regeneration diff, use the `files` array to separate generated paths from hand-written ones and review the latter line by line; summarize the former by net effect on the public surface -- For security findings, always err on the side of flagging — false positives are better than missed vulnerabilities -- Cross-reference the PR description with the actual diff to catch scope creep or an unstated break -- If the PR references an issue (`closingIssuesReferences`), check that the issue requirements are met - -$ARGUMENTS diff --git a/.claude/commands/publish.md b/.claude/commands/publish.md deleted file mode 100644 index 736d2a01..00000000 --- a/.claude/commands/publish.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: Monitor a release/publish run — diagnose failures, verify the package actually landed on PyPI. -argument-hint: '[run-id]' ---- - -Monitor a release and publish run — pinpoint why it failed, and confirm the version actually landed on PyPI. Releases go through GitHub Actions; this command is about watching and diagnosing them, not replacing the pipeline. - -## How a release actually happens here - -One workflow, `create-release.yml` (`workflow_dispatch`, or `bin/create-release.sh`), with three jobs in sequence: - -1. **`create-release`** — reads the current version from `pyproject.toml`, computes the next one from the requested bump, commits the bump **to `main`**, and cuts `release/<version>` from that commit. -2. **`create-tag`** — `tag-release.yml` tags that branch and cuts the GitHub Release. -3. **`publish`** — runs once the tag exists, under the `production` environment, so its required-reviewer prompt lands on this same run. It checks out the tag, verifies the version is the one just cut, builds the distribution, checks the PyPI JSON API for that version, and if it isn't there, publishes over OIDC trusted publishing. PyPI's trusted publisher is registered against `create-release.yml` and the `production` environment. - -So: **merging a PR to `main` publishes nothing.** Dispatching the workflow is the publishing event, and nothing uploads until the deployment is approved on the run page. A failed publish is retried with **Re-run failed jobs** on that run — the version and tag are already cut, and a new release is warranted only when the code itself is at fault. The job refuses a version that already exists on PyPI, so a re-run after a successful upload fails at the existence check rather than uploading twice. Note the build step runs *before* that check, so a green build tells you nothing about whether a publish happened. - -`tag-release.yml` writes the GitHub release body separately; see `/release-notes` for the curated-notes override. - -## Scope & guardrails - -- **`gh` reads are free; triggering a release is not.** Reading runs, jobs, and logs (`gh run list/view/watch`) needs no confirmation. **Dispatching `create-release.yml`** is an outward-facing and effectively irreversible action — a PyPI version can be yanked but **never** re-uploaded, so a bad publish burns that version number permanently. Confirm the bump type and the ref with the user, and default to watching a run they already started. -- **Never bump the version in `pyproject.toml` by hand.** The workflow owns the bump; a hand-bump collides with it and can produce a version that's tagged but never published. -- **Never push `main` or `release/*`.** Those are the user's. The pre-push hook blocks them. -- **The user owns the decision to publish a major.** A major reaches every consuming app and every external integrator. If the change set implies one, say so and stop — don't dispatch. - -## 1. Find the run - -```bash -gh run list --workflow=create-release.yml --limit 5 -gh run view <run-id> -gh run watch <run-id> # live, if it's in flight -``` - -## 2. Pinpoint the failure - -```bash -gh run view <run-id> --log-failed -``` - -Classify by stage: - -- **`create-release.yml` — branch already exists.** The workflow checks for `release/<version>` before creating it. A failure here usually means a previous run got partway, and the fix is to resolve the leftover branch, not to re-dispatch blindly. -- **`create-release.yml` — push to `main` rejected.** The version bump commits directly to a protected branch and needs `ACTIONS_TOKEN`; a permissions failure here looks like an auth error at the push step. -- **`publish` — waiting.** The job is paused on the `production` environment's required reviewer. Nothing is wrong; approve it from the run page (_Review deployments_). -- **`publish` — "checked out version X, expected Y".** The tag the job checked out does not carry the version this run cut. Nothing was uploaded; look at what `create-tag` tagged. -- **`publish` — "version exists on PyPI".** The job fails at the existence check and uploads nothing. After a successful publish this is the expected result of a re-run; otherwise the version wasn't bumped. -- **`publish` — build.** `pip install build twine` then `python -m build`. A build failure here is a packaging problem — usually `pyproject.toml` metadata or a missing file — that the test suite does not cover, since `just test-all` never builds a distribution. -- **`publish` — the upload.** OIDC trusted publishing. Failures are usually the PyPI-side trusted-publisher configuration (the publisher must name `create-release.yml` and the `production` environment) rather than anything in the code. - -## 3. Verify it actually landed - -A green workflow is not proof. Check PyPI directly: - -```bash -curl -s https://pypi.org/pypi/robosystems-client/json | jq -r '.info.version' # latest -curl -s https://pypi.org/pypi/robosystems-client/json | jq -r '.releases | keys[]' # history -``` - -Then confirm the published artifact is usable, since packaging problems don't fail the upload: - -```bash -pip download robosystems-client==<version> --no-deps -d /tmp/verify # fetch the wheel -unzip -l /tmp/verify/robosystems_client-<version>-*.whl | head -30 # what actually ships -``` - -Check `py.typed` is present in that listing — its absence turns the SDK untyped for every consumer and nothing in CI catches it. - -If the version is a major, downstream consumers need coordinated adoption — say so rather than treating the publish as the end of the task. External integrators pin against this package, so a major is a support event, not just a release. - -## Output - -A short status: which job, what failed and at which step, the root cause, the re-run link if any, and the verified published version from PyPI. If nothing failed, say so — don't manufacture work. - -$ARGUMENTS diff --git a/.claude/commands/release-notes.md b/.claude/commands/release-notes.md deleted file mode 100644 index fb906bf3..00000000 --- a/.claude/commands/release-notes.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: Draft curated release notes for an SDK release. -argument-hint: '[version]' ---- - -Draft curated release notes for an upcoming release, following the convention in `.github/release-notes/README.md`. - -## Why this command exists - -`tag-release.yml` generates release bodies from the changes since the last tag. That suits routine releases but reads poorly for a milestone, where the story is what the version _is_. For a published SDK it is worse than poor: post-1.0 the notes **are** the compatibility contract that integrators read before upgrading, and a generated changelog does not state what is additive, what is deprecated, or when a deprecation is removed. This command encodes the review and hygiene checks that keep the notes accurate and safe to publish. - -## Instructions - -### 1. Decide whether to curate at all - -Unlike the application repos, curation here is not optional across the board. Curated notes are **mandatory for a major, and for any minor that deprecates public surface** — those notes carry the contract. A minor that is purely additive and a plain patch can keep the generated changelog; skipping is a normal outcome in those cases, not a failure. If the user invoked this command for a patch, confirm they still want curated notes. - -### 2. Establish the version and the range - -- The target version comes from the argument (e.g. `/release-notes 1.2.0`). If none was given, ask what version the user intends to tag — the filename must match the eventual tag exactly, and a mismatched file is silently ignored. Derive it from the current `pyproject.toml` version plus the bump type the user will dispatch (`1.1.0` + `minor` → `1.2.0`). -- **Never bump the version yourself.** `create-release.yml` bumps `pyproject.toml` on `main` as its first step and derives the tag from the result — a hand-bump collides with it. -- **The version is a promise, so sanity-check the bump type against the diff.** If the range contains a removal, a rename, or a semantic change to existing surface, a minor is the wrong bump — stop and raise it before writing a line of prose. -- **The range depends on the release kind.** A major or a surface-deprecating minor covers the span since the previous release of that significance; an ordinary curated release covers the span since the last tag: - -```bash -LAST=$(git tag --sort=-creatordate | head -1) # ordinary: last tag -# major/minor: the previous major or minor tag, e.g. v1.0.0 when cutting v1.2.0 -git log "$RANGE_START"..origin/main --merges --format='%s' -gh pr list --state merged --limit 30 --json number,title,mergedAt -``` - -Note the generated links section will still compare against the last tag; the prose should state the span it covers explicitly. - -### 3. Review the changes for real - -Do not write notes from commit subjects alone. Read the PR bodies (`gh pr view <n>`) and spot-check diffs where the description is thin. Classify everything into public-surface changes, fixes, and internals, then check specifically: - -- **The compatibility contract.** This is the load-bearing check. The public surface is the one defined in `CLAUDE.local.md` — the facades (`clients/*`), root exports, documented models, error classes, and auth config; generated internals are exempt unless they show up in a facade signature or doc. For every change to it, decide which bucket it is in and say so in the notes: **added** (free, rides a minor), **deprecated** (must name the replacement and the earliest removal major), **removed** (majors only, and only after a deprecation shipped at least one further minor and 90 days earlier), or **changed semantics** (a break, even when the signature is untouched). The integration template pins the current major, so anything in the last two buckets breaks real consumers. -- **Regeneration vs. hand edits.** Most of `robosystems_client/` is generated by `just generate-sdk` from the API's OpenAPI spec, and the typed GraphQL models by ariadne-codegen from the checked-in `schema.graphql`. A regeneration that widens the surface is worth a sentence about what the API added — not a per-model enumeration. Say plainly when a release is a regeneration, and don't dress generated-internal churn up as new capability. -- **Upstream API coupling.** A regeneration tracks a specific RoboSystems API version. If the new surface only works against an API that isn't deployed yet, the notes must say so — integrators will call it the day they upgrade. -- **Runtime and dependency floors.** A raised Python floor or a dependency major is an upgrade blocker for someone. Note it. - -### 4. Security disclosure review - -This repo is public and the release publishes to PyPI in the same run, so the notes are world-readable immediately and are read by everyone upgrading. For any security-adjacent change: - -- Keep the line at PR-title neutrality: what area was hardened, never how or against what. -- No exploit mechanics, no affected-endpoint enumerations, no detection signatures or thresholds, no "previously protected only by X" tells. -- Never paste content from private analysis documents into the notes. -- Say clearly that upgrading is recommended, without describing the exposure. -- When in doubt, terser. - -### 5. Write the file - -Write `.github/release-notes/v<version>.md` — **body only**: - -- No `# RoboSystems Python SDK v<version>` heading, no release-statistics section, no links section, no generated-with footer. The workflow supplies all of those. Start at the first line of prose. -- `v1.0.0.md` is a good model for the format. -- Lead with one or two sentences saying what the version is. Then, for anything touching the public surface, a section per contract bucket — added / deprecated / removed / changed — ahead of the ordinary fixes and internals. Ground every line in a change you actually reviewed. - -### 6. Hand off — sequencing matters - -The file must exist **at the tagged ref**, and there is no window to add it late: `create-release.yml` bumps the version on `main`, cuts `release/<version>` from the result, and tags it in the same run. The same run then publishes from that tag, so by the time the package is on PyPI the notes are already fixed. They have to be **merged into `main` before the workflow is dispatched**. - -Write the draft on a feature branch (created via `just create-feature`), never on `main`. Present it for review and leave the merge and the dispatch to the user. diff --git a/.claude/commands/staged-review.md b/.claude/commands/staged-review.md deleted file mode 100644 index 51cffe63..00000000 --- a/.claude/commands/staged-review.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -description: Review the staged diff against this SDK's compatibility, generation, and packaging rules. ---- - -Review all staged changes (`git diff --cached`) with focus on the contexts below. Read the diff first — if nothing is staged, say so rather than reviewing the working tree. - -This is `robosystems-client`: a **published, post-1.0 Python SDK**, largely generated from the RoboSystems API's OpenAPI document and GraphQL schema, consumed by internal tooling and external integrators. It is a **public repository**. - -## Before anything else: is this file generated? - -```bash -git diff --cached --name-only -``` - -`robosystems_client/api/`, `robosystems_client/models/`, and `robosystems_client/graphql/generated/` are **generation output**. A hand edit there is erased by the next `just generate-sdk` / `just generate-graphql` — that's a blocking finding regardless of how correct the edit is. The fix belongs in one of: - -- `bin/generate-sdk.sh` — the post-generation patches applied to `openapi-python-client` output -- `[tool.ariadne-codegen]` in `pyproject.toml`, or the operation documents under `robosystems_client/graphql/operations/` — GraphQL generation inputs -- `robosystems_client/graphql/schema.graphql` — the checked-in schema snapshot, refreshed with `just refresh-schema` against a running backend -- the API's OpenAPI or GraphQL schema, in `RoboFinSystems/robosystems` — where wrong types actually originate - -If the staged diff mixes regenerated output with hand-written change, say which files are which; that distinction drives the rest of the review. - -## Compatibility (the section that decides the verdict) - -Post-1.0, the emitted type surface **is** the contract. For anything staged here: - -- Is an export removed or renamed? A signature or return type changed? An input type narrowed? Runtime semantics altered? Each is a **major**, requires coordination with the API and every consuming app, and must be stated explicitly rather than discovered by an integrator. -- Is it additive — new endpoints, new optional fields, new exports? Free, but name it. -- **A regeneration is not automatically safe.** An API schema change can turn an optional field required, or drop one, so the diff reaches consumers as a break with no hand-written line involved. Compare the emitted model and signature surface, not the diff shape. -- Does new surface appear in the package `__init__.py` exports, importable from where the README says it is? Unexported surface may as well not exist. -- Is the change applied to **both** the sync and async paths? A fix landed on one is a half-fix. - -## SDK implementation - -- Are new methods fully typed, with no `Any` used to silence `basedpyright`? -- Do the typed facades under `robosystems_client/clients/` follow the existing patterns rather than inventing a second style? -- Is error handling consistent — are API errors mapped to something a consumer can branch on, not swallowed into a generic throw? -- Are request/response types the generated models rather than hand-redeclared shapes that will drift? - -## Auth and secrets - -- Token and header handling: is anything logged, stringified into an exception message, or attached where it could surface in a consumer's traceback? An httpx error that carries request headers is a credential leak downstream. -- Are credentials read from configuration rather than defaulted to anything real? -- No API keys, JWTs, real graph IDs, or customer payloads in tests, fixtures, or comments. Fixtures should be invented. - -## Packaging - -- Changes to `pyproject.toml` — dependency pins, optional extras, `requires-python`, included packages, `py.typed` — change **what ships and who can install it**. A dropped `py.typed` silently turns a typed SDK into an untyped one for every consumer; a narrowed `requires-python` locks out supported versions (3.11–3.13). -- Never stage a version bump in `pyproject.toml` in a feature branch: `create-release.yml` owns the bump on `main` and publishes from the tag it cuts. - -## Testing - -- Do new methods have tests, including the error paths? -- Do tests exercise the public surface as a consumer would import it, rather than reaching into internals? -- Is the test asserting correct behavior, or just asserting what the code currently does? - -## Documentation - -- Is the README updated for new or changed surface? For a published package this is the primary integrator documentation. -- Are JSDoc comments present on new public methods, and accurate on changed ones? They surface in consumers' editors. -- Does a breaking change come with the migration line an integrator needs? - -## Public-repo hygiene - -- No customer names, graph IDs, internal cost/pricing detail, or real financial payloads in code, comments, or fixtures. -- If the change fixes a security issue, keep commit messages and comments terse and non-actionable — the area hardened, never the mechanism. Remember the vulnerable version stays installable from PyPI until a patch is published. - -## Output - -Provide a summary with: - -1. **Compatibility**: BREAKING / ADDITIVE / INTERNAL, with what a consumer must change if breaking -2. **Issues**: Problems that should be fixed before commit -3. **Suggestions**: Improvements that aren't blocking -4. **Questions**: Anything unclear that needs clarification - -Anchor each finding to `file:line`. If the staged diff is clean, say so plainly rather than manufacturing findings. diff --git a/.claude/commands/test.md b/.claude/commands/test.md deleted file mode 100644 index 05bdffac..00000000 --- a/.claude/commands/test.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -description: Run the full test and code-quality gate, fixing failures to green. -argument-hint: '[test-file-or-path]' ---- - -Run `just test-all` and systematically fix all failures to achieve 100% completion. - -## Timeouts - -Always use `timeout: 600000` (10 minutes) on Bash calls for `just test-all`. The default 2-minute Bash timeout is too short for the full suite. - -## Strategy - -1. **Run full suite first**: use the grep pattern below to extract the signal — pytest prints per-test output that can bury the summary. -2. **Fix in the order `test-all` runs**: pytest → format → lint → typecheck. The script short-circuits on the first failure, so fix that layer before re-running. -3. **Iterate on the failing layer only** before re-running the full suite (see Key Commands below). -4. **Stop when done**: once `just test-all` passes, stop immediately. Do NOT re-run to "confirm." - -## Output Handling - -**`just test-all` runs pytest FIRST, then format, lint, typecheck.** With `| tail -N`, you only see the end (typecheck output) — the pytest summary scrolls away. Always filter: - -``` -just test-all 2>&1 | grep -E "passed|failed|error:|FAILED|warnings summary|^= " | tail -20 -``` - -This captures: pytest result line ("X passed, Y failed"), any FAILED test names, ruff errors, and basedpyright errors. Absence of "failed" or "FAILED" AND presence of "passed" means success — stop there. - -For single-layer commands (below), output is short enough that `| tail -20` alone works. - -## Key Commands - -**Full suite:** - -- `just test-all` — pytest + format + lint + typecheck - -**Iteration (one layer at a time):** - -- `uv run pytest path/to/test.py` — run a single test file (fastest feedback) -- `just test` — pytest only -- `just lint` — ruff check + ruff format --check (no auto-fix) -- `uv run ruff check . --fix` — ruff auto-fix -- `just format` — ruff format (auto-write) -- `just typecheck` — basedpyright - -## Notes - -- **`just test-all` mutates the working tree.** It runs `just format` (`ruff format .`, auto-write) between pytest and the lint check, so a green run can still leave modified files. Check `git status` afterwards and stage what it rewrote — the pre-commit hook runs check-only commands (`ruff check`, `ruff format --check`, `basedpyright`, `pytest`) and fails on exactly those files. -- **Never hand-fix a failure inside generated code.** `robosystems_client/api/`, `robosystems_client/models/`, and `robosystems_client/graphql/generated/` are generation output; an edit there is erased by the next `just generate-sdk` / `just generate-graphql`. The fix belongs in `bin/generate-sdk.sh`'s post-generation patches, in the `[tool.ariadne-codegen]` config in `pyproject.toml`, or in the API's schema. -- **Regeneration needs a reachable API; the GraphQL half doesn't.** `just generate-sdk` fetches the OpenAPI document from a running backend and also refreshes the checked-in `schema.graphql` snapshot. `just generate-graphql` is hermetic — it runs `ariadne-codegen` against that checked-in snapshot plus the operation documents, so it works offline but only reflects the API as of the last `just refresh-schema`. A GraphQL operation test failing after an API change usually means the snapshot is stale, not that the operation is wrong. -- **`just test-all` never builds a distribution.** Packaging problems (`pyproject.toml` metadata, missing `py.typed`, a wrong `requires-python`) pass the whole gate and fail at publish time. Use `just build-package` when the change touches packaging. - -## Goal - -100% pass on `just test-all` with no errors of any kind. Efficiency matters — don't re-run the full suite until you've fixed all known issues in the current layer.