Update dock tool creation to current bucket-scoped API by robzolkos · Pull Request #327 · basecamp/basecamp-sdk

robzolkos · 2026-06-01T19:13:55Z

Summary

Updates dock tool creation to the current BC3 API: CreateTool posts to /{accountId}/buckets/{bucketId}/dock/tools.json with tool_type and optional title.
Renames the SDK operation from clone-shaped APIs to create-shaped APIs across Go, TypeScript, Ruby, Swift, Kotlin, and Python.
Regenerates OpenAPI, route metadata, generated services, SDK metadata, and conformance coverage from the updated Smithy spec.
Go Create validates toolType client-side (usage error before any HTTP request), mirroring the Update guard; test coverage rounded out across Go, Ruby, Python, and TypeScript (omit-title and validation-error cases).
Integrated with main post-Upstream sync: repin provenance to bc3 ba105ba7 (2026-07-22), register post-train contracts, codify pin semantics #390 by merge (author commits preserved verbatim); all generated artifacts regenerated at the current provenance boundary.

Ref: basecamp/basecamp-cli#471

Breaking changes

Operation rename: CloneTool → CreateTool. No deprecation alias is provided (pre-1.0 hard rename, per repo convention).
Endpoint change: POST /{accountId}/buckets/{bucketId}/dock/tools.json (bucket-scoped) replaces the legacy flat clone endpoint.
Request shape: {tool_type, title?} replaces the clone shape (source_recording_id-based). There is no source-tool parameter anymore.
Per-SDK signature changes: every SDK's tool-clone method is removed and replaced by the create-shaped signatures listed under "SDK API shape" below.

BC4 compatibility note

The tool_type create contract is BC5-only:

bc3's five branch dropped the source_recording_id requirement (477049c0d7, 2026-03-18) and added create-by-type (c1a59bf1a9, 2026-04-23).
five merged to bc3 master in 1d08f11882 at 2026-05-25T23:36:59Z — the same day basecamp-cli#471 was reported (2026-05-25T09:22:54Z, ~14h earlier), so the reporter's clone-shape observations matched what was served at that moment.
Current bc3 master implements tool_type creation (re-verified at the pinned provenance revision ba105ba7: Docks::ToolsController, config/routes.rb, and test/api/docks/tools_controller_api_test.rb assert tool_type + title → 201 on the bucket-scoped route).
bc3 origin/four (BC4, tracked by compatibility.bc3-four provenance) still unconditionally requires source_recording_id — CreateTool with only tool_type will 400 against BC4. Registered in the api-gaps registry (Record dock tool create contract change in api-gaps registry #389, spec/api-gaps/dock-tool-create-contract.md); upstream docs follow-up filed as bc3#12364.

Source of truth

Validated against bc3 master at the current SDK provenance pin (ba105ba7, 2026-07-22, set by #390). This PR makes no provenance changes — the dock-tools contract it models was verified unchanged between the original validation revision (ae96a694) and the current pin, and make sync-status is clean at the pin.

SDK API shape

Go: Tools().Create(ctx, bucketID, toolType, opts) — toolType required (usage error if empty), valid values documented on the method
TypeScript: client.tools.create(bucketId, { toolType, title? })
Ruby: account.tools.create(bucket_id:, tool_type:, title:)
Python: account.tools.create(bucket_id=..., tool_type=..., title=...)
Kotlin: account.tools.create(bucketId, CreateToolBody(toolType = ..., title = ...))
Swift: tools.create(bucketId:request:) with CreateToolRequest(toolType:title:)

Verification

Post-integration, at the merged head:

make check — full root suite, passing clean locally at this head (0086c09b): smithy-check, behavior-model-check, provenance-check, sync-spec-version/api-version checks, go/kt/py drift checks, go-check, ts-check, rb-check, kt-check, swift-check, py-check, conformance (all five runners: Go, TypeScript, Python, Ruby, Kotlin), url-routes/bucket-flat parity, api-gaps validation
make sync-status — clean at the ba105ba7 pin (no unabsorbed dock-tools deltas on master or four)

Unblocks the SDK portion of basecamp-cli#471.

github-actions · 2026-06-01T19:14:16Z

Spec Change Impact

Modified Operations:
- CreateDockTool: Updated to support bucket-scoped API.
Breaking API Change: Yes
- Adjustments to CreateDockTool may break compatibility if the previous non-bucket-scoped functionality relied on legacy parameters/fields that are now removed or altered.
SDKs Needing Regeneration: All SDKs must be regenerated to ensure consistency with the updated API spec.

Checklist of SDKs needing updates:

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the CloneTool operation to use a bucket-scoped endpoint across all SDKs and conformance tooling.

Changes:

Switched CloneTool endpoint from /dock/tools.json to /buckets/{bucketId}/dock/tools.json and threaded bucketId through generated clients.
Updated language SDK method signatures (TS/Swift/Ruby/Python/Kotlin/Go) and related tests/conformance runners.
Regenerated OpenAPI/Smithy-derived artifacts (schema, path mapping, metadata).

Reviewed changes

Copilot reviewed 12 out of 25 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
typescript/tests/services/tools.test.ts	Updates ToolsService clone test to include bucketId and verify bucket-scoped path.
typescript/src/generated/services/tools.ts	Changes clone signature to accept bucketId and posts to bucket-scoped endpoint.
typescript/src/generated/services/index.ts	Reorders/relocates ToolsService export.
typescript/src/generated/schema.d.ts	Adds bucket-scoped CloneTool path/operation typing and removes flat path.
typescript/src/generated/path-mapping.ts	Maps CloneTool to the bucket-scoped path and removes flat mapping.
typescript/src/generated/openapi-stripped.json	Adds bucket-scoped CloneTool path and removes the flat endpoint.
typescript/src/generated/metadata.json	Refreshes generated timestamp and relocates CloneTool retry metadata.
swift/Sources/Basecamp/Generated/Services/ToolsService.swift	Updates clone signature to include bucketId and uses bucket-scoped path.
spec/basecamp.smithy	Updates CloneTool HTTP URI to include bucketId label and adds required bucketId to input.
ruby/test/basecamp/services/tools_service_test.rb	Updates clone test to stub bucket-scoped endpoint and pass bucket_id.
ruby/lib/basecamp/generated/types.rb	Updates generated timestamp comment.
ruby/lib/basecamp/generated/services/tools_service.rb	Updates clone method to require bucket_id and post to bucket-scoped endpoint.
ruby/lib/basecamp/generated/metadata.json	Refreshes generated timestamp and relocates CloneTool retry metadata.
python/src/basecamp/generated/services/tools.py	Updates sync/async clone methods to require bucket_id and use bucket-scoped path.
openapi.json	Moves CloneTool endpoint under `/{accountId}/buckets/{bucketId}/dock/tools.json`.
kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/generated/services/tools.kt	Updates clone signature to include bucketId and uses bucket-scoped path.
kotlin/conformance/src/main/kotlin/com/basecamp/sdk/conformance/Main.kt	Reads bucketId from path params for CloneTool conformance dispatch.
go/pkg/generated/client.gen.go	Regenerates Go client to require bucketId for CloneTool request builders and interfaces.
go/pkg/basecamp/tools_test.go	Adds test asserting Tools.Create posts to bucket-scoped dock path.
go/pkg/basecamp/tools.go	Changes ToolsService.Create to accept bucketID and calls generated CloneTool with bucketId.
conformance/tests/paths.json	Updates CloneTool conformance case to include bucket-scoped path and pathParams.bucketId.
conformance/runner/typescript/runner.test.ts	Updates CloneTool runner to pass bucketId to client.tools.clone.
conformance/runner/ruby/runner.rb	Updates CloneTool runner to pass bucket_id from path params.
conformance/runner/python/runner.py	Updates CloneTool runner to pass bucket_id from path params.
conformance/runner/go/main.go	Updates CloneTool runner to pass bucketID into account.Tools().Create.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

robzolkos · 2026-06-01T19:18:26Z

Fixed — addressed the Go review feedback by deriving the expected bucket path from bucketID and recording the destination bucket in Tools.Create operation metadata.

cubic-dev-ai

2 issues found across 25 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

robzolkos · 2026-06-01T19:23:15Z

Fixed — addressed the issues identified by cubic: CloneTool operation metadata uses the destination bucket, and the Python conformance runner accepts omitted CloneTool titles.

github-actions · 2026-06-01T19:23:28Z

⚠️ Potential breaking changes detected:

Renamed and altered the signature of 'Create' in Go SDK: added a new required 'bucketID' parameter.
Renamed and altered the signature of 'clone' in Kotlin SDK: added a new required 'bucketId' parameter.
Renamed and altered the signature of 'clone' in Swift SDK: added a new required 'bucketId' parameter.
Removed '/dock/tools.json' endpoint definition and replaced it with '/buckets/{bucketId}/dock/tools.json' in TypeScript SDK, requiring 'bucketId' as a path parameter.

Review carefully before merging. Consider a major version bump.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

Copilot reviewed 32 out of 52 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 33 out of 53 changed files in this pull request and generated no new comments.

jeremy · 2026-07-22T08:14:20Z

Unblock recipe now that #390 has repinned provenance to bc3 ba105ba7 (2026-07-22):

Rebase onto current main. The branch predates the provenance schema restructure (BC5 readiness: forward-compat spec, briefs, parity lint #293), which is why it shows CONFLICTING.
Drop this branch's spec/api-provenance.json hunk entirely. It moves the pin backward (056a356e → ae96a694, 2026-06-01), and the pin never moves backward (now codified in AGENTS.md §Provenance is Mandatory). The dock-tools behavior this PR syncs was validated at ae96a694, which the current pin (ba105ba7) already covers — no provenance change is needed here at all.
Fix the 2 unresolved Copilot threads: ToolsService.Create should return ErrUsage on empty toolType, plus the doc-comment nit.

After that this should go green without any provenance work.

…reate-bucket-scope-20260601145434 * origin/main: (28 commits) Upstream sync: repin provenance to bc3 ba105ba7 (2026-07-22), register post-train contracts, codify pin semantics (basecamp#390) ci: pin conformance uv sync to the matrix Python; parse the fan-in gate (basecamp#388) BC5 readiness: pairwise BC4↔BC5 + check-bc5-compat orchestrator + scheduled CI (basecamp#308) CI: fold conformance suites into their language test jobs (basecamp#387) Fix TypeScript SDK Content-Type on GET requests (basecamp#384) BC5 launch reconciliation: registry refresh for the shipped BC5 API train (basecamp#325) BC5 readiness: cross-language wire-replay decoders (basecamp#301) BC5 readiness: Go wrapper forward-compat audit + field-level drift check (basecamp#309) BC5 readiness: TypeScript live wire-capture canary (basecamp#294) BC5 readiness: forward-compat spec, briefs, parity lint (basecamp#293) deps(ts): bump brace-expansion from 5.0.2 to 5.0.7 in /typescript (basecamp#386) typescript: bump fast-uri, brace-expansion, js-yaml overrides for fresh advisories (basecamp#385) deps(actions): bump the actions group with 6 updates (basecamp#382) deps(ruby): bump the bundler-dependencies group in /ruby with 2 updates (basecamp#379) deps(kotlin): bump the gradle-dependencies group (basecamp#383) deps(go): bump github.com/oapi-codegen/oapi-codegen/v2 in /go (basecamp#381) deps(ts): bump the npm-dependencies group in /typescript with 2 updates (basecamp#380) deps(smithy): bump the smithy-gradle-dependencies group (basecamp#378) deps(go): bump github.com/oapi-codegen/runtime (basecamp#377) Todos Update/Edit/Replace: merge-safe writes across all 6 SDKs (basecamp#375) ... # Conflicts: # go/pkg/basecamp/api-provenance.json # go/pkg/basecamp/version.go # go/pkg/generated/client.gen.go # kotlin/sdk/src/commonMain/kotlin/com/basecamp/sdk/BasecampConfig.kt # openapi.json # python/src/basecamp/_version.py # ruby/lib/basecamp/generated/metadata.json # ruby/lib/basecamp/generated/types.rb # ruby/lib/basecamp/version.rb # spec/api-provenance.json # spec/basecamp.smithy # swift/Sources/Basecamp/BasecampConfig.swift # typescript/src/client.ts # typescript/src/generated/metadata.ts # typescript/src/generated/openapi-stripped.json

Copilot

Pull request overview

Copilot reviewed 25 out of 45 changed files in this pull request and generated no new comments.

Copilot AI review requested due to automatic review settings June 1, 2026 19:13

github-actions Bot added typescript Pull requests that update TypeScript code ruby Pull requests that update the Ruby SDK go kotlin swift spec Changes to the Smithy spec or OpenAPI conformance Conformance test suite labels Jun 1, 2026

github-actions Bot added the enhancement New feature or request label Jun 1, 2026

Copilot AI reviewed Jun 1, 2026

View reviewed changes

Comment thread go/pkg/basecamp/tools_test.go Outdated

Comment thread go/pkg/basecamp/tools.go Outdated

github-actions Bot added bug Something isn't working and removed enhancement New feature or request labels Jun 1, 2026

cubic-dev-ai Bot reviewed Jun 1, 2026

View reviewed changes

Comment thread conformance/runner/python/runner.py Outdated

Comment thread go/pkg/basecamp/tools.go Outdated

Copilot AI review requested due to automatic review settings June 1, 2026 19:23

github-actions Bot added the breaking Breaking change to public API label Jun 1, 2026

github-actions Bot added the dependencies Pull requests that update a dependency file label Jun 1, 2026

Copilot AI reviewed Jun 1, 2026

robzolkos changed the title ~~Fix tools clone bucket-scoped endpoint~~ Update dock tool creation to current bucket-scoped API Jun 1, 2026

robzolkos mentioned this pull request Jun 1, 2026

tools create returns a 404 instead of creating a new tool in the project basecamp/basecamp-cli#471

Closed

robzolkos force-pushed the fix/tools-create-bucket-scope-20260601145434 branch from 7bc2869 to 7c6551d Compare June 3, 2026 18:10

github-actions Bot added enhancement New feature or request and removed bug Something isn't working labels Jun 3, 2026

robzolkos added 4 commits July 13, 2026 16:38

Fix tools clone bucket-scoped endpoint

61b374f

Address tool clone review feedback

65c96ee

Allow tool clone conformance title to be omitted

2da6b50

Update dock tool creation to current API

2109781

Add tool creation request coverage

7e713d9

robzolkos force-pushed the fix/tools-create-bucket-scope-20260601145434 branch from 7c6551d to 7e713d9 Compare July 13, 2026 20:58

Copilot AI review requested due to automatic review settings July 13, 2026 20:58

github-actions Bot removed the dependencies Pull requests that update a dependency file label Jul 13, 2026

Copilot started reviewing on behalf of robzolkos July 13, 2026 20:59 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

Comment thread go/pkg/basecamp/tools.go

Comment thread go/pkg/basecamp/tools.go

jeremy added 2 commits July 22, 2026 00:01

Validate tool type in Go tool creation

f6ce8b4

Round out tool create test coverage

5d89e6f

Copilot AI review requested due to automatic review settings July 22, 2026 07:05

Copilot started reviewing on behalf of jeremy July 22, 2026 07:05 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

This was referenced Jul 22, 2026

Record dock tool create contract change in api-gaps registry #389

Merged

Upstream sync: repin provenance to bc3 ba105ba7 (2026-07-22), register post-train contracts, codify pin semantics #390

Merged

Copilot AI review requested due to automatic review settings July 22, 2026 08:24

Copilot started reviewing on behalf of jeremy July 22, 2026 08:24 View session

jeremy requested review from dhh and jorgemanrubia and removed request for dhh and jorgemanrubia July 22, 2026 08:24

Copilot AI reviewed Jul 22, 2026

View reviewed changes

jeremy merged commit f2086f5 into basecamp:main Jul 22, 2026
48 checks passed

jeremy mentioned this pull request Jul 22, 2026

Fix tools create to use the BC5 create-by-type API (#471) basecamp/basecamp-cli#553

Merged

Uh oh!

Conversation

robzolkos commented Jun 1, 2026 • edited by jeremy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking changes

BC4 compatibility note

Source of truth

SDK API shape

Verification

Uh oh!

github-actions Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Spec Change Impact

Checklist of SDKs needing updates:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

robzolkos commented Jun 1, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

robzolkos commented Jun 1, 2026

Uh oh!

github-actions Bot commented Jun 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

jeremy commented Jul 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

robzolkos commented Jun 1, 2026 •

edited by jeremy

Loading

github-actions Bot commented Jun 1, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading