@bytesbrains/pi-contrib-gate 1.6.1

package/AGENTS.md

@@ -0,0 +1,125 @@
+# Contrib Gate — Agent Usage Guide
+
+> You are an AI agent. Use contrib-gate tools instead of raw git commands.
+
+## Golden Rule
+
+> **⚠️ DO NOT call `git push`, `git commit`, or `gh pr create` directly.**
+> Use `contrib_start_work(issue_id)` → `contrib_propose()` → `contrib_submit()` instead.
+> This ensures branch naming, conventional commits, and quality gates are enforced.
+
+## ⚡ Issue Linking Required
+
+> **Every piece of work MUST be linked to a real Gitea issue.** The gate validates the issue exists,
+> is open, and shows its title so you can verify relevance before starting work.
+>
+> **❌ Blocked:**
+> - Random/fake issue numbers (issue #999 doesn't exist → blocked)
+> - Direct `git checkout -b feat/issue-42` bypassing contrib_start_work
+> - Starting work on a closed issue
+>
+> **⚠️ Warned:**
+> - Issue assigned to someone else
+>
+> **✅ Allowed:**
+> - Issue exists + is open → branch created, work can begin
+>
+> **Rework on an existing PR?** If you're already on a feature branch (e.g., `feat/some-custom-name`),
+> calling `contrib_start_work(issue_id="42")` will link the issue without creating a new branch —
+> you just continue working on the existing PR.
+>
+> **Resuming work?** If you return to a branch like `feat/issue-42`, the issue is auto-detected
+> and you can start working immediately — no need to call `contrib_start_work` again.
+
+## Workflow
+
+```
+contrib_start_work(issue_id="42")   ← creates feat/issue-42 branch
+  │
+  ▼
+[make code changes — edit, write, bash for tests]
+  │
+  ▼
+contrib_propose(message="...")      ← validates + stages + quality-checks + commits
+  │
+  ▼
+contrib_submit(title="...")         ← pushes + creates PR
+  │
+  ▼
+contrib_status()                    ← verify everything looks good
+```
+
+## When Things Go Wrong
+
+| Problem | Solution |
+|---|---|
+| Quality gate failed | Fix the errors listed, then retry `contrib_propose()` |
+| Branch naming wrong | `git checkout -b feat/correct-name` and start from `contrib_propose()` |
+| Need to bypass a gate | Ask the human for confirmation — gates can be overridden |
+| Push blocked | Use `contrib_submit()` instead of `git push` |
+| Write/edit blocked: "No Gitea issue linked" | You forgot `contrib_start_work(issue_id)`. Call it first with a valid issue number. |
+| contrib_start_work blocked: "Issue #X does not exist" | Issue number is fake or wrong. Use `project_list_issues()` to find real issues. |
+| contrib_start_work blocked: "Issue #X is closed" | Pick an open issue or reopen it. Use `project_list_issues(state="open")`. |
+| contrib_start_work blocked: branch creation | You tried `git checkout -b feat/issue-42` directly. Use `contrib_start_work(issue_id)` instead. |
+| contrib_propose blocked: no issue | Run `contrib_start_work(issue_id)` to link an issue, then retry. |
+
+## Conventional Commits
+
+Your commit messages must follow this format:
+
+```
+type(scope): subject
+
+body (optional)
+
+Refs: #issue-id
+```
+
+Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `perf`, `ci`, `build`, `revert`
+
+Examples:
+- `feat(backup): add Firebase volume backup script`
+- `fix(ci): resolve stale info error in sync workflow`
+- `chore(deps): update playwright to v1.52`
+
+## Best Practice Guidance
+
+The contrib-gate can inject best-practice guidance into your commit workflow to encourage short, frequent, and atomic commits. These are **soft warnings** — they appear in `contrib_propose()` output but **never block** the commit.
+
+### Config (`commits.bestPractices.*`)
+
+Add these keys to `.contribrc.yml`:
+
+| Key | Default | Description |
+|---|---|---|
+| `commits.bestPractices.shortFrequentCommits` | `true` | When enabled, guidance text is shown after each commit |
+| `commits.bestPractices.maxLinesPerCommit` | `150` | Soft-warn if a commit exceeds this many lines added. Set to `0` to disable. |
+| `commits.bestPractices.requireAtomic` | `true` | Soft-warn if commit touches many unrelated directories |
+| `commits.bestPractices.maxUnrelatedDirs` | `3` | Threshold for the "non-atomic" heuristic |
+| `commits.bestPractices.guidanceText` | (see below) | Custom guidance injected into agent context |
+
+Default guidance text:
+- Commit after every logical unit of work.
+- Aim for < 150 lines per commit.
+- Each commit should do one thing — keep changes atomic.
+
+### What You'll See
+
+When `shortFrequentCommits` is enabled, every `contrib_propose()` output includes a guidance section:
+
+```
+✅ Changes committed (abc12345)
+   Branch: feat/my-feature
+   Message: feat(api): add endpoint
+
+📋 Best Practice Guidance:
+   • Commit after every logical unit of work.
+   • Aim for < 150 lines per commit.
+   • Each commit should do one thing — keep changes atomic.
+
+--- Soft Warnings (non-blocking) ---
+⚠️  Commit size (230 lines) exceeds best-practice threshold (150 lines).
+    Consider splitting into smaller, more frequent commits.
+
+Next: contrib_submit(title, body) to push and create PR.
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nandal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# Contrib Gate for Pi
+
+[![npm version](https://img.shields.io/npm/v/pi-contrib-gate)](https://www.npmjs.com/package/pi-contrib-gate)
+[![license](https://img.shields.io/npm/l/pi-contrib-gate)](./LICENSE)
+
+> Contribution gateway for AI agents — enforce branch naming, conventional commits, pre-commit quality gates, and PR automation. **Agents don't call `git push` — they call `contrib_submit()`.**
+
+> ⚡ **Every piece of work must be linked to a Gitea issue.** The gate blocks file modifications, commits, and PR creation until an issue is linked via `contrib_start_work(issue_id)`.
+
+## Install
+
+```bash
+pi install npm:pi-contrib-gate
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `contrib_start_work(issue_id)` | Create properly named branch, link to issue |
+| `contrib_propose(message, files)` | Validate, stage, quality-check, commit |
+| `contrib_submit(title, body)` | Push, create PR, return URL |
+| `contrib_status()` | Show branch, commits, changes, PR status |
+
+## Safety Intercepts
+
+The gate **passively monitors** all `bash` tool calls and:
+
+- ⛔ Blocks `write`/`edit` operations when no Gitea issue is linked (reminds agent to call `contrib_start_work(issue_id)` first)
+- ⛔ Blocks `write`/`edit` on protected branches (`main`, `dev`, `production`)
+- ⛔ Blocks `contrib_propose()` and `contrib_submit()` when no issue is linked
+- ⚠️ Warns on `git push --force`
+- ⚠️ Warns on non-conventional commit messages
+- ⚠️ Soft-warns on feature branches without a recognized issue ID
+- All blocks can be overridden with user confirmation
+
+## Quality Gates
+
+Every `contrib_propose()` runs:
+
+| Check | Default | Config |
+|---|---|---|
+| Conventional commit format | ✅ | `commits.convention` |
+| Max files changed (20) | ✅ | `quality.maxFilesChanged` |
+| Max lines added (500) | ✅ | `quality.maxLinesAdded` |
+| TypeScript check (`tsc --noEmit`) | ✅ | `quality.typeCheck` |
+| Lint check (`npm run lint`) | ✅ | `quality.lint` |
+| Doctor audit (god file detection) | ✅ | `quality.doctorAudit` |
+
+## Configuration
+
+Create `.contribrc.yml` in your project root (created automatically on first use with defaults):
+
+```yaml
+branches.featPattern: feat/
+branches.fixPattern: fix/
+branches.chorePattern: chore/
+commits.convention: conventional
+commits.maxSubjectLength: 72
+quality.maxFilesChanged: 20
+quality.maxLinesAdded: 500
+quality.lint: true
+quality.typeCheck: true
+quality.doctorAudit: true
+```
+
+## Example Workflow
+
+```
+→ contrib_start_work(issue_id="7", type="feat")
+✅ Work started on feat/issue-7
+
+→ [agent makes code changes...]
+
+→ contrib_propose(message="feat(backup): add Firebase volume backup script", body="Implements daily pg_dump + tar + upload.")
+✅ Changes committed (a1b2c3d)
+
+→ contrib_submit(title="feat: automated volume backups to Firebase Storage")
+🎉 PR created: http://localhost:3001/factory/wrok.in/pulls/47
+```
+
+## License
+
+MIT © [nandal](https://github.com/nandal)

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@bytesbrains/pi-contrib-gate",
+  "version": "1.6.1",
+  "description": "Contribution gateway for AI agents \u2014 enforce branch naming, conventional commits, pre-commit quality gates, and PR automation.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "governance",
+    "git",
+    "conventional-commits",
+    "ci",
+    "devops"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nandal/pi-ext",
+    "directory": "contrib-gate"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/contrib-gate",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  }
+}

package/src/__tests__/contrib-gate.test.ts

@@ -0,0 +1,375 @@
+import { describe, it, expect } from "vitest";
+import { DEFAULT_CONFIG, BEST_PRACTICES_DEFAULTS } from "../types";
+import { loadConfig } from "../config";
+import { validateBranchName, validateConventionalCommit, runQualityGate } from "../validate";
+import {
+  exec, currentBranch,
+  isClean, isMergeInProgress, isRebaseInProgress, isConflictInProgress,
+  scanForConflictMarkers, getStagedStats, countUnrelatedDirs,
+  extractIssueFromBranch,
+} from "../helpers";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// ═══════════════════════════════════════
+// Config
+// ═══════════════════════════════════════
+describe("ContribConfig", () => {
+  it("returns defaults when no config file", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "contrib-test-"));
+    const config = loadConfig(tmp);
+    expect(config.branches.featPattern).toBe("feat/");
+    expect(config.commits.convention).toBe("conventional");
+    expect(config.quality.maxFilesChanged).toBe(20);
+    expect(config.quality.maxLinesAdded).toBe(500);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("parses contribrc.yml", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "contrib-test-"));
+    fs.writeFileSync(path.join(tmp, ".contribrc.yml"), [
+      "branches.featPattern: feature/",
+      "commits.convention: simple",
+      "commits.maxSubjectLength: 100",
+      "quality.maxFilesChanged: 50",
+      "quality.lint: false",
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    expect(config.branches.featPattern).toBe("feature/");
+    expect(config.commits.convention).toBe("simple");
+    expect(config.commits.maxSubjectLength).toBe(100);
+    expect(config.quality.maxFilesChanged).toBe(50);
+    expect(config.quality.lint).toBe(false);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("handles missing config gracefully", () => {
+    const config = loadConfig("/nonexistent/path");
+    expect(config.branches.featPattern).toBe("feat/");
+  });
+
+  it("loads bestPractices defaults", () => {
+    const config = loadConfig("/nonexistent/path");
+    expect(config.commits.bestPractices.shortFrequentCommits).toBe(true);
+    expect(config.commits.bestPractices.maxLinesPerCommit).toBe(150);
+    expect(config.commits.bestPractices.requireAtomic).toBe(true);
+    expect(config.commits.bestPractices.maxUnrelatedDirs).toBe(3);
+    expect(config.commits.bestPractices.guidanceText).toEqual(BEST_PRACTICES_DEFAULTS.guidanceText);
+  });
+
+  it("parses bestPractices config keys", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "contrib-test-"));
+    fs.writeFileSync(path.join(tmp, ".contribrc.yml"), [
+      "commits.bestPractices.shortFrequentCommits: false",
+      "commits.bestPractices.maxLinesPerCommit: 200",
+      "commits.bestPractices.requireAtomic: false",
+      "commits.bestPractices.maxUnrelatedDirs: 5",
+      'commits.bestPractices.guidanceText: "Be thoughtful | Keep it small | Test everything"',
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    expect(config.commits.bestPractices.shortFrequentCommits).toBe(false);
+    expect(config.commits.bestPractices.maxLinesPerCommit).toBe(200);
+    expect(config.commits.bestPractices.requireAtomic).toBe(false);
+    expect(config.commits.bestPractices.maxUnrelatedDirs).toBe(5);
+    expect(config.commits.bestPractices.guidanceText).toEqual(["Be thoughtful", "Keep it small", "Test everything"]);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("backward-compatible with existing configs (no bestPractices keys)", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "contrib-test-"));
+    fs.writeFileSync(path.join(tmp, ".contribrc.yml"), [
+      "quality.maxLinesAdded: 600",
+      "quality.doctorAudit: false",
+    ].join("\n"));
+    const config = loadConfig(tmp);
+    // Existing keys still work
+    expect(config.quality.maxLinesAdded).toBe(600);
+    expect(config.quality.doctorAudit).toBe(false);
+    // Best practices get defaults
+    expect(config.commits.bestPractices.maxLinesPerCommit).toBe(150);
+    expect(config.commits.bestPractices.shortFrequentCommits).toBe(true);
+    expect(config.commits.bestPractices.requireAtomic).toBe(true);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+// ═══════════════════════════════════════
+// Validation
+// ═══════════════════════════════════════
+describe("validateBranchName", () => {
+  it("accepts feat/* branches", () => {
+    expect(validateBranchName("feat/issue-42").ok).toBe(true);
+    expect(validateBranchName("feat/add-login").ok).toBe(true);
+  });
+
+  it("accepts fix/* branches", () => {
+    expect(validateBranchName("fix/bug-123").ok).toBe(true);
+  });
+
+  it("accepts chore/* branches", () => {
+    expect(validateBranchName("chore/update-deps").ok).toBe(true);
+  });
+
+  it("rejects invalid branch names", () => {
+    expect(validateBranchName("main").ok).toBe(false);
+    expect(validateBranchName("dev").ok).toBe(false);
+    expect(validateBranchName("feature/something").ok).toBe(false);
+    expect(validateBranchName("hotfix/urgent").ok).toBe(false);
+  });
+});
+
+describe("validateConventionalCommit", () => {
+  const config = { ...DEFAULT_CONFIG, commits: { ...DEFAULT_CONFIG.commits, maxSubjectLength: 72 } };
+
+  it("accepts valid conventional commits", () => {
+    expect(validateConventionalCommit("feat: add login", config).ok).toBe(true);
+    expect(validateConventionalCommit("fix(api): resolve null pointer", config).ok).toBe(true);
+    expect(validateConventionalCommit("chore(deps): update packages", config).ok).toBe(true);
+  });
+
+  it("accepts all valid types", () => {
+    for (const type of ["feat", "fix", "chore", "docs", "style", "refactor", "test", "perf", "ci", "build", "revert"]) {
+      expect(validateConventionalCommit(`${type}: something`, config).ok).toBe(true);
+    }
+  });
+
+  it("rejects non-conventional messages", () => {
+    expect(validateConventionalCommit("added login", config).ok).toBe(false);
+    expect(validateConventionalCommit("Update stuff", config).ok).toBe(false);
+    expect(validateConventionalCommit("WIP", config).ok).toBe(false);
+  });
+
+  it("rejects subject too long", () => {
+    const long = "feat: " + "x".repeat(70);
+    expect(validateConventionalCommit(long, config).ok).toBe(false);
+  });
+
+  it("handles multiline messages", () => {
+    const msg = "feat: add feature\n\nExtended body text here.";
+    expect(validateConventionalCommit(msg, config).ok).toBe(true);
+  });
+});
+
+// ═══════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════
+describe("exec helper", () => {
+  it("returns ok true for successful command", () => {
+    const r = exec("echo hello");
+    expect(r.ok).toBe(true);
+    expect(r.stdout).toBe("hello");
+  });
+
+  it("returns ok false for failed command", () => {
+    const r = exec("nonexistent-command-12345 2>/dev/null");
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe("currentBranch", () => {
+  it("returns current branch name", () => {
+    const branch = currentBranch(process.cwd());
+    expect(typeof branch).toBe("string");
+    expect(branch.length).toBeGreaterThan(0);
+  });
+});
+
+describe("isClean", () => {
+  it("checks working tree status", () => {
+    const clean = isClean(process.cwd());
+    expect(typeof clean).toBe("boolean");
+  });
+});
+
+describe("getStagedStats", () => {
+  it("returns empty when nothing staged", () => {
+    const stats = getStagedStats(process.cwd());
+    expect(stats.files).toEqual([]);
+    expect(stats.linesAdded).toBe(0);
+  });
+
+  it("returns files and line counts for staged changes", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "contrib-stats-"));
+    exec("git init && git config user.email test@test && git config user.name test", tmp);
+    fs.writeFileSync(path.join(tmp, "a.txt"), "hello\nworld\n");
+    exec("git add a.txt && git commit -m init", tmp);
+    fs.writeFileSync(path.join(tmp, "a.txt"), "hello\nworld\nnew line\n");
+    exec("git add a.txt", tmp);
+    const stats = getStagedStats(tmp);
+    expect(stats.files).toContain("a.txt");
+    expect(stats.linesAdded).toBeGreaterThan(0);
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+describe("countUnrelatedDirs", () => {
+  it("counts distinct directories from file paths", () => {
+    const files = ["src/a.ts", "src/b.ts", "tests/c.test.ts"];
+    expect(countUnrelatedDirs(files)).toBe(2);
+  });
+
+  it("returns 1 for single-directory changes", () => {
+    const files = ["src/index.ts", "src/config.ts", "src/types.ts"];
+    // All in src/, but 2 subdirectories: src/* (all same level, no subdirs)
+    // All have just "src" as top dir, subdirs would be "src" only
+    const result = countUnrelatedDirs(files);
+    expect(result).toBe(1);
+  });
+
+  it("detects deeply nested unrelated subdirectories", () => {
+    const files = ["contrib-gate/src/a.ts", "contrib-gate/test/b.ts", "ci-gate/src/c.ts"];
+    expect(countUnrelatedDirs(files)).toBe(3);
+  });
+
+  it("handles empty file list", () => {
+    expect(countUnrelatedDirs([])).toBe(0);
+  });
+});
+
+// ═══════════════════════════════════════
+// Issue extraction from branches
+// ═══════════════════════════════════════
+describe("extractIssueFromBranch", () => {
+  it("extracts issue ID from feat/issue-N", () => {
+    expect(extractIssueFromBranch("feat/issue-42")).toBe("42");
+    expect(extractIssueFromBranch("feat/issue-7")).toBe("7");
+    expect(extractIssueFromBranch("feat/issue-123")).toBe("123");
+  });
+
+  it("extracts issue ID from fix/issue-N", () => {
+    expect(extractIssueFromBranch("fix/issue-99")).toBe("99");
+  });
+
+  it("extracts issue ID from chore/issue-N", () => {
+    expect(extractIssueFromBranch("chore/issue-1")).toBe("1");
+  });
+
+  it("extracts issue ID from bare issue-N", () => {
+    expect(extractIssueFromBranch("issue-42")).toBe("42");
+  });
+
+  it("returns null for branches without issue ID", () => {
+    expect(extractIssueFromBranch("feat/add-login")).toBe(null);
+    expect(extractIssueFromBranch("fix/bug-fix")).toBe(null);
+    expect(extractIssueFromBranch("main")).toBe(null);
+    expect(extractIssueFromBranch("dev")).toBe(null);
+    expect(extractIssueFromBranch("random-branch")).toBe(null);
+  });
+
+  it("returns null for issue-N in middle of branch name", () => {
+    expect(extractIssueFromBranch("feat/issue-42-hotfix")).toBe(null);
+    expect(extractIssueFromBranch("prefix-issue-42")).toBe(null);
+  });
+});
+
+// ═══════════════════════════════════════
+// Quality gates
+// ═══════════════════════════════════════
+describe("runQualityGate", () => {
+  it("checks changed files count", () => {
+    // In a test env without staged changes, this should pass
+    const config = { ...DEFAULT_CONFIG, quality: { ...DEFAULT_CONFIG.quality, typeCheck: false, lint: false } };
+    const result = runQualityGate(process.cwd(), config);
+    expect(typeof result.ok).toBe("boolean");
+  });
+
+  it("fails when staged files contain conflict markers", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "contrib-qg-conflict-"));
+    exec("git init && git config user.email test@test && git config user.name test", tmp);
+
+    // Seed initial commit
+    fs.writeFileSync(path.join(tmp, "file.txt"), "clean\n");
+    exec("git add file.txt && git commit -m init", tmp);
+
+    // Write conflict markers and stage
+    fs.writeFileSync(path.join(tmp, "file.txt"), "<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> dev\n");
+    exec("git add file.txt", tmp);
+
+    const config = { ...DEFAULT_CONFIG, quality: { ...DEFAULT_CONFIG.quality, typeCheck: false, lint: false } };
+    const result = runQualityGate(tmp, config);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.errors.some((e: string) => e.includes("conflict markers"))).toBe(true);
+    }
+
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});
+
+// ═══════════════════════════════════════
+// Merge conflict helpers
+// ═══════════════════════════════════════
+describe("isMergeInProgress", () => {
+  it("returns false when no merge in progress", () => {
+    expect(isMergeInProgress(process.cwd())).toBe(false);
+  });
+});
+
+describe("isRebaseInProgress", () => {
+  it("returns false when no rebase in progress", () => {
+    expect(isRebaseInProgress(process.cwd())).toBe(false);
+  });
+});
+
+describe("isConflictInProgress", () => {
+  it("returns false when no conflict in progress", () => {
+    expect(isConflictInProgress(process.cwd())).toBe(false);
+  });
+});
+
+// ═══════════════════════════════════════
+// Conflict marker scanning
+// ═══════════════════════════════════════
+describe("scanForConflictMarkers", () => {
+  it("returns empty when no conflict markers in staged files", () => {
+    const result = scanForConflictMarkers(process.cwd());
+    expect(result).toEqual([]);
+  });
+
+  it("detects conflict markers in a staged file (simulated via git show)", () => {
+    // Create a temp repo to test conflict detection properly
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "contrib-conflict-"));
+    exec("git init && git config user.email test@test && git config user.name test", tmp);
+
+    // Create a file with conflict markers
+    const filePath = path.join(tmp, "test.txt");
+    fs.writeFileSync(filePath, [
+      "line before",
+      "<<<<<<< HEAD",
+      "our change",
+      "=======",
+      "their change",
+      ">>>>>>> dev",
+      "line after",
+    ].join("\n"));
+
+    // Stage and commit a clean version first (need initial commit for git show :0:)
+    fs.writeFileSync(filePath, "clean content\n");
+    exec(`git add test.txt && git commit -m "init"`, tmp);
+
+    // Now write conflict markers and stage
+    fs.writeFileSync(filePath, "<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> dev\n");
+    exec("git add test.txt", tmp);
+
+    const result = scanForConflictMarkers(tmp);
+    expect(result).toContain("test.txt");
+
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns empty for clean staged files", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "contrib-clean-"));
+    exec("git init && git config user.email test@test && git config user.name test", tmp);
+
+    fs.writeFileSync(path.join(tmp, "clean.txt"), "no conflicts here\n");
+    exec("git add clean.txt && git commit -m init", tmp);
+    fs.writeFileSync(path.join(tmp, "clean.txt"), "updated clean content\n");
+    exec("git add clean.txt", tmp);
+
+    const result = scanForConflictMarkers(tmp);
+    expect(result).toEqual([]);
+
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+});