v4.2.7 feat(doctor): add Shell CLI on PATH check — surfaces plugin-without-global gotcha#50
Closed
kevintseng wants to merge 1 commit into
Closed
v4.2.7 feat(doctor): add Shell CLI on PATH check — surfaces plugin-without-global gotcha#50kevintseng wants to merge 1 commit into
kevintseng wants to merge 1 commit into
Conversation
…lobal gotcha (v4.2.7) The most common onboarding confusion (user hit it themselves today, README PR #49 documented it): `/plugin install memesh@pcircle-memesh` gives you MCP tools + hooks + `/memesh` skill inside Claude Code, but does NOT put `memesh` on the shell PATH. Typing `memesh reindex` in a terminal → `command not found`. New doctor check `Shell CLI on PATH` resolves `memesh` via `which` (POSIX) / `where` (Windows) and reports per install channel: - **plugin-marketplace**, no shell-PATH memesh → WARN with the exact fix (`npm install -g @pcircle/memesh`) and the clarification that both paths coexist and share `~/.memesh/knowledge-graph.db`. - **plugin-marketplace** with a separate shell-PATH memesh → PASS, names the path so the user knows where the global lives. - **npm-global** → PASS (running from the install itself, shell access available). - **source-checkout / npm-local / unknown** → informational PASS (no shell CLI is expected and `which` failing is not a real problem here). Wires through `runDoctor` like the existing `inspectNativeBinding` check, with a `resolveShellMemeshImpl` test seam so unit tests can inject success / failure paths without touching the real PATH. 4 new tests added (34 total in doctor.test.ts): - WARN on plugin-marketplace without shell PATH - PASS on plugin-marketplace with separate shell PATH - PASS on npm-global regardless of which output - informational PASS on source-checkout without shell PATH Version bumped 4.2.6 → 4.2.7 across all 7 anchor files. CHANGELOG entry added. Validation: - 34/34 doctor tests pass - npm run lint: clean - npx tsc --noEmit: clean - Manual: `memesh doctor` on this source checkout reports PASS with "/Users/.../bin/memesh (separate from this install...)" — correctly identifies the global memesh we installed earlier today. - Full test suite: 1039/1042 (same 3 pre-existing flakes — http /v1/recall, tools auto-archive, pre-bash-orchestration-nudge — confirmed unrelated to this change).
Multi-Model SynthesisBoth Claude and Codex reviews above are independent. The most Reviewer responsibility: read both, surface non-overlapping |
Contributor
Author
|
Superseded by the v4.2.7 consolidated PR — the Shell CLI on PATH check is included there along with 5 additional UX fixes from the E2E sweep. |
16 tasks
kevintseng
added a commit
that referenced
this pull request
May 13, 2026
…#50) (#51) * feat(doctor): add Shell CLI on PATH check — surfaces plugin-without-global gotcha (v4.2.7) The most common onboarding confusion (user hit it themselves today, README PR #49 documented it): `/plugin install memesh@pcircle-memesh` gives you MCP tools + hooks + `/memesh` skill inside Claude Code, but does NOT put `memesh` on the shell PATH. Typing `memesh reindex` in a terminal → `command not found`. New doctor check `Shell CLI on PATH` resolves `memesh` via `which` (POSIX) / `where` (Windows) and reports per install channel: - **plugin-marketplace**, no shell-PATH memesh → WARN with the exact fix (`npm install -g @pcircle/memesh`) and the clarification that both paths coexist and share `~/.memesh/knowledge-graph.db`. - **plugin-marketplace** with a separate shell-PATH memesh → PASS, names the path so the user knows where the global lives. - **npm-global** → PASS (running from the install itself, shell access available). - **source-checkout / npm-local / unknown** → informational PASS (no shell CLI is expected and `which` failing is not a real problem here). Wires through `runDoctor` like the existing `inspectNativeBinding` check, with a `resolveShellMemeshImpl` test seam so unit tests can inject success / failure paths without touching the real PATH. 4 new tests added (34 total in doctor.test.ts): - WARN on plugin-marketplace without shell PATH - PASS on plugin-marketplace with separate shell PATH - PASS on npm-global regardless of which output - informational PASS on source-checkout without shell PATH Version bumped 4.2.6 → 4.2.7 across all 7 anchor files. CHANGELOG entry added. Validation: - 34/34 doctor tests pass - npm run lint: clean - npx tsc --noEmit: clean - Manual: `memesh doctor` on this source checkout reports PASS with "/Users/.../bin/memesh (separate from this install...)" — correctly identifies the global memesh we installed earlier today. - Full test suite: 1039/1042 (same 3 pre-existing flakes — http /v1/recall, tools auto-archive, pre-bash-orchestration-nudge — confirmed unrelated to this change). * fix(cli,http,install-hooks,docs): close 5 UX gaps surfaced by E2E sweep (v4.2.7) Combined with the Shell CLI on PATH doctor check from previously-open PR #50 (cherry-picked here — superseded). Five user-visible fixes from the comprehensive E2E UX sweep: B1 — `memesh forget --confirm` is now accepted as a no-op Soft archive doesn't need a confirmation gate, but rejecting the flag as `error: unknown option '--confirm'` was hostile to users coming from `rm -i` / `git branch -D` conventions. Marked `[deprecated, no-op]` in --help. B2 — `memesh export -o <file>` flag Previously the only way to write to a file was shell redirection (`memesh export > backup.json`), undocumented in --help. Users tried `-o backup.json` first and saw `unknown option '-o'`. Added the flag with synchronous write + stderr confirmation. Stdout mode is preserved as the default (pipe-friendly). B3 — HTTP server returns JSON on unknown routes The 32 documented routes return `{success, data}` JSON, but unknown paths fell through to Express's default text/html 404 page. Clients piping responses into `JSON.parse` choked on `<!DOCTYPE html>`. Added a catch-all JSON 404 middleware: `{success: false, code: "NOT_FOUND", error: "No route for <M> <p>"}`. B4 — README upgrade-plugin.sh path includes pre-v4.2.5 fallback v4.2.6 release notes told users to run `bash ~/.claude/plugins/ cache/pcircle-memesh/memesh/<v>/scripts/upgrade-plugin.sh`, but plugin installs created before v4.2.5 don't contain this file. v4.2.3 / v4.2.4 users had no way to bootstrap the upgrade from inside their plugin. Added a fallback line pointing at the npm-global copy. README.md (EN) + README.th.md (TH already had "## Upgrading" section); 9 other locales still need that section added before they can host this fallback note — noted in CHANGELOG. B5 — `memesh install-hooks` refuses to double-wire over plugin runtime When Claude Code's plugin install is active, writing the same hooks into ~/.claude/settings.json caused every event to fire memesh's hook scripts TWICE — duplicate session-insight entities, duplicate recall injections, duplicate orchestration nudges. `installHooks()` now detects the plugin via ~/.claude/plugins/installed_plugins.json and bails with a clear message naming the install path + version, plus a `--force-over-plugin` escape hatch. Also fixed the `--dry-run` wording from past-tense "Added 7 hook entries" to future-tense "Would add 7". Plus the carried-over doctor Shell CLI on PATH check from PR #50: checks for shell-PATH `memesh` and surfaces a WARN with the exact `npm install -g @pcircle/memesh` fix when plugin-marketplace install lacks a separate global. PR #50 is now redundant — closing in favor of this PR. Validation: - 1043/1045 tests pass (same 2 pre-existing flakes — http /v1/recall, tools auto-archive — confirmed unrelated) - 7 new tests added: 3 install-hooks (plugin-runtime detect + force + no-memesh-entry) + 4 doctor (carried from PR #50) - npm run lint: clean - npx tsc --noEmit: clean - memesh doctor: Overall PASS_WITH_CONCERNS (only WARN is vector_index, unrelated) - All 5 fixes verified live end-to-end after build Version bump 4.2.6 → 4.2.7. CHANGELOG entry documents all 7 surfaces.
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
1 participant
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.
Summary
Most common onboarding confusion of the day: plugin install does NOT put
memeshon shell PATH. User hitscommand not found: memeshin a terminal. README PR #49 documented the workaround; this PR adds amemesh doctorcheck that fires the same warning automatically.New check:
Shell CLI on PATH. Resolvesmemeshviawhich(POSIX) /where(Windows). Per install channel:memesh→ WARN with the exact fix (npm install -g @pcircle/memesh) and the "both coexist, share same DB" reassurance.memesh→ PASS, shows the path.Docs synced
npm run buildmemesh doctorreports Overall: PASS with the new check correctly identifying the globalmemeshseparate from this source checkoutTest plan
npx vitest run tests/core/doctor.test.ts: 34/34 pass (was 30, +4 for the new check)npx tsc --noEmit: cleannpm run lint: cleannpm run build: smoke 6/6tests/transports/http.test.tsrecall-empty,tests/tools.test.tsauto-archive,tests/hooks/pre-bash-orchestration-nudge.test.ts— confirmed unrelated to this PR on every prior ship today)node dist/transports/cli/cli.js doctoron this checkout correctly identifies/Users/.../bin/memeshas the separate global install