memtrace 0.3.34 → 0.3.35

package/lib/skill-metadata.js

@@ -0,0 +1,303 @@
+"use strict";
+
+// Skill frontmatter upgrader.
+//
+// Anthropic's Claude Code docs (code.claude.com/docs/en/skills.md) name two
+// frontmatter fields that drive auto-invocation reliability:
+//   * `description` — leads with the use case, ideally in user-prompt language
+//   * `when_to_use` — appended to description, holds concrete trigger phrases
+//
+// Combined cap is 1,536 chars. Our skills shipped with `description` only,
+// leading with "Always use…" — strong directive but missing the trigger-phrase
+// signal Claude reaches for when deciding whether to auto-invoke.
+//
+// This module:
+//   1. parses a skill file's YAML frontmatter without depending on a yaml lib
+//      (the frontmatter we ship is a tightly-controlled subset — top-level
+//      key/value pairs plus one `allowed-tools` list)
+//   2. upgrades it: adds `when_to_use`, adds `paths`, leaves existing keys
+//      untouched
+//   3. round-trips byte-identical for a skill that's already been upgraded
+//
+// Tested in test/skill-metadata.test.js.
+
+// ── Parser ────────────────────────────────────────────────────────────
+
+/**
+ * Parse a skill markdown file with YAML frontmatter.
+ *
+ * @param {string} content
+ * @returns {{frontmatter: object, frontmatterRaw: string, body: string}}
+ */
+function parseSkillFile(content) {
+    if (typeof content !== "string") {
+        throw new TypeError("parseSkillFile: content must be a string");
+    }
+    if (!content.startsWith("---")) {
+        return { frontmatter: {}, frontmatterRaw: "", body: content };
+    }
+    // Find the closing `---` for the frontmatter.
+    const endMarker = content.indexOf("\n---", 3);
+    if (endMarker === -1) {
+        return { frontmatter: {}, frontmatterRaw: "", body: content };
+    }
+    const frontmatterRaw = content.slice(3, endMarker).replace(/^\n/, "");
+    // Body starts after `\n---\n`. Some files have `\n---\r\n`; handle both.
+    const afterClose = endMarker + 4;
+    let bodyStart = afterClose;
+    if (content[afterClose] === "\r") bodyStart += 1;
+    if (content[bodyStart] === "\n") bodyStart += 1;
+    const body = content.slice(bodyStart);
+    const frontmatter = parseFrontmatter(frontmatterRaw);
+    return { frontmatter, frontmatterRaw, body };
+}
+
+/**
+ * Minimal YAML subset parser for our skills' frontmatter shape.
+ * Handles:
+ *   - quoted and unquoted scalar values
+ *   - YAML list values (`allowed-tools:` followed by `  - item` lines)
+ *   - keeps unknown keys intact in insertion order
+ *
+ * @param {string} raw
+ * @returns {Record<string, string|string[]|boolean>}
+ */
+function parseFrontmatter(raw) {
+    const out = {};
+    const lines = raw.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line || /^\s*#/.test(line)) {
+            i++;
+            continue;
+        }
+        const m = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const key = m[1];
+        const valueRaw = m[2];
+        if (valueRaw === "") {
+            // Look ahead for a list
+            const list = [];
+            i++;
+            while (i < lines.length && /^\s+-\s+/.test(lines[i])) {
+                list.push(lines[i].replace(/^\s+-\s+/, "").trim());
+                i++;
+            }
+            out[key] = list;
+            continue;
+        }
+        out[key] = parseScalar(valueRaw);
+        i++;
+    }
+    return out;
+}
+
+function parseScalar(raw) {
+    const t = raw.trim();
+    if (t === "true") return true;
+    if (t === "false") return false;
+    if ((t.startsWith('"') && t.endsWith('"')) ||
+        (t.startsWith("'") && t.endsWith("'"))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+
+// ── Serializer ────────────────────────────────────────────────────────
+
+/**
+ * Serialize back to `--- ... ---\n\nbody`. Order:
+ *   1. name (always first if present)
+ *   2. description
+ *   3. when_to_use
+ *   4. paths
+ *   5. allowed-tools (list)
+ *   6. user-invocable
+ *   7. anything else, in original order
+ *
+ * Quoting rule: scalar values containing colons, hashes, or newlines get
+ * double-quoted; lists and bare identifiers don't.
+ *
+ * @param {{frontmatter: object, body: string}} parsed
+ * @returns {string}
+ */
+function serializeSkill(parsed) {
+    const fm = parsed.frontmatter || {};
+    const body = parsed.body || "";
+    const orderedKeys = [
+        "name",
+        "description",
+        "when_to_use",
+        "paths",
+        "allowed-tools",
+        "user-invocable",
+    ];
+    const seen = new Set();
+    const lines = ["---"];
+    for (const k of orderedKeys) {
+        if (k in fm) {
+            lines.push(...formatPair(k, fm[k]));
+            seen.add(k);
+        }
+    }
+    for (const k of Object.keys(fm)) {
+        if (!seen.has(k)) {
+            lines.push(...formatPair(k, fm[k]));
+        }
+    }
+    lines.push("---");
+    return lines.join("\n") + (body.startsWith("\n") ? "" : "\n") + body;
+}
+
+function formatPair(key, value) {
+    if (Array.isArray(value)) {
+        return [`${key}:`, ...value.map((v) => `  - ${v}`)];
+    }
+    if (typeof value === "boolean") {
+        return [`${key}: ${value}`];
+    }
+    const s = String(value);
+    if (s.includes(":") || s.includes("#") || s.includes("\n") || s.includes('"')) {
+        return [`${key}: "${s.replace(/"/g, '\\"')}"`];
+    }
+    return [`${key}: ${s}`];
+}
+
+// ── Upgrader ──────────────────────────────────────────────────────────
+
+/**
+ * Upgrade a skill's frontmatter to v0.3.35 best practices.
+ *
+ *   - Adds `when_to_use` from the trigger map (does not overwrite existing).
+ *   - Adds `paths` (does not overwrite existing).
+ *   - Leaves `description` as-is — operators are responsible for reframing
+ *     the description text manually since it requires per-skill judgement.
+ *
+ * @param {object} parsed         output of parseSkillFile
+ * @param {string} skillName      e.g. "memtrace-first"
+ * @param {object} triggers       { [skillName]: { whenToUse, paths } }
+ * @returns {object}              updated parsed
+ */
+function upgradeSkill(parsed, skillName, triggers) {
+    const fm = { ...(parsed.frontmatter || {}) };
+    const t = triggers[skillName];
+    if (!t) {
+        return parsed; // unknown skill — leave alone
+    }
+    if (!fm.when_to_use && t.whenToUse) {
+        fm.when_to_use = t.whenToUse;
+    }
+    if (!fm.paths && t.paths) {
+        fm.paths = t.paths;
+    }
+    return { ...parsed, frontmatter: fm };
+}
+
+// ── Default trigger map ───────────────────────────────────────────────
+//
+// Concrete trigger phrases per skill. The pool is biased toward language
+// users actually type, plus the imperatives the agent's planner uses
+// internally ("trace through", "find the function that", etc.).
+
+const CODE_PATHS = "**/*.{py,js,jsx,ts,tsx,mjs,cjs,rs,go,java,rb,c,cc,cpp,cxx,h,hpp,hh,cs,php,swift,kt,kts,scala,clj,cljs,ex,exs,erl,hrl,ml,mli,fs,fsx,r,jl,lua,dart,m,mm,asm,sql,gql,graphql,proto,sh,bash,zsh,fish,vue,svelte}";
+
+const DEFAULT_TRIGGERS = {
+    "memtrace-first": {
+        whenToUse:
+            "Triggered when user says 'where is', 'how does', 'what calls', 'why does', 'find the function that', 'trace through', 'show me', 'explain this code', 'investigate', 'debug', 'understand', 'audit', 'fix bug', 'refactor', 'review', 'check for'. Use BEFORE Read/Grep/Glob/find/rg for any code-discovery question in an indexed repo. Treat zero results as a query-broadening or reindex prompt — never as permission to grep.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-search": {
+        whenToUse:
+            "Triggered by 'find function', 'where is X defined', 'locate', 'look up', 'search for', 'find class', 'find type', 'find struct', 'find interface'. Also when user references a constant, error string, or magic value and asks where it's used.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-relationships": {
+        whenToUse:
+            "Triggered by 'who calls', 'callers of', 'callees', 'what does X call', 'who imports', 'where is X used', 'references to', 'inheritance', 'overrides', 'implementations of'. Use to walk the call graph rather than greping for symbol names.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-impact": {
+        whenToUse:
+            "Triggered by 'what breaks if', 'blast radius', 'impact of changing', 'safe to remove', 'safe to rename', 'dependencies on', 'who depends on', 'before refactor', 'before delete', 'risk of changing'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-evolution": {
+        whenToUse:
+            "Triggered by 'when did this change', 'what changed in', 'recent changes', 'evolution of', 'history of', 'who modified', 'why does this look like', 'before refactor X', 'after Y was added', 'last week's changes'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-cochange": {
+        whenToUse:
+            "Triggered by 'what changes together', 'co-change', 'historical coupling', 'hidden dependency', 'usually moves with', 'should I also touch', 'what else needs updating'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-graph": {
+        whenToUse:
+            "Triggered by 'most important', 'central to', 'critical functions', 'chokepoints', 'bridges', 'communities', 'modules', 'subsystems', 'hubs', 'depends on most', 'most depended on', 'architecture overview'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-quality": {
+        whenToUse:
+            "Triggered by 'dead code', 'unused functions', 'zero callers', 'complex functions', 'hotspots', 'cyclomatic complexity', 'cognitive complexity', 'code smells', 'refactoring candidates', 'tech debt'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-api-topology": {
+        whenToUse:
+            "Triggered by 'API endpoints', 'HTTP routes', 'who calls /endpoint', 'cross-service calls', 'service dependency', 'route handlers', 'fetch calls', 'REST surface', 'service diagram', 'call from frontend to backend'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-index": {
+        whenToUse:
+            "Triggered by 'index this repo', 'add to memtrace', 'parse this codebase', 'reindex', 'watch directory', 'enable live indexing', 'set up memtrace for'. Use when bringing a new project under code-intelligence coverage.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-change-impact-analysis": {
+        whenToUse:
+            "Triggered before edits, refactors, API changes, renames, removals, or PR review when user asks about 'what will break', 'what does this affect', 'is this safe', 'callers I need to update', 'before I merge'. Use to combine search + impact + change detection.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-codebase-exploration": {
+        whenToUse:
+            "Triggered by 'tour of this codebase', 'how is this organized', 'where do I start', 'onboard me', 'explain the architecture', 'main flows', 'main modules', 'key classes', 'I just cloned this'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-continuous-memory": {
+        whenToUse:
+            "Triggered by 'watch this folder', 'live indexing', 'incremental memtrace', 'always-on memory', 'keep up to date', 'pick up my saves', 'reflect uncommitted changes', 'why isn't memtrace seeing my edits'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-episode-replay": {
+        whenToUse:
+            "Triggered by 'replay history', 'why does this look like this', 'evolution of this design', 'past attempts at', 'we tried X before', 'reverted approach', 'how did we get here'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-incident-investigation": {
+        whenToUse:
+            "Triggered by 'production broke', 'incident', 'regression', 'something is failing', 'why is X slow', 'root cause', 'what changed when', 'last working state', 'bisect', 'broken since deploy'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-refactoring-guide": {
+        whenToUse:
+            "Triggered by 'refactor this', 'reduce complexity', 'split this function', 'extract module', 'clean up tech debt', 'reorganize', 'where should I start refactoring', 'priority for cleanup'.",
+        paths: CODE_PATHS,
+    },
+    "memtrace-session-continuity": {
+        whenToUse:
+            "Triggered at session start or resume — 'catch me up', 'what changed while I was away', 'resume', 'pick up where I left off', 'recap', 'orient', 'summary since yesterday', 'since last commit'.",
+        paths: CODE_PATHS,
+    },
+};
+
+module.exports = {
+    parseSkillFile,
+    parseFrontmatter,
+    serializeSkill,
+    upgradeSkill,
+    DEFAULT_TRIGGERS,
+    CODE_PATHS,
+};

package/lib/spawn-helper.js

@@ -0,0 +1,63 @@
+"use strict";
+
+// Shared spawn helpers for the npm shim.
+//
+// Why this exists: Node 18.20+ / 20.12+ / 21.7+ refuse to spawn `.cmd`
+// and `.bat` files on Windows without `shell: true`, as part of the
+// CVE-2024-27980 mitigation. The release notes from Node phrase this
+// as a "policy change" but in practice it surfaces as
+// `Error: spawn npm.cmd EINVAL` on first install — which is exactly
+// what Orbit hit on Windows during a fresh global install.
+//
+// The fix is small: when targeting `.cmd` / `.bat` on Windows, pass
+// `shell: true`. macOS and Linux don't need it (npm is a real binary
+// on PATH there).
+//
+// Pulled into its own module so we can TDD it without spawning real
+// processes. The unit + property tests live in
+// `npm/memtrace/test/spawn-helper.test.js`.
+
+/**
+ * Pick the platform-specific binary name for a tool that ships as a
+ * `.cmd` shim on Windows. Used for `npm`, `memtrace` itself, and
+ * anything else that has the same dual-name shape.
+ *
+ * @param {string} unixName  - the bare tool name on macOS/Linux ("npm")
+ * @param {string} platform  - usually `process.platform`
+ * @returns {string}         - "npm" or "npm.cmd"
+ */
+function platformBinary(unixName, platform) {
+    if (typeof unixName !== "string" || unixName.length === 0) {
+        throw new TypeError("platformBinary: unixName must be a non-empty string");
+    }
+    return platform === "win32" ? unixName + ".cmd" : unixName;
+}
+
+/**
+ * Build a spawn options object that's safe for the given platform.
+ *
+ * On Windows, returns options with `shell: true` set, which is
+ * mandatory for spawning `.cmd` / `.bat` files since the
+ * CVE-2024-27980 mitigation. On non-Windows platforms, returns the
+ * options unchanged so we don't accidentally re-tokenise arguments
+ * through a shell that doesn't need it.
+ *
+ * Pure: does not mutate `baseOpts`. Always returns a new object.
+ *
+ * @param {string} platform  - usually `process.platform`
+ * @param {object} [baseOpts] - any options to merge in
+ * @returns {object}
+ */
+function spawnOptionsForPlatform(platform, baseOpts) {
+    const base = baseOpts && typeof baseOpts === "object" ? baseOpts : {};
+    const merged = Object.assign({}, base);
+    if (platform === "win32") {
+        merged.shell = true;
+    }
+    return merged;
+}
+
+module.exports = {
+    platformBinary,
+    spawnOptionsForPlatform,
+};

package/lib/upgrade-skills.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+"use strict";
+
+// One-shot upgrader: walks every skill file under both
+// `npm/memtrace/skills/` and `npm/memtrace/installer/skills/` and
+// adds `when_to_use` + `paths` from the trigger map. Idempotent;
+// safe to re-run.
+//
+// Usage:  node npm/memtrace/lib/upgrade-skills.js
+//
+// Exit code 0 on success.
+
+const fs = require("fs");
+const path = require("path");
+const {
+    parseSkillFile,
+    serializeSkill,
+    upgradeSkill,
+    DEFAULT_TRIGGERS,
+} = require("./skill-metadata");
+
+const ROOTS = [
+    path.join(__dirname, "..", "skills"),
+    path.join(__dirname, "..", "installer", "skills"),
+];
+
+let totalScanned = 0;
+let totalUpgraded = 0;
+let totalSkipped = 0;
+
+function walk(root) {
+    if (!fs.existsSync(root)) return;
+    const entries = fs.readdirSync(root, { withFileTypes: true });
+    for (const e of entries) {
+        const full = path.join(root, e.name);
+        if (e.isDirectory()) {
+            walk(full);
+        } else if (e.isFile() && e.name.endsWith(".md")) {
+            processSkillFile(full);
+        }
+    }
+}
+
+function processSkillFile(filePath) {
+    totalScanned++;
+    const original = fs.readFileSync(filePath, "utf8");
+    const parsed = parseSkillFile(original);
+    const skillName = parsed.frontmatter.name || path.basename(filePath, ".md");
+
+    if (!DEFAULT_TRIGGERS[skillName]) {
+        totalSkipped++;
+        return;
+    }
+
+    const upgraded = upgradeSkill(parsed, skillName, DEFAULT_TRIGGERS);
+    const serialized = serializeSkill(upgraded);
+
+    if (serialized === original) {
+        totalSkipped++;
+        return;
+    }
+
+    fs.writeFileSync(filePath, serialized);
+    totalUpgraded++;
+    console.log(`upgraded: ${path.relative(process.cwd(), filePath)}`);
+}
+
+for (const root of ROOTS) {
+    walk(root);
+}
+
+console.log(`\nscanned ${totalScanned} skill files · upgraded ${totalUpgraded} · skipped ${totalSkipped}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.3.34",
+  "version": "0.3.35",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -22,6 +22,8 @@
   },
   "files": [
     "bin/",
+    "lib/",
+    "hooks/",
     "skills/",
     "installer/",
     "install.js",
@@ -37,9 +39,9 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.3.34",
-    "@memtrace/linux-x64": "0.3.34",
-    "@memtrace/win32-x64": "0.3.34"
+    "@memtrace/darwin-arm64": "0.3.35",
+    "@memtrace/linux-x64": "0.3.35",
+    "@memtrace/win32-x64": "0.3.35"
   },
   "engines": {
     "node": ">=18"