Skip to content

fix(cli): version-banner placeholders + doctor duplication check + install docs - #601

Merged
HenryLach merged 1 commit into
mainfrom
fix/duplication-check-and-version-banner
Jun 17, 2026
Merged

fix(cli): version-banner placeholders + doctor duplication check + install docs#601
HenryLach merged 1 commit into
mainfrom
fix/duplication-check-and-version-banner

Conversation

@HenryLach

Copy link
Copy Markdown
Owner

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 --version no longer shows vundefined, initialized unknown

The previous cmdVersion() unconditionally interpolated info.version and info.installedAt from .pi/taskplane.json even when the marker file didn't have those fields, producing:

Config:   .pi/taskplane.json (vundefined, initialized unknown)

This was reproducible in any repo where .pi/taskplane.json exists 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 doctor now detects two-copy duplication

New helper detectDuplicateTaskplaneInstall() identifies the 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 — which is the failure mode this PR was born from.

Sample doctor output in the duplication state:

  ⚠️  taskplane is installed in TWO locations with different versions:
       Pi-private: v0.30.2  (C:\Users\HenryLach\.pi\agent\npm\node_modules\taskplane)
       npm-global: v0.30.1  (C:\Users\HenryLach\AppData\Local\mise\installs\node\24.15.0\node_modules\taskplane)
       → `pi update` only refreshes the Pi-private copy.
       → Recommended fix: drop the npm-global copy and put Pi's bin dir on PATH:
           npm uninstall -g taskplane
           export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"  # add to ~/.bashrc / ~/.zshrc

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 null if npm root -g is unreachable.

3. README.md + docs/tutorials/install.md updates

  • README installation section — documents the PATH requirement for Pi 0.75.0+ (bash/zsh + PowerShell snippets) so taskplane <cmd> works on the shell after pi install npm:taskplane. Adds the duplication caveat for users who previously ran npm install -g taskplane under older docs.
  • Install tutorial — 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. Expands the 'taskplane not on PATH' section into three labeled options (npx, direct bin invocation, PATH addition) with platform-specific snippets.

Validation

Gate Result
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 ✅ 3,714 / 3,715 pass, 1 skipped — zero new failures
taskplane --version ✅ shows (metadata only) instead of (vundefined, initialized unknown)
taskplane doctor ✅ all checks pass; duplication check correctly silent in this repo (only Pi-private exists post-cleanup)

Note on release

This is a doctor + docs change; the CLI behavior changes are display-only and have no impact on /orch or /task execution. No release needed unless paired with other fixes. Will sit in [Unreleased] on the CHANGELOG and ship with the next batch.

…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
HenryLach enabled auto-merge June 17, 2026 21:07
@HenryLach
HenryLach merged commit b4ee216 into main Jun 17, 2026
1 check passed
@HenryLach
HenryLach deleted the fix/duplication-check-and-version-banner branch 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.
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