@raymondchins/agentmap 0.6.1 → 0.7.0

package/README.md

@@ -185,6 +185,25 @@ internally on `tool_name`. For reference, or to wire it by hand:
 That's the "forced to use it" in the tagline: the map stays current on its own, and the
 agent is steered to it the moment it reaches for a dependency-shaped grep or Bash search.
 
+### 3. Agent skills (Cursor, Claude Code, Codex)
+
+```bash
+npx @raymondchins/agentmap --install-skill
+```
+
+Copies a packaged **SKILL.md** (Claude Code / Codex / OpenCode) and a **Cursor rule**
+(`.cursor/rules/agentmap.mdc`, `alwaysApply: true`) into the current repo or global
+agent directories. Options:
+
+```bash
+agentmap --install-skill --platform cursor      # Cursor rule only
+agentmap --install-skill --platform claude      # .claude/skills/agentmap/SKILL.md
+agentmap --install-skill --global --platform claude  # ~/.claude/skills/...
+agentmap --install-skill --dry-run              # preview paths, no writes
+```
+
+Pair with `--install-hooks` (Claude Code) or `--mcp` (Cursor MCP).
+
 ---
 
 ## Quickstart
@@ -481,6 +500,8 @@ $ node agentmap.mjs --print | jq '.hubs[0]'
 | `--version` / `-v` | Print the version from `package.json` and exit 0. |
 | `--json` | **Global modifier.** When present, every command prints exactly one JSON object to stdout (no prose). Shapes vary per command: `--json --hubs` → `{command,fileCount,sha,hubs:[string]}`, `--json --find X` → `{command,query,matches:[{file,name,kind}]}`, `--json --relates X` → `{command,file,pagerank,exports,imports,dependents,related}`, `--json --any X` → `{command,query,kind,…payload}`, etc. Bare `--json` (no query flag) → `{command:"build",fileCount,features,topHub}`. |
 | `--install-hooks` | Copy `hooks/post-commit` into `.git/hooks/` (chmod 0755), ensure `.claude/agentmap.json` is in `.gitignore`, and auto-wire the Claude Code `PreToolUse(Grep)` nudge into `.claude/settings.json` (merge-safe + idempotent). Exit 0 on success, stderr + exit 1 on failure. |
+| `--hook-status` | Report whether the post-commit hook, PreToolUse nudge, and `.gitignore` entry are installed (no writes). |
+| `--install-skill` | Install packaged agent skill + Cursor rule (`--platform claude\|cursor\|agents\|all`, default `all`; `--project` default, or `--global`; `--dry-run` preview). |
 | `--mcp` | Start agentmap as a **stdio MCP server** so non-Claude-Code agents (Cursor, Cline, any MCP client) can call every flag as a first-class tool. |
 
 **Exit-code contract:** `0` = success / match / help / version; `1` = query returned zero results (`--any`, `--find`, `--relates`, `--feature` with no match); `2` = usage error (missing required arg, unknown flag). Any token starting with `-` that matches no known flag prints an error to stderr and exits 2.

package/agentmap.mjs

@@ -917,6 +917,60 @@ function installHooks({ dryRun = false } = {}) {
   console.log("\nDone — the map auto-refreshes on commit, and greps are nudged to agentmap first.");
 }
 
+// Marker string baked into hooks/post-commit — used by --hook-status to detect our
+// hook even when chained with other tools in the same file.
+const POST_COMMIT_MARKER = "agentmap — git post-commit hook";
+const NUDGE_REL = ".claude/hooks/agentmap-nudge.mjs";
+const MAP_IGNORE_LINE = ".claude/agentmap/";
+
+function hookStatus() {
+  const gitDir = sh("git rev-parse --git-dir");
+  if (!gitDir) {
+    console.log("not a git repository — run inside the repo you want to check");
+    return;
+  }
+  const hooksDir = `${gitDir}/hooks`;
+  const postCommitPath = `${hooksDir}/post-commit`;
+
+  let postCommit = "not installed";
+  if (existsSync(postCommitPath)) {
+    const body = readFileSync(postCommitPath, "utf8");
+    postCommit = body.includes(POST_COMMIT_MARKER) ? "installed" : "not installed (hook exists but agentmap not found)";
+  }
+
+  let nudge = existsSync(NUDGE_REL) ? "installed" : "not installed";
+
+  let grepWire = "not wired";
+  let bashWire = "not wired";
+  const settingsPath = ".claude/settings.json";
+  if (existsSync(settingsPath)) {
+    try {
+      const settings = parseSettings(readFileSync(settingsPath, "utf8"), settingsPath);
+      const entries = settings.hooks?.PreToolUse || [];
+      const has = (matcher) => entries.some(
+        (e) => e?.matcher === matcher && Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
+      );
+      grepWire = has("Grep") ? "wired" : "not wired";
+      bashWire = has("Bash") ? "wired" : "not wired";
+    } catch {
+      grepWire = "not wired (invalid settings.json)";
+      bashWire = "not wired (invalid settings.json)";
+    }
+  }
+
+  let gitignore = "missing entry";
+  if (existsSync(".gitignore")) {
+    const ok = readFileSync(".gitignore", "utf8").split(/\r?\n/).some((l) => l.trim() === MAP_IGNORE_LINE);
+    gitignore = ok ? "ok" : "missing entry";
+  }
+
+  console.log(`post-commit: ${postCommit}`);
+  console.log(`nudge (${NUDGE_REL}): ${nudge}`);
+  console.log(`PreToolUse(Grep): ${grepWire}`);
+  console.log(`PreToolUse(Bash): ${bashWire}`);
+  console.log(`.gitignore (${MAP_IGNORE_LINE}): ${gitignore}`);
+}
+
 // ---------------------------------------------------------------------------
 // --setup-mcp: register the agentmap MCP server in the global configs of
 // MCP-capable IDEs that aren't Claude Code (which uses --install-hooks instead).
@@ -998,7 +1052,8 @@ const out = (obj, prose) => { if (wantJson) console.log(JSON.stringify(obj)); el
 // NOT in this set is an unknown flag → usage error (exit 2), not a silent build.
 const KNOWN = new Set([
   "--json", "--print",
-  "--help", "-h", "--version", "-v", "--install-hooks", "--dry-run", "--setup-mcp", "--mcp",
+  "--help", "-h", "--version", "-v", "--install-hooks", "--hook-status", "--install-skill", "--platform", "--project", "--global",
+  "--dry-run", "--setup-mcp", "--mcp",
   "--any", "--find", "--relates", "--map", "--focus", "--tokens",
   "--symbols", "--feature", "--features", "--hubs",
 ]);
@@ -1007,7 +1062,7 @@ const KNOWN = new Set([
 // so a dash-leading query like `--any "-O/bin/sh"` is bound as the query, not
 // mistaken for an unknown flag. (arg() already rejects a "--"-leading value, so
 // `--any --foo` still falls through to the missing-arg guard instead.)
-const VALUE_FLAGS = new Set(["--any", "--find", "--relates", "--feature", "--focus", "--tokens", "--symbols"]);
+const VALUE_FLAGS = new Set(["--any", "--find", "--relates", "--feature", "--focus", "--tokens", "--symbols", "--platform"]);
 const valueIdx = new Set();
 for (let i = 0; i < args.length - 1; i++) if (VALUE_FLAGS.has(args[i])) valueIdx.add(i + 1);
 
@@ -1035,6 +1090,9 @@ Maintenance:
   --install-hooks [--dry-run]
                        install git post-commit + copy the PreToolUse nudge +
                        wire .claude/settings.json (--dry-run = preview, no writes)
+  --install-skill [--platform claude|cursor|agents|all] [--project|--global] [--dry-run]
+                       install SKILL.md / Cursor rule for coding agents
+  --hook-status          report whether agentmap git/nudge wiring is installed
   --setup-mcp [--dry-run]
                        configure MCP server for OpenCode & Antigravity IDE
                        (--dry-run = preview, no writes)
@@ -1073,6 +1131,29 @@ else if (has("--install-hooks")) {
   try { installHooks({ dryRun: has("--dry-run") }); process.exit(0); }
   catch (e) { console.error(`agentmap --install-hooks failed: ${e?.message || e}`); process.exit(1); }
 }
+// --install-skill: copy packaged SKILL.md / Cursor rule (see skills/install.mjs).
+else if (has("--install-skill")) {
+  try {
+    // lazy import keeps skills/install.mjs (and its package.json read) OFF the
+    // hot path — warm --any/--find queries must not load it.
+    const { installSkill } = await import("./skills/install.mjs");
+    installSkill({
+      platforms: arg("--platform") || "all",
+      project: !has("--global"),
+      global: has("--global"),
+      dryRun: has("--dry-run"),
+    });
+    process.exit(0);
+  } catch (e) {
+    console.error(`agentmap --install-skill failed: ${e?.message || e}`);
+    process.exit(1);
+  }
+}
+// --hook-status: report post-commit / nudge / settings wiring (no writes).
+else if (has("--hook-status")) {
+  try { hookStatus(); process.exit(0); }
+  catch (e) { console.error(`agentmap --hook-status failed: ${e?.message || e}`); process.exit(1); }
+}
 // --setup-mcp: configure MCP server for OpenCode & Antigravity IDE.
 else if (has("--setup-mcp")) {
   try { setupMcp({ dryRun: has("--dry-run") }); process.exit(0); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raymondchins/agentmap",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -14,6 +14,7 @@
     "agentmap.mjs",
     "mcp.mjs",
     "hooks",
+    "skills",
     "NOTICE"
   ],
   "scripts": {

package/skills/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: agentmap
+description: >-
+  Use for TypeScript/JavaScript codebase navigation — symbol lookup, blast radius,
+  reuse checks, and repo orientation. Prefer agentmap before serial grep when
+  exploring imports, exports, or where a symbol lives. Package is
+  @raymondchins/agentmap (not the unrelated npm package agentmap).
+---
+
+# agentmap
+
+Queryable, ranked **import graph** for TS/JS repos (PageRank hubs, symbol ranking, token-budgeted digest). Faster and more accurate than grep for structural questions.
+
+## When to use
+
+- **Where is X defined?** / **who imports this file?** / **what breaks if I edit this?**
+- **Reuse check** before adding a util, component, or type
+- **Session start** — orient to a large monorepo cheaply
+
+## When not to use
+
+- Raw string / config value search (try `agentmap --any` first — layer 4 is live `git grep`)
+- Non-TS/JS files, runtime call graphs, or full semantic "how does it work?" (use codebase search)
+- Next-style `--feature` on TanStack Router / non-`app/` layouts (often empty)
+
+## Commands (run in repo root)
+
+```bash
+# Smart router — default first move
+agentmap --any <query>
+
+# Reuse / symbol definition
+agentmap --find <SymbolName>
+
+# Blast radius (exports, imports, dependents, related files)
+agentmap --relates <path/to/file.ts>
+
+# Token-budgeted ranked digest
+agentmap --map --tokens 400
+agentmap --map --focus <path> --tokens 400
+
+# Hub files (PageRank)
+agentmap --hubs
+
+# JSON for tools
+agentmap --json --any <query>
+```
+
+Install: `npm i -g @raymondchins/agentmap` or `npx @raymondchins/agentmap`. Map cache: `.claude/agentmap/` (gitignored).
+
+## Agent platforms
+
+| Platform | Setup |
+|----------|--------|
+| **Claude Code** | `agentmap --install-hooks` (post-commit refresh + PreToolUse grep nudge) |
+| **Cursor / MCP clients** | `agentmap --mcp` in MCP config, or Shell + commands above |
+| **This skill** | `agentmap --install-skill` |
+
+## Workflow
+
+1. If the map may be stale after edits, run `agentmap` (no flags) or rely on post-commit hook.
+2. Start with `agentmap --any <symbol or topic>`.
+3. Before editing a hub file, run `agentmap --relates <that-file>`.
+4. Fall back to grep only when agentmap returns no useful structure hit.
+
+## Package name
+
+```bash
+npx @raymondchins/agentmap --any Procedure
+# NOT: npm install agentmap  (different package)
+```

package/skills/cursor-rule.mdc

@@ -0,0 +1,27 @@
+---
+description: agentmap ranked TS/JS repo map
+alwaysApply: true
+---
+
+This project can use **agentmap** (`@raymondchins/agentmap`) — a queryable import/symbol map at `.claude/agentmap/`.
+
+**Before Grep/Glob for structural questions** (where is a symbol, who imports a file, reuse check, blast radius), prefer:
+
+```bash
+agentmap --any <query>          # file → symbol → feature → git-grep fallback
+agentmap --find <Symbol>        # exported symbols matching name
+agentmap --relates <file.ts>    # imports, dependents, related files
+agentmap --map --tokens 400     # cheap repo orientation
+```
+
+Use Read/Grep directly when:
+
+1. agentmap already oriented you and you need exact lines to edit
+2. The map is missing — run `agentmap` once to build `.claude/agentmap/`
+3. Searching raw strings, logs, or non-TS files
+
+**Cursor MCP (optional):** `agentmap --mcp` exposes the same queries as tools.
+
+**Note:** `--features` only detects Next.js `app/` routes; TanStack `src/routes/` repos often show `features (0)`.
+
+Package: `@raymondchins/agentmap` — not the unrelated PyPI/npm `agentmap` package.

package/skills/install.mjs

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+// --install-skill: copy packaged SKILL.md / Cursor rule into project or global
+// agent directories (project or global scope).
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILLS_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** @type {Record<string, { label: string; src: string; dest: (root: string) => string; projectOnly?: boolean }>} */
+const PLATFORMS = {
+  claude: {
+    label: "Claude Code",
+    src: join(SKILLS_DIR, "SKILL.md"),
+    dest: (root) => join(root, ".claude", "skills", "agentmap", "SKILL.md"),
+  },
+  agents: {
+    label: "Codex / OpenCode (.agents)",
+    src: join(SKILLS_DIR, "SKILL.md"),
+    dest: (root) => join(root, ".agents", "skills", "agentmap", "SKILL.md"),
+  },
+  cursor: {
+    label: "Cursor",
+    src: join(SKILLS_DIR, "cursor-rule.mdc"),
+    dest: (root) => join(root, ".cursor", "rules", "agentmap.mdc"),
+    projectOnly: true,
+  },
+};
+
+function atomicWrite(dest, body) {
+  mkdirSync(dirname(dest), { recursive: true });
+  const tmp = `${dest}.tmp`;
+  writeFileSync(tmp, body, "utf8");
+  renameSync(tmp, dest);
+}
+
+function parsePlatforms(raw) {
+  if (!raw || raw === "all") return ["claude", "cursor", "agents"];
+  const names = raw.split(/[,+]/).map((s) => s.trim().toLowerCase()).filter(Boolean);
+  for (const n of names) {
+    if (!PLATFORMS[n]) {
+      throw new Error(`unknown platform '${n}' — choose: ${Object.keys(PLATFORMS).join(", ")}, all`);
+    }
+  }
+  return names;
+}
+
+function gitAddHint(paths) {
+  const unique = [...new Set(paths.map((p) => p.replace(/\/[^/]+$/, "") || p))];
+  if (unique.length) console.log(`\nOptional: git add ${unique.map((p) => `"${p}"`).join(" ")}`);
+}
+
+/**
+ * @param {{ platforms?: string; project?: boolean; global?: boolean; dryRun?: boolean }} opts
+ */
+export function installSkill({ platforms: platformsArg = "all", project = true, global: globalScope = false, dryRun = false } = {}) {
+  if (project && globalScope) throw new Error("use either --project or --global, not both");
+  // read version lazily (inside the function, not at module load) so importing
+  // this module is side-effect-free / off the CLI hot path.
+  const VERSION = JSON.parse(readFileSync(join(SKILLS_DIR, "..", "package.json"), "utf8")).version;
+  const scope = globalScope ? "global" : "project";
+  const root = globalScope ? homedir() : process.cwd();
+  const names = parsePlatforms(platformsArg);
+  const targets = [];
+
+  if (dryRun) console.log(`--dry-run: would install agentmap skill (${scope} scope):`);
+
+  for (const name of names) {
+    const cfg = PLATFORMS[name];
+    if (cfg.projectOnly && globalScope) {
+      console.log(`  skip ${cfg.label}: Cursor rule is project-scoped only (re-run with --project)`);
+      continue;
+    }
+    if (!existsSync(cfg.src)) throw new Error(`packaged skill missing: ${cfg.src}`);
+    const dest = cfg.dest(root);
+    const body = readFileSync(cfg.src, "utf8");
+    const versionFile = join(dirname(dest), ".agentmap_version");
+
+    if (dryRun) {
+      console.log(`  ${cfg.label}: ${dest}`);
+      continue;
+    }
+
+    atomicWrite(dest, body);
+    writeFileSync(versionFile, VERSION + "\n", "utf8");
+    console.log(`  ${cfg.label} → ${dest}`);
+    targets.push(dest);
+  }
+
+  if (!dryRun && targets.length) {
+    console.log(`\nagentmap --install-skill: installed ${targets.length} file(s) (${scope}).`);
+    if (!globalScope) gitAddHint(targets);
+    console.log("Pair with: agentmap --install-hooks (Claude Code) or agentmap --mcp (Cursor MCP).");
+  }
+}