v4.2.7 fix: close 5 E2E UX gaps + Shell CLI doctor check (consolidates #50) by kevintseng · Pull Request #51 · PCIRCLE-AI/memesh-llm-memory

kevintseng · 2026-05-13T10:04:24Z

Summary

Today's full E2E UX sweep surfaced 5 real bugs across CLI, HTTP, install-hooks, and README. This PR fixes them all + consolidates the previously-open #50 (Shell CLI on PATH doctor check).

B1 — memesh forget --confirm was rejected as unknown option. Now accepted as a documented no-op (soft archive doesn't need confirmation, but rejecting the flag was hostile UX).

B2 — memesh export had no --out <file> flag and --help didn't mention stdout redirect. Added -o, --out <file> with synchronous write + stderr confirmation. Stdout mode preserved as default (pipe-friendly).

B3 — HTTP unknown routes returned raw Express HTML, breaking the JSON contract every other route honors. Added a catch-all JSON 404 middleware:

{ "success": false, "code": "NOT_FOUND", "error": "No route for GET /v1/whatever" }

B4 — v4.2.6 README told users to run bash ~/.claude/plugins/cache/.../scripts/upgrade-plugin.sh, but v4.2.3 / v4.2.4 plugin installs don't have this file. Added the npm-global fallback (bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh") to README.md + README.th.md. Other 9 locales still need a ## Upgrading section before they can host this — noted as follow-up.

B5 — memesh install-hooks would write user-level hooks on top of an already-active plugin install, causing every event (session-start / Stop / PreToolUse) to fire memesh's hook scripts twice. Now detects ~/.claude/plugins/installed_plugins.json, refuses to write by default, surfaces a clear message with --force-over-plugin escape hatch. Also fixed --dry-run wording to future-tense ("Would add" instead of "Added").

Plus #50 (consolidated) — memesh doctor Shell CLI on PATH check. WARN on plugin-marketplace installs without a separate shell-PATH memesh, with npm install -g @pcircle/memesh as the fix.

Docs synced

Test plan

npx vitest run tests/core/install-hooks.test.ts tests/core/doctor.test.ts: 48/48 pass
- 14 install-hooks tests (11 existing + 3 new: plugin-runtime detect / force-over-plugin / no-memesh-entry)
- 34 doctor tests (30 existing + 4 carried from v4.2.7 feat(doctor): add Shell CLI on PATH check — surfaces plugin-without-global gotcha #50: Shell CLI WARN / PASS-with-separate / npm-global PASS / source-checkout PASS)
Full test suite: 1043/1045 (same 2 pre-existing flakes from earlier today — tests/transports/http.test.ts recall-empty, tests/tools.test.ts auto-archive — unrelated)
npm run lint: clean
npx tsc --noEmit: clean
npm run build: smoke 6/6
All 5 fixes verified live end-to-end after build:
- forget --confirm → 📦 Archived
- export -o /tmp/foo.json → file written + ✅ Exported N entities
- curl /v1/nonexistent → JSON 404 with code: "NOT_FOUND"
- install-hooks --dry-run → "Plugin install detected... --force-over-plugin"
- memesh doctor → new Shell CLI check active

…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).

…ep (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.

github-actions · 2026-05-13T10:04:58Z

Multi-Model Synthesis

Both Claude and Codex reviews above are independent. The most
valuable signals are the issues only ONE model raised — those
are the blind spots single-model review misses.

Reviewer responsibility: read both, surface non-overlapping
findings, decide which need fixing before merge.

kevintseng added 2 commits May 13, 2026 17:57

kevintseng merged commit c447d21 into main May 13, 2026
15 checks passed

kevintseng deleted the fix/e2e-findings-v4.2.8 branch May 13, 2026 10:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v4.2.7 fix: close 5 E2E UX gaps + Shell CLI doctor check (consolidates #50)#51

v4.2.7 fix: close 5 E2E UX gaps + Shell CLI doctor check (consolidates #50)#51
kevintseng merged 2 commits into
mainfrom
fix/e2e-findings-v4.2.8

kevintseng commented May 13, 2026

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

kevintseng commented May 13, 2026

Summary

Docs synced

Test plan

Uh oh!

github-actions Bot commented May 13, 2026

Multi-Model Synthesis

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant