Skip to content

install.sh: point at construct doctor after a fresh install - #1083

Merged
edwin-zvs merged 1 commit into
mainfrom
install-doctor-hint
Aug 1, 2026
Merged

install.sh: point at construct doctor after a fresh install#1083
edwin-zvs merged 1 commit into
mainfrom
install-doctor-hint

Conversation

@edwin-zvs

Copy link
Copy Markdown
Contributor

One line on the installer's closing message:

Done. Try:  construct
If anything looks off:  construct doctor

Why here

A just-installed machine is the likeliest one to be missing a harness CLI, an
OAuth login, or a writable state directory — which is precisely what doctor
checks. Before this, the only way to discover the command existed was
construct --help, which is the wrong surface for something whose entire job
is to be findable at the moment something is already wrong.

The installer also hand-rolls its own PATH check a few lines up:

case ":${PATH}:" in
  *":${BIN_DIR}:"*) ;;
  *) say "${BIN_DIR} is not on your PATH. …"

That's a weaker version of doctor's env.path finding — a case on $PATH
can't see a second construct shadowing the one the installer just wrote.

Why it's safe to suggest at this moment

Doctor never starts a daemon, and a fresh install — no config file, no daemon
running, no sessions — reports as healthy and exits 0. Verified against an
isolated home: 26 ok, 10 info, 5 warn, 0 error — construct looks healthy.
New users won't be greeted by a wall of warnings for having just installed.

Not changed

  • construct upgrade — its output is already more specific than a doctor
    pointer would be. The one state where doctor is relevant post-upgrade is
    client/daemon build skew, and upgrade already detects that and prints three
    concrete ways to fix it. Redirecting to doctor there would be strictly
    worse.
  • README.md — worth a mention in §1 Requirements (that list maps one-to-one
    onto doctor's harnesses and logins sections), but out of scope for this PR.

sh -n install.sh passes.

A just-installed machine is the likeliest one to be missing a harness CLI,
an OAuth login, or a writable state directory — exactly what `doctor`
reports. Until now the only way to learn the command exists was
`construct --help`, which is the wrong surface for something whose whole
job is to be findable when something is already wrong.

The installer's own PATH check is also a weaker version of doctor's: a
`case` on `$PATH` cannot see a second `construct` shadowing the one it
just wrote.

Safe to suggest here: doctor never starts a daemon, and a fresh install
with no config and no daemon running exits 0 as healthy, so this does not
send new users to a wall of warnings.
@edwin-zvs
edwin-zvs merged commit b3645ef into main Aug 1, 2026
1 check passed
@edwin-zvs
edwin-zvs deleted the install-doctor-hint branch August 1, 2026 13:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant