Fix tools create to use the BC5 create-by-type API (#471)#553
Conversation
`basecamp tools create` 404'd: it was modeled on the removed account-scoped
clone endpoint (`POST /dock/tools.json` with `source_recording_id`). bc3's
BC5 lineage replaced dock-tool creation with a bucket-scoped create-by-type
call, `POST /buckets/{bucket_id}/dock/tools.json` with `{tool_type, title?}`.
- Bump the SDK to f2086f5e (basecamp-sdk#327), which reshapes ToolsService.Create
to (bucketID, toolType, *CreateToolOptions) and posts to the bucket dock.
- Remove `--source`/`--clone` (they only ever 404'd); record the removal in
`.surface-breaking`.
- Add `--type`/`-t` (required), normalized against the CLI's existing dock
vocabulary and tolerant of degenerate spellings. A single ordered `toolTypes`
slice is the source of truth for normalization, `--type` completion, and the
unknown-type error listing. `board` is rejected as ambiguous.
- Resolve and send a real destination bucket (the 404 root cause: `--in` was
breadcrumb-only). New `resolveToolBucketID` mirrors `resolveColumnBucketID`.
- Guard a stray second positional with `cobra.MaximumNArgs(1)`.
- Fix stale "clone" prose in the parent and create help and agent_notes.
Create-by-type is BC5-only; against BC4 the API rejects it and the error
surfaces via convertSDKError.
Closes #471
github-actions
Bot
added
commands
Review carefully before merging. Consider a major version bump. |
There was a problem hiding this comment.
Pull request overview
Fixes basecamp tools create (previously returning 404) by switching from the removed account-scoped clone endpoint to the BC5 bucket-scoped create-by-type API, and ensuring the resolved project bucket ID is actually sent to the SDK/API.
Changes:
- Update
tools createto require--type/-t, normalize accepted type spellings, and callToolsService.Create(ctx, bucketID, toolType, opts)against/buckets/{bucket_id}/dock/tools.json. - Resolve a real destination bucket ID (flag > global flag > config > interactive), and reject extra positionals via
cobra.MaximumNArgs(1). - Update unit/e2e coverage and CLI surface artifacts to reflect the flag contract change; bump the SDK revision + provenance.
Tip
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| internal/version/sdk-provenance.json | Records the bumped SDK revision and updated API sync metadata. |
| internal/commands/tools.go | Implements create-by-type with type normalization + real bucket resolution. |
| internal/commands/tools_test.go | Adds targeted unit tests for type validation, normalization, bucket selection, request shape, and completion ordering. |
| go.mod | Bumps github.com/basecamp/basecamp-sdk/go to the revision that supports create-by-type. |
| go.sum | Updates module checksums for the SDK bump. |
| e2e/smoke/smoke_tools.bats | Updates smoke test to use --type message_board and removes clone precondition. |
| .surface-breaking | Records removal of --source/--clone as breaking surface changes. |
| .surface | Updates the CLI surface snapshot to remove --source/--clone and add --type. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Bare "board" (and separator variants) is intentionally rejected — it's ambiguous between message_board and kanban_board. Report that specifically instead of the generic "Unknown --type" wording, while still listing the accepted values. Addresses Copilot review feedback on #553.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1e42b77d66
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
- Build the create --type help text and the parent agent_notes accepted-type list from toolTypeFriendlyNames() instead of hard-coding them, so help stays in sync with validation and completion (Copilot + cubic review feedback). - API-COVERAGE.md: correct the stale "v0.7.3 / no new methods" line to reflect the f2086f5e bump and the BC5 create-by-type reshape, and add the previously uncounted dock_tools row (Codex P2 feedback).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fd3835e9a2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | todolists | 8 | `todolists` | ✅ | BC4 | - | list, show, create, update | | ||
| | todosets | 3 | `todosets` | ✅ | BC4 | - | Container for todolists, accessed via project dock (BC5: `todos_count`, `completed_loose_todos_count`, `todos_url`, `app_todos_url`) | | ||
| | todolist_groups | 8 | `todolistgroups` | ✅ | BC4 | - | list, show, create, update, position | | ||
| | dock_tools | 7 | `tools` | ✅ | BC4 | - | Dock tool management: show, update, trash, enable, disable, reposition. `create` is BC5-only (create-by-type: `POST /buckets/{id}/dock/tools.json`), replacing the removed clone call | |
There was a problem hiding this comment.
The coverage guide above says BC5 endpoints added to an existing BC4 section should be split into a separate BC5 row, but this new dock_tools row counts all 7 endpoints as BC4 while also noting that create is BC5-only. That makes the BC4/BC5 parity matrix ambiguous because the BC4 row now includes a BC5-only endpoint; please split create-by-type into a BC5 dock_tools row or keep the BC4 count limited to the BC4 endpoints.
Useful? React with 👍 / 👎.
|
|
||
| cmd.Flags().StringVarP(&sourceID, "source", "s", "", "Source tool ID to clone (required)") | ||
| cmd.Flags().StringVar(&sourceID, "clone", "", "Source tool ID (alias for --source)") | ||
| cmd.Flags().StringVarP(&toolType, "type", "t", "", "Tool type to create (required)") |
There was a problem hiding this comment.
Adding required --type and removing --source/--clone changes the command surface, but skills/basecamp/SKILL.md was not updated and still advertises Full CLI coverage: 155 endpoints with no tools-create guidance. Agents that rely on the skill can keep using stale coverage/syntax after this change; update the skill alongside the surface change.
Useful? React with 👍 / 👎.
Summary
basecamp tools createreturned a 404 (#471). It was modeled on the removed account-scoped clone endpoint (POST /dock/tools.jsonwithsource_recording_id). bc3's BC5 lineage replaced dock-tool creation with a bucket-scoped create-by-type call:POST /buckets/{bucket_id}/dock/tools.jsonwith{tool_type, title?}.This is the CLI follow-up to basecamp-sdk#327, which already reshaped the Go SDK to the new contract.
Changes
f2086f5e(PR Replace "pending" with "incomplete" in todos output; omit from default view #327 merge,v0.7.4-0.20260722082856-f2086f5e57f6). Pinned explicitly to Replace "pending" with "incomplete" in todos output; omit from default view #327 rather than SDKmain, which has since added an uncovered operation (Campfires.UpdateLine) that would trip the completeness bar.ToolsService.Createis now(ctx, bucketID, toolType, *CreateToolOptions).--source/--clone(they only ever 404'd); the removal is recorded in.surface-breaking.--type/-t(required), normalized against the CLI's existing dock vocabulary and tolerant of degenerate spellings (message-board,messages,Message::Board→Message::Board). A single orderedtoolTypesslice is the source of truth for normalization,--typeshell completion, and the unknown-type error listing — so the three can't drift. Bareboardis rejected as ambiguous (message vs kanban).--in/--projectwas breadcrumb-only and never reached the API. NewresolveToolBucketIDmirrorsresolveColumnBucketID(flag > global flag > config > interactive).cobra.MaximumNArgs(1)guards a stray second positional instead of silently dropping it.agent_notes.Types accepted
chat,inbox,kanban_board,message_board,questionnaire,schedule,todoset,vault(plus canonical class-names and common aliases).Testing
bin/cigreen (fmt/vet/lint, unit + e2e, surface, skill-drift, provenance, tidy).--typerequired (no request issued), unknown-type rejection with ordered friendly list (no request), full 8-type normalization table +boardrejection, extra-positional rejection, explicit-project-wins-and-is-sent (asserts/{account}/buckets/{bucket}/dock/tools.json), missing-project, title propagation, happy-path 201, and completion ordering.--type message_board;ensure_messageboardprecondition removed (create-by-type must succeed with no preexisting Message Board).Notes
convertSDKError. The SDK api-gaps registry tracks the BC4/BC5 split.Closes #471
Summary by cubic
Fixes
basecamp tools createby switching to the BC5 bucket-scoped create-by-type API and sending the resolved project bucket. Adds an ambiguity-specific error for--type board, and derives--typehelp and agent notes from the same type table used for validation.Bug Fixes
POST /buckets/{bucket_id}/dock/tools.jsonwith{tool_type, title?}; resolve the bucket from--project/flags/config and send it.--typecompletion.--type boardas ambiguous and prompt to usemessage_boardorkanban_board.github.com/basecamp/basecamp-sdk/goto include create-by-type support (ToolsService.Create(ctx, bucketID, toolType, opts)); updateAPI-COVERAGE.mdto add thedock_toolsrow and reflect the BC5 create-by-type reshape.Migration
--source/--clonewith required--type/-t. Accepted: chat, inbox, kanban_board, message_board, questionnaire, schedule, todoset, vault.-p/--project, global flag, or config. Create-by-type is BC5-only (BC4 will error).Written for commit fd3835e. Summary will update on new commits.