Fix search timeout, sort vocabulary, and metadata handling

[jeremy]

Fixes #470
Fixes #546

Problem

• basecamp search timing out #470 — basecamp search "<query>" --json hangs indefinitely (tested to 90s), no results, no error.
• search ignores query semantics and project filter #546 — rare queries return the same unrelated top results, --project is silently ignored, and basecamp search metadata fails / reports the wrong shape.

Root causes

1. Timeout (basecamp search timing out #470). --limit defaults to 0; the SDK treats 0 as "fetch ALL" and follows Link-header pagination across every page unbounded (followPagination). A broad or blank search paginates for 90s+. Affects all output formats.

2. "Identical unrelated results" (search ignores query semantics and project filter #546) — fixed upstream. The primary cause was old SDK GET requests carrying Content-Type: application/json, which made BC3 discard q and every filter (SDK Add lineup list command #324, closed; BC3 #12361). The current SDK sets that header only when the request has a body, so bodyless GETs like search no longer trip it, and BC3 defaults blank sort to best_match. The residual CLI defect was stale sort docs/vocabulary; unbounded pagination (cause 1) amplified any broad query into the timeout.

3. --project/filters ignored (search ignores query semantics and project filter #546). The global --project/--in flag was accepted but never read; --type/--creator/--since/--file-type did not exist. The SDK's SearchOptions now exposes the filter fields.

4. search metadata shape (search ignores query semantics and project filter #546). /searches/metadata.json returns recording/file search types (as key/value pairs) plus default_* filter labels; the CLI needed to present the real fields and count them correctly.

SDK

The SearchOptions.{BucketIds,TypeNames,CreatorIds,FileType,ExcludeChat,Since} (plus deprecated singulars) and the real SearchMetadata (RecordingSearchTypes/FileSearchTypes as key/value pairs plus five Default*Label fields) ship in the SDK. This PR bumps the pin to the current SDK tip (a98f52fd3ddd), which additionally hardens the generated array query params (bucket_ids[]/type_names[]/creator_ids[]) to omit empty slices on the wire (basecamp-sdk #407/#410) — the public SearchService wrapper the CLI uses was already safe, so that guard is defense in depth. The wrapper owns bracket wire-encoding, so the CLI just sets the option fields. No new SDK service methods and no CLI surface change came with the bump.

Rebased onto main after #554 merged. #554 made a minimal metadata reshape as a side effect of its SDK bump; this PR supersedes that with the full #546 implementation (correct non-default counts, graceful empty, plus all the filter flags).

Changes

• Bounded default (fixes basecamp search timing out #470). Default cap of 20 when neither --all nor an explicit --limit is given. --all → unbounded; explicit --limit must be > 0; --all + --limit together is a usage error. Regression tests prove a bare search returns 20 in one HTTP request while --all traverses every page.
• Sort vocabulary (search ignores query semantics and project filter #546). --sort normalizes to relevance (→ best_match, pinned explicitly) or recency (with deprecated created_at/updated_at aliases mapped in); unknown values are rejected.
• Full filter surface (completes search ignores query semantics and project filter #546). New flags:
  • --project/--in — resolved via app.Names.ResolveProject (ID or name) to bucket_ids[]. Only an explicit flag scopes; ambient config project stays ignored (search is account-wide).
  • --type — friendly aliases and canonical Keys through a dedicated table (todo, card→Kanban::Card, file/upload→Attachment, ping→Circle, check-in→Question, event→Schedule::Entry, folder→Vault, chat→Chat::Transcript, forward→Inbox::Forward, client→Client::Correspondence, …). Search uses a different type vocabulary than recordings, so this does not reuse normalizeRecordingType. Unknown values are rejected: BC3 silently discards an unrecognized type and returns unfiltered results.
  • --creator — resolved via app.Names.ResolvePerson (name/email/ID/me).
  • --file-type — case-normalized to BC3's case-sensitive Blob::TYPES (image→Image, …), so image does not silently disable the filter. Unknown values rejected.
  • --since — last_7_days/last_30_days/last_90_days/last_12_months/forever (BC5-only; no BC4 equivalent). Unknown values rejected.
  • --exclude-chat.
  • Each filter is sent in both the plural (BucketIds/TypeNames/CreatorIds) and deprecated singular forms, so BC5 honors the plural while older clients fall back to the singular.
• Real metadata (fixes search ignores query semantics and project filter #546 metadata). search metadata presents the real recording/file search types and default labels; the summary counts only selectable (non-default) options — the key:null "Everything"/"All files" default is excluded. Empty metadata is a graceful success, not an error.
• Docs/snapshots. .surface, skills/basecamp/SKILL.md, API-COVERAGE.md, and the search-metadata smoke test updated.

Verification

bin/ci fully green (fmt, vet, lint, unit + e2e BATS, naming, surface snapshot, skill-drift, SDK provenance, go mod tidy). grep 'replace' go.mod → none. Tests cover project/creator resolution (bucket_ids[]+bucket_id, creator_ids[]+creator_id), the --type/--file-type/--since vocabularies (dual plural+singular wire forms, invalid values rejected before any request), and the real metadata shape (non-default counts).

[github-actions]

⚠️ Potential breaking changes detected:

• Renaming of the '--sort' flag values: The flag previously allowed 'created_at' and 'updated_at', which are now treated as aliases for 'recency'. This could break scripts specifying the removed 'created_at' or 'updated_at' values.
• Introduction of a default search limit of 20 results when neither '--all' nor '--limit' is specified. Previously, there was no default limit, so scripts relying on this behavior may receive fewer results.
• Change in behavior of '--project/--in' flags: Any explicit use of these flags results in a usage error due to unsupported project-scoped searches.

Review carefully before merging. Consider a major version bump.

[Copilot]

Pull request overview

This PR fixes basecamp search behavior to avoid unbounded pagination timeouts, align --sort with current API vocabulary, and handle search metadata schema drift more gracefully while the pinned SDK lacks search filter fields.

Changes:

• Cap default search results at 20 unless --all is used; validate --limit (> 0) and forbid --all + --limit.
• Normalize --sort values to best_match (relevance) or recency, rejecting unknown values.
• Treat empty search metadata as a successful response with a notice (instead of a fatal error), and update docs/tests accordingly.

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 4 out of 4 changed files in this pull request and generated no comments.

File	Description
skills/basecamp/SKILL.md	Updates the skill docs/examples for capped search defaults, new sort vocabulary, and metadata caveats.
internal/commands/search.go	Implements bounded default limit, sort normalization, explicit --project/--in rejection, and graceful metadata handling.
internal/commands/search_test.go	Adds regression tests for default cap vs --all, sort mappings, --limit validation, project rejection, and metadata schema drift.
e2e/smoke/smoke_misc_read.bats	Updates smoke test to expect search metadata success even when metadata is empty (schema drift).

---

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

[cubic-dev-ai]

No issues found across 4 files

_{Re-trigger cubic}

[Copilot]

Pull request overview

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 731f11bd9b

ℹ️ 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".

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

internal/commands/search.go:447

• The metadata summary uses unconditionally plural "types", which produces ungrammatical output for singular counts (e.g., "1 recording types"). Consider pluralizing based on the count so the summary reads correctly for 0/1/N.

	recordingOptions := countSelectableTypes(metadata.RecordingSearchTypes)
	fileOptions := countSelectableTypes(metadata.FileSearchTypes)
	summary := fmt.Sprintf("Search filters: %d recording types, %d file types", recordingOptions, fileOptions)

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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