@pcircle/memesh 4.9.3 → 4.9.4

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "memesh",
       "source": "./",
       "description": "MeMesh \u2014 agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
-      "version": "4.9.3",
+      "version": "4.9.4",
       "author": {
         "name": "PCIRCLE AI"
       },

package/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "PCIRCLE AI"
   },
-  "version": "4.9.3",
+  "version": "4.9.4",
   "mcpServers": "./.claude-plugin/mcp.json",
   "homepage": "https://github.com/PCIRCLE-AI/memesh",
   "repository": "https://github.com/PCIRCLE-AI/memesh",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memesh",
   "description": "MeMesh — agentic memory for coding agents.",
-  "version": "4.9.3",
+  "version": "4.9.4",
   "mcpServers": "./.codex-plugin/mcp.json"
 }

package/dist/skills-manifest.json

@@ -8,7 +8,7 @@
     },
     {
       "path": ".claude-plugin/plugin.json",
-      "sha256": "e1ff07fff7c5002f916e6c55172e953e726a24f46a2a705585fef53d726867d6",
+      "sha256": "cfb107b54e757ba86356a0defdebf7b1f12fbf45acbf8920d91793d849f33f4e",
       "bytes": 572
     },
     {
@@ -18,7 +18,7 @@
     },
     {
       "path": ".codex-plugin/plugin.json",
-      "sha256": "c68af5ed07947baf7ef3d66c5262cf3a34ac20f0981cf223ecc652d6e298bca8",
+      "sha256": "627cae483533b13ec22c0288c8e1abc2d2a7521bc6ccad7813b1065b5ab91816",
       "bytes": 154
     },
     {
@@ -96,6 +96,11 @@
       "sha256": "4474f784643a3384a066b508473ff17ee39beecd86d57451300592971528d3c4",
       "bytes": 48742
     },
+    {
+      "path": "scripts/hooks/auto-update-runner.mjs",
+      "sha256": "6435dbe0d142f52349da0c2ef8f82c455935be506a1b9e78f09f117c776d02b7",
+      "bytes": 7347
+    },
     {
       "path": "scripts/hooks/decision-nudge.js",
       "sha256": "424bf5cd4f68cb55e441a5aed1db78b262df2a5ef4a7e60a56db2f9d3f103d5d",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcircle/memesh",
-  "version": "4.9.3",
+  "version": "4.9.4",
   "description": "MeMesh — agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
   "main": "dist/index.js",
   "type": "module",
@@ -27,6 +27,8 @@
     "README.md",
     "LICENSE",
     "llms-install.md",
+    "scripts/check-plugin-hook-artifact.mjs",
+    "scripts/lib/npm-bin.mjs",
     "AGENTS.md"
   ],
   "scripts": {
@@ -49,7 +51,8 @@
     "audit:prod": "node scripts/check-consumer-audit.mjs",
     "audit:memory": "node scripts/audit/memory-invariants.mjs",
     "check:entry-points-start": "node scripts/check-entry-points-start.mjs",
-    "verify:release": "npm run lint && npm run typecheck && node scripts/check-version-coherence.mjs && node scripts/check-generated-mirror.mjs && node scripts/check-agent-message-sync.mjs && npm run check:surface-parity && node scripts/check-doc-claims.mjs && node scripts/audit/verification-audit.mjs && npm run audit:prod && npm run check:entry-points-start",
+    "check:plugin-hook-artifact": "node scripts/check-plugin-hook-artifact.mjs",
+    "verify:release": "npm run lint && npm run typecheck && node scripts/check-version-coherence.mjs && node scripts/check-generated-mirror.mjs && node scripts/check-agent-message-sync.mjs && npm run check:surface-parity && node scripts/check-doc-claims.mjs && node scripts/audit/verification-audit.mjs && npm run audit:prod && npm run check:entry-points-start && npm run check:plugin-hook-artifact",
     "release:finish": "node scripts/finish-release.mjs",
     "verify:artifact": "npm run verify:release && npm run test:isolated && npm run test:packaged && npm run test:packaged:upgrade",
     "prepublishOnly": "npm run build && npm run verify:artifact",

package/scripts/check-plugin-hook-artifact.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/** Verify plugin hooks and host entrypoints before a cache/artifact swap. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { npmSync, envWithNpmCache } from './lib/npm-bin.mjs';
+
+export const CLAUDE_PLUGIN_ROOT_PREFIX = '${CLAUDE_PLUGIN_ROOT}/';
+
+function isSubpath(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+export function hookTargetsFromManifest(manifest) {
+  const targets = [];
+  for (const [event, entries] of Object.entries(manifest?.hooks ?? {})) {
+    if (!Array.isArray(entries)) throw new Error(`${event} is not an array in hooks/hooks.json`);
+    for (const entry of entries) {
+      for (const hook of entry?.hooks ?? []) {
+        if (hook?.type !== 'command') continue;
+        if (typeof hook.command !== 'string' || !hook.command.startsWith(CLAUDE_PLUGIN_ROOT_PREFIX)) {
+          throw new Error(`${event} command must start with ${CLAUDE_PLUGIN_ROOT_PREFIX}`);
+        }
+        const relative = hook.command.slice(CLAUDE_PLUGIN_ROOT_PREFIX.length);
+        if (!relative || /\s/.test(relative) || path.posix.normalize(relative) !== relative || relative.startsWith('../')) {
+          throw new Error(`${event} command is not a single safe plugin-relative path: ${hook.command}`);
+        }
+        targets.push({ event, relative });
+      }
+    }
+  }
+  if (targets.length === 0) throw new Error('hooks/hooks.json declares no command hooks');
+  return targets;
+}
+
+export function readHookManifest(root) {
+  return JSON.parse(fs.readFileSync(path.join(root, 'hooks', 'hooks.json'), 'utf8'));
+}
+
+export function validateHookTargets(root, manifest = readHookManifest(root)) {
+  const rootPath = path.resolve(root);
+  const targets = hookTargetsFromManifest(manifest);
+  const missing = [];
+  for (const target of targets) {
+    const resolved = path.resolve(rootPath, target.relative);
+    try {
+      if (isContainedRegularFile(rootPath, resolved)) continue;
+    } catch {
+      // Report the same bounded finding for missing and unreadable targets.
+    }
+    missing.push({ ...target, resolved });
+  }
+  return { targets, missing, ok: missing.length === 0 };
+}
+
+/**
+ * True only for a regular file whose every path component lives inside root.
+ * `lstat` rejects a symlink as the last component; `realpathSync` on both
+ * sides rejects a symlinked directory ABOVE it — `scripts/hooks -> /elsewhere`
+ * passed the lstat-only check and would have let a staged cache execute
+ * ambient bytes. Throws on a missing path, like the fs calls it wraps.
+ */
+function isContainedRegularFile(rootPath, resolved) {
+  if (!isSubpath(rootPath, resolved) || !fs.lstatSync(resolved).isFile()) return false;
+  return isSubpath(fs.realpathSync(rootPath), fs.realpathSync(resolved));
+}
+
+function safeRelativePath(value, label) {
+  if (typeof value !== 'string' || !value.startsWith('./')) {
+    throw new Error(`${label} must be a ./ relative path`);
+  }
+  const relative = value.slice(2);
+  if (!relative || path.posix.normalize(relative) !== relative || relative.startsWith('../') || path.isAbsolute(relative)) {
+    throw new Error(`${label} is not a safe plugin-relative path: ${value}`);
+  }
+  return relative;
+}
+
+function regularFile(root, relative, label) {
+  const rootPath = path.resolve(root);
+  const resolved = path.resolve(rootPath, relative);
+  if (!isSubpath(rootPath, resolved)) throw new Error(`${label} escapes plugin root: ${relative}`);
+  try {
+    if (isContainedRegularFile(rootPath, resolved)) return relative;
+  } catch {
+    // Fall through to one bounded diagnostic.
+  }
+  throw new Error(`${label} is missing or not a regular file: ${relative}`);
+}
+
+export function validatePluginEntrypoints(root) {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  const targets = [];
+  for (const [relativeManifest, expectedPrefix] of [
+    ['.claude-plugin/plugin.json', '${CLAUDE_PLUGIN_ROOT}/'],
+    ['.codex-plugin/plugin.json', './'],
+  ]) {
+    regularFile(root, relativeManifest, relativeManifest);
+    const plugin = JSON.parse(fs.readFileSync(path.join(root, relativeManifest), 'utf8'));
+    if (plugin.name !== 'memesh') throw new Error(`${relativeManifest} has unexpected plugin name`);
+    if (plugin.version !== packageJson.version) throw new Error(`${relativeManifest} version does not match package.json`);
+    const mcpManifest = safeRelativePath(plugin.mcpServers, `${relativeManifest} mcpServers`);
+    regularFile(root, mcpManifest, `${relativeManifest} mcpServers`);
+    targets.push({ kind: 'manifest', relative: relativeManifest });
+    targets.push({ kind: 'manifest', relative: mcpManifest });
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, mcpManifest), 'utf8'));
+    const entry = manifest.mcpServers?.memesh;
+    if (!entry || entry.command !== 'node' || !Array.isArray(entry.args) || typeof entry.args[0] !== 'string') {
+      throw new Error(`${mcpManifest} has no valid mcpServers.memesh node entry`);
+    }
+    const rawTarget = entry.args[0];
+    if (!rawTarget.startsWith(expectedPrefix)) {
+      throw new Error(`${mcpManifest} entry must start with ${expectedPrefix}`);
+    }
+    const target = rawTarget.slice(expectedPrefix.length);
+    if (path.posix.normalize(target) !== target || target.startsWith('../') || path.isAbsolute(target)) {
+      throw new Error(`${mcpManifest} entry is not a safe plugin-relative path: ${rawTarget}`);
+    }
+    regularFile(root, target, `${mcpManifest} entrypoint`);
+    targets.push({ kind: 'entrypoint', relative: target });
+  }
+  return { targets };
+}
+
+export function validateArtifactPaths(targets, files) {
+  const shipped = new Set(files.map((file) => typeof file === 'string' ? file : file.path));
+  const missing = targets.filter((target) => !shipped.has(target.relative));
+  return { missing, ok: missing.length === 0 };
+}
+
+function packFiles(root) {
+  const npmCache = fs.mkdtempSync(path.join(os.tmpdir(), 'memesh-pack-cache-'));
+  try {
+    const stdout = npmSync(['pack', '--dry-run', '--json', '--ignore-scripts'], {
+      cwd: root,
+      encoding: 'utf8',
+      env: envWithNpmCache(npmCache),
+    });
+    let report;
+    try { report = JSON.parse(String(stdout)); } catch { throw new Error('npm pack --dry-run did not return valid JSON'); }
+    const entry = Array.isArray(report) ? report[0] : report;
+    if (!entry || !Array.isArray(entry.files)) throw new Error('npm pack --dry-run returned no file list');
+    return entry.files;
+  } catch (error) {
+    if (error instanceof Error && /npm pack --dry-run (?:did not return|returned no)/.test(error.message)) throw error;
+    const record = error && typeof error === 'object' ? /** @type {Record<string, unknown>} */ (error) : {};
+    const status = typeof record.status === 'number' ? record.status : 'unknown';
+    const stderr = typeof record.stderr === 'string' ? record.stderr.trim() : '';
+    throw new Error(
+      `npm pack --dry-run failed (exit ${status}): ${stderr || (error instanceof Error ? error.message : String(error))}`,
+      { cause: error },
+    );
+  } finally {
+    fs.rmSync(npmCache, { recursive: true, force: true });
+  }
+}
+
+export function checkPluginHookArtifact(root, { checkPack = true } = {}) {
+  const source = validateHookTargets(root);
+  const plugin = validatePluginEntrypoints(root);
+  const allTargets = [...source.targets, ...plugin.targets];
+  if (!checkPack) return { ...source, plugin, artifact: null };
+  return { ...source, plugin, artifact: validateArtifactPaths(allTargets, packFiles(root)) };
+}
+
+function main(argv) {
+  const rootIndex = argv.indexOf('--root');
+  if (rootIndex !== -1 && (!argv[rootIndex + 1] || argv[rootIndex + 1].startsWith('--'))) {
+    console.error('plugin hook integrity: --root requires a directory argument');
+    process.exit(2);
+  }
+  const root = path.resolve(rootIndex === -1 ? process.cwd() : argv[rootIndex + 1]);
+  const checkPack = !argv.includes('--skip-pack');
+  try {
+    const result = checkPluginHookArtifact(root, { checkPack });
+    if (!result.ok) {
+      for (const item of result.missing) console.error(`Missing hook target: ${item.event} -> ${item.resolved}`);
+      process.exit(1);
+    }
+    if (result.artifact && !result.artifact.ok) {
+      for (const item of result.artifact.missing) console.error(`Target omitted from npm artifact: ${item.event ?? item.kind} -> ${item.relative}`);
+      process.exit(1);
+    }
+    console.log(`plugin artifact integrity: PASS (${result.targets.length} hook targets, ${result.plugin.targets.length} plugin/MCP targets${checkPack ? ', npm artifact checked' : ''})`);
+  } catch (error) {
+    console.error(`plugin hook integrity: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Run `main` only when this file is the entrypoint. Both sides go through
+ * realpath: Node resolves symlinks in `import.meta.url` but not in argv[1],
+ * so `node /var/folders/.../check-plugin-hook-artifact.mjs` (macOS tmp is a
+ * symlink) compared unequal, skipped `main`, and exited 0 with no output — a
+ * silent PASS from a checker that had checked nothing. Pinned by the tarball
+ * test in tests/plugin-hook-artifact.test.ts, which asserts on the output.
+ */
+function isEntrypoint(argv1) {
+  if (!argv1) return false;
+  const self = fileURLToPath(import.meta.url);
+  const given = path.resolve(argv1);
+  if (self === given) return true;
+  // A realpath failure must not become "not the entrypoint": that is exit 0
+  // with nothing checked, the fail-closed guard's caller only reads the exit
+  // code, and a staged plugin would swap in unverified. Let it throw.
+  return fs.realpathSync(self) === fs.realpathSync(given);
+}
+
+if (isEntrypoint(process.argv[1])) main(process.argv.slice(2));

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