arceus-s 1.6.4

package/dist/types/pipeline.d.ts

@@ -0,0 +1,18 @@
+import type { KnowledgeGraph } from '../core/graph/types.js';
+import { CommunityDetectionResult } from '../core/ingestion/community-processor.js';
+import { ProcessDetectionResult } from '../core/ingestion/process-processor.js';
+export interface PipelineResult {
+    graph: KnowledgeGraph;
+    /** Absolute path to the repo root — used for lazy file reads during LadybugDB loading */
+    repoPath: string;
+    /** Total files scanned (for stats) */
+    totalFileCount: number;
+    communityResult?: CommunityDetectionResult;
+    processResult?: ProcessDetectionResult;
+    /**
+     * True if the parse phase spawned a worker pool for this run. False means
+     * the sequential fallback handled every chunk. Primarily a test affordance
+     * so regression suites can prove which path executed.
+     */
+    usedWorkerPool: boolean;
+}

package/dist/types/pipeline.js

@@ -0,0 +1 @@
+export {};

package/hooks/claude/arc-hook.cjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+/**
+ * Arceus Claude Code Hook
+ *
+ * PreToolUse  — intercepts Grep/Glob/Bash searches and augments
+ *               with graph context from the Arceus index.
+ * PostToolUse — detects stale index after git mutations and notifies
+ *               the agent to reindex.
+ *
+ * NOTE: SessionStart hooks are broken on Windows (Claude Code bug).
+ * Session context is injected via CLAUDE.md / skills instead.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { acquireHookSlot } = require('./hook-lock.cjs');
+
+/**
+ * Read JSON input from stdin synchronously.
+ */
+function readInput() {
+  try {
+    const data = fs.readFileSync(0, 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Find the .arc directory by walking up from startDir.
+ * Returns the path to .arc/ or null if not found.
+ */
+function isGlobalRegistryDir(candidate) {
+  if (fs.existsSync(path.join(candidate, 'meta.json'))) return false;
+  return (
+    fs.existsSync(path.join(candidate, 'registry.json')) ||
+    fs.existsSync(path.join(candidate, 'repos'))
+  );
+}
+
+/**
+ * Walk up from `startDir` looking for a non-registry `.arc/` folder.
+ * Returns the path to `.arc/` or null if not found within 5 levels.
+ */
+function walkForArceusDir(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 5; i++) {
+    const candidate = path.join(dir, '.arc');
+    if (fs.existsSync(candidate)) {
+      if (!isGlobalRegistryDir(candidate)) return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Resolve the canonical (main) worktree root for `cwd`, when `cwd` is inside
+ * any git working tree — including a *linked* worktree created via
+ * `git worktree add`. Linked worktrees never contain `.arc/`, so the
+ * upward walk from cwd alone misses the index. Returns null when `cwd` is
+ * not inside a git repo or `git` is not available.
+ *
+ * Implementation: `git rev-parse --git-common-dir` resolves to the canonical
+ * `.git/` directory (or `.git/worktrees/...` parent) that is shared across
+ * all linked worktrees. The canonical repo root is its parent directory.
+ */
+function findCanonicalRepoRoot(cwd) {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf-8',
+      timeout: 2000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.error || result.status !== 0) return null;
+    const commonDir = (result.stdout || '').trim();
+    if (!commonDir || !path.isAbsolute(commonDir)) return null;
+    return path.dirname(commonDir);
+  } catch {
+    return null;
+  }
+}
+
+function findArceusDir(startDir) {
+  const cwd = startDir || process.cwd();
+
+  // Fast path: the cwd is inside the canonical repo (most common case).
+  const fromCwd = walkForArceusDir(cwd);
+  if (fromCwd) return fromCwd;
+
+  // Fallback: cwd may be inside a linked git worktree whose `.arc/`
+  // only lives in the canonical repo root. Resolve the shared git dir
+  // and retry from there.
+  const canonicalRoot = findCanonicalRepoRoot(cwd);
+  if (canonicalRoot && canonicalRoot !== cwd) {
+    return walkForArceusDir(canonicalRoot);
+  }
+  return null;
+}
+
+/**
+ * Extract search pattern from tool input.
+ */
+function extractPattern(toolName, toolInput) {
+  if (toolName === 'Grep') {
+    return toolInput.pattern || null;
+  }
+
+  if (toolName === 'Glob') {
+    const raw = toolInput.pattern || '';
+    const match = raw.match(/[*\/]([a-zA-Z][a-zA-Z0-9_-]{2,})/);
+    return match ? match[1] : null;
+  }
+
+  if (toolName === 'Bash') {
+    const cmd = toolInput.command || '';
+    if (!/\brg\b|\bgrep\b/.test(cmd)) return null;
+
+    const tokens = cmd.split(/\s+/);
+    let foundCmd = false;
+    let skipNext = false;
+    const flagsWithValues = new Set([
+      '-e',
+      '-f',
+      '-m',
+      '-A',
+      '-B',
+      '-C',
+      '-g',
+      '--glob',
+      '-t',
+      '--type',
+      '--include',
+      '--exclude',
+    ]);
+
+    for (const token of tokens) {
+      if (skipNext) {
+        skipNext = false;
+        continue;
+      }
+      if (!foundCmd) {
+        if (/\brg$|\bgrep$/.test(token)) foundCmd = true;
+        continue;
+      }
+      if (token.startsWith('-')) {
+        if (flagsWithValues.has(token)) skipNext = true;
+        continue;
+      }
+      const cleaned = token.replace(/['"]/g, '');
+      return cleaned.length >= 3 ? cleaned : null;
+    }
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the arc CLI path.
+ * 1. Relative path (works when script is inside npm package)
+ * 2. require.resolve (works when arc is globally installed)
+ * 3. Fall back to npx (returns empty string)
+ */
+function resolveCliPath() {
+  let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');
+  if (!fs.existsSync(cliPath)) {
+    try {
+      cliPath = require.resolve('arc/dist/cli/index.js');
+    } catch {
+      cliPath = '';
+    }
+  }
+  return cliPath;
+}
+
+/**
+ * Spawn a arc CLI command synchronously.
+ * Returns the stderr output (KuzuDB captures stdout at OS level).
+ */
+function runArceusCli(cliPath, args, cwd, timeout) {
+  const isWin = process.platform === 'win32';
+  if (cliPath) {
+    return spawnSync(process.execPath, [cliPath, ...args], {
+      encoding: 'utf-8',
+      timeout,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  }
+  // On Windows, invoke npx.cmd directly (no shell needed)
+  return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'arc', ...args], {
+    encoding: 'utf-8',
+    timeout: timeout + 5000,
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * PreToolUse handler — augment searches with graph context.
+ */
+function handlePreToolUse(input) {
+  const cwd = input.cwd || process.cwd();
+  if (!path.isAbsolute(cwd)) return;
+  const arceusDir = findArceusDir(cwd);
+  if (!arceusDir) return;
+
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
+
+  if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Bash') return;
+
+  const pattern = extractPattern(toolName, toolInput);
+  if (!pattern || pattern.length < 3) return;
+
+  const release = acquireHookSlot(arceusDir);
+  if (!release) return;
+
+  const cliPath = resolveCliPath();
+  let result = '';
+  try {
+    const child = runArceusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
+    if (!child.error && child.status === 0) {
+      result = child.stderr || '';
+    }
+  } catch {
+    /* graceful failure */
+  } finally {
+    release();
+  }
+
+  if (result && result.trim()) {
+    sendHookResponse('PreToolUse', result.trim());
+  }
+}
+
+/**
+ * Emit a PostToolUse hook response with additional context for the agent.
+ */
+function sendHookResponse(hookEventName, message) {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName, additionalContext: message },
+    }),
+  );
+}
+
+/**
+ * PostToolUse handler — detect index staleness after git mutations.
+ *
+ * Instead of spawning a full `arc analyze` synchronously (which blocks
+ * the agent for up to 120s and risks KuzuDB corruption on timeout), we do a
+ * lightweight staleness check: compare `git rev-parse HEAD` against the
+ * lastCommit stored in `.arc/meta.json`. If they differ, notify the
+ * agent so it can decide when to reindex.
+ */
+function handlePostToolUse(input) {
+  const toolName = input.tool_name || '';
+  if (toolName !== 'Bash') return;
+
+  const command = (input.tool_input || {}).command || '';
+  if (!/\bgit\s+(commit|merge|rebase|cherry-pick|pull)(\s|$)/.test(command)) return;
+
+  // Only proceed if the command succeeded
+  const toolOutput = input.tool_output || {};
+  if (toolOutput.exit_code !== undefined && toolOutput.exit_code !== 0) return;
+
+  const cwd = input.cwd || process.cwd();
+  if (!path.isAbsolute(cwd)) return;
+  const arceusDir = findArceusDir(cwd);
+  if (!arceusDir) return;
+
+  // Compare HEAD against last indexed commit — skip if unchanged
+  let currentHead = '';
+  try {
+    const headResult = spawnSync('git', ['rev-parse', 'HEAD'], {
+      encoding: 'utf-8',
+      timeout: 3000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    currentHead = (headResult.stdout || '').trim();
+  } catch {
+    return;
+  }
+
+  if (!currentHead) return;
+
+  let lastCommit = '';
+  let hadEmbeddings = false;
+  try {
+    const meta = JSON.parse(fs.readFileSync(path.join(arceusDir, 'meta.json'), 'utf-8'));
+    lastCommit = meta.lastCommit || '';
+    hadEmbeddings = meta.stats && meta.stats.embeddings > 0;
+  } catch {
+    /* no meta — treat as stale */
+  }
+
+  // If HEAD matches last indexed commit, no reindex needed
+  if (currentHead && currentHead === lastCommit) return;
+
+  const analyzeCmd = `npx arc analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+  sendHookResponse(
+    'PostToolUse',
+    `Arceus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
+      `Run \`${analyzeCmd}\` to update the knowledge graph.`,
+  );
+}
+
+// Dispatch map for hook events
+const handlers = {
+  PreToolUse: handlePreToolUse,
+  PostToolUse: handlePostToolUse,
+};
+
+function main() {
+  try {
+    const input = readInput();
+    const handler = handlers[input.hook_event_name || ''];
+    if (handler) handler(input);
+  } catch (err) {
+    if (process.env.ARC_DEBUG) {
+      console.error('Arceus hook error:', (err.message || '').slice(0, 200));
+    }
+  }
+}
+
+main();

package/hooks/claude/hook-lock.cjs

@@ -0,0 +1,119 @@
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_LOCK_SUBDIR = '.hook-locks';
+const HOOK_LOCK_MAX_INFLIGHT = 3;
+const HOOK_LOCK_STALE_MS = 30000;
+
+function acquireHookSlot(arceusDir) {
+  const lockDir = path.join(arceusDir, HOOK_LOCK_SUBDIR);
+  try {
+    fs.mkdirSync(lockDir, { recursive: true });
+  } catch {
+    // Cannot create lock dir (read-only fs, cross-user perm denial, out of
+    // inodes, etc.) — fail closed by returning null. Caller skips augment.
+    // Fail-open here would let N concurrent hooks all proceed unguarded and
+    // reintroduce the #1486 fan-out the guard exists to prevent.
+    return null;
+  }
+
+  const myPidStr = String(process.pid);
+
+  for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) {
+    const slotPath = path.join(lockDir, `slot-${slot}.lock`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' });
+        let released = false;
+        const release = () => {
+          if (released) return;
+          released = true;
+          try {
+            // Only unlink if we still own the slot. If we appeared stale and
+            // another hook took over, the file now belongs to it — leave alone.
+            const content = fs.readFileSync(slotPath, 'utf-8').trim();
+            if (content === myPidStr) fs.unlinkSync(slotPath);
+          } catch {
+            /* already removed or unreadable */
+          }
+        };
+        process.on('exit', release);
+        return release;
+      } catch {
+        // Slot exists. Decide whether to take it over.
+        // Open once and inspect mtime + content via the same fd so there's
+        // no TOCTOU between the metadata check and the content read
+        // (codeql js/file-system-race).
+        let fd;
+        try {
+          fd = fs.openSync(slotPath, 'r');
+        } catch {
+          continue; // Vanished between EEXIST and open — retry this slot.
+        }
+        let isLive = false;
+        let mtimeMs = Date.now();
+        try {
+          mtimeMs = fs.fstatSync(fd).mtimeMs;
+          const buf = Buffer.alloc(32);
+          const n = fs.readSync(fd, buf, 0, 32, 0);
+          const ownerStr = buf.slice(0, n).toString('utf-8').trim();
+          if (ownerStr === '') {
+            // Owner created the file but hasn't written its PID yet. The
+            // wx open+write window is microseconds; give it the benefit
+            // of the doubt and treat as live.
+            isLive = true;
+          } else {
+            const owner = Number.parseInt(ownerStr, 10);
+            if (Number.isFinite(owner) && owner > 0) {
+              try {
+                process.kill(owner, 0);
+                isLive = true;
+              } catch (e) {
+                // ESRCH = process gone → treat as dead. EPERM = process exists
+                // but owned by another user (cross-user lock dir) → still alive,
+                // keep the slot. Anything else: be conservative, assume alive.
+                if (e && e.code === 'ESRCH') {
+                  isLive = false;
+                } else {
+                  isLive = true;
+                }
+              }
+            }
+          }
+        } catch {
+          /* unreadable — treat as dead */
+        } finally {
+          try {
+            fs.closeSync(fd);
+          } catch {
+            /* already closed */
+          }
+        }
+        // For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins —
+        // a slow-but-alive hook is never wrongly evicted. For older slots,
+        // age is the final arbiter as a defense against PID reuse on long-
+        // abandoned slots. 30s >> the 7s augment timeout, so a healthy run
+        // never crosses this threshold.
+        if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) {
+          isLive = false;
+        }
+        if (isLive) break; // Try the next slot.
+        try {
+          fs.unlinkSync(slotPath);
+        } catch {
+          /* another hook beat us to it — retry will hit EEXIST */
+        }
+        // Loop and retry this slot.
+      }
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  HOOK_LOCK_SUBDIR,
+  HOOK_LOCK_MAX_INFLIGHT,
+  HOOK_LOCK_STALE_MS,
+  acquireHookSlot,
+};

package/hooks/claude/pre-tool-use.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# Arceus PreToolUse hook for Claude Code
+# Intercepts Grep/Glob/Bash searches and augments with graph context.
+# Receives JSON on stdin with { tool_name, tool_input, cwd, ... }
+# Returns JSON with additionalContext for graph-enriched results.
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+
+# Extract search pattern based on tool type
+PATTERN=""
+
+case "$TOOL_NAME" in
+  Grep)
+    PATTERN=$(echo "$INPUT" | jq -r '.tool_input.pattern // empty' 2>/dev/null)
+    ;;
+  Glob)
+    # Glob patterns are file paths, not search terms — extract meaningful part
+    RAW=$(echo "$INPUT" | jq -r '.tool_input.pattern // empty' 2>/dev/null)
+    # Strip glob syntax to get the meaningful name (e.g., "**/*.ts" → skip, "auth*.ts" → "auth")
+    PATTERN=$(echo "$RAW" | sed -n 's/.*[*\/]\([a-zA-Z][a-zA-Z0-9_-]*\).*/\1/p')
+    ;;
+  Bash)
+    CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+    # Only augment grep/rg commands
+    if echo "$CMD" | grep -qE '\brg\b|\bgrep\b'; then
+      # Extract pattern from rg/grep
+      if echo "$CMD" | grep -qE '\brg\b'; then
+        PATTERN=$(echo "$CMD" | sed -n "s/.*\brg\s\+\(--[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
+      elif echo "$CMD" | grep -qE '\bgrep\b'; then
+        PATTERN=$(echo "$CMD" | sed -n "s/.*\bgrep\s\+\(-[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
+      fi
+    fi
+    ;;
+  *)
+    # Not a search tool — skip
+    exit 0
+    ;;
+esac
+
+# Skip if pattern too short or empty
+if [ -z "$PATTERN" ] || [ ${#PATTERN} -lt 3 ]; then
+  exit 0
+fi
+
+# Check if we're in a Arceus-indexed repo
+dir="${CWD:-$PWD}"
+found=false
+for i in 1 2 3 4 5; do
+  if [ -d "$dir/.arc" ]; then
+    found=true
+    break
+  fi
+  parent="$(dirname "$dir")"
+  [ "$parent" = "$dir" ] && break
+  dir="$parent"
+done
+
+if [ "$found" = false ]; then
+  exit 0
+fi
+
+# Run arc augment — must be fast (<500ms target)
+# augment writes to stderr (KuzuDB captures stdout at OS level), so capture stderr and discard stdout
+RESULT=$(cd "$CWD" && npx -y arc augment "$PATTERN" 2>&1 1>/dev/null)
+
+if [ -n "$RESULT" ]; then
+  ESCAPED=$(echo "$RESULT" | jq -Rs .)
+  jq -n --argjson ctx "$ESCAPED" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      additionalContext: $ctx
+    }
+  }'
+else
+  exit 0
+fi

package/hooks/claude/session-start.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Arceus SessionStart hook for Claude Code
+# Fires on session startup. Stdout is injected into Claude's context.
+# Checks if the current directory has a Arceus index.
+
+dir="$PWD"
+found=false
+for i in 1 2 3 4 5; do
+  if [ -d "$dir/.arc" ]; then
+    found=true
+    break
+  fi
+  parent="$(dirname "$dir")"
+  [ "$parent" = "$dir" ] && break
+  dir="$parent"
+done
+
+if [ "$found" = false ]; then
+  exit 0
+fi
+
+# Inject Arceus context — this stdout goes directly into Claude's context
+cat << 'EOF'
+## Arceus Code Intelligence
+
+This codebase is indexed by Arceus, providing a knowledge graph with execution flows, relationships, and semantic search.
+
+**Available MCP Tools:**
+- `query` — Process-grouped code intelligence (execution flows related to a concept)
+- `context` — 360-degree symbol view (categorized refs, process participation)
+- `impact` — Blast radius analysis (what breaks if you change a symbol)
+- `detect_changes` — Git-diff impact analysis (what do your changes affect)
+- `rename` — Multi-file coordinated rename with confidence tags
+- `cypher` — Raw graph queries
+- `list_repos` — Discover indexed repos
+
+**Quick Start:** READ `arc://repo/{name}/context` for codebase overview, then use `query` to find execution flows.
+
+**Resources:** `arc://repo/{name}/context` (overview), `/processes` (execution flows), `/schema` (for Cypher)
+EOF
+
+exit 0