fix(cli): version-banner placeholders + doctor duplication check + install docs - #601
Merged
Merged
Conversation
…stall docs
Three related changes packaged together because they all spring from the
same operator-experience surface: Pi 0.75.0 (2026-05-17) moved user-scoped
pi extension installs from npm's global root to a private dir at
`~/.pi/agent/npm/node_modules/`, and the change wasn't reflected in
Taskplane's docs or its diagnostics.
bin/taskplane.mjs
* cmdVersion(): defensive rendering of .pi/taskplane.json. The previous
code unconditionally interpolated `info.version` and
`info.installedAt` even when the marker file lacked those fields,
surfacing user-visible 'vundefined, initialized unknown' placeholders.
Now only renders the parts that are actually present; falls through
to '(metadata only)' when neither field is set (which is the case in
e.g. taskplane's own source repo where the file carries only
migration history rather than init metadata).
* cmdDoctor() + new detectDuplicateTaskplaneInstall() helper:
Identifies the two-on-disk-copies state where users have both the
Pi-private install (refreshed by 'pi update') and a system npm-global
install (refreshed by 'npm install -g taskplane'). When the two
differ in version, the system-wide CLI silently drifts behind while
'pi update' reports success \u2014 the failure mode this branch was born
from. Doctor now WARNs with both versions, both paths, and a clear
remediation: 'npm uninstall -g taskplane' + add the Pi bin dir to
PATH. Same-version duplications are silently tolerated; the check
is best-effort and silently returns null if 'npm root -g' is
unreachable.
README.md
* Installation section: documents the PATH requirement for Pi 0.75.0+
(bash/zsh + PowerShell snippets) so that 'taskplane <cmd>' works on
the shell after 'pi install npm:taskplane'. Adds a note about the
duplication risk for users who ran 'npm install -g taskplane' under
older docs.
docs/tutorials/install.md
* Reframes Option A to explicitly steer users away from
'npm install -g taskplane' as the primary install command, citing
the Pi 0.75.0 install-location change and the duplication caveat.
* Expands the 'taskplane not on PATH' troubleshooting section: three
options (npx, direct bin invocation, PATH addition) with platform-
specific snippets for each.
Validation
npm run typecheck pass
npm run lint 286 warnings / 671 infos (identical to main)
npm run format:check pass (1 biome auto-format applied to bin/taskplane.mjs)
Full test suite 3714/3715 pass, 1 skipped, zero new failures
taskplane --version shows 'metadata only' (no more vundefined)
taskplane doctor all checks pass; duplication check silent
in this repo (user only has Pi-private copy)
HenryLach
enabled auto-merge
June 17, 2026 21:07
HenryLach
added a commit
that referenced
this pull request
Jun 17, 2026
Sage's review of #601 flagged three minor issues. All three are addressed here: 1. Summary message no longer recommends 'taskplane init' as a generic remediation when the underlying issue was a duplicate install. Previously, the doctor's final line was always '$N issue(s) found. Run taskplane init to fix config issues.', which was actively misleading when the only issue was a duplicate install (whose fix is 'npm uninstall -g taskplane', not init). Now tracks a separate duplicationDetected flag and emits a context-aware summary: 'See remediation hints above (npm uninstall -g taskplane for the duplicate install)' when duplication fired, or the original-style 'See remediation hints above; run taskplane init to fix config issues' otherwise. Either way the FAIL exit code is preserved so CI gates on doctor still catch the issue. 2. PowerShell-aware remediation in the duplication block. The original inline fix only showed bash syntax (export PATH=...), even though Taskplane is cross-platform and the duplicate-install issue is especially common on Windows + NVM-for-Windows (see #598). Now branches on process.platform: Windows users see the $env:PATH PowerShell snippet first with the Git Bash equivalent as a secondary 'or, for Git Bash:' line; non-Windows hosts see the bash form. Either OS+shell combination has a one-line copy/paste path that matches the host's likely shell. 3. 5-second timeout on execSync('npm root -g') in detectDuplicateTaskplaneInstall(). Guards against the rare case where npm is on PATH but hangs (slow registry probe, misconfigured custom prefix, etc.). taskplane doctor is a diagnostic and must never make the CLI feel hung. On timeout the catch branch runs, returning null and silently skipping the duplication check (best-effort by design). Sage's question-level finding about centralizing npm-root probing (sharing logic with extensions/taskplane/path-resolver.ts) was NOT addressed in this commit. Reasoning: bin/taskplane.mjs is a self-contained CLI script with no cross-module imports from the extensions tree; pulling in the resolver would expand the import surface for a 5-line execSync. The duplicated logic is small and the two functions have distinct purposes (the path-resolver finds Pi/ Taskplane for spawning; this helper detects on-disk duplication for diagnostics). Sage flagged this as 'medium confidence — verify', and on verification I'm keeping the duplication local. The out-of-scope finding (docs/specifications/** still referencing 'npm install -g taskplane') was correctly labeled by Sage as out-of-scope and is left for a docs consistency sweep. Validation npm run typecheck pass npm run format:check pass Full test suite 3714/3715 pass, 1 skipped, zero new failures Doctor smoke (no duplication) clean output, summary unchanged Doctor smoke (simulated dup) WARN block fires, PowerShell line shown first on Windows, FAIL summary now references npm uninstall instead of taskplane init
HenryLach
added a commit
that referenced
this pull request
Jun 17, 2026
fix(doctor): address Sage review findings on duplication-check PR #601
HenryLach
added a commit
that referenced
this pull request
Jun 17, 2026
Move the three improvements from [Unreleased] into a dated [0.30.3]
section:
Fixed:
- taskplane --version 'vundefined' placeholder (#601)
Enhanced:
- taskplane doctor duplicate-install detection with platform-aware
remediation (#601, #602)
Docs:
- README install section + install tutorial Pi 0.75.0 PATH guidance
(#601)
Insert fresh empty [Unreleased] placeholder per keep-a-changelog
convention.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three related changes packaged together because they all spring from the same operator-experience surface: Pi 0.75.0 (2026-05-17) moved user-scoped pi extension installs from npm's global root to a private dir at
~/.pi/agent/npm/node_modules/, and the change wasn't reflected in Taskplane's docs or its diagnostics.1.
taskplane --versionno longer showsvundefined, initialized unknownThe previous
cmdVersion()unconditionally interpolatedinfo.versionandinfo.installedAtfrom.pi/taskplane.jsoneven when the marker file didn't have those fields, producing:This was reproducible in any repo where
.pi/taskplane.jsonexists for some other purpose (e.g. taskplane's own source repo where the file carries only migration history rather than init metadata). The fix defensively renders only the fields that are actually present and falls through to(metadata only)when neither field is set.2.
taskplane doctornow detects two-copy duplicationNew helper
detectDuplicateTaskplaneInstall()identifies the state where users have both the Pi-private install (refreshed bypi update) and a system npm-global install (refreshed bynpm install -g taskplane). When the two differ in version, the system-wide CLI silently drifts behind whilepi updatereports success — which is the failure mode this PR was born from.Sample doctor output in the duplication state:
Same-version duplications are silently tolerated (not yet problematic; will drift later but isn't a problem in the present tense). Best-effort: silently returns
nullifnpm root -gis unreachable.3.
README.md+docs/tutorials/install.mdupdatestaskplane <cmd>works on the shell afterpi install npm:taskplane. Adds the duplication caveat for users who previously rannpm install -g taskplaneunder older docs.npm install -g taskplaneas the primary install command, citing the Pi 0.75.0 install-location change. Expands the 'taskplane not on PATH' section into three labeled options (npx, direct bin invocation, PATH addition) with platform-specific snippets.Validation
npm run typechecknpm run lintmainnpm run format:checkbin/taskplane.mjs)taskplane --version(metadata only)instead of(vundefined, initialized unknown)taskplane doctorNote on release
This is a doctor + docs change; the CLI behavior changes are display-only and have no impact on
/orchor/taskexecution. No release needed unless paired with other fixes. Will sit in[Unreleased]on the CHANGELOG and ship with the next batch.