opencode-branch-guard 0.1.0 → 0.2.0

package/README.md

@@ -5,10 +5,11 @@
 [![Test](https://img.shields.io/github/actions/workflow/status/hugobatista/opencode-branch-guard/test.yml?label=Test)](https://go.hugobatista.com/gh/opencode-branch-guard/actions/workflows/test.yml)
 [![npm](https://img.shields.io/npm/v/opencode-branch-guard.svg)](https://www.npmjs.com/package/opencode-branch-guard)
 
-OpenCode plugin. Blocks git mutations (`commit`, `push`, `merge`, `rebase`,
-`reset`, …) based on the current branch or repository, so protected branches stay
-clean. Deny a whole branch, allow a different policy per repository, and keep
-read-only commands untouched.
+OpenCode plugin. Controls git mutations (`commit`, `push`, `merge`, `rebase`,
+`reset`, …) based on the current branch or repository, so protected branches
+stay clean. Allow an operation, ask the user for approval, or deny it. Deny a
+whole branch, allow a different policy per repository, and keep read-only
+commands untouched.
 
 > **Requires OpenCode V2.** OpenCode V2 changed the plugin API; V1 plugin
 > implementations do not run in V2. This plugin is built against
@@ -17,14 +18,16 @@ read-only commands untouched.
 ## What it does
 
 - Intercepts the `shell` permission via `ctx.permission.hook("evaluate")` and
-  returns `effect: "deny"` when a git mutation violates the resolved policy.
+  returns `effect: "allow" | "ask" | "deny"` when a git mutation matches the
+  resolved policy.
 - Resolves the branch with `git -C <directory> branch --show-current`; the
   directory comes from the session (`ctx.session.get().location.directory`), not
   the plugin instance.
 - Resolves the policy hierarchically: `repos[<directory>]` overrides
   `branches[<branch>]`, which overrides `default`.
 - Applies the same decision to every resource of a compound command, so
-  `cd /tmp && git commit` is caught.
+  `cd /tmp && git commit` is caught. Precedence across resources is
+  `deny > ask > allow`.
 - Passes read-only commands (`status`, `log`, `diff`, `fetch`, …) and anything
   that is not a known git mutation.
 - Fails closed: with no options, every git mutation is denied.
@@ -52,7 +55,7 @@ Or add the package to `opencode.jsonc` (project or
 ```
 
 With no options the plugin is **fail-closed**: it denies every git mutation.
-Pass [options](#configuration) to allow the operations you want.
+Pass [options](#configuration) to allow or ask for the operations you want.
 
 > This is a **server** plugin. Configure it in `opencode.json(c)`. The
 > `cli.json` file is for terminal (TUI) plugins only.
@@ -78,11 +81,31 @@ Pass [options](#configuration) to allow the operations you want.
    }
    ```
 
+   To pass [options](#configuration) with a local path, use the object form and
+   set `package` to the path:
+
+   ```jsonc
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugins": [
+       {
+         "package": "/home/your-user/code/projects/opencode-branch-guard/src",
+         "options": {
+           "default": { "allow": ["commit", "push"] },
+           "branches": {
+             "main": { "allow": [], "ask": ["commit"] }
+           }
+         }
+       }
+     ]
+   }
+   ```
+
 3. Restart OpenCode.
 
 ## Configuration
 
-Pass options with the object form:
+Pass options with the object form. The plugin is configured under `options`:
 
 ```jsonc
 {
@@ -93,6 +116,7 @@ Pass options with the object form:
       "options": {
         "default": {
           "allow": ["add", "branch", "checkout", "commit", "push", "fetch", "merge", "pull", "rebase", "reset", "restore", "stash", "switch", "tag"],
+          "ask": [],
           "deny": []
         },
         "branches": {
@@ -105,72 +129,274 @@ Pass options with the object form:
 }
 ```
 
+### Policy shape
+
+A policy is `{ "allow": string[], "ask": string[], "deny": string[] }`. Every
+field is optional and holds a list of git operations.
+
+| Effect | Result |
+|---|---|
+| `allow` | The operation runs without prompting. |
+| `ask` | The client asks the user to approve the operation. |
+| `deny` | The operation is blocked. The message explains why. |
+
+An operation missing from every list is denied. This keeps the plugin
+fail-closed.
+
 ### Options
 
 | Option | Default | Description |
 |---|---|---|
-| `default` | none (fail-closed) | Baseline policy applied when no more specific rule matches. `allow` lists the permitted git operations; `deny` lists blocked ones. With no `default.allow`, every mutation is blocked. |
-| `branches` | none | Policy keyed by exact branch name, resolved at command time from the VCS. A matching entry replaces the baseline `allow` and unions its `deny` with the baseline. |
+| `default` | none (fail-closed) | Baseline policy applied when no more specific rule matches. Any mutation missing from the resolved `allow` and `ask` is denied. |
+| `branches` | none | Policy keyed by exact branch name, resolved at command time from the VCS. |
 | `repos` | none | Policy keyed by absolute location directory. Takes precedence over `branches` and `default`. |
 
-A policy is `{ "allow": string[], "deny": string[] }`. Both fields are optional.
+### Effects and precedence
+
+Precedence is **`deny > ask > allow`**:
+
+1. If the operation is in `deny`, it is denied. This wins over every other list.
+2. Otherwise, if it is in `ask`, the client asks the user.
+3. Otherwise, if it is in `allow`, it runs.
+4. Otherwise, it is denied (fail-closed).
+
+An operation listed in both `ask` and `allow` is asked. `deny` always wins.
 
-Recognized git operations: `add`, `branch`, `checkout`, `cherry-pick`, `clean`,
-`commit`, `merge`, `mv`, `push`, `rebase`, `reset`, `restore`, `revert`, `rm`,
-`stash`, `switch`, `tag`.
+When OpenCode checks a compound command, the plugin aggregates every resource
+with the same precedence: one `deny` blocks the command, otherwise one `ask`
+escalates it, otherwise it is allowed.
 
-### Semantics
+### How a policy is resolved
 
-- **Fail-closed.** No config, or an empty resolved `allow`, blocks every git
-  mutation.
-- **Hierarchical.** `default` is the baseline. A `branches.<name>` entry
-  overrides `allow` (replaces the baseline) and `deny` (unions with the
-  baseline). A `repos.<directory>` entry overrides both.
-- **`deny` wins.** An operation is allowed only if it is in the resolved `allow`
-  and not in the resolved `deny`.
-- **Exact branch match.** The branch is resolved at call time with
-  `git branch --show-current`. No globs.
-- **Read-only commands pass.** `status`, `log`, `diff`, `fetch` and anything not
-  in the mutation list are never blocked.
+For a command on branch `B` in directory `D`:
 
-The example above gives `main`/`master` an empty `allow` (no mutations), while
-every other branch inherits the permissive default.
+1. `base` is `default`.
+2. `rule` is `repos[D]` if present, otherwise `branches[B]`, otherwise nothing.
+3. `allow` is `rule.allow`, or `base.allow`, or `[]`.
+4. `ask` is `rule.ask`, or `base.ask`, or `[]`.
+5. `deny` is `base.deny` followed by `rule.deny`.
 
-### Per-repository override
+`allow` and `ask` **replace** the baseline. `deny` **unions** with the baseline.
+This means a specific rule that omits `ask` inherits the baseline `ask`, and a
+rule that sets `ask` replaces it.
+
+Because `deny` only unions with the baseline, a `repos` rule does not inherit
+the `deny` of the matching `branches` rule. Repeat the operation in the `repos`
+rule if you need it there.
+
+### Recognized git operations
+
+`add`, `branch`, `checkout`, `cherry-pick`, `clean`, `commit`, `merge`, `mv`,
+`push`, `rebase`, `reset`, `restore`, `revert`, `rm`, `stash`, `switch`, `tag`.
+
+Anything not in this list is treated as read-only and passes. The branch is
+matched exactly with `git branch --show-current`. There are no globs.
+
+### Examples
+
+Each example shows the `options` object. Wrap it in the `plugins` object form
+shown in [Configuration](#configuration).
+
+#### Common recipes
+
+| Goal | Use |
+|---|---|
+| Allow work on normal branches, ask on protected branches | `default.allow` plus `branches.<name>.ask` |
+| Block every mutation on protected branches | `branches.<name>: { "allow": [] }` |
+| Ask for every mutation | `default: { "ask": [...] }` |
+| Block one operation everywhere | `default: { "deny": ["push"] }` |
+| Different policy for one checkout | `repos: { "/path": { ... } }` |
+
+#### 1. Allow on normal branches, ask on protected branches
+
+```jsonc
+{
+  "default": {
+    "allow": ["add", "checkout", "switch", "commit", "merge", "push", "rebase", "stash"]
+  },
+  "branches": {
+    "main": {
+      "allow": [],
+      "ask": ["add", "checkout", "switch", "commit", "merge", "push", "rebase", "stash"]
+    },
+    "master": {
+      "allow": [],
+      "ask": ["add", "checkout", "switch", "commit", "merge", "push", "rebase", "stash"]
+    }
+  }
+}
+```
+
+| Command | Feature branch | `main` / `master` |
+|---|---|---|
+| `git commit` | `allow` | `ask` |
+| `git push` | `allow` | `ask` |
+| `git switch` | `allow` | `ask` |
+| `git reset` | `deny` | `deny` |
+| `git tag` | `deny` | `deny` |
+| `git status` | `allow` | `allow` |
+
+`allow` and `ask` replace the baseline. On `main`, `allow` is empty and `ask`
+lists the operations, so the listed ones ask. Anything else is denied.
+
+#### 2. Block every mutation on protected branches
+
+```jsonc
+{
+  "default": { "allow": ["commit", "push"] },
+  "branches": {
+    "main": { "allow": [] },
+    "master": { "allow": [] }
+  }
+}
+```
+
+| Command | Feature branch | `main` / `master` |
+|---|---|---|
+| `git commit` | `allow` | `deny` |
+| `git push` | `allow` | `deny` |
+| `git status` | `allow` | `allow` |
+
+An empty `allow` with no `ask` denies every mutation.
+
+#### 3. Ask for every mutation
+
+```jsonc
+{
+  "default": {
+    "ask": ["add", "branch", "checkout", "cherry-pick", "clean", "commit", "merge", "mv", "push", "rebase", "reset", "restore", "revert", "rm", "stash", "switch", "tag"]
+  }
+}
+```
+
+Every mutation asks on every branch. Read-only commands pass. Nothing is blocked,
+so the user decides.
+
+#### 4. Ask on `main`, hard-deny `push`
+
+```jsonc
+{
+  "default": { "allow": ["commit", "push"] },
+  "branches": {
+    "main": {
+      "allow": [],
+      "ask": ["commit"],
+      "deny": ["push"]
+    }
+  }
+}
+```
+
+| Command | Feature branch | `main` |
+|---|---|---|
+| `git commit` | `allow` | `ask` |
+| `git push` | `allow` | `deny` |
+| `git merge` | `deny` | `deny` |
+
+On `main`, `commit` asks, `push` is denied, and `merge` is denied because it is
+missing from every list.
+
+#### 5. Block `push` everywhere
+
+```jsonc
+{
+  "default": {
+    "allow": ["add", "checkout", "switch", "commit", "merge", "rebase", "stash"],
+    "deny": ["push"]
+  }
+}
+```
+
+`deny` wins over `allow`. `push` is blocked on every branch, even though the
+other mutations are allowed.
+
+#### 6. Allow only a small set of operations
+
+```jsonc
+{
+  "default": { "allow": ["commit", "push"] }
+}
+```
+
+Only `commit` and `push` are permitted. Every other mutation is denied on every
+branch. This is the strictest permissive form.
+
+#### 7. Protect a release branch
+
+```jsonc
+{
+  "default": { "allow": ["commit", "push", "merge"] },
+  "branches": {
+    "release": {
+      "allow": [],
+      "ask": ["merge", "tag"],
+      "deny": ["push", "reset", "clean"]
+    }
+  }
+}
+```
+
+On the branch named exactly `release`: `merge` and `tag` ask, `push`, `reset`,
+and `clean` are denied, and everything else is denied. Branch names match
+exactly. There are no globs.
+
+#### 8. Per-repository override
 
 Allow work in a single checkout even on a protected branch by keying it on the
 location directory:
 
 ```jsonc
 {
-  "plugins": [
-    {
-      "package": "opencode-branch-guard",
-      "options": {
-        "default": { "allow": ["commit", "push"] },
-        "branches": { "main": { "allow": [] } },
-        "repos": {
-          "/home/you/code/projects/scratch": {
-            "allow": ["add", "commit", "push", "reset", "stash", "switch"]
-          }
-        }
-      }
+  "default": { "allow": ["commit", "push"] },
+  "branches": {
+    "main": { "allow": [], "ask": ["commit"], "deny": ["push"] }
+  },
+  "repos": {
+    "/home/you/code/projects/scratch": {
+      "allow": ["add", "commit", "push", "reset", "stash", "switch"]
     }
-  ]
+  }
+}
+```
+
+In `/home/you/code/projects/scratch` the repo rule replaces the branch `allow`
+and `ask`, so `commit` runs without prompting. The repo rule omits `deny`, so it
+inherits only `default.deny` (empty here), not the branch `deny`.
+
+#### 9. Compound commands
+
+```jsonc
+{
+  "default": { "allow": ["add", "commit"], "deny": ["push"] }
 }
 ```
 
-### Blocklist instead of allowlist
+| Command | Result |
+|---|---|
+| `git add . && git commit -m x` | `allow` (both allowed) |
+| `git add . && git push` | `deny` (one resource denied) |
+| `git add . && git reset` | `deny` (one resource not allowed) |
+
+The plugin applies the policy to every resource of the command. Precedence is
+`deny > ask > allow`.
 
-Use `deny` when you want a permissive baseline with a few hard blocks:
+#### 10. Effect precedence
 
 ```jsonc
 {
-  "default": { "allow": ["commit", "push", "add", "checkout", "merge"], "deny": ["push"] }
+  "default": { "allow": ["commit"], "ask": ["commit"], "deny": [] }
 }
 ```
 
-`deny` wins over `allow`, so `push` is blocked even though it is listed.
+`commit` is in both `allow` and `ask`, so it asks. `ask` wins over `allow`.
+
+```jsonc
+{
+  "default": { "allow": ["commit"], "ask": ["commit"], "deny": ["commit"] }
+}
+```
+
+Adding `commit` to `deny` blocks it. `deny` wins over everything.
 
 ## Limitations
 
@@ -183,20 +409,40 @@ The plugin inspects the shell command string, so it can be bypassed by:
 - Compound commands the scanner cannot split.
 
 Also note that `branch` is treated as a mutation, so `git branch` and
-`git branch --show-current` are blocked on a protected branch. Use
+`git branch --show-current` are blocked or asked on a protected branch. Use
 `git rev-parse --abbrev-ref HEAD` if you need a read-only branch check there.
 
+### About `ask`
+
+The `ask` effect sends the operation to the OpenCode permission prompt. It has
+these limits:
+
+- **An explicit `deny` in your own `permissions` config is final.** The plugin
+  hook runs only for `allow` and `ask` decisions, so a `deny` rule in
+  `opencode.json(c)` blocks the command before the plugin sees it.
+- **Non-interactive clients decide how to handle `ask`.** A run without a user
+  (for example CI) may reject or stall. Keep `deny` for those environments.
+- **"Allow always" may not stick.** Approving always saves a durable `allow`
+  rule, but the plugin hook still runs and can escalate the command to `ask`
+  again. Use `allow` in the plugin options for a permanent decision.
+- **The plugin never downgrades.** If the core resolved an `ask` from your
+  config, the plugin does not turn it into `allow`.
+
 It is a guardrail against accidental mutations, not a security boundary.
 
 ## Verify
 
 After configuring, restart OpenCode and try:
 
-1. On `main`: ask the agent to run `git commit` — the command is denied with
-   `Blocked: git commit is not allowed by config`.
-2. On a feature branch: the same command is allowed.
-3. `git status` and `git log` are always allowed.
-4. On a directory listed in `repos`, the repository policy applies.
+1. On `main` with `{ "allow": [] }`: ask the agent to run `git commit` — the
+   command is denied with `Blocked: git commit is not allowed by config`.
+2. On `main` with `{ "allow": [], "ask": ["commit"] }`: the same command opens a
+   permission prompt.
+3. On a feature branch: the same command is allowed.
+4. `git status` and `git log` are always allowed.
+5. On a directory listed in `repos`, the repository policy applies.
+6. With `{ "allow": [], "ask": ["commit"], "deny": ["push"] }` on `main`:
+   `git push` is denied, and `git commit` asks.
 
 ## Uninstall
 
@@ -216,8 +462,8 @@ bun test            # unit (core logic) + functional (mocked plugin context)
 bun run build       # dist/index.js + dist/index.d.ts (npm entrypoint)
 ```
 
-- `src/core.ts` — pure logic: git operation parsing and policy resolution. No
-  OpenCode imports. Fully unit-tested.
+- `src/core.ts` — pure logic: git operation parsing, policy resolution, and the
+  `allow`/`ask`/`deny` decision. No OpenCode imports. Fully unit-tested.
 - `src/index.ts` — the plugin (`id: "branch-guard"`), a
   `Plugin.define({ id, setup })` from `@opencode/plugin`. It registers a
   `ctx.permission.hook("evaluate")`, resolves the session directory, and reads

package/dist/core.d.ts

@@ -2,6 +2,7 @@ export declare const OPS: readonly ["add", "branch", "checkout", "cherry-pick",
 export type GitOp = (typeof OPS)[number];
 export type BranchPolicy = {
     allow?: string[];
+    ask?: string[];
     deny?: string[];
 };
 export type Config = {
@@ -11,10 +12,12 @@ export type Config = {
 };
 export type ResolvedPolicy = {
     allow: string[];
+    ask: string[];
     deny: string[];
 };
+export type Effect = "allow" | "ask" | "deny";
 export type Decision = {
-    allowed: boolean;
+    effect: Effect;
     message?: string;
 };
 export declare function isGitOp(value: string): value is GitOp;

package/dist/index.js

@@ -65,17 +65,21 @@ function resolvePolicy(config, branch, directory) {
   const repoRule = directory !== undefined ? config.repos?.[directory] : undefined;
   const rule = repoRule ?? branchRule;
   const allow = rule?.allow ?? base.allow ?? [];
+  const ask = rule?.ask ?? base.ask ?? [];
   const deny = [...base.deny ?? [], ...rule?.deny ?? []];
-  return { allow, deny };
+  return { allow, ask, deny };
 }
 function decide(op, policy) {
   if (policy.deny.includes(op)) {
-    return { allowed: false, message: `Blocked: git ${op} is denied by config` };
+    return { effect: "deny", message: `Blocked: git ${op} is denied by config` };
   }
-  if (!policy.allow.includes(op)) {
-    return { allowed: false, message: `Blocked: git ${op} is not allowed by config` };
+  if (policy.ask.includes(op)) {
+    return { effect: "ask", message: `git ${op} requires approval by config` };
   }
-  return { allowed: true };
+  if (policy.allow.includes(op)) {
+    return { effect: "allow" };
+  }
+  return { effect: "deny", message: `Blocked: git ${op} is not allowed by config` };
 }
 
 // src/index.ts
@@ -116,17 +120,27 @@ var src_default = Plugin.define({
       }
       const branch = config.branches ? await currentBranch(directory ?? ctx.location.directory) : undefined;
       const policy = resolvePolicy(config, branch, directory);
+      let effect = "allow";
+      let message;
       for (const resource of event.resources) {
         const op = gitOp(resource);
         if (op === null)
           continue;
         const decision = decide(op, policy);
-        if (!decision.allowed) {
-          event.effect = "deny";
-          event.message = decision.message;
-          return;
+        if (decision.effect === "deny") {
+          effect = "deny";
+          message = decision.message;
+          break;
+        }
+        if (decision.effect === "ask") {
+          effect = "ask";
+          message ??= decision.message;
         }
       }
+      if (effect !== "allow") {
+        event.effect = effect;
+        event.message = message;
+      }
     });
   }
 });
@@ -134,4 +148,4 @@ export {
   src_default as default
 };
 
-//# debugId=4EB1771F16AB9A6E64756E2164756E21
+//# debugId=8C2497AAA571E94264756E2164756E21

package/dist/index.js.map

@@ -2,10 +2,10 @@
   "version": 3,
   "sources": ["../src/index.ts", "../src/core.ts"],
   "sourcesContent": [
-    "import { execFile } from \"node:child_process\"\nimport { promisify } from \"node:util\"\nimport { Plugin } from \"@opencode/plugin\"\nimport { decide, gitOp, resolvePolicy, type Config } from \"./core\"\n\nconst execFileAsync = promisify(execFile)\n\n// `ctx.vcs.get()` can return a stale or empty branch, so read it from git\n// directly. Returns undefined outside a repository.\nasync function currentBranch(directory: string): Promise<string | undefined> {\n  try {\n    const { stdout } = await execFileAsync(\n      \"git\",\n      [\"-C\", directory, \"branch\", \"--show-current\"],\n      { timeout: 3000, windowsHide: true },\n    )\n    const branch = stdout.trim()\n    return branch.length > 0 ? branch : undefined\n  } catch {\n    return undefined\n  }\n}\n\n// The plugin context's location is not necessarily the session's repository, and\n// the permission event does not carry a directory. Resolve it from the session.\nasync function sessionDirectory(ctx: Plugin.Context, sessionID: string): Promise<string | undefined> {\n  try {\n    return (await ctx.session.get({ sessionID })).location.directory\n  } catch {\n    return undefined\n  }\n}\n\nexport default Plugin.define({\n  id: \"branch-guard\",\n  async setup(ctx) {\n    const config = (ctx.options ?? {}) as Config\n    const directories = new Map<string, string | null>()\n\n    await ctx.permission.hook(\"evaluate\", async (event) => {\n      // V2 names the shell action \"shell\"; ignore every other action.\n      if (event.action !== \"shell\") return\n\n      let directory: string | undefined\n      if (config.branches || config.repos) {\n        const cached = directories.get(event.sessionID)\n        if (cached !== undefined) {\n          directory = cached ?? undefined\n        } else {\n          directory = await sessionDirectory(ctx, event.sessionID)\n          directories.set(event.sessionID, directory ?? null)\n        }\n      }\n\n      const branch = config.branches\n        ? await currentBranch(directory ?? ctx.location.directory)\n        : undefined\n      const policy = resolvePolicy(config, branch, directory)\n\n      for (const resource of event.resources) {\n        const op = gitOp(resource)\n        if (op === null) continue\n        const decision = decide(op, policy)\n        if (!decision.allowed) {\n          event.effect = \"deny\"\n          event.message = decision.message\n          return\n        }\n      }\n    })\n  },\n})\n",
-    "// Pure branch-guard logic. No OpenCode imports, so it is fully unit-testable.\n\nexport const OPS = [\n  \"add\",\n  \"branch\",\n  \"checkout\",\n  \"cherry-pick\",\n  \"clean\",\n  \"commit\",\n  \"merge\",\n  \"mv\",\n  \"push\",\n  \"rebase\",\n  \"reset\",\n  \"restore\",\n  \"revert\",\n  \"rm\",\n  \"stash\",\n  \"switch\",\n  \"tag\",\n] as const\n\nexport type GitOp = (typeof OPS)[number]\n\n// Git global flags that consume the following token as their value.\nconst FLAG_WITH_VALUE = new Set([\n  \"-C\",\n  \"-c\",\n  \"--git-dir\",\n  \"--work-tree\",\n  \"--exec-path\",\n  \"--namespace\",\n  \"--separate-git-dir\",\n  \"--config-env\",\n])\n\nexport type BranchPolicy = {\n  allow?: string[]\n  deny?: string[]\n}\n\nexport type Config = {\n  default?: BranchPolicy\n  branches?: Record<string, BranchPolicy>\n  repos?: Record<string, BranchPolicy>\n}\n\nexport type ResolvedPolicy = {\n  allow: string[]\n  deny: string[]\n}\n\nexport type Decision = {\n  allowed: boolean\n  message?: string\n}\n\nexport function isGitOp(value: string): value is GitOp {\n  return (OPS as readonly string[]).includes(value)\n}\n\n// Extract the git mutation from a shell command string. Returns null for\n// non-git commands, git invocations without a known mutation, and read-only\n// commands (`status`, `log`, `diff`, ...).\nexport function gitOp(cmd: string): GitOp | null {\n  const tokens = cmd.trim().split(/\\s+/).filter(Boolean)\n  if (tokens[0] !== \"git\") return null\n\n  let i = 1\n  while (i < tokens.length) {\n    const token = tokens[i]\n    if (token === undefined) return null\n    if (!token.startsWith(\"-\")) {\n      return isGitOp(token) ? token : null\n    }\n    if (token.startsWith(\"--\") && token.includes(\"=\")) {\n      i += 1\n    } else if (FLAG_WITH_VALUE.has(token)) {\n      i += 2\n    } else {\n      i += 1\n    }\n  }\n  return null\n}\n\n// Resolve the effective policy for a command. `repos[directory]` overrides\n// `branches[branch]`, which overrides `default`. A rule's `allow` replaces the\n// baseline; its `deny` unions with the baseline. No resolved `allow` means no\n// mutation is permitted (fail-closed).\nexport function resolvePolicy(\n  config: Config,\n  branch: string | undefined,\n  directory: string | undefined,\n): ResolvedPolicy {\n  const base = config.default ?? {}\n  const branchRule = branch !== undefined ? config.branches?.[branch] : undefined\n  const repoRule = directory !== undefined ? config.repos?.[directory] : undefined\n  const rule = repoRule ?? branchRule\n  const allow = rule?.allow ?? base.allow ?? []\n  const deny = [...(base.deny ?? []), ...(rule?.deny ?? [])]\n  return { allow, deny }\n}\n\nexport function decide(op: string, policy: ResolvedPolicy): Decision {\n  if (policy.deny.includes(op)) {\n    return { allowed: false, message: `Blocked: git ${op} is denied by config` }\n  }\n  if (!policy.allow.includes(op)) {\n    return { allowed: false, message: `Blocked: git ${op} is not allowed by config` }\n  }\n  return { allowed: true }\n}\n"
+    "import { execFile } from \"node:child_process\"\nimport { promisify } from \"node:util\"\nimport { Plugin } from \"@opencode/plugin\"\nimport { decide, gitOp, resolvePolicy, type Config, type Effect } from \"./core\"\n\nconst execFileAsync = promisify(execFile)\n\n// `ctx.vcs.get()` can return a stale or empty branch, so read it from git\n// directly. Returns undefined outside a repository.\nasync function currentBranch(directory: string): Promise<string | undefined> {\n  try {\n    const { stdout } = await execFileAsync(\n      \"git\",\n      [\"-C\", directory, \"branch\", \"--show-current\"],\n      { timeout: 3000, windowsHide: true },\n    )\n    const branch = stdout.trim()\n    return branch.length > 0 ? branch : undefined\n  } catch {\n    return undefined\n  }\n}\n\n// The plugin context's location is not necessarily the session's repository, and\n// the permission event does not carry a directory. Resolve it from the session.\nasync function sessionDirectory(ctx: Plugin.Context, sessionID: string): Promise<string | undefined> {\n  try {\n    return (await ctx.session.get({ sessionID })).location.directory\n  } catch {\n    return undefined\n  }\n}\n\nexport default Plugin.define({\n  id: \"branch-guard\",\n  async setup(ctx) {\n    const config = (ctx.options ?? {}) as Config\n    const directories = new Map<string, string | null>()\n\n    await ctx.permission.hook(\"evaluate\", async (event) => {\n      // V2 names the shell action \"shell\"; ignore every other action.\n      if (event.action !== \"shell\") return\n\n      let directory: string | undefined\n      if (config.branches || config.repos) {\n        const cached = directories.get(event.sessionID)\n        if (cached !== undefined) {\n          directory = cached ?? undefined\n        } else {\n          directory = await sessionDirectory(ctx, event.sessionID)\n          directories.set(event.sessionID, directory ?? null)\n        }\n      }\n\n      const branch = config.branches\n        ? await currentBranch(directory ?? ctx.location.directory)\n        : undefined\n      const policy = resolvePolicy(config, branch, directory)\n\n      // Aggregate every resource of a compound command. Precedence is\n      // `deny > ask > allow`: a single denied operation blocks the command,\n      // otherwise a single ask escalates it. Never downgrade an effect the\n      // core already resolved (for example an `ask` from the user's config).\n      let effect: Effect = \"allow\"\n      let message: string | undefined\n      for (const resource of event.resources) {\n        const op = gitOp(resource)\n        if (op === null) continue\n        const decision = decide(op, policy)\n        if (decision.effect === \"deny\") {\n          effect = \"deny\"\n          message = decision.message\n          break\n        }\n        if (decision.effect === \"ask\") {\n          effect = \"ask\"\n          message ??= decision.message\n        }\n      }\n      if (effect !== \"allow\") {\n        event.effect = effect\n        event.message = message\n      }\n    })\n  },\n})\n",
+    "// Pure branch-guard logic. No OpenCode imports, so it is fully unit-testable.\n\nexport const OPS = [\n  \"add\",\n  \"branch\",\n  \"checkout\",\n  \"cherry-pick\",\n  \"clean\",\n  \"commit\",\n  \"merge\",\n  \"mv\",\n  \"push\",\n  \"rebase\",\n  \"reset\",\n  \"restore\",\n  \"revert\",\n  \"rm\",\n  \"stash\",\n  \"switch\",\n  \"tag\",\n] as const\n\nexport type GitOp = (typeof OPS)[number]\n\n// Git global flags that consume the following token as their value.\nconst FLAG_WITH_VALUE = new Set([\n  \"-C\",\n  \"-c\",\n  \"--git-dir\",\n  \"--work-tree\",\n  \"--exec-path\",\n  \"--namespace\",\n  \"--separate-git-dir\",\n  \"--config-env\",\n])\n\nexport type BranchPolicy = {\n  allow?: string[]\n  ask?: string[]\n  deny?: string[]\n}\n\nexport type Config = {\n  default?: BranchPolicy\n  branches?: Record<string, BranchPolicy>\n  repos?: Record<string, BranchPolicy>\n}\n\nexport type ResolvedPolicy = {\n  allow: string[]\n  ask: string[]\n  deny: string[]\n}\n\nexport type Effect = \"allow\" | \"ask\" | \"deny\"\n\nexport type Decision = {\n  effect: Effect\n  message?: string\n}\n\nexport function isGitOp(value: string): value is GitOp {\n  return (OPS as readonly string[]).includes(value)\n}\n\n// Extract the git mutation from a shell command string. Returns null for\n// non-git commands, git invocations without a known mutation, and read-only\n// commands (`status`, `log`, `diff`, ...).\nexport function gitOp(cmd: string): GitOp | null {\n  const tokens = cmd.trim().split(/\\s+/).filter(Boolean)\n  if (tokens[0] !== \"git\") return null\n\n  let i = 1\n  while (i < tokens.length) {\n    const token = tokens[i]\n    if (token === undefined) return null\n    if (!token.startsWith(\"-\")) {\n      return isGitOp(token) ? token : null\n    }\n    if (token.startsWith(\"--\") && token.includes(\"=\")) {\n      i += 1\n    } else if (FLAG_WITH_VALUE.has(token)) {\n      i += 2\n    } else {\n      i += 1\n    }\n  }\n  return null\n}\n\n// Resolve the effective policy for a command. `repos[directory]` overrides\n// `branches[branch]`, which overrides `default`. A rule's `allow` and `ask`\n// replace the baseline; its `deny` unions with the baseline. No resolved\n// `allow` means no mutation is permitted (fail-closed).\nexport function resolvePolicy(\n  config: Config,\n  branch: string | undefined,\n  directory: string | undefined,\n): ResolvedPolicy {\n  const base = config.default ?? {}\n  const branchRule = branch !== undefined ? config.branches?.[branch] : undefined\n  const repoRule = directory !== undefined ? config.repos?.[directory] : undefined\n  const rule = repoRule ?? branchRule\n  const allow = rule?.allow ?? base.allow ?? []\n  const ask = rule?.ask ?? base.ask ?? []\n  const deny = [...(base.deny ?? []), ...(rule?.deny ?? [])]\n  return { allow, ask, deny }\n}\n\n// Resolve the effect for one git operation. Precedence is `deny > ask > allow`.\n// An operation missing from every list is denied (fail-closed).\nexport function decide(op: string, policy: ResolvedPolicy): Decision {\n  if (policy.deny.includes(op)) {\n    return { effect: \"deny\", message: `Blocked: git ${op} is denied by config` }\n  }\n  if (policy.ask.includes(op)) {\n    return { effect: \"ask\", message: `git ${op} requires approval by config` }\n  }\n  if (policy.allow.includes(op)) {\n    return { effect: \"allow\" }\n  }\n  return { effect: \"deny\", message: `Blocked: git ${op} is not allowed by config` }\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "4EB1771F16AB9A6E64756E2164756E21",
+  "mappings": "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",
+  "debugId": "8C2497AAA571E94264756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-branch-guard",
-  "version": "0.1.0",
-  "description": "OpenCode plugin: blocks git mutations (commit, push, merge, rebase, ...) based on the current branch or repository, so protected branches stay clean.",
+  "version": "0.2.0",
+  "description": "OpenCode plugin: allows, asks, or blocks git mutations (commit, push, merge, rebase, ...) based on the current branch or repository, so protected branches stay clean.",
   "type": "module",
   "license": "MIT",
   "author": {