oco-claude-plugin 0.1.0

package/plugin/mcp/bridge.js

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+/**
+ * OCO MCP Bridge Server
+ *
+ * Minimal MCP server that bridges Claude Code to the local OCO runtime.
+ * Exposes only composite, high-value tools.
+ *
+ * Transport: stdio (Claude Code spawns this process)
+ * Backend: calls local `oco` CLI binary
+ */
+
+const { spawn } = require("child_process");
+const readline = require("readline");
+
+const OCO_BIN = process.env.OCO_BIN || "oco";
+const WORKSPACE = process.env.OCO_WORKSPACE || process.cwd();
+
+// --- MCP Protocol Handler ---
+
+const rl = readline.createInterface({ input: process.stdin });
+let buffer = "";
+
+rl.on("line", (line) => {
+  try {
+    const request = JSON.parse(line);
+    handleRequest(request).then((response) => {
+      process.stdout.write(JSON.stringify(response) + "\n");
+    });
+  } catch {
+    // Ignore malformed lines
+  }
+});
+
+async function handleRequest(request) {
+  const { id, method, params } = request;
+
+  switch (method) {
+    case "initialize":
+      return success(id, {
+        protocolVersion: "2024-11-05",
+        serverInfo: { name: "oco-bridge", version: "0.1.0" },
+        capabilities: {
+          tools: { listChanged: false },
+        },
+      });
+
+    case "tools/list":
+      return success(id, { tools: TOOLS });
+
+    case "tools/call":
+      return handleToolCall(id, params.name, params.arguments || {});
+
+    default:
+      return error(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+// --- Tool Definitions ---
+
+const TOOLS = [
+  {
+    name: "oco.search_codebase",
+    description:
+      "Composite codebase search: lexical + structural ranking with symbol-aware narrowing. Returns compact ranked results.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search query (natural language or symbol name)",
+        },
+        workspace: {
+          type: "string",
+          description: "Workspace root path (defaults to cwd)",
+        },
+        limit: {
+          type: "integer",
+          description: "Max results (default: 10)",
+          default: 10,
+        },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "oco.trace_error",
+    description:
+      "Composite error analysis: maps stack trace to codebase, identifies likely root cause regions, suggests next verification step.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        stacktrace: {
+          type: "string",
+          description: "The stack trace or error output to analyze",
+        },
+        workspace: {
+          type: "string",
+          description: "Workspace root path",
+        },
+      },
+      required: ["stacktrace"],
+    },
+  },
+  {
+    name: "oco.verify_patch",
+    description:
+      "Composite verification: detects project type, runs build/test/lint/typecheck, returns structured verdict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: {
+          type: "string",
+          description: "Workspace root path",
+        },
+        checks: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Specific checks to run (build, test, lint, typecheck). Defaults to all available.",
+        },
+      },
+    },
+  },
+  {
+    name: "oco.collect_findings",
+    description:
+      "Composite state extraction: current evidence, open questions, unresolved risks, suggested next action from the OCO session.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: {
+          type: "string",
+          description: "OCO session ID (optional, uses latest if omitted)",
+        },
+      },
+    },
+  },
+];
+
+// --- Tool Handlers ---
+
+async function handleToolCall(id, toolName, args) {
+  try {
+    switch (toolName) {
+      case "oco.search_codebase":
+        return await searchCodebase(id, args);
+      case "oco.trace_error":
+        return await traceError(id, args);
+      case "oco.verify_patch":
+        return await verifyPatch(id, args);
+      case "oco.collect_findings":
+        return await collectFindings(id, args);
+      default:
+        return error(id, -32601, `Unknown tool: ${toolName}`);
+    }
+  } catch (e) {
+    return success(id, {
+      content: [{ type: "text", text: `Error: ${e.message}` }],
+      isError: true,
+    });
+  }
+}
+
+async function searchCodebase(id, args) {
+  const workspace = args.workspace || WORKSPACE;
+  const limit = args.limit || 10;
+
+  const result = await runOco([
+    "search",
+    args.query,
+    "--workspace",
+    workspace,
+    "--limit",
+    String(limit),
+    "--format",
+    "json",
+  ]);
+
+  if (result.error) {
+    // Graceful degradation: return empty results
+    return success(id, {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ results: [], note: "OCO backend unavailable, use standard search tools" }),
+        },
+      ],
+    });
+  }
+
+  return success(id, {
+    content: [{ type: "text", text: result.stdout }],
+  });
+}
+
+async function traceError(id, args) {
+  const workspace = args.workspace || WORKSPACE;
+
+  // Parse stack trace to extract file paths and line numbers
+  const frames = parseStackTrace(args.stacktrace);
+
+  if (frames.length === 0) {
+    return success(id, {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            frames: [],
+            note: "Could not parse stack trace. Provide the raw error output.",
+          }),
+        },
+      ],
+    });
+  }
+
+  // Search for each unique file in the stack trace
+  const fileSet = [...new Set(frames.map((f) => f.file))];
+  const results = [];
+
+  for (const file of fileSet.slice(0, 5)) {
+    const search = await runOco([
+      "search",
+      file,
+      "--workspace",
+      workspace,
+      "--limit",
+      "3",
+      "--format",
+      "json",
+    ]);
+    if (!search.error && search.stdout) {
+      try {
+        const parsed = JSON.parse(search.stdout);
+        results.push({ file, matches: parsed });
+      } catch {
+        // skip
+      }
+    }
+  }
+
+  return success(id, {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          parsed_frames: frames,
+          codebase_matches: results,
+          suggestion: "Inspect the deepest application frame first. Check for null access, type errors, or missing validation.",
+        }),
+      },
+    ],
+  });
+}
+
+async function verifyPatch(id, args) {
+  const workspace = args.workspace || WORKSPACE;
+  const checks = args.checks || ["build", "test", "lint", "typecheck"];
+
+  const verdicts = {};
+
+  for (const check of checks) {
+    const cmd = getCheckCommand(workspace, check);
+    if (!cmd) {
+      verdicts[check] = { status: "skip", reason: "not available" };
+      continue;
+    }
+
+    const result = await runShell(cmd.command, cmd.args, { cwd: workspace });
+    const passed = result.exitCode === 0;
+    verdicts[check] = {
+      status: passed ? "pass" : "fail",
+      // Only include output on failure to avoid leaking noisy stderr warnings
+      ...(passed ? {} : { output: truncate((result.stderr + "\n" + result.stdout).trim(), 500) }),
+    };
+
+    // Stop on first failure
+    if (result.exitCode !== 0) {
+      break;
+    }
+  }
+
+  const entries = Object.values(verdicts);
+  const allSkipped = entries.every((v) => v.status === "skip");
+  const hasFail = entries.some((v) => v.status === "fail");
+  const verdict = hasFail ? "FAIL" : allSkipped ? "SKIP" : "PASS";
+
+  return success(id, {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          verdict,
+          checks: verdicts,
+          ...(allSkipped && { note: "No verification commands available for this workspace. Manual review required." }),
+        }),
+      },
+    ],
+  });
+}
+
+async function collectFindings(id, args) {
+  const sessionId = args.session_id || "latest";
+
+  const result = await runOco([
+    "trace",
+    sessionId,
+    "--format",
+    "json",
+  ]);
+
+  if (result.error) {
+    return success(id, {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            evidence: [],
+            open_questions: [],
+            risks: [],
+            next_action: "No OCO session data available. Use standard investigation.",
+          }),
+        },
+      ],
+    });
+  }
+
+  return success(id, {
+    content: [{ type: "text", text: result.stdout }],
+  });
+}
+
+// --- Helpers ---
+
+function parseStackTrace(text) {
+  const frames = [];
+  // Common patterns: file:line, file(line), at file:line:col
+  const patterns = [
+    /at\s+(?:\w+\s+\()?([^:(\s]+):(\d+)/g, // JS/TS: at func (file:line:col)
+    /File "([^"]+)", line (\d+)/g, // Python: File "path", line N
+    /([^\s]+\.rs):(\d+)/g, // Rust: file.rs:line
+    /([^\s]+\.[a-z]+):(\d+)/g, // Generic: file.ext:line
+  ];
+
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      frames.push({ file: match[1], line: parseInt(match[2], 10) });
+    }
+  }
+
+  return frames;
+}
+
+function getCheckCommand(workspace, check) {
+  const fs = require("fs");
+  const path = require("path");
+
+  const hasFile = (name) =>
+    fs.existsSync(path.join(workspace, name));
+
+  switch (check) {
+    case "build":
+      if (hasFile("Cargo.toml"))
+        return { command: "cargo", args: ["build"] };
+      if (hasFile("package.json"))
+        return { command: "npm", args: ["run", "build"] };
+      return null;
+    case "test":
+      if (hasFile("Cargo.toml"))
+        return { command: "cargo", args: ["test"] };
+      if (hasFile("package.json"))
+        return { command: "npm", args: ["test"] };
+      if (hasFile("pyproject.toml"))
+        return { command: "pytest", args: [] };
+      return null;
+    case "lint":
+      if (hasFile("Cargo.toml"))
+        return { command: "cargo", args: ["clippy", "--", "-D", "warnings"] };
+      if (hasFile("package.json"))
+        return { command: "npm", args: ["run", "lint"] };
+      return null;
+    case "typecheck":
+      if (hasFile("Cargo.toml"))
+        return { command: "cargo", args: ["check"] };
+      if (hasFile("tsconfig.json"))
+        return { command: "npx", args: ["tsc", "--noEmit"] };
+      if (hasFile("pyproject.toml"))
+        return { command: "mypy", args: ["."] };
+      return null;
+    default:
+      return null;
+  }
+}
+
+function runOco(args) {
+  return runShell(OCO_BIN, args, {});
+}
+
+function runShell(command, args, options) {
+  return new Promise((resolve) => {
+    const proc = spawn(command, args, {
+      ...options,
+      timeout: 30000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (d) => (stdout += d.toString()));
+    proc.stderr.on("data", (d) => (stderr += d.toString()));
+
+    proc.on("close", (code) => {
+      resolve({ exitCode: code, stdout, stderr, error: null });
+    });
+
+    proc.on("error", (err) => {
+      resolve({ exitCode: -1, stdout: "", stderr: "", error: err.message });
+    });
+  });
+}
+
+function truncate(str, maxLen) {
+  if (!str || str.length <= maxLen) return str || "";
+  return str.slice(0, maxLen) + "\n... (truncated)";
+}
+
+function success(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function error(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}

package/plugin/settings-fragment.json

@@ -0,0 +1,64 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/user-prompt-submit.cjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/pre-tool-use.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/post-tool-use.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/stop.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
+  "mcpServers": {
+    "oco": {
+      "command": "node",
+      "args": [".claude/mcp/bridge.js"],
+      "env": {
+        "OCO_BIN": "oco"
+      }
+    }
+  },
+  "permissions": {
+    "allow": ["Bash(oco *)"]
+  }
+}

package/plugin/skills/oco-inspect-repo-area/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: oco-inspect-repo-area
+description: Explore and understand a specific area of the repository using OCO-backed code intelligence. Use when the task is exploratory and repo-specific.
+triggers:
+  - "explore"
+  - "understand"
+  - "how does"
+  - "what does"
+  - "show me the"
+  - "explain the"
+  - "where is"
+  - "codebase"
+  - "module"
+  - "architecture"
+---
+
+# OCO: Inspect Repository Area
+
+You are performing a focused exploration of a codebase area. Follow this structured workflow.
+
+## Step 1: Identify the Target Area
+
+Determine which part of the codebase needs exploration:
+- A module, package, or directory
+- A feature or capability
+- A data flow or interaction pattern
+
+## Step 2: Gather Ranked Context (via OCO)
+
+Use the `oco.search_codebase` MCP tool if available, otherwise use standard search tools:
+
+```
+oco.search_codebase({ query: "<area description>", workspace: "." })
+```
+
+This returns ranked, symbol-aware results — prefer these over raw file dumping.
+
+## Step 3: Read Key Files Selectively
+
+Based on search results, read only the most relevant files. **Do NOT dump entire directories.**
+
+Priority order:
+1. Entry points and public API surfaces
+2. Core types and data structures
+3. Key implementation logic
+4. Tests (for behavior documentation)
+
+## Step 4: Summarize Before Acting
+
+Before taking any action, produce a **compact summary**:
+- Purpose of the area
+- Key types and their relationships
+- Entry points and data flow
+- Potential concerns or complexity hotspots
+
+## Rules
+
+- Never read more than 10 files without summarizing first
+- Prefer symbol-level inspection over full file reads
+- If an area is complex (>5 files), delegate to the `@codebase-investigator` subagent
+- Report confidence level: high / medium / low

package/plugin/skills/oco-investigate-bug/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: oco-investigate-bug
+description: Systematic bug investigation without a full stacktrace. Enforces evidence-first debugging with reproduction and root cause analysis.
+triggers:
+  - "debug"
+  - "bug"
+  - "not working"
+  - "broken"
+  - "doesn't work"
+  - "wrong behavior"
+  - "unexpected"
+  - "regression"
+---
+
+# OCO: Investigate Bug
+
+You are investigating a bug without a clear stack trace. Follow strict evidence-based debugging.
+
+## Step 1: Understand the Symptom
+
+Clarify with the user if needed:
+- **Expected behavior**: What should happen?
+- **Actual behavior**: What happens instead?
+- **Reproduction steps**: How to trigger it?
+- **When it started**: Recent change? Always broken?
+
+## Step 2: Narrow the Scope
+
+Identify the subsystem:
+1. Search for relevant code using `oco.search_codebase` or standard search
+2. Identify the code path from user action to observed behavior
+3. List candidate files (max 5 initial candidates)
+
+## Step 3: Gather Evidence
+
+For each candidate:
+1. Read the relevant code section
+2. Look for: edge cases, missing validation, incorrect logic, state corruption, timing issues
+3. Check recent changes (`git log --oneline -10 -- <file>`)
+4. Check tests: do existing tests cover this case?
+
+## Step 4: Reproduce or Narrow
+
+Before proposing a fix:
+- If tests exist: check if they pass or fail
+- If no tests: describe how to reproduce
+- Narrow to the smallest possible scope
+
+## Step 5: Root Cause Analysis
+
+State the root cause with evidence:
+- **Root cause**: [description]
+- **Evidence**: [what you found in the code]
+- **Why it wasn't caught**: [missing test, edge case, etc.]
+
+## Step 6: Fix Only After Evidence
+
+Once root cause is confirmed:
+1. Propose the minimal fix
+2. Explain why the fix addresses the root cause
+3. Identify if new tests are needed
+4. After applying changes, run the verification workflow described in the `oco-verify-fix` skill (build, test, lint, typecheck)
+5. Use `oco.collect_findings` to synthesize current evidence and remaining open questions
+
+## Rules
+
+- **Never guess at fixes** — evidence first
+- After 2 failed attempts at the same approach, step back and reconsider
+- If scope exceeds 5 files, delegate reading to `@codebase-investigator`
+- For semantic review of proposed patches, delegate to `@patch-verifier`
+- Always document what you ruled out and why

package/plugin/skills/oco-safe-refactor/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: oco-safe-refactor
+description: Structured refactoring with impact analysis, staged changes, and verification. Use for renames, restructuring, module extraction.
+triggers:
+  - "refactor"
+  - "rename"
+  - "restructure"
+  - "extract"
+  - "move to"
+  - "split into"
+  - "reorganize"
+  - "decouple"
+---
+
+# OCO: Safe Refactor
+
+You are performing a refactoring operation. Follow this staged, verification-gated workflow.
+
+## Step 1: Define the Refactoring Scope
+
+Clearly state:
+- **What** is being refactored (symbol, module, pattern)
+- **Why** (improve clarity, reduce coupling, fix naming)
+- **Boundary**: what files/modules are affected
+
+## Step 2: Impact Analysis
+
+Before making any changes:
+
+1. **Find all usages** of the target symbol/pattern:
+   - Use `oco.search_codebase` or Grep for symbol references
+   - Check imports, re-exports, type references, test references
+   - Check config files, documentation, comments
+
+2. **Map the dependency graph**:
+   - What depends on the thing being refactored?
+   - What does it depend on?
+   - Are there external consumers (API, CLI, exports)?
+
+3. **Produce impact summary**:
+   - Files affected: [list]
+   - Symbols affected: [list]
+   - Risk level: low / medium / high
+   - Breaking changes: yes / no
+
+If impact is high (>10 files or breaking changes), delegate deep analysis to `@refactor-reviewer` subagent.
+
+## Step 3: Staged Changes
+
+Apply changes in this order:
+1. **Internal implementation** (the core change)
+2. **Direct consumers** (files importing/using the changed entity)
+3. **Indirect consumers** (transitive dependencies)
+4. **Tests** (update to match new structure)
+5. **Documentation/config** (if applicable)
+
+**After each stage, verify the build compiles.**
+
+## Step 4: Verification
+
+Run the full verification suite:
+1. Build: `cargo build` / `npm run build` / equivalent
+2. Type check: `cargo check` / `tsc --noEmit` / equivalent
+3. Tests: `cargo test` / `npm test` / equivalent
+4. Lint: `cargo clippy` / `eslint` / equivalent
+
+Follow the verification workflow described in the `oco-verify-fix` skill (build, test, lint, typecheck in order).
+
+## Step 5: Review
+
+Delegate reviews to the appropriate subagents:
+- `@refactor-reviewer` — check for stale references, breaking changes, and hidden impact
+- `@patch-verifier` — semantic review of the change for correctness and completeness
+
+## Rules
+
+- Never rename/move without searching for all usages first
+- Never skip the impact analysis step
+- If >10 files change, produce a summary for user review before committing
+- Preserve all existing test coverage
+- Keep each logical change as a separate commit if practical