Fix linearctl 0.8.0 contract regressions

[qwrobins]

Summary

Fixes the 0.8.0 regression batch across search scope, pagination retry plumbing, resolver ambiguity preferences, file redirect safety, leading global flags, curated safety taxonomy, bulk failure envelopes, Retry-After behavior, and envelope-aware validation paths.

Behavior / breaking changes:

• issue search <text> without --team searches the whole workspace again, even when the active profile has a default team. Use explicit --team to scope search.
• Bulk operation failures now preserve mapped per-item categories in errors[] / data.failed[] and derive the process exit code by category priority: auth > rate-limit > not-found > general.
• File upload/download cross-host redirects are followed after dropping Linear authorization and signed upload headers; same-host redirects keep the existing behavior.
• issue create --dry-run resolves friendly names before emitting the dry-run payload, so dry-run validates resolvability.

Verification

• bun run typecheck
• bun run test
• bun run build

Fixes #133
Fixes #134
Fixes #136
Fixes #137
Fixes #138
Fixes #139
Fixes #140
Fixes #141
Fixes #142

Summary by CodeRabbit

Release Notes v0.8.0

• New Features

  • Issue search now requires explicit --team flag; default team no longer applied
  • Bulk operations now categorize errors (authentication, rate-limit, not-found) with context-specific exit codes
  • Improved friendly-name resolution with case-sensitive matching and precedence rules
  • Dry-run now resolves friendly names before displaying preview

• Bug Fixes

  • Cross-host file redirects now drop headers for security; same-host redirects preserve them
  • Retry-After header values properly capped to prevent excessive waits
  • Schema pull default directory corrected to <config-dir>/schema

• Changed

  • Issue search rejects --order-by/--order-dir flags with validation error
  • Pagination now consistently respects retry configuration across all list commands

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a941a7f5-f488-4b81-aa79-2b11bc0aff33

📥 Commits

Reviewing files that changed from the base of the PR and between 1ab7aa1 and 78983c6.

⛔ Files ignored due to path filters (2)

• src/generated/embedded-skills.ts is excluded by !**/generated/**
• src/generated/manifest/curated-commands.json is excluded by !**/generated/**

📒 Files selected for processing (34)

• CHANGELOG.md
• docs/commands.md
• package.json
• skills/linearctl/SKILL.md
• src/commands/api.ts
• src/commands/attachment.ts
• src/commands/comment.ts
• src/commands/cycle.ts
• src/commands/file.ts
• src/commands/gql.ts
• src/commands/issue.ts
• src/commands/label.ts
• src/commands/metadata/curated-taxonomy.ts
• src/commands/project-status.ts
• src/commands/project.ts
• src/commands/schema.ts
• src/commands/state.ts
• src/commands/team.ts
• src/commands/user.ts
• src/core/registry/commands.ts
• src/core/registry/option-catalog.ts
• src/core/resolution/resolve.ts
• src/core/transport/retry.ts
• tests/cli/main.test.ts
• tests/commands/api.test.ts
• tests/commands/curated-taxonomy.test.ts
• tests/commands/dry-run.test.ts
• tests/commands/file.test.ts
• tests/commands/gql.test.ts
• tests/commands/issue.test.ts
• tests/commands/project.test.ts
• tests/commands/schema.test.ts
• tests/core/resolution/resolve.test.ts
• tests/core/transport/retry.test.ts

---

📝 Walkthrough

Walkthrough

This release (v0.8.0) bundles eight interconnected fixes addressing regressions and hardening issues: validation-error routing unification, retry-option consistency across list commands, issue-search default-team scoping, file-redirect cross-host security, name-resolution tie-breaking, Retry-After capping, CLI global-option recognition, and curated command safety classification.

Changes

Core v0.8.0 Changes

Layer / File(s)	Summary
Release documentation and version bump CHANGELOG.md, package.json, docs/commands.md, skills/linearctl/SKILL.md	Version bumped from 0.7.3 to 0.8.0. Changelog and user-facing docs updated to describe all CLI behavior changes: issue search/list filtering, bulk-operation error categories and exit-code selection, file redirect host validation, dry-run friendly-name resolution, retry-option propagation, resolution match precedence, Retry-After capping, ordering-flag rejection, schema pull defaults, and envelope-aware JSON error output.
Validation error centralization across API, GraphQL, and schema commands src/commands/api.ts, src/commands/gql.ts, src/commands/schema.ts	Manifest-missing, unknown-resource/operation, missing---id, invalid-input, and positional-argument validation errors now route through emitValidationError with appropriate sourceLayer annotations (api: "generated", gql: "raw-graphql", schema: "curated") instead of direct stderr writes. Reorganizes try/catch boundaries so validation errors stay within envelope boundaries when --json-envelope is active.
Retry-option propagation to all list/pagination commands src/commands/attachment.ts, src/commands/comment.ts, src/commands/cycle.ts, src/commands/label.ts, src/commands/project-status.ts, src/commands/project.ts, src/commands/state.ts, src/commands/team.ts, src/commands/user.ts	Imports normalizeRetryOptions and wires retry: normalizeRetryOptions(options) into GraphQL pagination requests for all nine resource-list commands, ensuring --no-retry and --max-retries flags are honored consistently across pagination paths instead of defaulting to 3 retries.
Issue command: default-team filtering, dry-run resolution, bulk error categorization src/commands/issue.ts	buildIssueFilter accepts applyDefaultTeam flag; issue search sets it to false to disable profile default-team application (fixing regression where searches were silently scoped to default team). Dry-run check moved to after friendly-name resolution so output contains resolved IDs. Issue search rejects --order-by/--order-dir with validation error. Bulk-operation failures now preserve error category (authentication/rate-limit/not-found/general); bulkExitCode helper derives exit code from category priority rather than always returning 1. JSON-envelope error output uses categorized CommandError[] entries.
File upload/download: cross-host redirect header stripping src/commands/file.ts	Maintains mutable currentInit across redirect iterations and validates redirect URLs use only http/https protocols. On cross-host redirect (host differs from original), strips headers from currentInit before following, preserving same-host redirect security while preventing credential leakage on cross-host jumps.
Friendly-name resolution: case-sensitive exact matching and team-scoped label preference src/core/resolution/resolve.ts	Introduces internal helpers for case-sensitive exact filtering and preference-based match selection. Team/user ID resolution prioritizes case-sensitive exact matches over case-insensitive candidates. Label ID resolution applies team scoping when teamId is provided and prefers team-scoped labels over workspace labels with the same name, reducing false ambiguity errors.
Retry delay behavior: Retry-After header capping and callback support src/core/transport/retry.ts	Adds onRetryDelay callback to RetryOptions and RetryDelayEvent interface. Tags delay source (retry-after vs backoff), caps retry-after delays to MAX_DELAY_MS (30s), invokes callback if provided, and appends "from Retry-After" to stderr rate-limit warnings when delay came from header.
CLI registry updates: global options, help defaults, and safety classification src/core/registry/option-catalog.ts, src/core/registry/commands.ts, src/commands/metadata/curated-taxonomy.ts	Adds version and metadata to OPTION_GROUPS.global so leading-position global flags are recognized. Updates schema pull help text to document correct default output directory (<config-dir>/schema instead of old path). Reclassifies safety: CONFIRMATION_REQUIRED contains only issue bulk-delete; safetyFor derives destructive classification from operation names containing "archive"/"delete" or matching auth logout.
Test coverage for all improvements tests/cli/main.test.ts, tests/commands/api.test.ts, tests/commands/gql.test.ts, tests/commands/schema.test.ts, tests/commands/dry-run.test.ts, tests/commands/file.test.ts, tests/commands/issue.test.ts, tests/commands/project.test.ts, tests/commands/curated-taxonomy.test.ts, tests/core/resolution/resolve.test.ts, tests/core/transport/retry.test.ts	Adds comprehensive coverage: validation-error envelope output for api/gql/schema commands, retry-option propagation through list pagination, issue-search default-team non-application, issue-create dry-run friendly-name resolution, bulk-operation failure categorization and exit-code mapping, file cross-host redirect header handling, resolution tie-breaking (case-sensitive exact, email-first, team-scoped label), and Retry-After header delay capping. Includes new test helper for default-team profiles and safety-rank comparison test for bulk vs singular operations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• qwrobins/linearctl#130: Main PR's updates to bulk-operation failure categorization and Retry-After behavior directly continue code paths and contracts from this PR.
• qwrobins/linearctl#131: Both PRs modify resolution logic in src/core/resolution/resolve.ts and file redirect behavior in src/commands/file.ts with compatible validation rules.
• qwrobins/linearctl#129: Main PR's validation-error routing and curated command safety classification build directly on this PR's output boundary and metadata work.

Suggested labels

codex

Poem

🐰 Eight fixes bundled in the spring,
Retry flows through lists, the validation bell does ring,
Cross-host redirects drop their headers with care,
Team searches breathe free air!
Resolution matches, case-sensitive and true—
Dry runs resolve names, a better debut. 🌱

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.94% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Fix linearctl 0.8.0 contract regressions' directly and clearly summarizes the main objective of the PR, which addresses multiple regressions introduced in 0.8.0 across multiple features and components.
Linked Issues check	✅ Passed	All nine linked issues (#133–#142) have their requirements demonstrably met by corresponding code changes in the raw_summary across CHANGELOG, docs, pagination, resolvers, file handling, option groups, taxonomy, bulk operations, retry behavior, and validation paths.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the nine linked issues; no out-of-scope modifications detected. Updates to CHANGELOG, documentation, tests, and implementation files all address the stated regressions.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-133-142-contract-regressions

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}