opencode-block 1.1.14 → 1.2.1

package/README.md

@@ -0,0 +1,291 @@
+# Block
+
+**Protect files from unwanted AI modifications in [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenCode](https://opencode.ai).**
+
+Drop a `.block` file in any directory to control what AI agents can and cannot edit. Protect configs, lock files, migrations, or entire directories with simple pattern rules.
+
+## Why use this?
+
+- **Prevent accidents** — Stop Claude from touching lock files, CI workflows, or database migrations
+- **Scope to features** — Keep Claude focused on relevant directories, not unrelated code
+- **Guide Claude** — Custom messages explain why files are protected and what to do instead
+- **Zero friction** — Once set up, protection works automatically on every session
+
+## Requirements
+
+- **Python 3.8+** — Required for the protection hook
+
+## Installation
+
+### Claude Code
+
+1. Register the marketplace:
+
+```
+/plugin marketplace add kodroi/block-marketplace
+```
+
+2. Install the plugin:
+
+```
+/plugin install block@block-marketplace
+```
+
+### OpenCode
+
+Add the plugin to your `opencode.json` config:
+
+```json
+{
+  "plugins": ["opencode-block"]
+}
+```
+
+Or for local development, clone this repo and reference the plugin directly:
+
+```json
+{
+  "plugins": ["file:///path/to/block/opencode/index.ts"]
+}
+```
+
+You can also set up the plugin manually by copying files into your project. The plugin expects `hooks/protect_directories.py` to be a sibling of the directory containing `index.ts`:
+
+```
+your-project/
+├── .opencode/
+│   └── plugin/
+│       └── index.ts              # copied from opencode/index.ts
+├── hooks/
+│   └── protect_directories.py    # copied from hooks/protect_directories.py
+```
+
+> **Note:** The `tool.execute.before` hook protects tools called by the primary agent. Tools invoked by subagents spawned via the `task` tool may not be intercepted.
+
+## Usage
+
+Use the `/block:create` command to interactively create a `.block` file:
+
+```
+/block:create
+```
+
+Or create a `.block` file manually in any directory you want to protect.
+
+## .block Format
+
+The `.block` file uses JSON format with three modes:
+
+### Block All (Default)
+
+Empty file or `{}` blocks all modifications:
+
+```json
+{}
+```
+
+### Allowed List
+
+Only allow specific patterns, block everything else:
+
+```json
+{
+  "allowed": ["*.test.ts", "tests/**/*", "docs/*.md"]
+}
+```
+
+### Blocked List
+
+Block specific patterns, allow everything else:
+
+```json
+{
+  "blocked": ["*.lock", "package-lock.json", "migrations/**/*", ".github/**/*"]
+}
+```
+
+### Guide Messages
+
+Add a message shown when Claude tries to modify protected files:
+
+```json
+{
+  "blocked": ["migrations/**/*"],
+  "guide": "Database migrations are protected. Ask before modifying."
+}
+```
+
+### Pattern-Specific Guides
+
+Different messages for different patterns:
+
+```json
+{
+  "blocked": [
+    { "pattern": "*.lock", "guide": "Lock files are auto-generated. Run the package manager instead." },
+    { "pattern": ".github/**/*", "guide": "CI workflows need manual review." }
+  ],
+  "guide": "This directory has protected files."
+}
+```
+
+### Scope to Feature
+
+Keep Claude focused on specific directories during feature work:
+
+```json
+{
+  "allowed": ["src/features/auth/**/*", "src/components/auth/**/*", "tests/auth/**/*"],
+  "guide": "Working on auth feature. Only touching auth-related files."
+}
+```
+
+### Agent-Specific Rules (Claude Code only)
+
+Scope protection to specific subagent types. For example, block a code-review agent from modifying source files:
+
+```text
+src/
+└── .block      → {"agents": ["code-reviewer"]}
+```
+
+This blocks the `code-reviewer` subagent from writing to `src/`. Other subagents and the main agent are unaffected — the `.block` file is skipped for them.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `agents` | `string[]` | Subagent types this `.block` file applies to (others are skipped). Main agent is always skipped. |
+| `disable_main_agent` | `bool` | When `true`, the main agent is skipped (for use without `agents`) |
+
+**Truth table:**
+
+*"Skipped" means this `.block` file is skipped — other `.block` files may still block.*
+
+| Config | Main agent | Listed subagents | Other subagents |
+|--------|-----------|-----------------|-----------------|
+| No agent keys | Blocked | Blocked | Blocked |
+| `agents: ["TestCreator"]` | Skipped | Blocked | Skipped |
+| `disable_main_agent: true` | Skipped | Blocked | Blocked |
+| Both keys set | Skipped | Blocked | Skipped |
+| `agents: []` | Skipped | Skipped | Skipped |
+
+
+## Pattern Syntax
+
+| Pattern | Description |
+|---------|-------------|
+| `*` | Matches any characters except path separator |
+| `**` | Matches any characters including path separator (recursive) |
+| `?` | Matches single character |
+
+### Examples
+
+| Pattern | Matches |
+|---------|---------|
+| `*.ts` | All TypeScript files in the directory |
+| `**/*.ts` | All TypeScript files recursively |
+| `src/**/*` | Everything under src/ |
+| `*.test.*` | Files with .test. in the name |
+| `config?.json` | config1.json, configA.json, etc. |
+
+## Local Configuration Files
+
+For personal or machine-specific protection rules that shouldn't be committed to git, use `.block.local`:
+
+```json
+{
+  "blocked": [".env.local", ".env.*.local", "appsettings.Development.json"]
+}
+```
+
+Add `.block.local` to your `.gitignore`.
+
+When both files exist in the same directory:
+- Blocked patterns are combined (union)
+- Allowed patterns and guide messages use local file
+- Cannot mix `allowed` and `blocked` modes between files
+
+## How It Works
+
+The plugin hooks into file operations from Claude Code and OpenCode. When the AI agent tries to modify a file, the plugin checks for `.block` files in the target directory and all parent directories, then combines their rules.
+
+- **Claude Code**: Uses a PreToolUse hook to intercept Edit, Write, NotebookEdit, and Bash tools
+- **OpenCode**: Uses a `tool.execute.before` hook to intercept edit, write, bash, and patch tools
+
+- `.block` files themselves are always protected
+- Protection cascades to all subdirectories
+
+### Hierarchical Inheritance
+
+When multiple `.block` files exist in the directory hierarchy:
+
+**Blocked patterns are combined (union)**:
+```
+project/
+├── .block          → {"blocked": ["*.log", "*.tmp"]}
+└── src/
+    └── .block      → {"blocked": ["generated/**"]}
+```
+Files in `src/` are blocked if they match ANY pattern from either file (`*.log`, `*.tmp`, OR `generated/**`).
+
+**Allowed patterns override completely**:
+```
+project/
+├── .block          → {"blocked": ["*.lock"]}
+└── features/
+    └── .block      → {"allowed": ["*.ts"]}
+```
+The `allowed` in `features/` completely overrides the parent — only `*.ts` files can be modified.
+
+**Guide messages from the closest file take precedence**:
+When files are blocked by an inherited pattern, the guide message from the closest `.block` file is shown.
+
+## Development
+
+### Running Tests
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ -v --cov=hooks --cov-report=term-missing
+```
+
+### Project Structure
+
+```
+block/
+├── hooks/
+│   ├── protect_directories.py   # Main protection logic (Python)
+│   ├── subagent_tracker.py      # Subagent event tracker (Claude Code)
+│   ├── run-hook.cmd             # Cross-platform entry point (Claude Code)
+│   └── run-subagent-hook.cmd    # Subagent hook entry point (Claude Code)
+├── opencode/
+│   ├── index.ts                 # OpenCode plugin entry point
+│   └── package.json             # npm package metadata
+├── tests/
+│   ├── conftest.py              # Shared fixtures
+│   ├── test_basic_protection.py
+│   ├── test_allowed_patterns.py
+│   ├── test_blocked_patterns.py
+│   ├── test_guide_messages.py
+│   ├── test_local_config.py
+│   ├── test_invalid_config.py
+│   ├── test_marker_file_protection.py
+│   ├── test_tool_types.py
+│   ├── test_bash_commands.py
+│   ├── test_wildcards.py
+│   └── test_edge_cases.py
+├── commands/
+│   └── create.md                # Interactive command (Claude Code)
+├── .claude-plugin/
+│   └── plugin.json              # Plugin metadata (Claude Code)
+└── pyproject.toml               # Python project config
+```
+
+## License
+
+MIT

package/index.ts

@@ -1,134 +1,134 @@
-/**
- * Block plugin for OpenCode
- *
- * Provides file and directory protection using .block configuration files.
- * Intercepts file modification tools (edit, write, bash, patch) and blocks
- * them based on protection rules defined in .block files.
- *
- * This is the OpenCode equivalent of the Claude Code PreToolUse hook.
- */
-import type { Plugin } from "@opencode-ai/plugin";
-import { resolve } from "path";
-
-/** Tools that modify files and should be checked against .block rules. */
-const PROTECTED_TOOLS = new Set(["edit", "write", "bash", "patch"]);
-
-/**
- * Maps OpenCode tool names to the names expected by protect_directories.py.
- * The Python script was originally written for Claude Code's tool naming.
- */
-const TOOL_NAME_MAP: Record<string, string> = {
-  edit: "Edit",
-  write: "Write",
-  bash: "Bash",
-  patch: "Write",
-};
-
-/**
- * Build the JSON input that protect_directories.py expects on stdin.
- *
- * Claude Code hook input format:
- *   { "tool_name": "Edit", "tool_input": { "file_path": "..." } }
- *   { "tool_name": "Bash", "tool_input": { "command": "..." } }
- *
- * OpenCode uses camelCase args: filePath for edit/write/patch, command for bash.
- */
-function buildHookInput(
-  tool: string,
-  args: Record<string, unknown>,
-): string | null {
-  const toolName = TOOL_NAME_MAP[tool];
-  if (!toolName) return null;
-
-  const toolInput: Record<string, unknown> = {};
-
-  if (tool === "bash") {
-    if (!args.command) return null;
-    toolInput.command = args.command;
-  } else {
-    // edit, write, patch — OpenCode provides the path as "filePath"
-    if (!args.filePath) return null;
-    toolInput.file_path = args.filePath;
-  }
-
-  return JSON.stringify({ tool_name: toolName, tool_input: toolInput });
-}
-
-/**
- * Locate protect_directories.py relative to this plugin file.
- *
- * NOTE: import.meta.dir is a Bun-specific API. OpenCode runs plugins via Bun,
- * so this is safe. Packages installed via npm are cached under
- * ~/.cache/opencode/node_modules/.
- *
- * When installed via npm the layout is:
- *   node_modules/opencode-block/protect_directories.py  (copied by prepack)
- *   node_modules/opencode-block/index.ts
- *
- * When used from the repo directly:
- *   opencode/index.ts
- *   hooks/protect_directories.py
- */
-function findScript(): string {
-  const pluginDir = import.meta.dir;
-  // npm-installed: protect_directories.py is copied alongside index.ts
-  const colocated = resolve(pluginDir, "protect_directories.py");
-  try {
-    const fs = require("fs");
-    if (fs.existsSync(colocated)) return colocated;
-  } catch {
-    // Fall through to repo layout
-  }
-  // Repo layout: ../hooks/protect_directories.py
-  return resolve(pluginDir, "..", "hooks", "protect_directories.py");
-}
-
-export const BlockPlugin: Plugin = async ({ $ }) => {
-  const scriptPath = findScript();
-
-  return {
-    "tool.execute.before": async (input, output) => {
-      if (!PROTECTED_TOOLS.has(input.tool)) return;
-
-      const hookInput = buildHookInput(
-        input.tool,
-        output.args as Record<string, unknown>,
-      );
-      if (!hookInput) return;
-
-      try {
-        const result =
-          await $`echo ${hookInput} | python3 ${scriptPath}`.quiet();
-        const stdout = result.stdout.toString().trim();
-        if (!stdout) return;
-
-        const decision = JSON.parse(stdout);
-        if (decision.decision === "block") {
-          throw new Error(decision.reason);
-        }
-      } catch (err: unknown) {
-        if (err instanceof SyntaxError) {
-          // Python output wasn't JSON — not a block, ignore
-          return;
-        }
-        // Block errors from our own throw above — re-throw
-        if (err instanceof Error && err.message) {
-          const msg = err.message;
-          // Infrastructure failures (python3 not found, spawn errors) should
-          // not prevent the operation — log a warning and let it proceed.
-          if (
-            (err as NodeJS.ErrnoException).code === "ENOENT" ||
-            msg.includes("not found") ||
-            msg.includes("No such file") ||
-            msg.includes("python3")
-          ) {
-            console.warn(`[block] Protection check skipped: ${msg}`);
-            return;
-          }
-        }
-        // Re-throw actual block errors and other unexpected failures
-        throw err;
-      }
-    },
-  };
-};
+/**
+ * Block plugin for OpenCode
+ *
+ * Provides file and directory protection using .block configuration files.
+ * Intercepts file modification tools (edit, write, bash, patch) and blocks
+ * them based on protection rules defined in .block files.
+ *
+ * This is the OpenCode equivalent of the Claude Code PreToolUse hook.
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+import { resolve } from "path";
+
+/** Tools that modify files and should be checked against .block rules. */
+const PROTECTED_TOOLS = new Set(["edit", "write", "bash", "patch"]);
+
+/**
+ * Maps OpenCode tool names to the names expected by protect_directories.py.
+ * The Python script was originally written for Claude Code's tool naming.
+ */
+const TOOL_NAME_MAP: Record<string, string> = {
+  edit: "Edit",
+  write: "Write",
+  bash: "Bash",
+  patch: "Write",
+};
+
+/**
+ * Build the JSON input that protect_directories.py expects on stdin.
+ *
+ * Claude Code hook input format:
+ *   { "tool_name": "Edit", "tool_input": { "file_path": "..." } }
+ *   { "tool_name": "Bash", "tool_input": { "command": "..." } }
+ *
+ * OpenCode uses camelCase args: filePath for edit/write/patch, command for bash.
+ */
+function buildHookInput(
+  tool: string,
+  args: Record<string, unknown>,
+): string | null {
+  const toolName = TOOL_NAME_MAP[tool];
+  if (!toolName) return null;
+
+  const toolInput: Record<string, unknown> = {};
+
+  if (tool === "bash") {
+    if (!args.command) return null;
+    toolInput.command = args.command;
+  } else {
+    // edit, write, patch — OpenCode provides the path as "filePath"
+    if (!args.filePath) return null;
+    toolInput.file_path = args.filePath;
+  }
+
+  return JSON.stringify({ tool_name: toolName, tool_input: toolInput });
+}
+
+/**
+ * Locate protect_directories.py relative to this plugin file.
+ *
+ * NOTE: import.meta.dir is a Bun-specific API. OpenCode runs plugins via Bun,
+ * so this is safe. Packages installed via npm are cached under
+ * ~/.cache/opencode/node_modules/.
+ *
+ * When installed via npm the layout is:
+ *   node_modules/opencode-block/protect_directories.py  (copied by prepack)
+ *   node_modules/opencode-block/index.ts
+ *
+ * When used from the repo directly:
+ *   opencode/index.ts
+ *   hooks/protect_directories.py
+ */
+function findScript(): string {
+  const pluginDir = import.meta.dir;
+  // npm-installed: protect_directories.py is copied alongside index.ts
+  const colocated = resolve(pluginDir, "protect_directories.py");
+  try {
+    const fs = require("fs");
+    if (fs.existsSync(colocated)) return colocated;
+  } catch {
+    // Fall through to repo layout
+  }
+  // Repo layout: ../hooks/protect_directories.py
+  return resolve(pluginDir, "..", "hooks", "protect_directories.py");
+}
+
+export const BlockPlugin: Plugin = async ({ $ }) => {
+  const scriptPath = findScript();
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (!PROTECTED_TOOLS.has(input.tool)) return;
+
+      const hookInput = buildHookInput(
+        input.tool,
+        output.args as Record<string, unknown>,
+      );
+      if (!hookInput) return;
+
+      try {
+        const result =
+          await $`echo ${hookInput} | python3 ${scriptPath}`.quiet();
+        const stdout = result.stdout.toString().trim();
+        if (!stdout) return;
+
+        const decision = JSON.parse(stdout);
+        if (decision.decision === "block") {
+          throw new Error(decision.reason);
+        }
+      } catch (err: unknown) {
+        if (err instanceof SyntaxError) {
+          // Python output wasn't JSON — not a block, ignore
+          return;
+        }
+        // Block errors from our own throw above — re-throw
+        if (err instanceof Error && err.message) {
+          const msg = err.message;
+          // Infrastructure failures (python3 not found, spawn errors) should
+          // not prevent the operation — log a warning and let it proceed.
+          if (
+            (err as NodeJS.ErrnoException).code === "ENOENT" ||
+            msg.includes("not found") ||
+            msg.includes("No such file") ||
+            msg.includes("python3")
+          ) {
+            console.warn(`[block] Protection check skipped: ${msg}`);
+            return;
+          }
+        }
+        // Re-throw actual block errors and other unexpected failures
+        throw err;
+      }
+    },
+  };
+};

package/package.json

@@ -1,28 +1,28 @@
-{
-  "name": "opencode-block",
-  "version": "1.1.14",
-  "description": "File and directory protection for OpenCode using .block marker files with pattern matching",
-  "main": "index.ts",
-  "scripts": {
-    "prepack": "node -e \"require('fs').copyFileSync('../hooks/protect_directories.py','protect_directories.py')\"",
-    "postpack": "node -e \"try{require('fs').unlinkSync('protect_directories.py')}catch(e){}\""
-  },
-  "keywords": [
-    "opencode",
-    "opencode-plugin",
-    "protection",
-    "security",
-    "file-blocking",
-    "directory-lock"
-  ],
-  "author": "Iiro Rahkonen",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kodroi/block"
-  },
-  "files": [
-    "index.ts",
-    "protect_directories.py"
-  ]
-}
+{
+  "name": "opencode-block",
+  "version": "1.2.1",
+  "description": "File and directory protection for OpenCode using .block marker files with pattern matching",
+  "main": "index.ts",
+  "scripts": {
+    "prepack": "node -e \"const fs=require('fs');fs.copyFileSync('../hooks/protect_directories.py','protect_directories.py');fs.copyFileSync('../README.md','README.md')\"",
+    "postpack": "node -e \"const fs=require('fs');['protect_directories.py','README.md'].forEach(f=>{try{fs.unlinkSync(f)}catch(e){}})\""
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "protection",
+    "security",
+    "file-blocking",
+    "directory-lock"
+  ],
+  "author": "Iiro Rahkonen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kodroi/block"
+  },
+  "files": [
+    "index.ts",
+    "protect_directories.py"
+  ]
+}