qualitative-research-pro 1.0.0

package/hooks/dist/forge-compile-check.mjs

@@ -0,0 +1,92 @@
+// src/forge-compile-check.ts
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { execSync } from "child_process";
+import { join } from "path";
+import { tmpdir } from "os";
+var STATE_DIR = process.env.CLAUDE_PROJECT_DIR ? join(process.env.CLAUDE_PROJECT_DIR, ".claude", "cache", "forge") : join(tmpdir(), "claude-forge");
+var STATE_FILE = join(STATE_DIR, "compiler-state.json");
+function readStdin() {
+  return readFileSync(0, "utf-8");
+}
+function ensureStateDir() {
+  if (!existsSync(STATE_DIR)) {
+    mkdirSync(STATE_DIR, { recursive: true });
+  }
+}
+function saveState(state) {
+  ensureStateDir();
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+}
+function findProjectRoot(cwd) {
+  let dir = cwd;
+  while (dir !== "/") {
+    if (existsSync(join(dir, "foundry.toml"))) return dir;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function runForge(filePath, cwd) {
+  const projectRoot = findProjectRoot(cwd);
+  if (!projectRoot) {
+    return { success: true, output: "No foundry.toml found, skipping forge build" };
+  }
+  try {
+    const output = execSync("forge build 2>&1", {
+      encoding: "utf-8",
+      timeout: 6e4,
+      maxBuffer: 1024 * 1024,
+      cwd: projectRoot
+    });
+    return { success: true, output };
+  } catch (error) {
+    const output = error.stdout || error.stderr || error.message;
+    return { success: false, output };
+  }
+}
+async function main() {
+  const input = JSON.parse(readStdin());
+  if (input.tool_name !== "Write" && input.tool_name !== "Edit") {
+    console.log("{}");
+    return;
+  }
+  const filePath = input.tool_input?.file_path || input.tool_response?.filePath || "";
+  if (!filePath.endsWith(".sol")) {
+    console.log("{}");
+    return;
+  }
+  const result = runForge(filePath, input.cwd);
+  const state = {
+    session_id: input.session_id,
+    file_path: filePath,
+    has_errors: !result.success,
+    errors: result.output,
+    timestamp: Date.now()
+  };
+  saveState(state);
+  if (!result.success) {
+    const errorLines = result.output.split("\n").filter((l) => l.includes("Error") || l.includes("error")).slice(0, 10);
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: `FORGE BUILD ERRORS:
+
+${errorLines.join("\n")}
+
+Fix compilation errors before proceeding.`
+      }
+    }));
+  } else {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: "forge build: compilation successful"
+      }
+    }));
+  }
+}
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/hooks/dist/gas-snapshot-diff.mjs

@@ -0,0 +1,71 @@
+// src/gas-snapshot-diff.ts
+import { readFileSync, existsSync } from "fs";
+import { execSync } from "child_process";
+import { join } from "path";
+function readStdin() {
+  return readFileSync(0, "utf-8");
+}
+function findProjectRoot(cwd) {
+  let dir = cwd;
+  while (dir !== "/") {
+    if (existsSync(join(dir, "foundry.toml"))) return dir;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function checkGasSnapshot(cwd) {
+  const projectRoot = findProjectRoot(cwd);
+  if (!projectRoot) {
+    return { hasRegression: false, diff: "" };
+  }
+  const snapshotFile = join(projectRoot, ".gas-snapshot");
+  if (!existsSync(snapshotFile)) {
+    return { hasRegression: false, diff: "" };
+  }
+  try {
+    const output = execSync("forge snapshot --check --tolerance 5 2>&1", {
+      encoding: "utf-8",
+      timeout: 12e4,
+      maxBuffer: 1024 * 1024,
+      cwd: projectRoot
+    });
+    return { hasRegression: false, diff: output };
+  } catch (error) {
+    const output = error.stdout || error.stderr || error.message;
+    const regressionLines = output.split("\n").filter((l) => l.includes("regression") || l.includes("FAIL")).slice(0, 10);
+    return { hasRegression: true, diff: regressionLines.join("\n") };
+  }
+}
+async function main() {
+  const input = JSON.parse(readStdin());
+  if (input.tool_name !== "Write" && input.tool_name !== "Edit") {
+    console.log("{}");
+    return;
+  }
+  const filePath = input.tool_input?.file_path || input.tool_response?.filePath || "";
+  if (!filePath.endsWith(".sol")) {
+    console.log("{}");
+    return;
+  }
+  const result = checkGasSnapshot(input.cwd);
+  if (result.hasRegression) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: `GAS REGRESSION DETECTED (>5% increase):
+
+${result.diff}
+
+Review gas impact. Run \`forge snapshot --diff\` for full comparison.`
+      }
+    }));
+  } else {
+    console.log("{}");
+  }
+}
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/hooks/dist/memory-awareness.mjs

@@ -0,0 +1,276 @@
+// src/memory-awareness.ts
+import { readFileSync } from "fs";
+import { spawnSync } from "child_process";
+
+// src/shared/opc-path.ts
+import { existsSync } from "fs";
+import { join } from "path";
+function getOpcDir() {
+  const envOpcDir = process.env.CLAUDE_OPC_DIR;
+  if (envOpcDir && existsSync(envOpcDir)) {
+    return envOpcDir;
+  }
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const localOpc = join(projectDir, "opc");
+  if (existsSync(localOpc)) {
+    return localOpc;
+  }
+  const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+  if (homeDir) {
+    const globalClaude = join(homeDir, ".claude");
+    const globalScripts = join(globalClaude, "scripts", "core");
+    if (existsSync(globalScripts)) {
+      return globalClaude;
+    }
+  }
+  return null;
+}
+
+// src/memory-awareness.ts
+function readStdin() {
+  return readFileSync(0, "utf-8");
+}
+function extractIntent(prompt) {
+  const metaPhrases = [
+    /^(can you|could you|would you|please|help me|i want to|i need to|let's|lets)\s+/gi,
+    /^(show me|tell me|find|search for|look for|recall|remember)\s+/gi,
+    /^(how do i|how can i|how to|what is|what are|where is|where are)\s+/gi,
+    /\s+(for me|please|thanks|thank you)$/gi,
+    /\?$/g
+  ];
+  let intent = prompt.trim();
+  for (const pattern of metaPhrases) {
+    intent = intent.replace(pattern, "");
+  }
+  intent = intent.trim();
+  if (intent.length < 5) {
+    return extractKeywords(prompt);
+  }
+  return intent;
+}
+function extractKeywords(prompt) {
+  const stopWords = /* @__PURE__ */ new Set([
+    "a",
+    "an",
+    "the",
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "have",
+    "has",
+    "had",
+    "do",
+    "does",
+    "did",
+    "will",
+    "would",
+    "could",
+    "should",
+    "may",
+    "might",
+    "must",
+    "can",
+    "to",
+    "of",
+    "in",
+    "for",
+    "on",
+    "with",
+    "at",
+    "by",
+    "from",
+    "as",
+    "into",
+    "through",
+    "during",
+    "before",
+    "after",
+    "above",
+    "below",
+    "between",
+    "under",
+    "again",
+    "further",
+    "then",
+    "once",
+    "here",
+    "there",
+    "when",
+    "where",
+    "why",
+    "how",
+    "all",
+    "each",
+    "few",
+    "more",
+    "most",
+    "other",
+    "some",
+    "such",
+    "no",
+    "nor",
+    "not",
+    "only",
+    "own",
+    "same",
+    "so",
+    "than",
+    "too",
+    "very",
+    "s",
+    "t",
+    "just",
+    "don",
+    "now",
+    "i",
+    "me",
+    "my",
+    "you",
+    "your",
+    "we",
+    "help",
+    "with",
+    "our",
+    "they",
+    "them",
+    "their",
+    "it",
+    "its",
+    "this",
+    "that",
+    "these",
+    "what",
+    "which",
+    "who",
+    "whom",
+    "and",
+    "but",
+    "if",
+    "or",
+    "because",
+    "until",
+    "while",
+    "about",
+    "against",
+    "also",
+    "get",
+    "got",
+    "make",
+    "want",
+    "need",
+    "look",
+    "see",
+    "use",
+    "like",
+    "know",
+    "think",
+    "take",
+    "come",
+    "go",
+    "say",
+    "said",
+    "tell",
+    "please",
+    "help",
+    "let",
+    "sure",
+    "recall",
+    "remember",
+    "similar",
+    "problems",
+    "issues"
+  ]);
+  const words = prompt.toLowerCase().replace(/[^\w\s-]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !stopWords.has(w));
+  return [...new Set(words)].slice(0, 5).join(" ");
+}
+function checkMemoryRelevance(intent, projectDir) {
+  if (!intent || intent.length < 3) return null;
+  const opcDir = getOpcDir();
+  if (!opcDir) return null;
+  const searchTerm = intent.replace(/[_\/]/g, " ").replace(/\b\w{1,2}\b/g, "").replace(/\s+/g, " ").trim();
+  const result = spawnSync("uv", [
+    "run",
+    "python",
+    "scripts/core/recall_learnings.py",
+    "--query",
+    searchTerm,
+    // Single keyword for text match
+    "--k",
+    "3",
+    "--json",
+    "--text-only"
+    // Fast text search for hints
+  ], {
+    encoding: "utf-8",
+    cwd: opcDir,
+    env: {
+      ...process.env,
+      PYTHONPATH: opcDir
+    },
+    timeout: 5e3
+    // 5s timeout for fast check
+  });
+  if (result.status !== 0 || !result.stdout) {
+    return null;
+  }
+  try {
+    const data = JSON.parse(result.stdout);
+    if (!data.results || data.results.length === 0) {
+      return null;
+    }
+    const results = data.results.slice(0, 3).map((r) => {
+      const content = r.content || "";
+      const preview = content.split("\n").filter((l) => l.trim().length > 0).map((l) => l.trim()).join(" ").slice(0, 120);
+      return {
+        id: (r.id || "unknown").slice(0, 8),
+        type: r.learning_type || r.type || "UNKNOWN",
+        content: preview + (content.length > 120 ? "..." : ""),
+        score: r.score || 0
+      };
+    });
+    return {
+      count: data.results.length,
+      results
+    };
+  } catch {
+    return null;
+  }
+}
+async function main() {
+  const input = JSON.parse(readStdin());
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || input.cwd;
+  if (process.env.CLAUDE_AGENT_ID) {
+    return;
+  }
+  if (input.prompt.length < 15) {
+    return;
+  }
+  if (input.prompt.trim().startsWith("/")) {
+    return;
+  }
+  const intent = extractIntent(input.prompt);
+  if (intent.length < 3) {
+    return;
+  }
+  const match = checkMemoryRelevance(intent, projectDir);
+  if (match) {
+    const resultLines = match.results.map(
+      (r, i) => `${i + 1}. [${r.type}] ${r.content} (id: ${r.id})`
+    ).join("\n");
+    const claudeContext = `MEMORY MATCH (${match.count} results) for "${intent}":
+${resultLines}
+Use /recall "${intent}" for full content. Disclose if helpful.`;
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext: claudeContext
+      }
+    }));
+  }
+}
+main().catch(() => {
+});

package/hooks/dist/natspec-enforcer.mjs

@@ -0,0 +1,67 @@
+// src/natspec-enforcer.ts
+import { readFileSync, existsSync } from "fs";
+function readStdin() {
+  return readFileSync(0, "utf-8");
+}
+function checkNatSpec(filePath) {
+  if (!existsSync(filePath)) return [];
+  const content = readFileSync(filePath, "utf-8");
+  const lines = content.split("\n");
+  const missing = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    const isFunctionDecl = /^\s*(function\s+\w+)/.test(line);
+    if (!isFunctionDecl) continue;
+    const isPublicOrExternal = /\b(public|external)\b/.test(line);
+    if (!isPublicOrExternal) continue;
+    const isOverride = /\boverride\b/.test(line);
+    if (isOverride) continue;
+    let hasNatSpec = false;
+    for (let j = i - 1; j >= Math.max(0, i - 5); j--) {
+      const prevLine = lines[j].trim();
+      if (prevLine.startsWith("///") || prevLine.startsWith("/**") || prevLine.startsWith("*")) {
+        hasNatSpec = true;
+        break;
+      }
+      if (prevLine === "" || prevLine === "}" || prevLine === "{") continue;
+      break;
+    }
+    if (!hasNatSpec) {
+      const funcMatch = line.match(/function\s+(\w+)/);
+      const funcName = funcMatch ? funcMatch[1] : "unknown";
+      missing.push(`Line ${i + 1}: ${funcName}() missing NatSpec`);
+    }
+  }
+  return missing;
+}
+async function main() {
+  const input = JSON.parse(readStdin());
+  if (input.tool_name !== "Write" && input.tool_name !== "Edit") {
+    console.log("{}");
+    return;
+  }
+  const filePath = input.tool_input?.file_path || input.tool_response?.filePath || "";
+  if (!filePath.endsWith(".sol")) {
+    console.log("{}");
+    return;
+  }
+  const missing = checkNatSpec(filePath);
+  if (missing.length > 0) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: `NATSPEC: ${missing.length} public/external function(s) missing documentation:
+
+${missing.join("\n")}
+
+Add /// @notice, @param, @return for each.`
+      }
+    }));
+  } else {
+    console.log("{}");
+  }
+}
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});