Fix Windows fresh-install crash: missing questionary (v2.3.3)

[nmbrthirteen]

Fixes #51

Fresh Windows installs of v2.3.1 crashed on launch with ModuleNotFoundError: No module named 'questionary'.

Root cause

The hermetic Python dep install ran only on first-run setup, gated on the backend tree existing (ensureRuntime) rather than the deps being present. If pip failed or was interrupted, the failure was swallowed (python: skipped), setup reported Done., and the launcher handed straight off to Python, which crashed on import questionary. A plain binary reinstall didn't recover because the half-provisioned runtime/ persists.

Fix

• provision.go: EnsurePython installs deps through a requirements-hash stamp (.podcli-deps), so a failed/partial install self-heals on the next run and the check is a cheap no-op once satisfied. Bootstrap pip via ensurepip when the interpreter lacks a working pip.
• main.go: verify hermetic Python deps on every runtime-wanting launch, not just first run; abort with an actionable run 'podcli setup' to retry message instead of crashing Python on the missing import.

Also carries the earlier "Surface the real AI CLI failure" backend change that never landed on the rewritten main, and bumps version to 2.3.3.

Existing users on a broken runtime recover by running podcli once on 2.3.3 (no purge needed).

Summary by CodeRabbit

• New Features

  • First-time setup now installs missing backend Python dependencies automatically when needed.
  • Better error details are shown when AI clip suggestions fail, making it easier to tell whether it’s a login, rate limit, timeout, or output issue.

• Bug Fixes

  • Improved startup handling so dependency problems are surfaced clearly instead of failing silently.
  • Reduced unnecessary reinstallations by skipping Python dependency setup when nothing has changed.

• Chores

  • Updated the package version to 2.3.3.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f3a3bc3f-87a5-4929-be9b-10da5ff29eb2

📥 Commits

Reviewing files that changed from the base of the PR and between 2fa331d and f1d73ca.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (5)

• backend/main.py
• backend/services/claude_suggest.py
• cli/internal/provision/provision.go
• cli/main.go
• package.json

---

📝 Walkthrough

Walkthrough

This PR improves error reporting for AI clip suggestion failures by adding a classify_cli_error helper and error_sink propagation from suggest_with_claude to handle_suggest_clips. It also adds hashed dependency stamping and pip bootstrap in the CLI's provision package, and updates main.go to propagate runtime provisioning errors. The package version is bumped.

Changes

Suggest-clips error detail propagation

Layer / File(s)	Summary
Error classification and retry tracking backend/services/claude_suggest.py	Adds classify_cli_error() to normalize CLI failure text, an error_sink parameter, and last_detail tracking across timeouts, exceptions, JSON parse failures, and no-clip/no-usable-clip outcomes.
Failure message consumption backend/main.py	handle_suggest_clips passes an errors list as error_sink and reports the first captured error, falling back to a generic message when none is captured.

CLI runtime dependency provisioning

Layer / File(s)	Summary
Dependency stamping and pip bootstrap cli/internal/provision/provision.go	EnsurePython delegates to a new ensureDeps that hashes requirements, checks a .podcli-deps stamp to skip reinstall, and calls pipInstall, which now bootstraps pip via ensurePip/ensurepip when unavailable.
Error-propagating runtime provisioning cli/main.go	ensureRuntime() now returns an error and calls new ensureBackendDeps() to install Python requirements when hermetic mode is enabled; runEngine() prints and exits on provisioning failure.
Version bump package.json	Package version updated from 2.3.1 to 2.3.3.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant handle_suggest_clips
  participant suggest_with_claude
  participant classify_cli_error
  Client->>handle_suggest_clips: request clip suggestions
  handle_suggest_clips->>suggest_with_claude: call with error_sink list
  suggest_with_claude->>suggest_with_claude: track last_detail on failure
  suggest_with_claude->>classify_cli_error: classify(last_detail)
  classify_cli_error-->>suggest_with_claude: actionable message
  suggest_with_claude-->>handle_suggest_clips: return None, error_sink populated
  handle_suggest_clips-->>Client: emit first error or fallback message

Loading

sequenceDiagram
  participant podcli
  participant ensureRuntime
  participant ensureBackendDeps
  participant provision_EnsurePython
  podcli->>ensureRuntime: runEngine invokes on wantsRuntime
  ensureRuntime->>ensureRuntime: setup(nil) if BackendRoot missing
  ensureRuntime->>ensureBackendDeps: check hermetic python deps
  ensureBackendDeps->>provision_EnsurePython: install if requirements-runtime.txt exists
  provision_EnsurePython-->>ensureBackendDeps: success or error
  ensureBackendDeps-->>ensureRuntime: return error or nil
  ensureRuntime-->>podcli: return error
  podcli->>podcli: print podcli: error, exit 1

Loading

Possibly related PRs

• nmbrthirteen/podcli#39: Both PRs touch suggest_with_claude and handle_suggest_clips error/failure messaging paths in the same functions.

✨ 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 fix/windows-python-deps

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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