Skip to content

Refresh diagnostics documentation #1283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
codeforester merged 1 commit into from
Jun 30, 2026
Merged

Refresh diagnostics documentation #1283

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/check-parallelism.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,17 @@ After all probe PIDs exit, the parent shell parses the files, validates required
fields, adds any parent-owned results, and only then renders text or calls the
Python JSON renderer.

Python-backed project artifact and IDE diagnostics use bounded subprocess
probes instead of the shell background result-file collector. The shared
diagnostic timeout is `process.DIAGNOSTIC_TIMEOUT_SECONDS` (10 seconds), and it
is passed to Homebrew artifact checks, Brewfile and mise delegate probes, IDE
extension and app-install probes, Python artifact package probes, and Git remote
diagnostics. When one of these subprocess probes times out, the Python layer
returns the normal finding ID for that probe with timeout-specific text, usually
as a warning when the diagnostic is informational. The parent `check`/`doctor`
rendering still preserves the same deterministic text and JSON order; the
timeout changes the finding content, not the ordering contract.

## Constraints

- Preserve `basectl check --format json` schema and ordering.
Expand Down
1 change: 1 addition & 0 deletions docs/doctor-findings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,7 @@ Doctor commands use the same diagnostic item fields. The top-level
| `BASE-P161` | Manifest command project script path readiness |
| `BASE-P170` | Project Python version requirement support window |
| `BASE-P171` | Selected project Python interpreter availability |
| `BASE-P172` | Actual inspectable project Python runtime: environment manager, virtualenv path, interpreter path, and Python minor version |

`BASE-P050` is the stable project virtual-environment readiness finding. The
Bash setup/check path reports detailed venv health messages when a project venv
Expand Down
8 changes: 5 additions & 3 deletions docs/observability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

> **STATUS** — `basectl history` and the local history index are implemented as
> the first slice. `basectl explain last-error`, `basectl report`, and history
> cleanup integration remain future work.
> cleanup integration are tracked but not scheduled longer-term future work.

Issue: #396
Tracker: [#396](https://github.com/basefoundry/base/issues/396)

Base currently exposes raw runtime logs through `basectl logs` and structured
local command metadata through `basectl history`. This document defines the
Expand Down Expand Up @@ -144,7 +144,7 @@ The retention contract should be:
log path safely, but `basectl history` should mark missing logs clearly.
- Durable user state under `~/.base.d` is never cleaned by history retention.

## Future Commands
## Shipped Commands

### `basectl history`

Expand All @@ -168,6 +168,8 @@ Expected options:
`basectl logs` should remain the command for opening or tailing raw log files.
`basectl history` should point to logs, not replace them.

## Planned Commands

### `basectl explain last-error`

`basectl explain last-error` should find the latest failed history record,
Expand Down
Loading