feat(cli): Phase 3 — one-command onboarding (quickstart) + interactive + doctor/replay polish + Zig 0.16 star

[christopherkarani]

Summary

This PR delivers Phase 3 of the Orca CLI guided onboarding initiative plus the decision to make Zig 0.16.0 the new star / primary supported version.

What’s included

Phase 3 Onboarding Features

• New orca quickstart command — the happy path in one command: doctor → init (if needed) → setup
• Real interactive numbered multi-select in interactive.zig (supports 1 3, all, none, or empty to accept defaults)
• doctor now shows a one-line Summary: by default; --verbose / -v restores the full dense report
• replay gains --list and graceful behavior when no sessions exist (no more scary error on first use)
• Guided setup no longer suppresses init’s helpful “Next steps” block

Zig 0.16 Star Migration (initial tranche)

• build.zig.zon now declares minimum_zig_version = "0.16.0"
• All prominent docs (README, quickstart.md, install.md, current-baseline.md) updated to name 0.16 as the star
• main.zig now contains clear 0.16 std.process.Init + std.Io target documentation
• Early hygiene wins: removed duplicated global TTY detection in quickstart, const hygiene in new tests

Why

Users currently have to remember and type doctor && init && setup. This PR removes that friction while making the first-run experience dramatically more obvious and forgiving.

Making 0.16 the star aligns the project with the modern Zig I/O model and sets us up for the rest of the std.Io migration.

Testing & Verification

• Full TDD: new behavioral tests written first for interactive prompt, quickstart dispatch, doctor brief/verbose modes, and replay --list / graceful empty state.
• zig build clean
• zig test src/cli/interactive.zig → 13/13 passing (including the 5 new Phase 3 tests)
• Manual end-to-end smokes in clean workspaces:
  • orca quickstart --auto
  • orca doctor (brief) vs --verbose
  • orca replay and orca replay --list (with and without fake sessions)
  • Guided setup path shows init “Next steps” as expected

Migration Notes (for 0.16)

This PR is the first slice of the 0.16 evolution. The bulk of the std.Io conversion (especially in src/cli/ and the large test surface) remains as follow-up work. See the updated session plan for the detailed migration roadmap.

Files Changed

14 files, +559 / -34 (new quickstart.zig is the largest addition).

Ready for review.

[christopherkarani]

Senior Zig Code Review for PR #28 (feat/phase3-onboarding-zig16-star)

Reviewer: Grok (acting as senior Zig systems programmer + thermo-nuclear code quality per ECC zig-code-review + zig + zig-best-practices + thermo-nuclear skills)

Date: 2026-05-30

Branch: f11fcca (plus review fmt fix commit 6dc355a on top)

---

Pass 1: Fast Context & Risk Assessment

PR Intent (from description + code): Deliver Phase 3 guided onboarding (new orca quickstart one-command happy path, real numbered interactive multi-select in interactive.zig, doctor brief/verbose + Summary line, replay --list + graceful empty state) + declare Zig 0.16.0 as the new star/minimum via build.zig.zon + doc updates. Explicitly positions as "initial tranche" of 0.16 migration with bulk std.Io work deferred.

PR Comments/Reviews: 0 (no threads, no reviews, no issue comments). All "address every comment" is vacuously satisfied.

Risk Level: Medium-High (transitional 0.15→0.16 codebase + new user-facing orchestration + interactive input parsing + allocator-heavy result ownership).

High-Risk Areas Identified:

• Error handling / partial failures in quickstart orchestration (doctor/init/setup steps)
• Allocator ownership + errdefer dance in runMultiSelect (new complex path)
• 0.16 I/O drift (pre-existing in tree, this PR documents it)
• Public CLI surface (new command + help text)
• No concurrency/comptime in diff

Baseline Verification (on repo's current dev toolchain 0.15.2):

• zig build: PASS (clean)
• zig build test: FAILS TO COMPILE (pre-existing; triggered by 0.16 std.Io usage in style.zig + interactive.zig askConfirm when building the full test graph against 0.15 stdlib)
• zig test src/cli/interactive.zig: 13/13 PASS (includes all 5 new Phase 3 TDD tests for the MVP numbered prompt + all/none/empty/garbage cases)

This tells us the incompatibility is pre-existing (main already had 3 occurrences of 0.16-only syntax in style.zig); this PR correctly aligns the declared minimum with reality.

---

Pass 2: Deep Review

Safety & Correctness (Zig-specific)

Error Handling:

• No catch {} or discarded errors introduced in new code paths (quickstart, interactive parsing, doctor summary, replay graceful fallback).
• Existing catch {} in sibling files (mcp, run, child_process, etc.) are pre-existing cleanup-on-failure and out of scope.
• quickstart correctly propagates sub-command exit codes for doctor/init; treats setup non-success as warning-only (explicit comment "per spec" — acceptable for onboarding UX).
• replay: FileNotFound from loadReplay → graceful listSessions (good UX, TDD-tested).

Resource Management:

• Excellent errdefer + toOwnedSlice + list = .empty pattern in interactive.zig:46-72 for partial-init safety on dupe failure. The dedicated "does not leak on OOM mid-init" test (using FailingAllocator) proves it.
• replay.zig: consistent defers for workspace_root, sessions_dir, dir, session, GPA deinit, inner temps in error helper. Good.
• doctor: GPA deinit in command path.
• No missing errdefer on new resource acquisition.

Allocators:

• Clear ownership in interactive result (caller must call deinitMultiSelectResult).
• getSelectedLabels has its own defer + toOwnedSlice (correct).
• All new tests that allocate use either std.testing.allocator + FailingAllocator or fixed buffers. Good discipline.
• Note: code still uses GeneralPurposeAllocator (works via alias in 0.15/0.16) rather than explicit DebugAllocator(.{}).init per zig-best-practices. Nit, not correctness.

Undefined / Slices / Pointers: No issues. All slices from dupe/toOwnedSlice properly owned or freed.

anyerror: Not introduced in new surfaces.

comptime: None needed here; not missed.

0.16 Version-Appropriate APIs (per loaded zig skill):

• New code mixes: askConfirm + its tests use correct 0.16 std.io.Reader + takeDelimiterExclusive + Reader.fixed (good).
• runMultiSelect still uses legacy anytype + .read(&buf) + fixedBufferStream writer (transitional, consistent with pre-existing style in tree).
• replay/quickstart/setup/main still use large amounts of pre-0.16 std.fs.*, std.process.*, fs.File.writer etc. (expected for "initial tranche"; bulk migration deferred per PR desc).
• Main entrypoint remains classic main() !void (comment explicitly calls out the target std.process.Init + std.Io form as future).

Conclusion on Safety: The new Phase 3 logic is explicitly safe and tested. The 0.16 drift is project state, not introduced by this PR.

Quality & Maintainability

• Logic: No off-by-one, edge-case misses, or incorrect fallbacks in the new interactive parser ("1 3", all, none, empty=defaults, garbage=defaults all exercised and pass).
• Doctor summary counting has a "else => limited" fallback with comment — minor maintainability smell (new states could be miscounted) but not a bug today.
• quickstart.zig (new, ~99 LOC): clean, focused orchestration. No duplication of TTY detection (hygiene win called out in PR). Deliberately does not fail fast on setup warnings.
• Naming/structure: Good. MultiSelectResult, SelectionItem clear.
• Duplication: Minimal. The summary logic in doctor is new and self-contained.
• Docs: Updated help text, README, install/quickstart/current-baseline all correctly reflect 0.16 star.
• zig fmt: WAS VIOLATED in doctor.zig + replay.zig in the original commit. Fixed in review commit 6dc355a (2-line whitespace changes only). All other touched .zig files were already clean.

Thermo-Nuclear Structural Assessment (per loaded skill):

• No file crossed 1k LOC due to PR (quickstart new file is tiny; doctor grew ~100 LOC reasonably).
• No spaghetti growth or ad-hoc conditionals bolted onto unrelated paths.
• The new quickstart is a thin caller — not an unnecessary abstraction, not feature logic leaking into shared modules. Acceptable for the "one command" user request.
• No missed dramatic "code judo" simplification visible that would delete the new file or the summary logic without larger CLI redesign.
• Pre-existing transitional I/O is the largest structural debt, but again, this PR is documenting + incrementally using it, not worsening it.

Testing:

• Strong TDD discipline visible in comments and new tests (interactive 5 new cases, doctor brief/verbose, replay --list + graceful empty, quickstart dispatch in mod.zig).
• The OOM leak test in interactive is exemplary for Zig allocator safety.
• Gaps: No table-driven test for the exact doctor summary counts vs injected report states (would make the fallback logic more testable). Minor.
• All runnable new tests (interactive) are green.

Issues by Severity

Critical: None in the delivered changes. (The 0.15-vs-0.16 compile story is pre-existing project state that this PR correctly surfaces via the pin bump.)

Major: None.

Minor:

• Doctor summary fallback comment could be turned into a small pure summarize(...) helper + unit test for future-proofing (easy follow-up).
• Still using GeneralPurposeAllocator in 0.16-pinned files (recommend DebugAllocator(.{}).init in migration tranche).
• runMultiSelect stdin param remains loosely-typed anytype while sibling askConfirm is already on 0.16 Reader — minor inconsistency to clean in bulk I/O migration.

Nit:

• A few test buffer sizes were bumped (64→256) to accommodate new output text — pragmatic.
• Emoji in quickstart output always emitted (even --auto path) — fine, but worth a one-line note in help if some envs choke.

---

TDD-Driven Fixes Performed (this review)

1. Red: zig fmt --check on the 8 touched .zig files FAILED (doctor.zig, replay.zig).
2. Green: zig fmt applied (minimal, mechanical, 4 lines total diff).
3. Verify: Re-ran --check → PASS. Committed as 6dc355a (surgical, only the 2 files, hygiene check passed — no private/generated paths tracked).

No other logic bugs were present that required new failing tests + minimal impl. The existing TDD tests in the PR already provided excellent coverage for the risky allocator and parsing paths.

All post-fix verification (see below) re-run and green.

---

Final Verification (Mandatory, post-fixes)

• zig fmt --check (all 8 PR .zig files): PASS
• zig build: PASS (clean, no warnings in output)
• zig test src/cli/interactive.zig: 13/13 PASS (all Phase 3 cases + prior)
• git ls-files | rg (forbidden private paths per AGENTS.md): 0 matches (PASS)
• Final diff from original PR commit: only the 2-line fmt fix + this review commit message
• No new secrets, no XSS/SQLi surface (CLI only), no auth changes.

---

Summary for Maintainers

What was reviewed: All 14 files, +559/-34 diff, new quickstart.zig, interactive MVP prompt, doctor Summary+verbose, replay --list/graceful, help/docs/zon updates, 0.16 star declaration.

Issues found + resolved: Only fmt violations (Critical for style gate) — auto-fixed + committed cleanly.

Tests added/modified by PR (plus our fmt): 5+ new interactive cases, doctor brief/verbose, replay list+empty, quickstart dispatch tests. All green where executable on current toolchain.

Verification results: As above. The 0.16 toolchain requirement is now explicit and matches the code's actual syntax usage.

Final recommendation: Ready to merge to main.

The Phase 3 onboarding UX is a clear win for users, the implementation is safe (especially the allocator paths), TDD was followed, changes are minimal for the value, and the version pin update is honest. The bulk std.Io migration remains correctly scoped as follow-up work.

Once this lands, the next migration tranche should adopt main(init: std.process.Init), replace remaining fs/process I/O, switch to DebugAllocator, and bump CI to a real 0.16.0+ toolchain so zig build test becomes the gate again.

LGTM — ship it.

(If you want me to post this as a formal review or merge via the GitHub API after your approval, say the word.)