@tyroneross/navgator 0.2.2 → 0.9.0

package/hooks/post-edit-suggest.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# PostToolUse (Write|Edit) — suggest a scan only after touching architecture-critical files.
+# (The original "3+ files modified" heuristic would need persistent state across
+# hook invocations and produced noise anyway. Pattern-matching on the edited
+# path alone is silent by default and still catches the cases that matter.)
+set -u
+
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+[ -f "$project/.navgator/architecture/index.json" ] || exit 0
+
+path=$(python3 -c '
+import sys, json
+try:
+  print(json.loads(sys.stdin.read()).get("tool_input", {}).get("file_path", ""))
+except Exception:
+  pass
+' 2>/dev/null)
+
+[ -z "$path" ] && exit 0
+
+case "$path" in
+  *schema.prisma|*/migrations/*|*/drizzle/*|\
+  */api/*/route.ts|*/api/*/route.js|*/app/api/*|*/pages/api/*|\
+  *Package.swift|*.pbxproj|*Podfile|*.entitlements|*Info.plist)
+    echo "Architecture-critical file changed — consider running the navgator \`scan\` MCP tool to keep tracking fresh."
+    ;;
+  *) exit 0 ;;
+esac
+exit 0

package/hooks/pre-edit-warn.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# PreToolUse (Edit|Write) — warn only when editing an architecture-critical file.
+# Silent otherwise.
+set -u
+
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+[ -f "$project/.navgator/architecture/index.json" ] || exit 0
+
+path=$(python3 -c '
+import sys, json
+try:
+  print(json.loads(sys.stdin.read()).get("tool_input", {}).get("file_path", ""))
+except Exception:
+  pass
+' 2>/dev/null)
+
+[ -z "$path" ] && exit 0
+
+case "$path" in
+  *schema.prisma|*/migrations/*|*/drizzle/*|*/prisma/*|\
+  */api/*/route.ts|*/api/*/route.js|*/app/api/*|*/pages/api/*|\
+  */workers/*|*/queues/*|*/jobs/*|\
+  *Package.swift|*.pbxproj|*Podfile|*.entitlements|*Info.plist)
+    echo "Architecture-critical file. Consider running the navgator \`explore\` MCP tool first to check downstream impact."
+    ;;
+  *) exit 0 ;;
+esac
+exit 0

package/hooks/session-start.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# SessionStart hook — suggest a scan only when navgator data is missing or stale.
+# Silent otherwise (exits 0 with no stdout).
+set -u
+
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+index="$project/.navgator/architecture/index.json"
+
+# Not a navgator-tracked project yet — stay silent. A user who wants tracking
+# runs `/navgator:scan` explicitly; auto-nagging on every SessionStart across
+# every project is noise.
+[ -f "$index" ] || exit 0
+
+# Tracked project: check freshness. Suggest refresh only if >24h old.
+if [ "$(find "$index" -mtime +1 -print 2>/dev/null)" ]; then
+  echo "NavGator data is >24h old. Consider running the navgator \`scan\` MCP tool to refresh."
+fi
+
+exit 0

package/hooks/stop-suggest.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Stop hook — suggest a scan only if the architecture index is clearly stale
+# relative to tracked source files. Silent otherwise.
+#
+# "Clearly stale" = index.json exists and is older than any file in common
+# source dirs within the last 24h.
+set -u
+
+emit_empty() {
+  printf '{}\n'
+}
+
+emit_context() {
+  python3 - "$1" <<'PY' || emit_empty
+import json
+import sys
+
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": "Stop",
+        "additionalContext": sys.argv[1],
+    }
+}))
+PY
+}
+
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+index="$project/.navgator/architecture/index.json"
+[ -f "$index" ] || {
+  emit_empty
+  exit 0
+}
+
+# If anything under typical source dirs is newer than index.json, suggest refresh.
+# find -newer is POSIX; errors silenced for dirs that don't exist.
+newer=$(find \
+  "$project/src" "$project/app" "$project/lib" "$project/core" \
+  "$project/server" "$project/api" "$project/packages" \
+  -type f -newer "$index" -not -path "*/node_modules/*" -not -path "*/.next/*" \
+  -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.turbo/*" \
+  -print -quit 2>/dev/null)
+
+if [ -n "$newer" ]; then
+  emit_context "Source files have changed since the last navgator scan — consider running the navgator \`scan\` MCP tool before ending the session."
+else
+  emit_empty
+fi
+
+exit 0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@tyroneross/navgator",
-  "version": "0.2.2",
-  "description": "Architecture connection tracker for Claude Code - know your stack before you change it",
+  "version": "0.9.0",
+  "description": "Architecture connection tracker for Claude Code and Codex - know your stack before you change it",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "navgator": "./dist/cli/index.js"
+    "navgator": "dist/cli/index.js"
   },
   "exports": {
     ".": {
@@ -31,10 +31,18 @@
     "hooks",
     "agents",
     ".claude-plugin",
+    ".codex-plugin",
+    ".agents",
+    ".mcp.json",
     "scripts/install-plugin.sh",
+    "scripts/install-codex-plugin.sh",
     "CLAUDE.md",
     "README.md"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "build": "npm run build:cli && npm run build:web",
     "build:cli": "tsc && npm run build:fixshebang",
@@ -44,15 +52,21 @@
     "dev": "tsc --watch",
     "dev:web": "cd web && next dev",
     "start": "node dist/cli/index.js",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test": "vitest run",
+    "test:release": "vitest run --exclude __tests__/scanner-audit.test.ts --exclude __tests__/scanner-characterization.test.ts --exclude __tests__/scanner-incremental.test.ts",
     "lint": "eslint src/**/*.ts",
     "clean": "rm -rf dist web/.next",
     "prepublishOnly": "npm run clean && npm run build",
     "link:local": "npm run build && npm link",
-    "install-plugin": "bash scripts/install-plugin.sh --global"
+    "install:claude": "bash scripts/install-plugin.sh --global",
+    "install:codex": "bash scripts/install-codex-plugin.sh --user",
+    "install:codex-workspace": "bash scripts/install-codex-plugin.sh --workspace",
+    "install-plugin": "bash scripts/install-plugin.sh --global",
+    "mcp": "node dist/mcp/server.js"
   },
   "keywords": [
     "claude-code",
+    "codex",
     "architecture",
     "dependencies",
     "devtools",
@@ -61,27 +75,32 @@
     "impact-analysis"
   ],
   "author": "Tyrone Ross",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tyroneross/navgator"
+    "url": "git+https://github.com/tyroneross/NavGator.git"
   },
-  "homepage": "https://github.com/tyroneross/navgator#readme",
+  "homepage": "https://github.com/tyroneross/NavGator#readme",
   "bugs": {
-    "url": "https://github.com/tyroneross/navgator/issues"
+    "url": "https://github.com/tyroneross/NavGator/issues"
   },
   "engines": {
     "node": ">=20.0.0"
   },
   "dependencies": {
     "commander": "^14.0.0",
-    "glob": "^13.0.0"
+    "glob": "^13.0.0",
+    "graphology": "^0.26.0",
+    "graphology-communities-louvain": "^2.0.2",
+    "graphology-metrics": "^2.4.0"
   },
   "optionalDependencies": {
     "ts-morph": "^27.0.0"
   },
   "devDependencies": {
+    "@sourcegraph/scip-typescript": "^0.4.0",
     "@types/node": "^22.0.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
   }
 }

package/scripts/install-codex-plugin.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# NavGator Codex plugin installer
+# Usage: ./install-codex-plugin.sh [--user | --workspace]
+
+SCOPE="${1:---user}"
+BOLD="\033[1m"
+GREEN="\033[0;32m"
+YELLOW="\033[0;33m"
+RED="\033[0;31m"
+RESET="\033[0m"
+
+info()  { echo -e "${BOLD}$1${RESET}"; }
+ok()    { echo -e "${GREEN}$1${RESET}"; }
+warn()  { echo -e "${YELLOW}$1${RESET}"; }
+err()   { echo -e "${RED}$1${RESET}" >&2; }
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+update_marketplace() {
+  local marketplace_path="$1"
+  local marketplace_name="$2"
+  local display_name="$3"
+  local source_path="$4"
+
+  mkdir -p "$(dirname "$marketplace_path")"
+
+  node - <<'NODE' "$marketplace_path" "$marketplace_name" "$display_name" "$source_path"
+const fs = require("fs");
+
+const [marketplacePath, marketplaceName, displayName, sourcePath] = process.argv.slice(2);
+
+let data = {
+  name: marketplaceName,
+  interface: { displayName },
+  plugins: [],
+};
+
+if (fs.existsSync(marketplacePath)) {
+  data = JSON.parse(fs.readFileSync(marketplacePath, "utf8"));
+  if (!data || typeof data !== "object") data = {};
+  if (!Array.isArray(data.plugins)) data.plugins = [];
+  if (!data.interface || typeof data.interface !== "object") data.interface = {};
+  if (!data.name) data.name = marketplaceName;
+  if (!data.interface.displayName) data.interface.displayName = displayName;
+}
+
+const entry = {
+  name: "navgator",
+  source: {
+    source: "local",
+    path: sourcePath,
+  },
+  policy: {
+    installation: "AVAILABLE",
+    authentication: "ON_INSTALL",
+  },
+  category: "Coding",
+};
+
+const index = data.plugins.findIndex((plugin) => plugin && plugin.name === "navgator");
+if (index >= 0) {
+  data.plugins[index] = {
+    ...data.plugins[index],
+    ...entry,
+    source: entry.source,
+    policy: entry.policy,
+  };
+} else {
+  data.plugins.push(entry);
+}
+
+fs.writeFileSync(marketplacePath, `${JSON.stringify(data, null, 2)}\n`);
+NODE
+}
+
+case "$SCOPE" in
+  --user)
+    TARGET_DIR="$HOME/plugins"
+    MARKETPLACE_PATH="$HOME/.agents/plugins/marketplace.json"
+    LINK_PATH="$TARGET_DIR/navgator"
+    info "Installing navgator for Codex at user scope..."
+    mkdir -p "$TARGET_DIR" "$HOME/.agents/plugins"
+    ln -sfn "$PLUGIN_ROOT" "$LINK_PATH"
+    if [ -L "$TARGET_DIR/gator" ]; then
+      warn "Removing legacy Codex alias ~/plugins/gator ..."
+      rm -f "$TARGET_DIR/gator"
+    fi
+    update_marketplace "$MARKETPLACE_PATH" "local" "Local Plugins" "./plugins/navgator"
+    echo ""
+    ok "navgator Codex plugin installed for your user account."
+    echo ""
+    echo "  Plugin link: $LINK_PATH -> $PLUGIN_ROOT"
+    echo "  Marketplace: $MARKETPLACE_PATH"
+    echo ""
+    warn "Restart Codex if the plugin does not appear immediately."
+    ;;
+  --workspace)
+    MARKETPLACE_PATH="$PLUGIN_ROOT/.agents/plugins/marketplace.json"
+    info "Refreshing repo-local Codex marketplace metadata..."
+    update_marketplace "$MARKETPLACE_PATH" "navgator-local-workspace" "NavGator Workspace Plugins" "./"
+    echo ""
+    ok "navgator Codex workspace metadata refreshed."
+    echo ""
+    echo "  Marketplace: $MARKETPLACE_PATH"
+    echo "  Source path: ./"
+    echo ""
+    warn "Open this repository as the Codex workspace, or symlink it into another workspace's plugins directory."
+    ;;
+  *)
+    echo "Usage: $0 [--user | --workspace]"
+    echo ""
+    echo "  --user       Install for your Codex user account (~/.agents/plugins/marketplace.json)"
+    echo "  --workspace  Refresh repo-local workspace metadata (.agents/plugins/marketplace.json)"
+    exit 1
+    ;;
+esac

package/scripts/install-plugin.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# NavGator (gator) plugin installer for Claude Code
+# NavGator Claude Code plugin installer
 # Usage: ./install-plugin.sh [--global | --project]
 
 SCOPE="${1:---global}"
@@ -20,19 +20,21 @@ err()   { echo -e "${RED}$1${RESET}" >&2; }
 case "$SCOPE" in
   --global)
     TARGET_DIR="$HOME/.claude/plugins"
-    LINK_NAME="gator"
-    info "Installing gator plugin globally (all projects)..."
+    LINK_NAME="navgator"
+    info "Installing navgator plugin globally for Claude Code..."
     ;;
   --project)
     TARGET_DIR=".claude/plugins"
-    LINK_NAME="gator"
-    info "Installing gator plugin for current project only..."
+    LINK_NAME="navgator"
+    info "Installing navgator plugin for the current Claude Code project..."
     ;;
   *)
     echo "Usage: $0 [--global | --project]"
     echo ""
-    echo "  --global   Install for all projects (~/.claude/plugins/gator)"
-    echo "  --project  Install for current project only (.claude/plugins/gator)"
+    echo "  --global   Install for all Claude projects (~/.claude/plugins/navgator)"
+    echo "  --project  Install for the current Claude project (.claude/plugins/navgator)"
+    echo ""
+    echo "For Codex installs, run: bash scripts/install-codex-plugin.sh [--user | --workspace]"
     exit 1
     ;;
 esac
@@ -53,11 +55,11 @@ if [ ! -f "$NAVGATOR_PATH/.claude-plugin/plugin.json" ]; then
   exit 1
 fi
 
-# --- Clean up old navgator symlink ---
-OLD_LINK="$HOME/.claude/plugins/navgator"
-if [ -L "$OLD_LINK" ]; then
-  warn "Removing old 'navgator' symlink..."
-  rm -f "$OLD_LINK"
+# --- Clean up old navgator alias ---
+OLD_ALIAS="$TARGET_DIR/navgator"
+if [ -L "$OLD_ALIAS" ]; then
+  warn "Removing legacy 'navgator' Claude plugin alias..."
+  rm -f "$OLD_ALIAS"
 fi
 
 # --- Create symlink ---
@@ -74,22 +76,25 @@ ln -sfn "$NAVGATOR_PATH" "$FULL_LINK"
 # --- Verify ---
 if [ -f "$FULL_LINK/.claude-plugin/plugin.json" ]; then
   echo ""
-  ok "gator plugin installed successfully!"
+  ok "navgator Claude plugin installed successfully!"
   echo ""
   echo "  Location: $FULL_LINK -> $NAVGATOR_PATH"
   echo "  Scope:    $([ "$SCOPE" = "--global" ] && echo "all projects" || echo "current project only")"
   echo ""
-  echo "  Available commands:"
-  echo "    /gator:scan         Scan project architecture"
-  echo "    /gator:status       Show architecture summary"
-  echo "    /gator:impact       Analyze change impact"
-  echo "    /gator:connections  Show component connections"
-  echo "    /gator:diagram      Generate architecture diagram"
-  echo "    /gator:export       Export architecture data"
-  echo "    /gator:check        Run health checks"
-  echo "    /gator:ui           Launch web dashboard"
-  echo "    /gator:update       Update to latest version"
-  echo "    /gator:install      Re-run this installer"
+  echo "  Claude slash commands:"
+  echo "    /navgator:scan"
+  echo "    /navgator:map"
+  echo "    /navgator:trace"
+  echo "    /navgator:impact"
+  echo "    /navgator:test"
+  echo "    /navgator:review"
+  echo "    /navgator:llm-map"
+  echo "    /navgator:schema"
+  echo "    /navgator:dead"
+  echo "    /navgator:lessons"
+  echo ""
+  echo "  Codex install:"
+  echo "    bash scripts/install-codex-plugin.sh --user"
   echo ""
   warn "Restart Claude Code for changes to take effect."
 else

package/skills/architecture-export/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: architecture-export
+description: Use when user asks to show or generate an architecture diagram, visualize dependencies, export architecture docs, create architecture documentation, save architecture output, or create a mermaid diagram of their project.
+version: 0.4.0
+user-invocable: true
+argument-hint: "[diagram|export] [options]"
+---
+
+# Architecture Diagrams & Export
+
+Generate architecture diagrams and export architecture summaries using the real NavGator MCP and CLI surfaces.
+
+## Prerequisites
+
+Before generating output, check whether architecture data exists. If the MCP tool or CLI reports missing data, run or recommend `navgator scan` first. Do not fabricate architecture from raw source when scan data is unavailable.
+
+## Diagrams
+
+For in-chat diagrams, use the `navgator diagram` MCP tool.
+
+**MCP modes:**
+- `summary`: top connected components only (default)
+- `focus`: center on a specific component; pass `focus: "<component-name>"`
+- `layer`: show one layer; pass `focus: "<layer-name>"` such as `frontend`, `backend`, `database`, `queue`, `infra`, or `external`
+
+The MCP tool returns Mermaid markdown that can be rendered in any Mermaid-compatible viewer.
+
+For file output, use the CLI `diagram` command. NavGator does not have an `export` command.
+
+```bash
+# Raw Mermaid
+npx @tyroneross/navgator diagram --summary --output architecture.mmd
+
+# Markdown-wrapped Mermaid
+npx @tyroneross/navgator diagram --summary --markdown --output ARCHITECTURE.md
+
+# Focused component diagram
+npx @tyroneross/navgator diagram --focus "component-name" --markdown --output component-architecture.md
+
+# Layer diagram
+npx @tyroneross/navgator diagram --layer backend --markdown --output backend-architecture.md
+```
+
+## Summary Export
+
+For an in-chat executive summary, use the `navgator summary` MCP tool.
+
+For a JSON file, use the CLI `summary` command and shell redirection:
+
+```bash
+npx @tyroneross/navgator summary > architecture-summary.json
+```
+
+If the user asks for machine-readable graph data, point them to the generated scan artifacts rather than inventing an export command:
+
+- `.navgator/architecture/index.json`
+- `.navgator/architecture/graph.json`
+- `.navgator/architecture/file_map.json`
+
+## Decision Tree
+
+| User Intent | Tool | Notes |
+|-------------|------|-------|
+| "Show architecture diagram" | MCP `navgator diagram` | Summary mode |
+| "Diagram of X component" | MCP `navgator diagram` with `mode: "focus"` | Component-focused |
+| "Show backend layer" | MCP `navgator diagram` with `mode: "layer"` | Pass layer name as `focus` |
+| "Save a Mermaid diagram" | CLI `npx @tyroneross/navgator diagram --output <file>` | Add `--markdown` for Markdown docs |
+| "Export architecture summary" | CLI `npx @tyroneross/navgator summary > <file>.json` | JSON file output |
+| "Architecture summary in chat" | MCP `navgator summary` | Executive summary |
+| "Export full graph JSON" | Existing `.navgator/architecture/*.json` files | No CLI export command exists |
+
+## Guardrails
+
+- Do not use `navgator export`; that command is not registered.
+- Do not run npm or write files unless the user asked for file output.
+- Use `focus` for complex diagrams so the output stays readable.
+- Prefer Markdown-wrapped Mermaid for documentation files and raw Mermaid for diagram-only artifacts.
+
+*navgator - architecture tracker*

package/skills/architecture-scan/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: architecture-scan
+description: Use when user asks to scan architecture, check dependencies, find outdated packages, show project structure, refresh architecture, or run a health check. Navgator scan, status, and staleness check.
+version: 0.4.0
+user-invocable: false
+---
+
+# Architecture Scan & Status
+
+Scan project architecture, check health, and monitor staleness using NavGator MCP tools. This skill covers scanning, status display, and health checks.
+
+## When to Activate
+
+- User asks about project architecture, stack, or dependencies
+- User wants to check for outdated packages or vulnerabilities
+- Session starts and architecture data may be stale (>24h since last scan)
+- User adds/removes dependencies or makes structural changes
+- After `npm install`, `pip install`, or similar dependency operations
+
+## Scanning
+
+Use the `navgator scan` MCP tool to detect components, connections, AI prompts, and infrastructure.
+
+**Options:**
+- Default: Full scan including code analysis
+- `quick: true`: Package files only, skip code analysis (faster)
+
+After scanning, present a smart brevity brief:
+- **Line 1**: "Scanned [project]. [N] components, [N] connections."
+- **What's new**: Added/removed components since last scan
+- **What to watch**: Outdated packages, vulnerabilities, low-confidence detections
+- **AI routing**: Providers and model count if AI calls detected
+
+## Status
+
+Use the `navgator status` MCP tool to show architecture summary without re-scanning.
+
+Returns: component counts by type/layer, connection counts, AI routing table, last scan timestamp, and staleness indicator.
+
+If no architecture data exists, recommend running a scan first.
+
+## Health Checks
+
+Use the `navgator scan` MCP tool with a follow-up review of the results. Health information is included in scan output:
+- Outdated packages
+- Security vulnerabilities
+- Orphaned connections (dead code references)
+- Missing imports and unused dependencies
+
+## Decision Tree
+
+| User Intent | MCP Tool | Notes |
+|-------------|----------|-------|
+| "Scan my project" | `navgator scan` | Full scan |
+| "Quick scan" | `navgator scan` (quick: true) | Packages only |
+| "What's my stack?" | `navgator status` | No re-scan needed |
+| "Any outdated packages?" | `navgator scan` | Check health results |
+| "Is architecture data fresh?" | `navgator status` | Check timestamp |
+
+## Output Format
+
+Keep output concise. Do NOT dump raw CLI output. Summarize into a scannable brief.
+
+*navgator — architecture tracker*