SDK query contracts: universal OR filters, truthful lifecycle scope, and scripting guarantees

Merged
UN
3mo ago
+1172-247

Outcome

This broad SDK/CLI tranche makes project discovery and automation predictable across lifecycle history, query surfaces, package integrations, and shell clients.

  • adds a reusable public SDK parser for repeatable/CSV OR filters with per-token validation and escaped literal commas/backslashes
  • applies one grammar across list, search, aggregate, and update-many for status, type, priority, tag, assignee, sprint, and release
  • makes plain list/search truthful all-status discovery surfaces with reproducible status=all receipts
  • publishes a scripting contract for exit codes, stdout/stderr separation, stable structured fields, jq/xargs/NDJSON composition, and bulk dry-run safety
  • updates CLI contracts, generated SDK surface, token budgets, changelog, focused/integration/consumer gates, and canonical PM history

Canonical PM items

  • pm-999jh7 — truthful lifecycle scope and receipts
  • pm-gknu — uniform multi-value filter grammar
  • pm-psy1 — executable CLI scripting contract

Verification

  • 6,799 tests; exact 100% statements / branches / functions / lines
  • full local release suite green through static quality, retrieval/context negative controls, contracts, SDK surface, token surfaces, packed npx, and 88-command package-first dogfood
  • isolated Bun install + bunx + public SDK consumer exercised all-status reads, repeated filters, and bulk dry-run
  • ESLint, zero-clone jscpd, docs links, changelog check, package artifact, pnpm audit, and tracked-secret scan pass
  • GitHub Dependabot, code-scanning, and secret-scanning inventories: zero open alerts
  • all 22 open GitHub issues have canonical PM .toon backlinks

Hosted analysis is intentionally left to this pushed exact SHA; the local pre-push gate correctly reported that the prior main SHA had no DeepScan result.

Summary by Sourcery

Align SDK and CLI query surfaces around truthful all-status discovery and a uniform multi-value filter grammar, and publish a tested scripting contract for machine clients.

New Features:

  • Introduce reusable multi-value filter parsing in the SDK for status, type, tag, priority, assignee, sprint, and release selectors with CSV and repeatable flag support.
  • Add a documented CLI scripting contract covering exit codes, stdout/stderr separation, stable structured fields, and shell composition guidance.

Bug Fixes:

  • Make plain list and search commands operate as all-status discovery surfaces with explicit status receipts so lifecycle scope is truthful and consistent.
  • Fix inconsistencies where type, priority, and tag filters previously mishandled comma-separated values across list, search, aggregate, and bulk update surfaces.

Enhancements:

  • Update list, search, aggregate, and update-many query handling to use shared OR semantics across multi-value filters and expose validated status selections in aggregate results.
  • Adjust list command defaults and help text so bare list reflects the full lifecycle scope while maintaining specialized lifecycle shortcuts.
  • Export new SDK query utilities and extend filter echoing so machine clients can rely on stable, contract-checked filter representations.

Documentation:

  • Add a CLI Scripting Contract guide and cross-link it from the main and docs READMEs to document scripting guarantees and OR filter behavior.
  • Update the changelog to record lifecycle scope fixes and the new filter grammar and scripting guarantees.

Tests:

  • Add unit and integration tests to gate the multi-value filter grammar, all-status lifecycle receipts, and scripting process contract for CLI and SDK consumers.

Summary by cubic

Unifies multi-value OR filters across the SDK/CLI, makes lifecycle discovery truthful by defaulting list/search to all statuses, and documents a scripting contract with stable exit codes and stream behavior. Addresses pm-999jh7, pm-gknu, and pm-psy1.

  • New Features

    • Reusable parser for repeatable/CSV filters with \, and \\ escapes and empty-value rejection; applied to --status, --type, --priority, --tag, --assignee, --sprint, and --release across list/search/aggregate/update-many.
    • list and search default to status=all and echo filters.status: "all"; aggregate discloses concrete selections via status_values.
    • Published CLI scripting contract (docs/SCRIPTING.md): stable exit codes, stdout-only data, stderr-only errors, and portable xargs composition; exported sdk/query/multi-value-filters on the public surface.

  • Migration

    • Scripts that relied on active-only listing should add --status open (or specify explicit statuses).
    • When passing CSV values with literal commas or backslashes, escape as \, and \\.