feat: sidecar binary support (#170)

[zrosenbauer]

Summary

Draft PR tracking issue #170 — sidecar binary support for kidd-powered CLIs.

This PR currently contains only a .gitignore update. Implementation will land in subsequent commits following the plan tracked locally in .joggr/.gg/tasks/sidecar-binary-support/.

Approach

Clean-slate redesign with config-as-code (selected over the agent-recommended Hybrid). Key design points:

• Zod-first sidecars schema in @kidd-cli/config; type-inference flows into runtime
• Single-stage TS-native pipeline: download → verify → extract → place straight into platforms/{os-arch}/ (no dist/vendors/ indirection)
• kidd-sidecars.json manifest emitted alongside platform binaries — sidecar() runtime and lazy-download share one typed source of truth
• Public API is sidecar() (Shape B): { exec(name, args), path(name) } — bare-verb export matching command(), cli(), middleware()
• Stdlib-only spawn (node:child_process); TS-native extraction (tar + extract-zip); no execa, no bash scripts
• npm @cli-{platform} optional-dep packages generated for non-compiled distribution
• Per-sidecar lazy: true defers download to first runtime use, with retry-with-backoff
• macOS xattr -cr + ad-hoc codesign on darwin-* outputs (graceful skip when host is non-darwin)

Plan

5 phases, 19 tasks:

Phase	Tasks	Scope
1 — Foundation	4	Config types + Zod schemas, platform helpers, retry helper
2 — Bundler pipeline	8	Types, download, extract, place, macOS, manifest, orchestrate, wire-up
3 — Runtime resolver	3	sidecar() factory, lazy runtime, core export wiring
4 — Distribution + CLI	2	npm @cli-{platform} staging, wire into kidd build
5 — Example, integration, docs	3	examples/sidecar-demo, integration test, concept/guide/reference docs

Acceptance criteria (from #170)

• sidecars config validates via Zod; existing configs unchanged
• Platform helpers exported from @kidd-cli/utils with explicit return types + tests
• Bundler downloads + extracts .tar.gz/.zip via TS-native libs (no bash); writes to platforms/{os-arch}/
• macOS quarantine strip + ad-hoc codesign on darwin outputs; executableFiles on platform packages
• @cli-{platform} npm optional-dep packages generated
• sidecar() exported from @kidd-cli/core; exec() returns { stdout, stderr, exitCode } via stdlib
• Lookup-miss throws actionable error; lazy mode supports retry + Result tuples
• Optional checksum verification rejects mismatches at build time
• Unit tests + at least one real-download integration test
• examples/sidecar-demo end-to-end working
• bun build --compile succeeds for all 7 targets with sidecars
• docs/concepts/sidecars.md + docs/guides/add-a-sidecar.md + docs/reference/sidecar.md
• pnpm check and pnpm test green; isolatedDeclarations passes

Test plan

• Unit tests pass for all new modules (pnpm test)
• Type checking + linting green (pnpm check)
• Integration test downloads rg v14.1.1 and verifies end-to-end on host platform
• CI integration matrix passes on macOS ARM/Intel, Linux x64, Windows x64
• examples/sidecar-demo builds and runs locally

Closes #170

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0f24d8d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
oss-kidd	Ignored	Preview	May 11, 2026 5:27pm

[codspeed-hq]

Merging this PR will not alter performance

✅ 2 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing feat/sidecar-binary-support (0f24d8d) with main (0e12cc0)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩