50 lines
1.8 KiB
Markdown
50 lines
1.8 KiB
Markdown
# `4.7.0` Project Source Diagnostics And Recovery
|
|
|
|
Status: Planned
|
|
|
|
## Goal
|
|
|
|
Make project-source selection and startup failures understandable enough that a
|
|
chat-host user can recover without reading internals or raw tracebacks.
|
|
|
|
## Public API Changes
|
|
|
|
The chat-host path should expose clearer project-source diagnostics:
|
|
|
|
- `pyro doctor` should report the active project-source kind and its readiness
|
|
- `pyro mcp serve` and host helpers should explain whether they are using
|
|
tracked local files, `--project-path`, `--repo-url`, or no project source
|
|
- startup failures should recommend the right fallback:
|
|
`--project-path`, `--repo-url`, `--no-project-source`, or explicit
|
|
`seed_path`
|
|
|
|
## Implementation Boundaries
|
|
|
|
- keep diagnostics focused on the chat-host path rather than inventing a broad
|
|
source-management subsystem
|
|
- prefer actionable recovery guidance over long implementation detail dumps
|
|
- make project-source diagnostics visible from the same surfaces users already
|
|
touch: help text, `doctor`, host helpers, and startup errors
|
|
|
|
## Non-Goals
|
|
|
|
- no generic repo-health audit product
|
|
- no attempt to auto-fix arbitrary local checkout corruption
|
|
- no host-specific divergence in project-source behavior
|
|
|
|
## Acceptance Scenarios
|
|
|
|
- a user can tell which project source the chat host will use before creating a
|
|
workspace
|
|
- a user who hits a project-source failure gets a concrete recovery path instead
|
|
of a raw permission traceback
|
|
- host helper doctor and repair flows can explain project-source problems, not
|
|
only MCP config problems
|
|
|
|
## Required Repo Updates
|
|
|
|
- docs, help text, and troubleshooting updated with project-source diagnostics
|
|
and fallback guidance
|
|
- at least one smoke or targeted CLI test covering the new failure guidance
|
|
- host-helper docs updated to show when to prefer `--project-path`,
|
|
`--repo-url`, or `--no-project-source`
|