autoctxd 0.4.1

package/scripts/install.ps1

@@ -0,0 +1,71 @@
+# autoctxd one-command installer for Windows (PowerShell)
+#   irm https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.ps1 | iex
+
+$ErrorActionPreference = "Stop"
+
+Write-Host ""
+Write-Host "================================================="
+Write-Host "      autoctxd installer"
+Write-Host "================================================="
+Write-Host ""
+
+$ClaudeDir = if ($env:CLAUDE_DIR) { $env:CLAUDE_DIR } else { Join-Path $env:USERPROFILE ".claude" }
+$CtxDir = Join-Path $ClaudeDir "autoctxd"
+$RepoUrl = if ($env:AUTOCTXD_REPO) { $env:AUTOCTXD_REPO } else { "https://github.com/autoctxd/autoctxd.git" }
+
+# 1. Check Bun
+if (-not (Get-Command bun -ErrorAction SilentlyContinue)) {
+    Write-Host "Bun not found. Installing Bun..."
+    irm bun.sh/install.ps1 | iex
+    $env:Path = "$env:USERPROFILE\.bun\bin;$env:Path"
+}
+Write-Host "  Bun: $(bun --version)"
+
+# 2. git check
+if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
+    Write-Error "git is required. Please install Git for Windows and re-run."
+    exit 1
+}
+
+# 3. Clone or update
+if (-not (Test-Path $ClaudeDir)) { New-Item -ItemType Directory -Path $ClaudeDir | Out-Null }
+
+if (Test-Path (Join-Path $CtxDir ".git")) {
+    Write-Host "  Updating existing install at $CtxDir..."
+    Push-Location $CtxDir
+    git pull --ff-only
+    Pop-Location
+} elseif (Test-Path $CtxDir) {
+    Write-Host "  Found existing non-git install at $CtxDir - using as-is."
+} else {
+    Write-Host "  Cloning to $CtxDir..."
+    git clone $RepoUrl $CtxDir
+}
+
+Push-Location $CtxDir
+
+# 4. deps
+Write-Host "  Installing dependencies..."
+bun install
+
+# 5. init DB
+Write-Host "  Initializing database..."
+bun run src/cli/index.ts init
+
+# 6. hooks
+Write-Host "  Registering hooks in $ClaudeDir\settings.json..."
+bun run scripts/install-hooks.ts
+
+# 7. doctor
+Write-Host ""
+Write-Host "  Running doctor..."
+bun run src/cli/index.ts doctor
+
+Pop-Location
+
+Write-Host ""
+Write-Host "================================================="
+Write-Host "  Installed. Restart Claude Code to activate."
+Write-Host "  CLI:  cd $CtxDir; bun run src/cli/index.ts"
+Write-Host "================================================="
+Write-Host ""

package/scripts/install.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# autoctxd one-command installer for macOS/Linux
+#   curl -fsSL https://raw.githubusercontent.com/autoctxd/autoctxd/main/scripts/install.sh | bash
+
+set -e
+
+echo ""
+echo "================================================="
+echo "      autoctxd installer"
+echo "================================================="
+echo ""
+
+CLAUDE_DIR="${CLAUDE_DIR:-$HOME/.claude}"
+CTX_DIR="$CLAUDE_DIR/autoctxd"
+REPO_URL="${AUTOCTXD_REPO:-https://github.com/autoctxd/autoctxd.git}"
+
+# 1. Check Bun
+if ! command -v bun >/dev/null 2>&1; then
+    echo "Bun not found. Installing Bun..."
+    curl -fsSL https://bun.sh/install | bash
+    export PATH="$HOME/.bun/bin:$PATH"
+fi
+echo "  Bun: $(bun --version)"
+
+# 2. Check git
+if ! command -v git >/dev/null 2>&1; then
+    echo "Error: git is required. Please install git and re-run."
+    exit 1
+fi
+
+# 3. Clone or update
+mkdir -p "$CLAUDE_DIR"
+if [ -d "$CTX_DIR/.git" ]; then
+    echo "  Updating existing install at $CTX_DIR..."
+    cd "$CTX_DIR" && git pull --ff-only
+elif [ -d "$CTX_DIR" ] && [ ! -d "$CTX_DIR/.git" ]; then
+    echo "  Found existing non-git install at $CTX_DIR — using as-is."
+    cd "$CTX_DIR"
+else
+    echo "  Cloning to $CTX_DIR..."
+    git clone "$REPO_URL" "$CTX_DIR"
+    cd "$CTX_DIR"
+fi
+
+# 4. Install deps
+echo "  Installing dependencies..."
+bun install
+
+# 5. Init DB
+echo "  Initializing database..."
+bun run src/cli/index.ts init
+
+# 6. Install hooks
+echo "  Registering hooks in $CLAUDE_DIR/settings.json..."
+bun run scripts/install-hooks.ts
+
+# 7. Verify
+echo ""
+echo "  Running doctor..."
+bun run src/cli/index.ts doctor
+
+echo ""
+echo "================================================="
+echo "  Installed. Restart Claude Code to activate."
+echo "  CLI:  cd $CTX_DIR && bun run src/cli/index.ts"
+echo "================================================="
+echo ""

package/scripts/uninstall-hooks.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env bun
+// Removes only autoctxd hook entries from settings.json, leaves other hooks intact.
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from "fs";
+import { join, resolve } from "path";
+
+const CTX_ROOT = resolve(join(import.meta.dir, ".."));
+const CLAUDE_DIR = resolve(join(CTX_ROOT, ".."));
+const SETTINGS = join(CLAUDE_DIR, "settings.json");
+
+function isClaudeCtxHookEntry(entry: any): boolean {
+  return JSON.stringify(entry).includes("autoctxd");
+}
+
+async function main() {
+  if (!existsSync(SETTINGS)) {
+    console.log("  No settings.json found — nothing to uninstall.");
+    return;
+  }
+
+  const backup = `${SETTINGS}.backup.${Date.now()}`;
+  copyFileSync(SETTINGS, backup);
+  console.log(`  Backed up → ${backup}`);
+
+  let cfg: any;
+  try {
+    cfg = JSON.parse(readFileSync(SETTINGS, "utf8"));
+  } catch (e) {
+    console.error(`  Cannot parse settings.json: ${e}`);
+    process.exit(1);
+  }
+
+  let removed = 0;
+  for (const hookName of ["PreToolUse", "PostToolUse", "Stop"]) {
+    const entries: any[] = cfg.hooks?.[hookName] || [];
+    const kept = entries.filter(e => !isClaudeCtxHookEntry(e));
+    removed += entries.length - kept.length;
+
+    if (kept.length === 0) {
+      delete cfg.hooks?.[hookName];
+    } else {
+      cfg.hooks[hookName] = kept;
+    }
+  }
+
+  // Clean empty hooks object
+  if (cfg.hooks && Object.keys(cfg.hooks).length === 0) {
+    delete cfg.hooks;
+  }
+
+  writeFileSync(SETTINGS, JSON.stringify(cfg, null, 2) + "\n");
+  console.log(`  Removed ${removed} autoctxd hook entries.`);
+  console.log(`  Data directory preserved. To wipe memory: bun run src/cli/index.ts reset`);
+  console.log(`  Restart Claude Code for changes to take effect.`);
+}
+
+main();

package/src/ai/active-guard.ts

@@ -0,0 +1,96 @@
+// Active Guard: the revolutionary piece. Detects when Claude's about to do
+// something that contradicts a past architectural decision and surfaces a
+// warning that MCP serves into Claude's context on-demand.
+
+import { getDb } from "../db/sqlite/schema";
+import { getDecisionsByProject, type Decision } from "../db/sqlite/decisions";
+
+export interface GuardWarning {
+  decision: Decision;
+  reason: string;
+  confidence: number; // 0..1
+}
+
+// Given a proposed action (tool call or code snippet), return any decisions
+// that the action might contradict. Used by MCP's check_intent tool.
+export function checkIntent(
+  projectPath: string,
+  intent: string
+): GuardWarning[] {
+  const decisions = getDecisionsByProject(projectPath);
+  if (decisions.length === 0) return [];
+
+  const warnings: GuardWarning[] = [];
+  const intentLower = intent.toLowerCase();
+
+  for (const d of decisions) {
+    const warning = analyzeDecision(d, intent, intentLower);
+    if (warning) warnings.push(warning);
+  }
+
+  warnings.sort((a, b) => b.confidence - a.confidence);
+  return warnings.slice(0, 3);
+}
+
+function analyzeDecision(d: Decision, intent: string, intentLower: string): GuardWarning | null {
+  // Extract the rejected alternative(s)
+  if (d.alternatives) {
+    const alternatives = d.alternatives.toLowerCase().split(/[,;]/).map(s => s.trim());
+    for (const alt of alternatives) {
+      if (alt.length >= 3 && intentLower.includes(alt)) {
+        return {
+          decision: d,
+          reason: `Intent mentions "${alt}", which was rejected in favor of the original decision.`,
+          confidence: 0.85,
+        };
+      }
+    }
+  }
+
+  // Dependency decisions: if a new install matches a different package than the one chosen
+  const depMatch = intent.match(/\b(?:npm|bun|pnpm|yarn|pip|cargo)\s+(?:install|add|i)\s+([@\w\-/\.]+)/i);
+  if (depMatch && /Added .+ dep: (\S+)/i.test(d.title)) {
+    const chosenDep = d.title.match(/Added .+ dep: (\S+)/i)?.[1]?.toLowerCase();
+    const proposedDep = depMatch[1].toLowerCase();
+    if (chosenDep && proposedDep !== chosenDep && isSameCategory(chosenDep, proposedDep)) {
+      return {
+        decision: d,
+        reason: `You installed "${chosenDep}" for this role previously. Installing "${proposedDep}" may duplicate or conflict.`,
+        confidence: 0.7,
+      };
+    }
+  }
+
+  // Migration pattern: if decision said "migrated from A to B", warn on references to A
+  const migrMatch = d.decision_text.match(/(?:migrated|switched|moved)\s+(?:from\s+)?([\w\-/@.]+?)\s+to\s+[\w\-/@.]+/i);
+  if (migrMatch) {
+    const oldTech = migrMatch[1].toLowerCase();
+    if (oldTech.length >= 3 && intentLower.includes(oldTech)) {
+      return {
+        decision: d,
+        reason: `You migrated away from "${oldTech}" in this project. Intent mentions it — likely regression.`,
+        confidence: 0.75,
+      };
+    }
+  }
+
+  return null;
+}
+
+// Very rough category heuristic so we don't warn "redis vs sqlite" (different categories)
+// but do warn "express vs hono" (both web frameworks)
+const CATEGORIES: Record<string, string[]> = {
+  web_framework: ["express", "hono", "fastify", "koa", "oak", "flask", "fastapi", "gin", "axum"],
+  orm: ["drizzle-orm", "prisma", "typeorm", "sequelize", "sqlalchemy", "mongoose"],
+  validation: ["zod", "yup", "joi", "ajv", "valibot"],
+  testing: ["jest", "vitest", "mocha", "pytest"],
+  state_mgmt: ["redux", "zustand", "jotai", "valtio", "pinia", "vuex"],
+  db_driver: ["better-sqlite3", "pg", "mysql2", "mongodb", "redis"],
+};
+
+function isSameCategory(a: string, b: string): boolean {
+  for (const group of Object.values(CATEGORIES)) {
+    if (group.includes(a) && group.includes(b)) return true;
+  }
+  return false;
+}

package/src/ai/adaptive-ranker.ts

@@ -0,0 +1,48 @@
+// Adaptive ranker: the same base ranker, but adjusts scores using accumulated
+// user feedback. Items marked irrelevant get suppressed; items marked useful
+// get amplified. This is what makes autoctxd learn over time.
+
+import { getScoreDeltas } from "../db/sqlite/feedback";
+
+export interface RankableItem {
+  type: "decision" | "observation" | "summary" | "pattern" | "unfinished";
+  id: string | number;
+  text: string;
+  baseScore: number;
+}
+
+export interface RankedItem extends RankableItem {
+  finalScore: number;
+  feedbackDelta: number;
+  suppressed: boolean;
+}
+
+const SUPPRESSION_THRESHOLD = -4;
+
+export function adaptiveRank(
+  items: RankableItem[],
+  projectPath?: string
+): RankedItem[] {
+  const deltas = getScoreDeltas(projectPath);
+  const globalDeltas = projectPath ? getScoreDeltas() : new Map();
+
+  const ranked: RankedItem[] = items.map(item => {
+    const key = `${item.type}:${item.id}`;
+    const projectDelta = deltas.get(key) || 0;
+    const globalDelta = globalDeltas.get(key) || 0;
+    // Project-specific feedback weighs 2x vs cross-project
+    const totalDelta = projectDelta * 2 + globalDelta;
+    const finalScore = item.baseScore + totalDelta;
+
+    return {
+      ...item,
+      finalScore,
+      feedbackDelta: totalDelta,
+      suppressed: totalDelta <= SUPPRESSION_THRESHOLD,
+    };
+  });
+
+  return ranked
+    .filter(r => !r.suppressed)
+    .sort((a, b) => b.finalScore - a.finalScore);
+}

package/src/ai/classifier.ts

@@ -0,0 +1,256 @@
+// Heuristic classifier for observations - no API calls needed
+
+export type ObservationType =
+  | "bug_fix"
+  | "refactor"
+  | "new_feature"
+  | "config"
+  | "research"
+  | "test"
+  | "decision"
+  | "blocked"
+  | "deploy"
+  | "other";
+
+interface ClassificationResult {
+  type: ObservationType;
+  importance: number; // 0-10
+}
+
+const PATTERNS: Array<{ type: ObservationType; keywords: RegExp; baseImportance: number }> = [
+  {
+    type: "bug_fix",
+    keywords: /\b(fix|bug|error|issue|crash|broken|patch|hotfix|resolve|regression|exception|throw|catch|undefined|null\s+ref|NaN|infinite\s+loop)\b/i,
+    baseImportance: 7,
+  },
+  {
+    type: "decision",
+    keywords: /\b(chose|decided|picked|selected|switched\s+to|migrated?\s+to|replaced|instead\s+of|over|vs|versus|trade-?off|architecture|design\s+decision|went\s+with)\b/i,
+    baseImportance: 9,
+  },
+  {
+    type: "refactor",
+    keywords: /\b(refactor|rename|extract|inline|move|restructure|reorganize|clean\s*up|simplif|deduplicate|DRY|split|merge|consolidat)\b/i,
+    baseImportance: 5,
+  },
+  {
+    type: "new_feature",
+    keywords: /\b(add|implement|create|new\s+(feature|component|endpoint|page|route|module|service|function|class|hook)|introduce|build|scaffold)\b/i,
+    baseImportance: 7,
+  },
+  {
+    type: "test",
+    keywords: /\b(test|spec|assert|expect|mock|stub|coverage|jest|vitest|mocha|pytest|describe\(|it\(|should)\b/i,
+    baseImportance: 4,
+  },
+  {
+    type: "config",
+    keywords: /\b(config|setting|env|\.env|docker|compose|nginx|webpack|vite|tsconfig|package\.json|eslint|prettier|ci|cd|pipeline|yaml|yml|toml)\b/i,
+    baseImportance: 4,
+  },
+  {
+    type: "deploy",
+    keywords: /\b(deploy|release|publish|ship|production|staging|build|bundle|dist|push\s+to|merge\s+to\s+main|tag\s+v)\b/i,
+    baseImportance: 8,
+  },
+  {
+    type: "blocked",
+    keywords: /\b(blocked|stuck|can'?t|cannot|impossible|workaround|hack|TODO|FIXME|HACK|skip|disable|comment\s*out)\b/i,
+    baseImportance: 6,
+  },
+  {
+    type: "research",
+    keywords: /\b(research|investigat|explor|read|review|understand|learn|docs|documentation|stack\s*overflow|github\s+issue|RFC)\b/i,
+    baseImportance: 3,
+  },
+];
+
+// Tool calls that are internal harness/agent plumbing, not user-driven work.
+// These were leaking into the activity timeline as the dominant share of
+// "other" observations. They still get persisted so the DB stays complete,
+// but at importance 1 they fall out of top-observations and context injection.
+const META_TOOLS = new Set([
+  "Monitor",
+  "ToolSearch",
+  "TaskStop",
+  "TaskOutput",
+  "TodoWrite",
+]);
+
+// Same idea, but for cases where the hook captured the tool as Bash/PowerShell
+// while the summary clearly carries the metadata payload of another tool.
+const META_SUMMARY_PATTERNS: RegExp[] = [
+  /^Monitor:\s*\{/,
+  /^ToolSearch:\s*\{/,
+  /^TaskStop:\s*\{/,
+  /^TodoWrite/,
+];
+
+export function classifyObservation(
+  toolName: string,
+  summary: string,
+  filePaths?: string[]
+): ClassificationResult {
+  // MCP external tools are never architectural decisions
+  if (toolName.startsWith("mcp__")) {
+    return { type: "other", importance: 2 };
+  }
+
+  // Internal tool metadata — keep the record but mark it low-importance so it
+  // doesn't pollute "top observations" or get injected as recovered context.
+  if (META_TOOLS.has(toolName) || META_SUMMARY_PATTERNS.some(p => p.test(summary))) {
+    return { type: "other", importance: 1 };
+  }
+
+  // Hard overrides that always win over keyword scoring
+  const override = hardOverride(toolName, summary);
+  if (override) {
+    let result = { ...override };
+    if (toolName === "Edit" || toolName === "Write") {
+      result.importance = Math.min(10, result.importance + 1);
+    }
+    return result;
+  }
+
+  let bestMatch: ClassificationResult = { type: "other", importance: 3 };
+  let highestScore = 0;
+
+  for (const pattern of PATTERNS) {
+    const matches = summary.match(pattern.keywords);
+    if (matches) {
+      const score = matches.length * pattern.baseImportance;
+      if (score > highestScore) {
+        highestScore = score;
+        bestMatch = { type: pattern.type, importance: pattern.baseImportance };
+      }
+    }
+  }
+
+  // Fallback heuristics by tool + file path when keywords miss
+  if (bestMatch.type === "other") {
+    const inferred = inferFromToolAndFiles(toolName, summary, filePaths);
+    if (inferred) bestMatch = inferred;
+  }
+
+  // Boost importance for certain tool types
+  if (toolName === "Edit" || toolName === "Write") {
+    bestMatch.importance = Math.min(10, bestMatch.importance + 1);
+  }
+
+  // Boost for critical files
+  if (filePaths?.some(f => /(auth|payment|security|migration|schema)/i.test(f))) {
+    bestMatch.importance = Math.min(10, bestMatch.importance + 2);
+  }
+
+  // Reduce for common/trivial files
+  if (filePaths?.every(f => /(readme|changelog|license|\.md$)/i.test(f))) {
+    bestMatch.importance = Math.max(1, bestMatch.importance - 2);
+  }
+
+  return bestMatch;
+}
+
+function hardOverride(toolName: string, summary: string): ClassificationResult | null {
+  // Package manager installs are always stack decisions — higher signal than
+  // generic "add" keyword that would otherwise classify as new_feature.
+  if (toolName === "Bash" && /\b(npm|bun|pnpm|yarn|pip|cargo|go)\s+(?:install|add|i)\b/i.test(summary)) {
+    return { type: "decision", importance: 8 };
+  }
+  // Spawning an Agent is exploration/research, never an architectural decision —
+  // even when the agent's prompt happens to contain words like "architecture"
+  // or "decision" that would otherwise trigger keyword scoring.
+  if (toolName === "Agent") {
+    return { type: "research", importance: 4 };
+  }
+  return null;
+}
+
+function inferFromToolAndFiles(
+  toolName: string,
+  summary: string,
+  filePaths?: string[]
+): ClassificationResult | null {
+  const files = filePaths || [];
+  const anyMatch = (rx: RegExp) => files.some(f => rx.test(f));
+
+  // Test files
+  if (anyMatch(/(\.test\.|\.spec\.|__tests__|\/tests?\/)/i)) {
+    return { type: "test", importance: 5 };
+  }
+
+  // Config files
+  if (anyMatch(/(package\.json|tsconfig|\.env|webpack|vite\.config|eslint|prettier|docker|compose|\.ya?ml$|\.toml$|Cargo\.toml|pyproject|go\.mod)/i)) {
+    return { type: "config", importance: 5 };
+  }
+
+  // Bash / PowerShell: detect flavor by command. (PowerShell is captured under
+  // the same heuristics — they all show up in the same activity stream and
+  // were the bulk of the legacy "other" share.)
+  if (toolName === "Bash" || toolName === "PowerShell") {
+    if (/\b(npm|bun|pip|cargo|go)\s+(install|add|i)\b/i.test(summary)) {
+      return { type: "decision", importance: 8 }; // dependency choice = stack decision
+    }
+    if (/\b(test|vitest|jest|pytest|go\s+test|cargo\s+test)\b/i.test(summary)) {
+      return { type: "test", importance: 5 };
+    }
+    if (/\b(build|bundle|compile|tsc|webpack)\b/i.test(summary)) {
+      return { type: "deploy", importance: 6 };
+    }
+    if (/\b(git\s+(push|tag)|deploy|publish|release)\b/i.test(summary)) {
+      return { type: "deploy", importance: 8 };
+    }
+    // Read-only git commands are exploration, not config or deploy
+    if (/\bgit\s+(status|log|diff|show|blame|branch|remote|fetch)\b/i.test(summary)) {
+      return { type: "research", importance: 2 };
+    }
+    // Filesystem / process inspection
+    if (/^(?:Bash:\s*|PowerShell:\s*)?(?:List|Check|Find|Show|View|Read|Cat|Look|Verify|Inspect)\b/i.test(summary)) {
+      return { type: "research", importance: 2 };
+    }
+    if (/\b(kill|pkill|ps\b|netstat|lsof|top|tasklist|taskkill)\b/i.test(summary)) {
+      return { type: "other", importance: 2 };
+    }
+    if (/\b(rm|del|delete|drop\s+table)\b/i.test(summary)) {
+      return { type: "refactor", importance: 5 };
+    }
+  }
+
+  // Write of new source file → new_feature
+  if (toolName === "Write" && anyMatch(/\.(ts|tsx|js|jsx|py|go|rs|java|rb|php|vue|svelte)$/i)) {
+    return { type: "new_feature", importance: 7 };
+  }
+
+  // Edit of source file → refactor by default
+  if (toolName === "Edit" && anyMatch(/\.(ts|tsx|js|jsx|py|go|rs|java|rb|php|vue|svelte)$/i)) {
+    return { type: "refactor", importance: 5 };
+  }
+
+  // Web research
+  if (toolName === "WebFetch" || toolName === "WebSearch") {
+    return { type: "research", importance: 3 };
+  }
+
+  // Agent spawn → usually exploration
+  if (toolName === "Agent") {
+    return { type: "research", importance: 4 };
+  }
+
+  return null;
+}
+
+export function extractFilePaths(text: string): string[] {
+  const patterns = [
+    /(?:^|\s)([a-zA-Z]:\\[\w\\.-]+)/g,         // Windows absolute
+    /(?:^|\s)(\/[\w/.-]+\.\w+)/g,               // Unix absolute
+    /(?:^|\s)((?:src|lib|app|pages|components|test|spec)\/[\w/.-]+)/g, // Relative common
+  ];
+
+  const paths = new Set<string>();
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      paths.add(match[1].trim());
+    }
+  }
+  return [...paths];
+}