@pcircle/memesh 4.9.3 → 4.10.1

package/scripts/lib/npm-bin.mjs

@@ -0,0 +1,123 @@
+import { execFileSync, execSync } from 'node:child_process';
+
+/**
+ * Run npm / npx from a build script, on every platform we support.
+ *
+ * Two separate Windows problems, and fixing only the first is what made this
+ * take two attempts:
+ *
+ *   1. npm ships on Windows as `npm.cmd`. `execFileSync('npm', …)` does not
+ *      consult `PATHEXT` — that is a shell behaviour and execFile uses no
+ *      shell — so it fails with `spawnSync npm ENOENT` while the identical
+ *      command typed into a terminal works.
+ *
+ *   2. Naming it `npm.cmd` then fails with `spawnSync npm.cmd EINVAL`. Since
+ *      the fix for CVE-2024-27980, Node refuses to spawn `.cmd` and `.bat`
+ *      files without `shell: true`, because the Windows command interpreter
+ *      re-parses the argument list. On Windows there is no shell-free way to
+ *      invoke npm.
+ *
+ * So `shell: true` is required there, not a shortcut — and it is scoped to
+ * Windows, so macOS and Linux keep passing arguments as an array with no
+ * interpreter in the path at all.
+ *
+ * What `shell: true` costs is argument re-parsing, which matters only for
+ * arguments that are not literals. There is exactly one — the tarball name
+ * `npm pack` prints — and `assertSafeShellArg()` below is how it is made safe
+ * rather than assumed safe. Call it on anything that did not come from this
+ * repository's own source.
+ *
+ * Both scripts on the publish path had written this by hand:
+ *
+ *   check-consumer-audit.mjs  ->  audit:prod  ->  verify:release  ->  prepublishOnly
+ *   run-tests-isolated.mjs    ->  test:isolated                   ->  prepublishOnly
+ *
+ * One owner, so a third caller cannot get it wrong a third way.
+ */
+const isWindows = process.platform === 'win32';
+
+export const NPM = isWindows ? 'npm.cmd' : 'npm';
+export const NPX = isWindows ? 'npx.cmd' : 'npx';
+
+/**
+ * Reject anything that could mean something to a command interpreter.
+ *
+ * Deliberately an allow-list. A deny-list of shell metacharacters has to be
+ * complete to be correct, and `cmd.exe` gives `%`, `^` and `&` meanings that a
+ * POSIX-shaped deny-list would miss.
+ */
+export function assertSafeShellArg(value, what) {
+  // `:` and `~` are here for one reason: Windows absolute paths
+  // (`C:\Users\RUNNER~1\AppData\Local\Temp\...` — 8.3 short names carry the `~`,
+  // and that is literally what `os.tmpdir()` returns on a Windows runner).
+  // `smoke-packed-artifact.mjs` passes an absolute `os.tmpdir()` path to
+  // `npm pack --pack-destination` and to `npm install`, so without it
+  // `npm run test:packaged` throws on Windows before packing anything —
+  // fail-closed, but it means the packaged smoke test cannot run there at all.
+  // Neither has meaning to cmd.exe (`~` is a POSIX-shell nicety, and the POSIX
+  // branch never reaches here — it uses execFileSync with no shell at all).
+  // Every character that DOES mean something to cmd.exe (`%^&|<>"'` and
+  // whitespace) stays excluded.
+  if (typeof value !== 'string' || !/^[A-Za-z0-9._@:~\-+=/\\]+$/.test(value)) {
+    throw new Error(
+      `${what} is not a safe argument to pass through a shell: ${JSON.stringify(value)}`
+    );
+  }
+  return value;
+}
+
+/**
+ * Spawn `bin` with `args`.
+ *
+ * POSIX: no shell, arguments stay an array, nothing is re-parsed.
+ *
+ * Windows: every argument is validated, then the command line is built here and
+ * handed to `execSync`. Passing an ARRAY together with `shell: true` is
+ * deprecated (DEP0190) precisely because the arguments are concatenated without
+ * escaping — doing the concatenation ourselves, after checking each part, is
+ * the same operation with the check that makes it sound, and it does not print
+ * a deprecation warning on every release gate.
+ *
+ * The usual advice — "use execFile with an argument array, never build a shell
+ * string" — is right, and is what the POSIX branch does. It does not apply to
+ * the Windows branch because there is no execFile that works: npm is a `.cmd`,
+ * and Node refuses to exec one without a shell. The choice there is not
+ * array-vs-string, it is checked-vs-unchecked. Every argument reaching the
+ * concatenation has passed `assertSafeShellArg`, which is an allow-list, so no
+ * character with meaning to `cmd.exe` can be in one. `tests/consumer-audit-
+ * gate.test.ts` pins that, including the `%` and `^` forms a POSIX-shaped
+ * deny-list would miss.
+ */
+function runSync(bin, args, opts) {
+  if (!isWindows) return execFileSync(bin, args, opts);
+  const safeArgs = args.map((arg, i) => assertSafeShellArg(arg, `${bin} argument ${i} (${arg})`));
+  return execSync([bin, ...safeArgs].join(' '), opts);
+}
+
+/** `npm <args>`, spawned correctly for the platform. */
+export function npmSync(args, opts = {}) {
+  return runSync(NPM, args, opts);
+}
+
+/** `npx <args>`, spawned correctly for the platform. */
+export function npxSync(args, opts = {}) {
+  return runSync(NPX, args, opts);
+}
+
+/**
+ * `baseEnv` with every spelling of `npm_config_cache` removed and the private
+ * cache set. Windows environment names are case-insensitive and Node keeps
+ * the lexicographically first of two keys that differ only in case (`N`
+ * before `n`); Vitest adds an upper-cased copy of every variable to its
+ * Windows workers. So `{ ...process.env, npm_config_cache }` handed npm the
+ * runner's `NPM_CONFIG_CACHE=C:\npm\cache` and never the private directory —
+ * measured on windows-latest with the fake npm in
+ * `tests/consumer-audit-gate.test.ts`.
+ */
+export function envWithNpmCache(cacheDir, baseEnv = process.env) {
+  const env = Object.fromEntries(
+    Object.entries(baseEnv).filter(([key]) => key.toLowerCase() !== 'npm_config_cache'),
+  );
+  env.npm_config_cache = cacheDir;
+  return env;
+}

package/scripts/upgrade-plugin.sh

@@ -91,6 +91,11 @@ MARKETPLACE_DIR="$CLAUDE_CONFIG_ROOT/plugins/marketplaces/pcircle-memesh"
 INSTALL_REGISTRY="$CLAUDE_CONFIG_ROOT/plugins/installed_plugins.json"
 CACHE_ROOT="$CLAUDE_CONFIG_ROOT/plugins/cache/pcircle-memesh/memesh"
 LOCK_DIR="$CACHE_ROOT.lock"
+# Use the checker shipped beside this upgrade script, not a file newly staged
+# from the target commit. This keeps upgrades from legacy marketplace commits
+# testable and prevents a target archive from disabling its own validation.
+UPGRADE_SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ARTIFACT_CHECKER="$UPGRADE_SCRIPT_DIR/check-plugin-hook-artifact.mjs"
 
 # ─── Pre-flight ────────────────────────────────────────────────────────────
 if [ ! -d "$MARKETPLACE_DIR" ]; then
@@ -514,6 +519,25 @@ echo "==> Installing runtime deps (this may take a minute)..."
   exit 1
 }
 
+# Validate a real staged plugin before moving it into the live cache. The
+# host registry may load hooks immediately after the swap; a manifest that
+# names a missing script would otherwise surface as a frightening `127` in the
+# user's next session. Tiny legacy marketplace fixtures (and genuinely old
+# plugin archives) have no plugin wiring to validate, so preserve their
+# historical cache-refresh behavior; once wiring is present, the checker is
+# mandatory and fail-closed. The checker itself comes from this script's
+# installed release, never from the target archive being validated.
+if [ -f "$STAGE_PATH/hooks/hooks.json" ] || [ -f "$STAGE_PATH/.claude-plugin/plugin.json" ] || [ -f "$STAGE_PATH/.codex-plugin/plugin.json" ]; then
+  if [ ! -f "$PLUGIN_ARTIFACT_CHECKER" ]; then
+    echo "ERROR: plugin artifact checker is missing beside the upgrade script — the live cache at $NEW_INSTALL_PATH was not touched" >&2
+    exit 1
+  fi
+  if ! node "$PLUGIN_ARTIFACT_CHECKER" --root "$STAGE_PATH" --skip-pack; then
+    echo "ERROR: staged plugin artifact integrity check failed — the live cache at $NEW_INSTALL_PATH was not touched" >&2
+    exit 1
+  fi
+fi
+
 # ─── 5. Swap the staged copy in ───────────────────────────────────────────
 if [ -e "$NEW_INSTALL_PATH" ] || [ -L "$NEW_INSTALL_PATH" ]; then
   HAD_LIVE_CACHE=1

package/skills/memesh/SKILL.md

@@ -28,14 +28,14 @@ All examples below use CLI. MCP tools accept the same parameters as JSON objects
 | Tool | Purpose |
 |---|---|
 | `work_package` | Prepare one bounded untrusted `digest` (calendar cluster) or `transcript` package from the newest Claude Code session under the client's single matching MCP workspace root; submit exactly one strict result or defer. Submit only stages pending human review and retains bounded redacted source turns for comparison; agents cannot apply or reject. No hidden reasoning, raw transcript, transcript path, API key, LLM, embedding, or vector data is exposed or used; hashes identify freshness and workspace scope rather than authentication. |
-| `remember` | Store knowledge as an entity with observations, tags, and relations |
+| `remember` | Store knowledge as an entity with observations, tags, and relations; `note` (free text) derives title/observations/name; `replace: true` rewrites a named memory, keeping history |
 | `recall` | Search stored knowledge; empty query lists recent memories |
 | `forget` | Archive an entity or remove one exact observation |
 | `export` | Export memories as portable JSON |
 | `import` | Import a JSON export with the required skip, append, or overwrite strategy |
 | `learn` | Record a structured lesson with error, fix, root cause, and prevention |
 | `task_state` | Read or update user-stated goal, next step, blocker, and finished work |
-| `briefing` | Assemble the current project's work topology |
+| `briefing` | Assemble the current project's work topology, closing with a capped index of its durable memories |
 | `user_patterns` | Analyze work schedule, tool preferences, and focus areas |
 | `improvement` | Propose an evidence-linked product improvement or read its status; only a human may accept or reject it |
 | `message` | Discover live agents in one project, then contact one exact recipient with a bounded, untrusted payload. Native size and availability failures are distinct; acceptance, discovery, polling, and fetching do not acknowledge |
@@ -101,6 +101,8 @@ Call the `briefing` MCP tool or run `memesh briefing`. It returns the assembled
 work topology: where the work was left off (goal / next / blocked / done),
 decisions and direction, lessons not to repeat, what is known, recent activity.
 One call is cheaper than re-exploring the repo to reconstruct the same picture.
+`memesh briefing --index` returns only the index of durable memories — what is
+known here, one line each, without the ranked sections.
 Generic briefing and SessionStart context do not report unread durable messages:
 they have no recipient identity. If you already know the exact logical
 recipient, pass `recipient` with `project` (MCP) or use
@@ -154,7 +156,7 @@ With the Claude Code plugin, the first eight rows happen **without any action fr
 | **UserPromptSubmit** | When you submit a prompt | Detects "remember this" intent (5 languages) and reminds Claude to use memesh |
 | **PostToolUse (Bash)** | After `git commit` | Auto-tracks the commit with diff stats as a memory entity |
 | **PostToolUse (ExitPlanMode/AskUserQuestion)** | A plan is approved or you answer a question | Reminds Claude to `remember` the decision if it's worth keeping — once per tool per session |
-| **Stop** | Session ends | Auto-captures session knowledge and applies the configured update policy |
+| **Stop** | Session ends | Auto-captures session knowledge, ingests the project's Claude Code memory directory (frontmatter notes → `source:note-file` memories), shows one line when the turn made a decision-shaped move and stored no memory, and applies the configured update policy. The two writes (session capture, note-directory ingestion) stop when auto-capture is off (`memesh config set autoCapture false` / `MEMESH_AUTO_CAPTURE=false`); the advisory line still runs |
 | **PreCompact** | Before context compaction | Saves important knowledge before history is compressed |
 | **PreToolUse (Bash)** | Before a command runs | Fires accepted lesson-guards — warns when a recorded mistake is about to repeat |
 | **SessionStart/SessionEnd (Codex)** | An ordinary Codex CLI plugin session starts, resumes, or ends | Launches the detached exact-thread companion, replaces its generation on resume, and retires it after the bounded idle queue window; a matching owner-private config may override its project/principal |
@@ -174,7 +176,8 @@ and retiring outdated info.
 | Situation | Action |
 |-----------|--------|
 | User states what they're working on / what's next / what's blocking | `memesh task --goal "…"` / `--next "…"` / `--blocked "…"` |
-| Design decision made | `memesh remember --name "auth-choice" --type decision --obs "Use OAuth 2.0 with PKCE" --tags "project:myapp"` |
+| Design decision made | `memesh remember "Use OAuth 2.0 with PKCE for the API" --type decision --tags "project:myapp"` (or `remember({ note })` over MCP) |
+| A stored memory is wrong | `memesh remember --name "auth-choice" --obs "the corrected fact" --replace` — the memory keeps its type and the old version moves to `metadata.replaced_history` (add `--type` only to reclassify it) |
 | Bug fixed | `memesh learn --error "what broke" --fix "what fixed it" --root-cause "why" --severity major` |
 | Starting work on a feature | `memesh recall "feature-name" --json` |
 | User asks "what did we decide?" | `memesh recall "topic" --tag "project:myapp"` |
@@ -211,7 +214,13 @@ memesh remember \
 Use a **stable name** (`db-choice`, not `db-choice-2026-08-16`): reusing the
 name appends to the same entity instead of scattering duplicates. `--title` is
 the human-readable headline; the name stays the machine key. If this replaces
-an older decision, add `--supersedes "old-db-choice"`.
+an older decision, add `--supersedes "old-db-choice"`. To correct it instead
+of adding to it, repeat the call with `--replace`.
+
+Quicker when the text is all you have: `memesh remember "SQLite for local-first
+storage"` (MCP: `remember({ note: "…" })`). The first line becomes the title,
+each following paragraph an observation, and the name is derived from the text,
+so repeating the same text does not create a duplicate.
 Types: `decision` `pattern` `lesson_learned` `bug_fix` `architecture` `convention` `feature` `best_practice` `concept` `tool` `note`
 
 ### You need context on a specific topic
@@ -245,9 +254,12 @@ memesh reindex --fts                         # rebuild the local keyword index
 
 ## Memory hygiene
 
-1. **Stable names append.** Remembering under an existing name adds
-   observations and dedupes tags — it never replaces the entity. Reuse the
-   name to grow one memory; do not mint `-v2` / dated variants of it.
+1. **Stable names append — unless you ask to replace.** Remembering under an
+   existing name adds observations and dedupes tags by default. Pass
+   `replace: true` (CLI: `--replace`) to rewrite the entity's observations,
+   tags and title instead — the previous version moves to
+   `metadata.replaced_history`, not lost. Reuse the name to grow or correct
+   one memory; do not mint `-v2` / dated variants of it.
 2. **`supersedes` retires the loser.** When a new memory replaces an old one,
    record it with `--supersedes <old-name>` (MCP: a relation of type
    `supersedes`). The old entity is archived — recoverable, out of recall.