@gitkraken/conflict-tools 0.0.1-beta.1

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]

package/LICENSE

@@ -0,0 +1,19 @@
+Core Tools License
+
+Copyright (c) 2025-2026 Axosoft, LLC dba GitKraken ("GitKraken")
+
+This software and associated documentation files (the "Software") may be compiled as part of GitKraken software products, including the gitkraken/vscode-gitlens open source project (collectively, the "GitKraken Products"), to the extent the Software is a required component of the GitKraken Products; provided, however, that the Software and its functionality may only be used if you (and any entity that you represent) have agreed to, and are in compliance with, the GitKraken End User License Agreement, available at https://gitkraken.com/eula (the "EULA"), or other agreement governing the use of the Software, as agreed by you and GitKraken, and otherwise have a valid subscription for the correct number of user seats for the applicable version of the Software (e.g., GitLens Free+, GitLens Pro, GitLens Teams, and GitLens Enterprise).
+
+The Software is licensed, not sold. This license only gives you some rights to use the Software. GitKraken reserves all other rights. Unless applicable law gives you more rights despite this limitation, you may use the Software only as expressly permitted in this license. In doing so, you must comply with any technical limitations in the Software that only allow you to use it in certain ways. You may not (i) work around any technical limitations in the Software, (ii) reverse engineer, decompile or disassemble the Software, or otherwise attempt to derive the source code for the Software, except and to the extent required by third party licensing terms governing use of certain open source components that may be included with the Software, (iii) remove, minimize, block or modify any notices of GitKraken or its suppliers in the Software, (iv) use the software in any way that is against the law, (v) host, share, publish, rent or lease the Software; (vi) distribute the Software as a stand-alone or integrated offering or combine it with any of your applications for others to use, (vii) use the Software other than in connection with validly licensed GitKraken Products or (viii) use any portion of the Software to create software with the same or similar functionality.
+
+You agree that GitKraken and/or its licensors (as applicable) retain all right, title and interest in and to the Software and all modifications and/or patches thereto. You are not granted any other rights beyond what is expressly stated herein. Except as set forth above, it is forbidden to copy, merge, publish, distribute, sublicense, modify and/or sell the Software.
+
+If you give feedback about the Software to GitKraken, you give to GitKraken, without charge, the right to use, share and commercialize your feedback in any way and for any purpose. You will not give feedback that is subject to a license that requires GitKraken to license its software or documentation to third parties because we include your feedback in them. These rights survive this License.
+
+The full text of this Core Tools License shall be included in all copies or substantial portions of the Software.
+
+This License and the EULA, if applicable, are the entire agreement for the Software. You must comply with all domestic and international export laws and regulations that apply to the Software, which include restrictions on destinations, end users and end use. This License is governed and construed by the laws of the State of Arizona, United States without regard to any choice or conflict of law principles or rules.
+
+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 GITKRAKEN, 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.
+
+For all third party components incorporated into the Software, those components are licensed under the original license provided by the owner of the applicable component.

package/README.md

@@ -0,0 +1,271 @@
+# @gitkraken/conflict-tools
+
+AI-powered git conflict resolution. Parses conflict markers, resolves conflicts with an agentic AI loop that has access to git context (blame, grep, diff, log, file content), and writes results back to the working tree.
+
+## What it does
+
+Three entry points, each serving a different consumer need:
+
+- `extractConflict()` — parses conflict markers from a single file and returns a structured representation. No AI, no resolution. Used by editors, eval harnesses, and any consumer that needs the raw conflict data.
+
+- `resolveConflict()` — takes one `Conflict` and an optional `ResolutionContext`, runs the AI tool-use loop, returns a `Resolution` with resolved content, confidence, and metrics. The single-file workhorse.
+
+- `resolveConflicts() + applyResolutions()` — batch-resolve every currently unmerged file in the working tree, then write and stage results. The library does NOT orchestrate `git rebase`/`merge`/`cherry-pick`. The consumer drives the operation lifecycle and calls these in its own loop.
+
+The library never calls `git` or an AI provider directly. Consumers supply adapters via ports.
+
+## Install
+
+```bash
+pnpm add @gitkraken/conflict-tools @gitkraken/shared-tools
+```
+
+## Ports
+
+### `ConflictGitPort`
+
+A bag of optional high-level git ops, plus an optional raw `exec` fallback. Provide `exec` only (the library's dispatchers will build the git commands themselves), provide individual ops (your adapter's native API is used directly), or mix both.
+
+```typescript
+import type { ConflictGitPort } from '@gitkraken/conflict-tools';
+
+const git: ConflictGitPort = {
+    exec: async (args, options) => simpleGit.raw(...args),
+};
+```
+
+High-level ops the library dispatches through:
+
+| Op | Purpose |
+|---|---|
+| `readFile(path)` | Read working-tree file content (used during conflict extraction) |
+| `showFile(ref, path, opts?)` | Read file content at a specific ref. Supports `startLine`/`endLine` |
+| `unmergedEntries()` | List files git considers unresolved |
+| `mergeBase(a, b)` | Common ancestor between two refs |
+| `blame(path, opts?)` | Line-level authorship. Supports `startLine`/`endLine` (maps to `git blame -L`) |
+| `grep(pattern, opts?)` | Content search across the tree. Supports `maxResults` |
+| `diff(from, to, opts?)` | Unified diff between refs, optionally scoped to a path |
+| `log(opts?)` | Commit history. Supports `ref`, `path`, `maxCount` |
+| `writeFile(path, content)` | Write resolved content to the working tree |
+| `deleteFile(path)` | Remove a file from the working tree |
+| `stageFiles(paths)` | Stage resolved files (`git add`) |
+| `checkoutFile(path, 'ours' \| 'theirs')` | Apply a side directly via git |
+
+Outputs from `showFile` and `blame` are capped at 1000 lines; `grep` and `log` at 100 results. When the cap fires, the library prepends an actionable header (e.g. `[Output capped at 1000 lines. Use startLine/endLine to read other regions of the file.]`) so the AI can re-query with a narrower range.
+
+If a flow needs an op that the consumer didn't supply and `exec` is unavailable, the library throws `ConflictGitPortMissingOpError`.
+
+### `ConflictModelPort`
+
+A single-method port for AI inference. The library owns the tool-use loop — it calls `generate`, dispatches any `toolCalls` it sees against `ConflictGitPort`, feeds the results back, and repeats until the model returns a final structured answer.
+
+```typescript
+import type { ConflictModelPort } from '@gitkraken/conflict-tools';
+
+const model: ConflictModelPort = {
+    generate: async ({ system, messages, tools, temperature, signal }) => {
+        // Map to your AI SDK (Vercel AI SDK, Anthropic, OpenAI, VS Code LLM API, ...)
+        // Return { text?, toolCalls?, usage? }
+    },
+};
+```
+
+The shape of `tools`, `toolCalls`, and `toolResults` follows abstract types (`ToolDefinition`, `ToolCall`, `ToolResult`) so consumers can adapt any SDK. The library does not require streaming or any provider-specific feature.
+
+## Entry points
+
+### `extractConflict(filePath, deps)` — parse only
+
+```typescript
+import { extractConflict } from '@gitkraken/conflict-tools';
+
+const conflict = await extractConflict('src/auth.ts', { git });
+
+// conflict.filePath        — 'src/auth.ts'
+// conflict.markers[]       — position, sides, and surrounding context per marker block
+// conflict.type            — 'text' | 'binary'
+// conflict.rawContent      — original file content with markers preserved
+```
+
+Returns `null` for files without conflict markers (including delete-modify situations — the consumer decides what to do with those, see `UnmergedEntry.reason`).
+
+### `resolveConflict(conflict, context, deps)` — single file
+
+```typescript
+import { resolveConflict } from '@gitkraken/conflict-tools';
+
+const resolution = await resolveConflict(conflict, context, {
+    model,
+    git,
+    config: { maxSteps: 15, temperature: 0 },
+    onProgress: (event) => console.log(event),
+});
+
+// resolution.content       — resolved file content (markers replaced)
+// resolution.strategy      — 'ai' | 'take-ours' | 'take-theirs' | 'skipped'
+// resolution.confidence    — 0..1, from the AI's own self-assessment
+// resolution.description   — one-or-two sentence rationale, from the AI
+// resolution.chunks?       — per-marker decisions (for observability and validation)
+// resolution.metrics?      — { inputTokens, outputTokens, stepCount, toolCallCount, ... }
+```
+
+`ResolutionContext` carries optional hints the AI can use:
+
+```typescript
+interface ResolutionContext {
+    commitMessage?: string;
+    prDescription?: string;
+    previousResolutions?: Resolution[];
+    fileNeighbors?: string[];
+    refs?: { ours: string; theirs: string; base?: string };
+    threeWayDiff?: { oursDiff: string; theirsDiff: string };
+    metadata?: Record<string, unknown>;
+}
+```
+
+When `refs` is provided, the library computes `git diff base..ours -- file` and `git diff base..theirs -- file` automatically and includes both in the prompt. This typically lets the AI resolve without any tool calls. Consumers that already have these diffs cached can pass `threeWayDiff` directly to skip the computation.
+
+### `resolveConflicts(deps, context?) + applyResolutions(resolutions, deps)` — batch
+
+```typescript
+import { resolveConflicts, applyResolutions } from '@gitkraken/conflict-tools';
+
+const step = await resolveConflicts(
+    {
+        model,
+        git,
+        config: {
+            excludeFiles: ['*.lock', 'pnpm-lock.yaml', '*.generated.ts'],
+            fallbackStrategy: 'take-theirs',
+            maxSteps: 15,
+        },
+        onProgress: (event) => updateUI(event),
+    },
+    { commitMessage, refs },
+);
+
+// step.resolutions[]       — successful resolutions
+// step.errors[]            — { filePath, error } for files that failed (no fallback or AI exhausted)
+
+await applyResolutions(step.resolutions, { git });
+// All non-skipped resolutions are written via writeFile and staged via stageFiles.
+```
+
+`StepConfig` extends `ResolverConfig` with two batch-only fields:
+- `excludeFiles` — glob patterns (matched on basename via `picomatch`); matched files are skipped before AI is invoked.
+- `fallbackStrategy` — when AI fails for a file, fall back to `'take-ours'` or `'take-theirs'` instead of recording an error.
+
+The function inspects the working tree once (via `unmergedEntries`), processes each conflict sequentially, and returns. It does not call `git rebase --continue` or any other operation command — that is the consumer's job.
+
+## Consumer examples
+
+### GitLens — single-file editor command
+
+```typescript
+const git = createVSCodeConflictGit(vscodeGitApi);
+const model = createVSCodeAiModel(vscodeLlmApi);
+
+const conflict = await extractConflict(activeFilePath, { git });
+if (conflict) {
+    const resolution = await resolveConflict(conflict, { commitMessage }, { model, git });
+    showInDiffEditor(resolution);
+}
+```
+
+### GitLens / GKD — batch "resolve all" (user-driven)
+
+```typescript
+const step = await resolveConflicts({ git, model, onProgress: webview.post });
+const approved = await reviewDialog(step.resolutions);
+await applyResolutions(approved, { git });
+// User clicks "continue rebase" themselves.
+```
+
+### CLI / GitHub Action — automated rebase loop
+
+```typescript
+// The rebase loop lives in the consumer (e.g. @merge-mate/core), not in conflict-tools.
+for (const commit of commits) {
+    const result = await git.exec(['rebase', '--onto', target, `${commit}^`, commit]);
+    if (result.exitCode === 0) continue;
+
+    const step = await resolveConflicts({
+        git, model,
+        config: { excludeFiles: ['*.lock'], fallbackStrategy: 'take-ours' },
+        onProgress: emit,
+    });
+    await applyResolutions(step.resolutions, { git });
+    await git.exec(['rebase', '--continue']);
+}
+```
+
+### Eval harness
+
+```typescript
+const conflict = await extractConflict(fixturePath, { git });
+const resolution = await resolveConflict(conflict!, context, { model, git });
+score(resolution, goldenFile);
+```
+
+## Observability
+
+`resolveConflicts` and `resolveConflict` accept an `onProgress` callback that receives a discriminated `ConflictProgressEvent`:
+
+| Event | When |
+|---|---|
+| `conflict:found` | A conflict file has been parsed |
+| `resolution:applied` | A resolution was produced for a file |
+| `resolution:fallback` | AI failed; fallback strategy applied |
+| `resolution:failed` | AI failed and no fallback configured |
+| `resolver:tool-call` | The AI invoked a tool (show, grep, blame, diff, log) |
+| `resolver:step-usage` | Token usage for one model call |
+| `resolver:completed` | The resolver finished a single file |
+
+Operation-level events (rebase started, step completed, etc.) are the consumer's responsibility — the library has no opinion about the surrounding workflow.
+
+## Error handling
+
+| Error | Codes | When |
+|---|---|---|
+| `ConflictError` | `PARSE_FAILED`, `BINARY_CONFLICT` | Conflict extraction failed |
+| `AIError` | `VALIDATION_EXHAUSTED`, `INCOMPLETE_RESOLUTION` | Model could not produce a valid resolution after retries |
+| `ConflictGitPortMissingOpError` | — | A required git op is missing and no `exec` fallback was provided |
+
+```typescript
+import { resolveConflict, AIError, ConflictError } from '@gitkraken/conflict-tools';
+
+try {
+    await resolveConflict(conflict, context, { model, git });
+} catch (error) {
+    if (error instanceof ConflictError && error.code === 'BINARY_CONFLICT') {
+        // Binary file — apply your own fallback (take-ours, take-theirs, skip).
+    } else if (error instanceof AIError) {
+        // Model exhausted retries. Configure StepConfig.fallbackStrategy or handle here.
+    }
+}
+```
+
+In the batch entry point, errors that have a configured fallback do not throw — they are downgraded to `resolution:fallback` events, and the resulting resolutions appear in `step.resolutions`. Errors without a fallback land in `step.errors` and the loop continues with the next file.
+
+## Semver policy
+
+| Change | Bump |
+|---|---|
+| New optional field on an exported type | patch |
+| New variant in `ConflictProgressEvent` | minor |
+| New optional method on `ConflictGitOps` | patch |
+| New required method on a port | major |
+| Remove or rename an exported field | major |
+| Change the signature of a port method | major |
+| Bundled prompt change (no API change) | patch |
+| New required field on a config | major |
+
+## Contributing
+
+This package follows the monorepo's standard tooling — see the root [CONTRIBUTING.md](../../CONTRIBUTING.md). Local commands:
+
+```bash
+pnpm --filter @gitkraken/conflict-tools build
+pnpm --filter @gitkraken/conflict-tools typecheck
+pnpm --filter @gitkraken/conflict-tools test
+```

package/dist/errors/ai.d.ts

@@ -0,0 +1,10 @@
+//#region src/errors/ai.d.ts
+type AIErrorCode = 'VALIDATION_EXHAUSTED' | 'INCOMPLETE_RESOLUTION';
+declare class AIError extends Error {
+  readonly code: AIErrorCode;
+  constructor(code: AIErrorCode, message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+export { AIError, AIErrorCode };

package/dist/errors/ai.js

@@ -0,0 +1 @@
+var e=class extends Error{code;constructor(e,t,n){super(t,n),this.name=`AIError`,this.code=e}};export{e as AIError};

package/dist/errors/conflict.d.ts

@@ -0,0 +1,10 @@
+//#region src/errors/conflict.d.ts
+type ConflictErrorCode = 'PARSE_FAILED';
+declare class ConflictError extends Error {
+  readonly code: ConflictErrorCode;
+  constructor(code: ConflictErrorCode, message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+export { ConflictError, ConflictErrorCode };

package/dist/errors/conflict.js

@@ -0,0 +1 @@
+var e=class extends Error{code;constructor(e,t,n){super(t,n),this.name=`ConflictError`,this.code=e}};export{e as ConflictError};

package/dist/extraction/extract.d.ts

@@ -0,0 +1,10 @@
+import { ConflictGitPort } from "../ports/git.js";
+import { Conflict } from "../types/conflict.js";
+
+//#region src/extraction/extract.d.ts
+declare function extractConflict(filePath: string, deps: {
+  git: ConflictGitPort;
+  signal?: AbortSignal;
+}): Promise<Conflict | null>;
+//#endregion
+export { extractConflict };

package/dist/extraction/extract.js

@@ -0,0 +1 @@
+import{readFile as e}from"../git/port-dispatch.js";import{parseConflictMarkers as t}from"./parser.js";async function n(n,r){let i=await e(r.git,n,{signal:r.signal}),a=t(i);return a.length===0?null:{filePath:n,markers:a,type:`text`,rawContent:i}}export{n as extractConflict};

package/dist/extraction/parser.d.ts

@@ -0,0 +1,6 @@
+import { ConflictMarker } from "../types/conflict.js";
+
+//#region src/extraction/parser.d.ts
+declare function parseConflictMarkers(content: string, contextLines?: number): ConflictMarker[];
+//#endregion
+export { parseConflictMarkers };

package/dist/extraction/parser.js

@@ -0,0 +1,5 @@
+import{ConflictError as e}from"../errors/conflict.js";const t=`<<<<<<<`,n=`|||||||`,r=`=======`,i=`>>>>>>>`;function a(a,l=3){let u=a.split(`
+`),d=[],f=0;for(;f<u.length;){let a=u[f];if(a===void 0||!o(a,t)){f++;continue}let p=f,m=s(a,t);f++;let h=[],g=null,_=null;for(;f<u.length;){let i=u[f];if(i===void 0)break;if(o(i,t))throw new e(`PARSE_FAILED`,`Nested conflict marker at line ${f+1}`);if(o(i,n)){_=s(i,n),f++,g=[];break}if(o(i,r)){f++;break}h.push(i),f++}if(f>=u.length)throw new e(`PARSE_FAILED`,`Unterminated conflict marker starting at line ${p+1}`);if(g!==null){for(;f<u.length;){let n=u[f];if(n===void 0)break;if(o(n,t))throw new e(`PARSE_FAILED`,`Nested conflict marker at line ${f+1}`);if(o(n,r)){f++;break}g.push(n),f++}if(f>=u.length)throw new e(`PARSE_FAILED`,`Unterminated conflict marker starting at line ${p+1}`)}let v=[];for(;f<u.length;){let n=u[f];if(n===void 0)break;if(o(n,t))throw new e(`PARSE_FAILED`,`Nested conflict marker at line ${f+1}`);if(o(n,i))break;v.push(n),f++}if(f>=u.length)throw new e(`PARSE_FAILED`,`Unterminated conflict marker starting at line ${p+1}`);let y=f,b=u[f],x=b===void 0?``:s(b,i);f++;let S=d[d.length-1],C=S?S.endLine+1:0,w=Math.max(C,p-l),T=u.slice(w,p).join(`
+`);d.push({startLine:p,endLine:y,ours:c(h),base:g===null?null:c(g),theirs:c(v),oursLabel:m,theirsLabel:x,baseLabel:_,contextBefore:T,contextAfter:``})}for(let e=0;e<d.length;e++){let t=d[e];if(!t)continue;let n=d[e+1],r=n?n.startLine:u.length,i=Math.min(r,t.endLine+1+l);d[e]={...t,contextAfter:u.slice(t.endLine+1,i).join(`
+`)}}return d}function o(e,t){return e.startsWith(t)&&(e.length===t.length||e[t.length]===` `)}function s(e,t){return e.slice(t.length).trim()}function c(e){return e.join(`
+`)}export{a as parseConflictMarkers};

package/dist/git/port-dispatch.d.ts

@@ -0,0 +1,15 @@
+import { BlameOptions, ConflictDiffOptions, ConflictGitPort, GrepOptions, LogOptions, OpOptions, ShowFileOptions, UnmergedEntry } from "../ports/git.js";
+
+//#region src/git/port-dispatch.d.ts
+declare function readFile(git: ConflictGitPort, path: string, opts?: OpOptions): Promise<string>;
+declare function showFile(git: ConflictGitPort, ref: string, path: string, opts?: ShowFileOptions): Promise<string>;
+declare function unmergedEntries(git: ConflictGitPort, opts?: OpOptions): Promise<UnmergedEntry[]>;
+declare function mergeBase(git: ConflictGitPort, a: string, b: string, opts?: OpOptions): Promise<string>;
+declare function blame(git: ConflictGitPort, path: string, opts?: BlameOptions): Promise<string>;
+declare function grep(git: ConflictGitPort, pattern: string, opts?: GrepOptions): Promise<string>;
+declare function diff(git: ConflictGitPort, from: string, to: string, opts?: ConflictDiffOptions): Promise<string>;
+declare function log(git: ConflictGitPort, opts?: LogOptions): Promise<string>;
+declare function writeFile(git: ConflictGitPort, path: string, content: string, opts?: OpOptions): Promise<void>;
+declare function stageFiles(git: ConflictGitPort, paths: string[], opts?: OpOptions): Promise<void>;
+//#endregion
+export { blame, diff, grep, log, mergeBase, readFile, showFile, stageFiles, unmergedEntries, writeFile };

package/dist/git/port-dispatch.js

@@ -0,0 +1,2 @@
+import{ConflictGitPortMissingOpError as e}from"../ports/git.js";import{sliceLines as t,truncateLines as n,truncateMatches as r}from"./truncation.js";function i(e){return`Search capped at ${e} matches. There may be more — narrow with a more specific pattern or path.`}function a(t,n){throw new e(t,n)}function o(e,t){return e!=null&&t!=null?`startLine=${e}, endLine=${t}`:e==null?`endLine=${t}`:`startLine=${e}`}async function s(e,t,n){return e.readFile?e.readFile(t,n):a(`readFile`)}async function c(e,r,i,s){let c;if(e.showFile)c=await e.showFile(r,i,s);else if(e.exec){let n=t(await e.exec([`show`,`${r}:${i}`],{signal:s?.signal}),s?.startLine,s?.endLine);if(!n.ok)return n.reason===`invalid-range`?`[Invalid range: ${o(n.startLine,n.endLine)} (startLine must be <= endLine).]`:`[Range out of bounds: file has ${n.total} lines, requested ${o(n.startLine,n.endLine)}.]`;c=n.content}else return a(`showFile`);return n(c,1e3,`Output capped at 1000 lines. Use startLine/endLine to read other regions of the file.`)}async function l(e,t){if(e.unmergedEntries)return e.unmergedEntries(t);if(e.exec){let n=await e.exec([`status`,`--porcelain=v2`],{signal:t?.signal}),r=[];for(let e of n.split(`
+`)){if(!e.startsWith(`u `))continue;let t=e.split(` `),n=t[1]??``,i=t.slice(10).join(` `);r.push({path:i,reason:_(n)})}return r}return a(`unmergedEntries`)}async function u(e,t,n,r){return e.mergeBase?e.mergeBase(t,n,r):e.exec?(await e.exec([`merge-base`,`--`,t,n],{signal:r?.signal})).trim():a(`mergeBase`)}async function d(e,t,r){let i=r?.startLine,s=r?.endLine,c=Number.isFinite(i),l=Number.isFinite(s);if(c&&l&&i>s)return`[Invalid range: ${o(i,s)} (startLine must be <= endLine).]`;let u;if(e.blame)u=await e.blame(t,r);else if(e.exec){let n=[`blame`,`--porcelain`],a=c?Math.max(1,i):void 0,o=l?Math.max(1,s):void 0;a!=null&&o!=null?n.push(`-L`,`${a},${o}`):a==null?o!=null&&n.push(`-L`,`1,${o}`):n.push(`-L`,`${a},`),r?.ref&&n.push(r.ref),n.push(`--`,t),u=await e.exec(n,{signal:r?.signal})}else return a(`blame`);return n(u,1e3,`Output capped at 1000 lines. Use startLine/endLine to inspect other regions.`)}async function f(e,t,n){let o=n?.maxResults,s=o!=null&&Number.isFinite(o)?Math.min(Math.max(1,o),100):100,c;if(e.grep)c=await e.grep(t,n);else if(e.exec){let r=[`grep`,`-n`,`--`,t];n?.ref&&r.push(n.ref),c=await e.exec(r,{signal:n?.signal})}else return a(`grep`);return r(c,s,i(s))}async function p(e,t,n,r){if(e.diff)return e.diff(t,n,r);if(e.exec){let i=[`diff`,t,n];return r?.path&&i.push(`--`,r.path),e.exec(i,{signal:r?.signal})}return a(`diff`)}async function m(e,t){let r=t?.maxCount,i=r!=null&&Number.isFinite(r)?Math.min(Math.max(1,r),100):100,o;if(e.log)o=await e.log({...t,maxCount:i});else if(e.exec){let n=[`log`,`--oneline`,`-n`,String(i)];t?.ref&&n.push(t.ref),t?.path&&n.push(`--`,t.path),o=await e.exec(n,{signal:t?.signal})}else return a(`log`);return n(o,100,`Output capped at 100 commits. Use path to scope to a file or refine the ref range.`)}async function h(e,t,n,r){return e.writeFile?e.writeFile(t,n,r):a(`writeFile`)}async function g(e,t,n){if(e.stageFiles)return e.stageFiles(t,n);if(e.exec){await e.exec([`add`,`--`,...t],{signal:n?.signal});return}return a(`stageFiles`)}function _(e){switch(e){case`DD`:return`both-deleted`;case`AU`:return`added-by-us`;case`UD`:return`deleted-by-them`;case`UA`:return`added-by-them`;case`DU`:return`deleted-by-us`;case`AA`:return`both-added`;case`UU`:return`both-modified`;default:return e}}export{d as blame,p as diff,f as grep,m as log,u as mergeBase,s as readFile,c as showFile,g as stageFiles,l as unmergedEntries,h as writeFile};

package/dist/git/truncation.d.ts

@@ -0,0 +1,16 @@
+//#region src/git/truncation.d.ts
+type SliceResult = {
+  ok: true;
+  content: string;
+} | {
+  ok: false;
+  reason: 'out-of-range' | 'invalid-range';
+  total: number;
+  startLine?: number;
+  endLine?: number;
+};
+declare function truncateLines(text: string, cap: number, hint: string): string;
+declare function truncateMatches(text: string, cap: number, hint: string): string;
+declare function sliceLines(text: string, startLine?: number, endLine?: number): SliceResult;
+//#endregion
+export { SliceResult, sliceLines, truncateLines, truncateMatches };

package/dist/git/truncation.js

@@ -0,0 +1,8 @@
+function e(e,t,n){if(t<=0||e.length===0)return e;let r=e.split(`
+`);return(r.length>0&&r[r.length-1]===``?r.length-1:r.length)<=t?e:`[${n}]\n\n${r.slice(0,t).join(`
+`)}`}function t(e,t,n){if(t<=0||e.length===0)return e;let r=e.split(`
+`).filter(e=>e.length>0);return r.length<=t?r.join(`
+`):`[${n}]\n\n${r.slice(0,t).join(`
+`)}`}function n(e,t,n){let r=Number.isFinite(t),i=Number.isFinite(n);if(!r&&!i)return{ok:!0,content:e};let a=e.split(`
+`),o=a.length>0&&a[a.length-1]===``,s=o?a.slice(0,-1):a,c=s.length;if(r&&i&&t>n)return{ok:!1,reason:`invalid-range`,total:c,startLine:t,endLine:n};let l=r?Math.max(1,t):1;if(l>c)return{ok:!1,reason:`out-of-range`,total:c,startLine:t,endLine:n};let u=i?Math.min(c,Math.max(1,n)):c,d=s.slice(l-1,u).join(`
+`);return{ok:!0,content:o?`${d}\n`:d}}export{n as sliceLines,e as truncateLines,t as truncateMatches};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { AIError, AIErrorCode } from "./errors/ai.js";
+import { ConflictError, ConflictErrorCode } from "./errors/conflict.js";
+import { BlameOptions, ConflictDiffOptions, ConflictGitOps, ConflictGitPort, ConflictGitPortMissingOpError, GrepOptions, LogOptions, OpOptions, ShowFileOptions, UnmergedEntry } from "./ports/git.js";
+import { Conflict, ConflictMarker, ConflictType } from "./types/conflict.js";
+import { extractConflict } from "./extraction/extract.js";
+import { ToolCall, ToolDefinition, ToolResult } from "./types/tool.js";
+import { ConflictModelMessage, ConflictModelParams, ConflictModelPort, ConflictModelResult, ResolverConfig } from "./ports/model.js";
+import { Resolution, ResolutionContext, ResolutionMetrics, ResolutionRefs, ResolutionStrategy, ResolvedChunk, ThreeWayDiff } from "./types/resolution.js";
+import { createResolution } from "./resolution/create-resolution.js";
+import { takeOurs, takeTheirs } from "./resolution/take-strategy.js";
+import { applyResolutions } from "./resolver/apply-resolutions.js";
+import { ConflictProgressEvent } from "./types/events.js";
+import { resolveConflict } from "./resolver/resolve-conflict.js";
+import { StepConfig, StepResult } from "./types/step.js";
+import { resolveConflicts } from "./resolver/resolve-conflicts.js";
+export { AIError, type AIErrorCode, type BlameOptions, type Conflict, type ConflictDiffOptions, ConflictError, type ConflictErrorCode, type ConflictGitOps, type ConflictGitPort, ConflictGitPortMissingOpError, type ConflictMarker, type ConflictModelMessage, type ConflictModelParams, type ConflictModelPort, type ConflictModelResult, type ConflictProgressEvent, type ConflictType, type GrepOptions, type LogOptions, type OpOptions, type Resolution, type ResolutionContext, type ResolutionMetrics, type ResolutionRefs, type ResolutionStrategy, type ResolvedChunk, type ResolverConfig, type ShowFileOptions, type StepConfig, type StepResult, type ThreeWayDiff, type ToolCall, type ToolDefinition, type ToolResult, type UnmergedEntry, applyResolutions, createResolution, extractConflict, resolveConflict, resolveConflicts, takeOurs, takeTheirs };

package/dist/index.js

@@ -0,0 +1 @@
+import{AIError as e}from"./errors/ai.js";import{ConflictError as t}from"./errors/conflict.js";import{ConflictGitPortMissingOpError as n}from"./ports/git.js";import{extractConflict as r}from"./extraction/extract.js";import{createResolution as i}from"./resolution/create-resolution.js";import{takeOurs as a,takeTheirs as o}from"./resolution/take-strategy.js";import{applyResolutions as s}from"./resolver/apply-resolutions.js";import{resolveConflict as c}from"./resolver/resolve-conflict.js";import{resolveConflicts as l}from"./resolver/resolve-conflicts.js";export{e as AIError,t as ConflictError,n as ConflictGitPortMissingOpError,s as applyResolutions,i as createResolution,r as extractConflict,c as resolveConflict,l as resolveConflicts,a as takeOurs,o as takeTheirs};

package/dist/ports/git.d.ts

@@ -0,0 +1,75 @@
+import { GitPort } from "@gitkraken/shared-tools";
+
+//#region src/ports/git.d.ts
+interface OpOptions {
+  signal?: AbortSignal;
+}
+interface ConflictDiffOptions extends OpOptions {
+  path?: string;
+}
+interface ShowFileOptions extends OpOptions {
+  startLine?: number;
+  endLine?: number;
+}
+interface BlameOptions extends OpOptions {
+  ref?: string;
+  startLine?: number;
+  endLine?: number;
+}
+interface GrepOptions extends OpOptions {
+  ref?: string;
+  maxResults?: number;
+}
+interface LogOptions extends OpOptions {
+  ref?: string;
+  path?: string;
+  maxCount?: number;
+}
+interface UnmergedEntry {
+  path: string;
+  reason: string;
+}
+interface ConflictGitOps {
+  readFile?: (path: string, opts?: OpOptions) => Promise<string>;
+  /**
+   * Returns the contents of `path` at `ref`. When `opts.startLine`/`endLine` are provided,
+   * implementations should return only that line range (1-indexed, inclusive). The library
+   * returns an actionable message instead of empty content when the requested range is fully
+   * out of bounds — applies to the exec-fallback path only.
+   */
+  showFile?: (ref: string, path: string, opts?: ShowFileOptions) => Promise<string>;
+  unmergedEntries?: (opts?: OpOptions) => Promise<UnmergedEntry[]>;
+  mergeBase?: (a: string, b: string, opts?: OpOptions) => Promise<string>;
+  /**
+   * Returns line-by-line authorship for `path`. When `opts.startLine`/`endLine` are provided,
+   * implementations should restrict to that 1-indexed inclusive range. The library does not
+   * validate the range against actual file size — invalid ranges may surface as exceptions
+   * from the underlying git command.
+   */
+  blame?: (path: string, opts?: BlameOptions) => Promise<string>;
+  /**
+   * Searches `pattern` across the working tree (or at `opts.ref`). When `opts.maxResults` is
+   * provided, implementations should return at most that many matches. Results are
+   * post-processed by the library against a hard cap of 100 matches.
+   */
+  grep?: (pattern: string, opts?: GrepOptions) => Promise<string>;
+  diff?: (from: string, to: string, opts?: ConflictDiffOptions) => Promise<string>;
+  /**
+   * Returns commit history (typically one line per commit). When `opts.maxCount` is provided,
+   * implementations should respect it (the library clamps the requested value to a hard
+   * maximum of 100 before calling).
+   */
+  log?: (opts?: LogOptions) => Promise<string>;
+  writeFile?: (path: string, content: string, opts?: OpOptions) => Promise<void>;
+  stageFiles?: (paths: string[], opts?: OpOptions) => Promise<void>;
+}
+type ConflictGitPort = ConflictGitOps & {
+  exec?: GitPort['exec'];
+};
+declare class ConflictGitPortMissingOpError extends Error {
+  readonly op: string;
+  readonly hint: string;
+  constructor(op: string, hint?: string);
+}
+//#endregion
+export { BlameOptions, ConflictDiffOptions, ConflictGitOps, ConflictGitPort, ConflictGitPortMissingOpError, GrepOptions, LogOptions, OpOptions, ShowFileOptions, UnmergedEntry };

package/dist/ports/git.js

@@ -0,0 +1 @@
+var e=class extends Error{op;hint;constructor(e,t){super(`ConflictGitPort is missing op '${e}'. `+`Provide either '${e}' directly, or provide 'exec' as a fallback. ${t??``}`.trim()),this.name=`ConflictGitPortMissingOpError`,this.op=e,this.hint=t??``}};export{e as ConflictGitPortMissingOpError};

package/dist/ports/model.d.ts

@@ -0,0 +1,39 @@
+import { ToolCall, ToolDefinition } from "../types/tool.js";
+import { AiTokenUsage } from "@gitkraken/shared-tools";
+
+//#region src/ports/model.d.ts
+interface ConflictModelPort {
+  generate(params: ConflictModelParams): Promise<ConflictModelResult>;
+}
+interface ConflictModelParams {
+  system?: string;
+  messages: ConflictModelMessage[];
+  tools?: ToolDefinition[];
+  maxTokens?: number;
+  temperature?: number;
+  signal?: AbortSignal;
+}
+type ConflictModelMessage = {
+  role: 'user';
+  content: string;
+} | {
+  role: 'assistant';
+  content?: string;
+  toolCalls?: ToolCall[];
+} | {
+  role: 'tool';
+  toolCallId: string;
+  toolName: string;
+  content: string;
+};
+interface ConflictModelResult {
+  text?: string;
+  toolCalls?: ToolCall[];
+  usage?: AiTokenUsage;
+}
+interface ResolverConfig {
+  maxSteps?: number;
+  temperature?: number;
+}
+//#endregion
+export { ConflictModelMessage, ConflictModelParams, ConflictModelPort, ConflictModelResult, ResolverConfig };

package/dist/ports/model.js

@@ -0,0 +1 @@
+export{};

package/dist/resolution/chunk-apply.d.ts

@@ -0,0 +1,7 @@
+import { ConflictMarker } from "../types/conflict.js";
+import { ResolvedChunk } from "../types/resolution.js";
+
+//#region src/resolution/chunk-apply.d.ts
+declare function applyChunks(rawContent: string, markers: ConflictMarker[], chunks: ResolvedChunk[]): string;
+//#endregion
+export { applyChunks };

package/dist/resolution/chunk-apply.js

@@ -0,0 +1,9 @@
+function e(e,n,r){let i=e.split(`
+`),a=new Map;for(let e of r)a.set(e.markerIndex,e);let o=[],s=0;for(let e=0;e<n.length;e++){let r=n[e];if(!r)continue;let c=a.get(e);if(!c)continue;r.startLine>s&&o.push(i.slice(s,r.startLine).join(`
+`));let l=t(c,r);l!==``&&o.push(l),s=r.endLine+1}return s<i.length&&o.push(i.slice(s).join(`
+`)),o.join(`
+`)}function t(e,t){switch(e.strategy){case`ours`:return t.ours;case`theirs`:return t.theirs;case`merged`:{let i=e.content.split(`
+`);return n(i,t.contextBefore),r(i,t.contextAfter),i.join(`
+`)}}}function n(e,t){if(t===``)return;let n=t.split(`
+`),r=Math.min(n.length,e.length);for(let t=r;t>0;t--){let r=!0;for(let i=0;i<t;i++)if(n[n.length-t+i]!==e[i]){r=!1;break}if(r){e.splice(0,t);return}}}function r(e,t){if(t===``)return;let n=t.split(`
+`),r=Math.min(n.length,e.length);for(let t=r;t>0;t--){let r=!0;for(let i=0;i<t;i++)if(n[i]!==e[e.length-t+i]){r=!1;break}if(r){e.splice(e.length-t,t);return}}}export{e as applyChunks};

package/dist/resolution/create-resolution.d.ts

@@ -0,0 +1,12 @@
+import { Conflict } from "../types/conflict.js";
+import { Resolution, ResolutionMetrics, ResolvedChunk } from "../types/resolution.js";
+
+//#region src/resolution/create-resolution.d.ts
+interface CreateResolutionOptions {
+  confidence: number;
+  description?: string;
+  metrics?: ResolutionMetrics;
+}
+declare function createResolution(conflict: Conflict, chunks: ResolvedChunk[], options: CreateResolutionOptions): Resolution;
+//#endregion
+export { CreateResolutionOptions, createResolution };

package/dist/resolution/create-resolution.js

@@ -0,0 +1 @@
+import{applyChunks as e}from"./chunk-apply.js";function t(t,i,a){let o=a.description!==void 0&&a.description.trim().length>0?a.description:r(i);return{filePath:t.filePath,content:e(t.rawContent,t.markers,i),strategy:n(i),confidence:a.confidence,description:o,chunks:i,...a.metrics?{metrics:a.metrics}:{}}}function n(e){if(e.length===0)return`skipped`;let t=new Set(e.map(e=>e.strategy));if(t.size===1){if(t.has(`ours`))return`take-ours`;if(t.has(`theirs`))return`take-theirs`}return`ai`}function r(e){if(e.length===0)return`No markers resolved.`;let t=new Set(e.map(e=>e.strategy));if(t.size===1){if(t.has(`ours`))return`All markers resolved by taking ours.`;if(t.has(`theirs`))return`All markers resolved by taking theirs.`}return`Resolved ${e.length} marker(s) with mixed strategies.`}export{t as createResolution};

package/dist/resolution/take-strategy.d.ts

@@ -0,0 +1,8 @@
+import { Conflict } from "../types/conflict.js";
+import { Resolution } from "../types/resolution.js";
+
+//#region src/resolution/take-strategy.d.ts
+declare function takeOurs(conflict: Conflict): Resolution;
+declare function takeTheirs(conflict: Conflict): Resolution;
+//#endregion
+export { takeOurs, takeTheirs };

package/dist/resolution/take-strategy.js

@@ -0,0 +1 @@
+import{createResolution as e}from"./create-resolution.js";function t(t){return e(t,t.markers.map((e,t)=>({markerIndex:t,strategy:`ours`})),{confidence:1})}function n(t){return e(t,t.markers.map((e,t)=>({markerIndex:t,strategy:`theirs`})),{confidence:1})}export{t as takeOurs,n as takeTheirs};

package/dist/resolver/apply-resolutions.d.ts

@@ -0,0 +1,9 @@
+import { ConflictGitPort } from "../ports/git.js";
+import { Resolution } from "../types/resolution.js";
+
+//#region src/resolver/apply-resolutions.d.ts
+declare function applyResolutions(resolutions: Resolution[], deps: {
+  git: ConflictGitPort;
+}): Promise<void>;
+//#endregion
+export { applyResolutions };

package/dist/resolver/apply-resolutions.js

@@ -0,0 +1 @@
+import{stageFiles as e,writeFile as t}from"../git/port-dispatch.js";async function n(n,r){let i=n.filter(e=>e.strategy!==`skipped`);if(i.length!==0){for(let e of i)await t(r.git,e.filePath,e.content);await e(r.git,i.map(e=>e.filePath))}}export{n as applyResolutions};

package/dist/resolver/deps.d.ts

@@ -0,0 +1,14 @@
+import { ConflictGitPort } from "../ports/git.js";
+import { ConflictModelPort, ResolverConfig } from "../ports/model.js";
+import { ConflictProgressEvent } from "../types/events.js";
+
+//#region src/resolver/deps.d.ts
+interface ResolverDeps<C extends ResolverConfig = ResolverConfig> {
+  model: ConflictModelPort;
+  git: ConflictGitPort;
+  config?: C;
+  onProgress?: (event: ConflictProgressEvent) => void;
+  signal?: AbortSignal;
+}
+//#endregion
+export { ResolverDeps };

package/dist/resolver/deps.js

@@ -0,0 +1 @@
+export{};

package/dist/resolver/loop.d.ts

@@ -0,0 +1,14 @@
+import { Conflict } from "../types/conflict.js";
+import { ResolutionContext, ResolutionMetrics, ResolvedChunk } from "../types/resolution.js";
+import { ResolverDeps } from "./deps.js";
+
+//#region src/resolver/loop.d.ts
+interface ResolverLoopResult {
+  chunks: ResolvedChunk[];
+  confidence: number;
+  description: string;
+  metrics: ResolutionMetrics;
+}
+declare function runResolverLoop(conflict: Conflict, context: ResolutionContext, deps: ResolverDeps): Promise<ResolverLoopResult>;
+//#endregion
+export { ResolverLoopResult, runResolverLoop };

package/dist/resolver/loop.js

@@ -0,0 +1 @@
+import{AIError as e}from"../errors/ai.js";import{parseModelResponse as t}from"./parse-response.js";import{buildPrompt as n}from"./prompt.js";import{createResolverTools as r}from"./tools.js";import{validateChunks as i}from"./validate.js";async function a(a,s,c){let l=c.config?.maxSteps??15,u=c.config?.temperature??0,{definitions:d,execute:f}=r(c.git),{system:p,userMessage:m}=n(a,s),h=[{role:`user`,content:m}],g=c.signal?{signal:c.signal}:void 0,_=0,v=0,y=[];for(;_<l;){_++;let e=await c.model.generate({system:p,messages:[...h],tools:d,temperature:u,signal:c.signal});if(e.usage&&(y.push(e.usage),c.onProgress?.({type:`resolver:step-usage`,filePath:a.filePath,stepNumber:_,usage:e.usage})),e.toolCalls&&e.toolCalls.length>0){h.push({role:`assistant`,content:e.text,toolCalls:e.toolCalls});for(let t of e.toolCalls){c.onProgress?.({type:`resolver:tool-call`,filePath:a.filePath,tool:t.name,args:t.args,stepNumber:_}),v++;let e=await f(t,g);h.push({role:`tool`,toolCallId:e.toolCallId,toolName:t.name,content:e.content})}continue}let n=e.text??``;if(!n.trim()){h.push({role:`assistant`,content:``}),h.push({role:`user`,content:`Your response was empty. Please respond with a valid JSON object containing "confidence" (0-1), "description" (1-2 sentences), and "chunks" (array of { markerIndex, strategy, content? }).`});continue}let r;try{r=t(n,a.markers.length)}catch(e){let t=e instanceof Error?e.message:String(e);h.push({role:`assistant`,content:n}),h.push({role:`user`,content:`Failed to parse your response: ${t}. Please respond with a valid JSON object containing "confidence" (0-1), "description" (1-2 sentences), and "chunks" (array of { markerIndex, strategy, content? }).`});continue}let s=i(r.chunks,a);if(!s.valid){h.push({role:`assistant`,content:n}),h.push({role:`user`,content:`Validation failed: ${s.feedback}\nPlease fix the issues and respond with a corrected JSON object.`});continue}return{chunks:r.chunks,confidence:r.confidence,description:r.description,metrics:o(y,_,v)}}throw new e(`VALIDATION_EXHAUSTED`,`Resolver exhausted ${l} steps without producing a valid resolution for ${a.filePath}.`)}function o(e,t,n){let r={inputTokens:0,outputTokens:0};for(let t of e)r.inputTokens+=t.inputTokens,r.outputTokens+=t.outputTokens,t.cacheReadTokens&&(r.cacheReadTokens=(r.cacheReadTokens??0)+t.cacheReadTokens),t.cacheWriteTokens&&(r.cacheWriteTokens=(r.cacheWriteTokens??0)+t.cacheWriteTokens),t.reasoningTokens&&(r.reasoningTokens=(r.reasoningTokens??0)+t.reasoningTokens),t.cost&&(r.cost=(r.cost??0)+t.cost);return{...r,stepCount:t,toolCallCount:n}}export{a as runResolverLoop};

package/dist/resolver/parse-response.d.ts

@@ -0,0 +1,11 @@
+import { ResolvedChunk } from "../types/resolution.js";
+
+//#region src/resolver/parse-response.d.ts
+interface ParsedResolution {
+  confidence: number;
+  description: string;
+  chunks: ResolvedChunk[];
+}
+declare function parseModelResponse(text: string, markerCount: number): ParsedResolution;
+//#endregion
+export { ParsedResolution, parseModelResponse };

package/dist/resolver/parse-response.js

@@ -0,0 +1 @@
+function e(e,n){let r=t(e);if(r===null)throw Error(`No valid JSON object found in model response.`);let i;try{i=JSON.parse(r)}catch{throw Error(`Failed to parse JSON from model response.`)}if(typeof i!=`object`||!i||Array.isArray(i))throw Error(`Model response must be a JSON object.`);let a=i,o=a.confidence;if(typeof o!=`number`||!Number.isFinite(o)||o<0||o>1)throw Error(`Field "confidence" must be a number in [0, 1].`);let s=a.description;if(typeof s!=`string`||s.trim().length===0)throw Error(`Field "description" must be a non-empty string.`);let c=a.chunks;if(!Array.isArray(c))throw Error(`Field "chunks" must be an array.`);let l=[];for(let e of c){if(typeof e!=`object`||!e)throw Error(`Each chunk must be an object.`);let t=e,r=t.markerIndex,i=t.strategy;if(typeof r!=`number`||!Number.isInteger(r))throw Error(`Each chunk must have an integer markerIndex.`);if(r<0||r>=n)throw Error(`markerIndex ${r} is out of range (0..${n-1}).`);if(i===`ours`||i===`theirs`)l.push({markerIndex:r,strategy:i});else if(i===`merged`){let e=t.content;if(typeof e!=`string`)throw Error(`Chunk at markerIndex ${r} with strategy "merged" must have a string "content".`);l.push({markerIndex:r,strategy:i,content:e})}else throw Error(`Unknown strategy "${String(i)}" at markerIndex ${r}.`)}return{confidence:o,description:s.trim(),chunks:l}}function t(e){let t=e.trim(),n=/```(?:json)?\s*\n([\s\S]*?)\n\s*```/.exec(t);if(n){let e=n[1];if(e!==void 0)return e.trim()}let r=/\{[\s\S]*\}/.exec(t);return r?r[0]:null}export{e as parseModelResponse};

package/dist/resolver/prompt.d.ts

@@ -0,0 +1,11 @@
+import { Conflict } from "../types/conflict.js";
+import { ResolutionContext } from "../types/resolution.js";
+
+//#region src/resolver/prompt.d.ts
+interface PromptPair {
+  system: string;
+  userMessage: string;
+}
+declare function buildPrompt(conflict: Conflict, context: ResolutionContext): PromptPair;
+//#endregion
+export { PromptPair, buildPrompt };

package/dist/resolver/prompt.js

@@ -0,0 +1,37 @@
+function e(e,r){return{system:t(e),userMessage:n(e,r)}}function t(e){let t=e.markers.length-1;return`You are a git conflict resolver. Your task is to resolve merge conflicts by analyzing the conflicting changes and producing a correct resolution for each conflict marker.
+
+You will receive a file with conflict markers. Each marker has an "ours" side (current branch) and a "theirs" side (incoming branch), and optionally a "base" (common ancestor).
+
+When provided, the "Three-way diffs" section shows what each side changed relative to the common ancestor. Prefer resolving from this data and the conflict markers. Use the tools (show_file_at_ref, grep, blame, diff, log) only when the provided context is insufficient.
+
+You have access to tools to inspect the repository: show_file_at_ref, grep, blame, diff, log. Use them to understand the intent behind each change before resolving.
+
+Tool outputs are capped to keep context manageable. Prefer narrow queries: pass startLine/endLine when you need specific regions of a file, use path scope on grep/log, and use specific patterns over broad ones. If a tool response includes a 'capped' header, the underlying data is larger — re-run with a narrower range or filter to see other regions.
+
+When you are ready to resolve, respond with a JSON object in this format:
+
+\`\`\`json
+{
+  "confidence": 0.85,
+  "description": "Combined both sides because they edited adjacent fields without conflicting intent.",
+  "chunks": [
+    { "markerIndex": 0, "strategy": "ours" },
+    { "markerIndex": 1, "strategy": "theirs" },
+    { "markerIndex": 2, "strategy": "merged", "content": "resolved code here" }
+  ]
+}
+\`\`\`
+
+Top-level fields:
+- "confidence": a number in [0, 1]. 1 = absolutely sure the resolution preserves both sides' intent. 0.5 = significant uncertainty. Lower if the conflict is ambiguous, semantics are unclear, or you had to guess.
+- "description": one or two sentences in plain English explaining WHAT was resolved and WHY. Do not give a chunk-by-chunk play-by-play.
+- "chunks": array of resolved chunks, one per conflict marker.
+
+Rules:
+- You must resolve ALL ${e.markers.length} marker(s). Every markerIndex from 0 to ${t} must appear exactly once in "chunks".
+- Use "ours" to keep the current branch version.
+- Use "theirs" to keep the incoming branch version.
+- Use "merged" with "content" when you need to combine or rewrite both sides. The content replaces only the conflict region (between <<<<<<< and >>>>>>>), not the entire file.
+- Do NOT include conflict markers (<<<<<<<, =======, >>>>>>>) in your resolved content.
+- Respond ONLY with the JSON object when you are ready. Do not wrap it in markdown code blocks.`}function n(e,t){let n=[],r=t.threeWayDiff;if(n.push(`File: ${e.filePath}`),n.push(``),t.commitMessage&&(n.push(`Commit message: ${t.commitMessage}`),n.push(``)),t.prDescription&&(n.push(`PR description: ${t.prDescription}`),n.push(``)),t.fileNeighbors&&t.fileNeighbors.length>0&&(n.push(`Related files in this directory: ${t.fileNeighbors.join(`, `)}`),n.push(``)),t.previousResolutions&&t.previousResolutions.length>0){n.push(`Previously resolved conflicts in this session:`);for(let e of t.previousResolutions)n.push(`  - ${e.filePath}: ${e.strategy} (${e.description})`);n.push(``)}if(r){let e=t.refs?.ours??`ours`,i=t.refs?.theirs??`theirs`;n.push(`Three-way diffs for this file:`),n.push(``),n.push(`--- ours changes (base → ${e}) ---`),n.push(r.oursDiff),n.push(``),n.push(`--- theirs changes (base → ${i}) ---`),n.push(r.theirsDiff),n.push(``)}n.push(`Conflict markers (${e.markers.length} total):`),n.push(``);for(let t=0;t<e.markers.length;t++){let r=e.markers[t];r&&(n.push(`--- Marker ${t} (lines ${r.startLine}-${r.endLine}) ---`),r.contextBefore&&n.push(`Context before:\n${r.contextBefore}`),n.push(`<<<<<<< ${r.oursLabel}`),n.push(r.ours),r.base!==null&&(n.push(`||||||| ${r.baseLabel??`base`}`),n.push(r.base)),n.push(`=======`),n.push(r.theirs),n.push(`>>>>>>> ${r.theirsLabel}`),r.contextAfter&&n.push(`Context after:\n${r.contextAfter}`),n.push(``))}return n.join(`
+`)}export{e as buildPrompt};

package/dist/resolver/resolve-conflict.d.ts

@@ -0,0 +1,8 @@
+import { Conflict } from "../types/conflict.js";
+import { Resolution, ResolutionContext } from "../types/resolution.js";
+import { ResolverDeps } from "./deps.js";
+
+//#region src/resolver/resolve-conflict.d.ts
+declare function resolveConflict(conflict: Conflict, context: ResolutionContext, deps: ResolverDeps): Promise<Resolution>;
+//#endregion
+export { resolveConflict };

package/dist/resolver/resolve-conflict.js

@@ -0,0 +1 @@
+import{createResolution as e}from"../resolution/create-resolution.js";import{runResolverLoop as t}from"./loop.js";import{buildThreeWayDiff as n}from"./three-way-diff.js";async function r(r,i,a){let{chunks:o,confidence:s,description:c,metrics:l}=await t(r,i.threeWayDiff||!i.refs?i:{...i,threeWayDiff:await n(r.filePath,i.refs,{git:a.git,signal:a.signal})},{model:a.model,git:a.git,config:a.config,onProgress:a.onProgress,signal:a.signal}),u=e(r,o,{confidence:s,description:c,metrics:l});return a.onProgress?.({type:`resolver:completed`,filePath:r.filePath,stepCount:l.stepCount??0}),u}export{r as resolveConflict};

package/dist/resolver/resolve-conflicts.d.ts

@@ -0,0 +1,9 @@
+import { ResolutionContext } from "../types/resolution.js";
+import { ResolverDeps } from "./deps.js";
+import { StepConfig, StepResult } from "../types/step.js";
+
+//#region src/resolver/resolve-conflicts.d.ts
+type ResolveConflictsDeps = ResolverDeps<StepConfig>;
+declare function resolveConflicts(deps: ResolveConflictsDeps, context?: ResolutionContext): Promise<StepResult>;
+//#endregion
+export { ResolveConflictsDeps, resolveConflicts };

package/dist/resolver/resolve-conflicts.js

@@ -0,0 +1 @@
+import{AIError as e}from"../errors/ai.js";import{unmergedEntries as t}from"../git/port-dispatch.js";import{extractConflict as n}from"../extraction/extract.js";import{takeOurs as r,takeTheirs as i}from"../resolution/take-strategy.js";import{resolveConflict as a}from"./resolve-conflict.js";import o from"picomatch";async function s(e,r){let i=e.config?.excludeFiles??[],a=i.length>0?o(i,{basename:!0}):()=>!1,s=(await t(e.git,{signal:e.signal})).filter(e=>!a(e.path)),u={...r??{}},d=[],f=[];for(let t of s){if(e.signal?.aborted)break;let r;try{r=await n(t.path,{git:e.git,signal:e.signal})}catch(e){f.push({filePath:t.path,error:l(e)});continue}if(!r)continue;e.onProgress?.({type:`conflict:found`,filePath:r.filePath,conflictType:r.type,markerCount:r.markers.length});let i=await c(r,u,e,f);i&&(u.previousResolutions=[...u.previousResolutions??[],i],d.push(i),e.onProgress?.({type:`resolution:applied`,filePath:i.filePath,strategy:i.strategy,confidence:i.confidence,description:i.description}))}return{resolutions:d,errors:f}}async function c(t,n,o,s){try{return await a(t,n,{model:o.model,git:o.git,config:o.config,onProgress:o.onProgress,signal:o.signal})}catch(n){let a=l(n),c=o.config?.fallbackStrategy;return c?(o.onProgress?.({type:`resolution:fallback`,filePath:t.filePath,error:a,cause:a instanceof e?a.code:void 0}),c===`take-ours`?r(t):i(t)):(s.push({filePath:t.filePath,error:a}),o.onProgress?.({type:`resolution:failed`,filePath:t.filePath,error:a}),null)}}function l(e){return e instanceof Error?e:Error(String(e))}export{s as resolveConflicts};

package/dist/resolver/three-way-diff.d.ts

@@ -0,0 +1,10 @@
+import { ConflictGitPort } from "../ports/git.js";
+import { ResolutionRefs, ThreeWayDiff } from "../types/resolution.js";
+
+//#region src/resolver/three-way-diff.d.ts
+declare function buildThreeWayDiff(filePath: string, refs: ResolutionRefs, deps: {
+  git: ConflictGitPort;
+  signal?: AbortSignal;
+}): Promise<ThreeWayDiff>;
+//#endregion
+export { buildThreeWayDiff };

package/dist/resolver/three-way-diff.js

@@ -0,0 +1 @@
+import{diff as e,mergeBase as t}from"../git/port-dispatch.js";async function n(n,r,i){let a=r.base??await t(i.git,r.ours,r.theirs,{signal:i.signal}),[o,s]=await Promise.all([e(i.git,a,r.ours,{path:n,signal:i.signal}),e(i.git,a,r.theirs,{path:n,signal:i.signal})]);return{oursDiff:o,theirsDiff:s}}export{n as buildThreeWayDiff};

package/dist/resolver/tools.d.ts

@@ -0,0 +1,11 @@
+import { ConflictGitPort, OpOptions } from "../ports/git.js";
+import { ToolCall, ToolDefinition, ToolResult } from "../types/tool.js";
+
+//#region src/resolver/tools.d.ts
+interface ResolverTools {
+  definitions: ToolDefinition[];
+  execute: (call: ToolCall, opts?: OpOptions) => Promise<ToolResult>;
+}
+declare function createResolverTools(git: ConflictGitPort): ResolverTools;
+//#endregion
+export { createResolverTools };

package/dist/resolver/tools.js

@@ -0,0 +1 @@
+import{blame as e,diff as t,grep as n,log as r,showFile as i}from"../git/port-dispatch.js";function a(e,t){let n=e[t];if(!(typeof n!=`number`||!Number.isInteger(n)))return Math.max(1,n)}function o(o){let s={show_file_at_ref:async(e,t)=>{let n=String(e.ref??``),r=String(e.path??``),s=a(e,`startLine`),c=a(e,`endLine`);return i(o,n,r,{...t,startLine:s,endLine:c})},grep:async(e,t)=>{let r=String(e.pattern??``),i=e.ref==null?void 0:String(e.ref),s=a(e,`maxResults`);return n(o,r,{...t,ref:i,maxResults:s})},blame:async(t,n)=>{let r=String(t.path??``),i=t.ref==null?void 0:String(t.ref),s=a(t,`startLine`),c=a(t,`endLine`);return e(o,r,{...n,ref:i,startLine:s,endLine:c})},diff:async(e,n)=>{let r=String(e.from??``),i=String(e.to??``),a=e.path==null?void 0:String(e.path);return t(o,r,i,{...n,path:a})},log:async(e,t)=>{let n=e.ref==null?void 0:String(e.ref),i=e.path==null?void 0:String(e.path),s=a(e,`maxCount`);return r(o,{...t,ref:n,path:i,maxCount:s})}},c=[{name:`show_file_at_ref`,description:`Show the contents of a file at a specific git ref (commit, branch, tag). Output is capped at 1000 lines — pass startLine/endLine to read a specific region of a larger file.`,parameters:{type:`object`,properties:{ref:{type:`string`,description:`Git ref (commit SHA, branch name, tag).`},path:{type:`string`,description:`File path relative to the repository root.`},startLine:{type:`integer`,description:`Optional 1-indexed start line (inclusive). Use with endLine to read a region.`},endLine:{type:`integer`,description:`Optional 1-indexed end line (inclusive).`}},required:[`ref`,`path`]}},{name:`grep`,description:`Search for a pattern in the repository using git grep. Results are capped at 100 matches — narrow the search with a more specific pattern, a path scope, or a smaller maxResults.`,parameters:{type:`object`,properties:{pattern:{type:`string`,description:`Search pattern.`},ref:{type:`string`,description:`Optional git ref to search in.`},maxResults:{type:`integer`,description:`Optional cap on returned matches (default 100, hard maximum 100).`}},required:[`pattern`]}},{name:`blame`,description:`Show git blame (line-by-line authorship) for a file. Output is capped at 1000 lines — pass startLine/endLine to inspect a specific region.`,parameters:{type:`object`,properties:{path:{type:`string`,description:`File path relative to the repository root.`},ref:{type:`string`,description:`Optional git ref to blame at.`},startLine:{type:`integer`,description:`Optional 1-indexed start line (inclusive). Maps to git blame -L start,end.`},endLine:{type:`integer`,description:`Optional 1-indexed end line (inclusive).`}},required:[`path`]}},{name:`diff`,description:`Show the diff between two git refs.`,parameters:{type:`object`,properties:{from:{type:`string`,description:`Source git ref.`},to:{type:`string`,description:`Target git ref.`},path:{type:`string`,description:`Optional file path to scope the diff.`}},required:[`from`,`to`]}},{name:`log`,description:`Show commit history (one line per commit). Output is capped at 100 commits — pass a path to scope to a single file or refine the ref range to focus the view.`,parameters:{type:`object`,properties:{ref:{type:`string`,description:`Optional git ref to log from.`},path:{type:`string`,description:`Optional file path to scope the log.`},maxCount:{type:`integer`,description:`Optional maximum number of commits to return (default 100, hard maximum 100).`}},required:[]}}];async function l(e,t){let n=s[e.name];if(!n)return{toolCallId:e.id,content:`Unknown tool: ${e.name}`,isError:!0};try{let r=await n(e.args,t);return{toolCallId:e.id,content:r}}catch(t){let n=t instanceof Error?t.message:String(t);return{toolCallId:e.id,content:n,isError:!0}}}return{definitions:c,execute:l}}export{o as createResolverTools};

package/dist/resolver/validate.d.ts

@@ -0,0 +1,11 @@
+import { Conflict } from "../types/conflict.js";
+import { ResolvedChunk } from "../types/resolution.js";
+
+//#region src/resolver/validate.d.ts
+interface ValidationResult {
+  valid: boolean;
+  feedback: string;
+}
+declare function validateChunks(chunks: ResolvedChunk[], conflict: Conflict): ValidationResult;
+//#endregion
+export { ValidationResult, validateChunks };

package/dist/resolver/validate.js

@@ -0,0 +1,2 @@
+const e=[/^<{7}(\s|$)/,/^\|{7}(\s|$)/,/^={7}(\s|$)/,/^>{7}(\s|$)/];function t(t,n){let r=[],i=n.markers.length,a=new Set;for(let e of t)a.has(e.markerIndex)&&r.push(`Duplicate markerIndex ${e.markerIndex}.`),a.add(e.markerIndex);for(let e=0;e<i;e++)a.has(e)||r.push(`Missing resolution for marker ${e}.`);for(let n of t)if(n.strategy===`merged`){let t=n.content.split(`
+`);for(let i of t)for(let t of e)t.test(i)&&r.push(`Marker ${n.markerIndex}: resolved content contains conflict marker "${i.trim()}".`)}return r.length===0?{valid:!0,feedback:``}:{valid:!1,feedback:r.join(` `)}}export{t as validateChunks};

package/dist/types/conflict.d.ts

@@ -0,0 +1,22 @@
+//#region src/types/conflict.d.ts
+type ConflictType = 'text';
+interface ConflictMarker {
+  startLine: number;
+  endLine: number;
+  ours: string;
+  base: string | null;
+  theirs: string;
+  oursLabel: string;
+  theirsLabel: string;
+  baseLabel: string | null;
+  contextBefore: string;
+  contextAfter: string;
+}
+interface Conflict {
+  filePath: string;
+  markers: ConflictMarker[];
+  type: ConflictType;
+  rawContent: string;
+}
+//#endregion
+export { Conflict, ConflictMarker, ConflictType };

package/dist/types/conflict.js

@@ -0,0 +1 @@
+export{};

package/dist/types/events.d.ts

@@ -0,0 +1,43 @@
+import { ConflictType } from "./conflict.js";
+import { ResolutionStrategy } from "./resolution.js";
+import { AiTokenUsage } from "@gitkraken/shared-tools";
+
+//#region src/types/events.d.ts
+type ConflictProgressEvent = {
+  type: 'conflict:found';
+  filePath: string;
+  conflictType: ConflictType;
+  markerCount: number;
+} | {
+  type: 'resolution:applied';
+  filePath: string;
+  strategy: ResolutionStrategy;
+  confidence?: number;
+  description?: string;
+} | {
+  type: 'resolution:fallback';
+  filePath: string;
+  error: Error;
+  cause?: string;
+} | {
+  type: 'resolution:failed';
+  filePath: string;
+  error: Error;
+} | {
+  type: 'resolver:tool-call';
+  filePath: string;
+  tool: string;
+  args: Record<string, unknown>;
+  stepNumber: number;
+} | {
+  type: 'resolver:step-usage';
+  filePath: string;
+  stepNumber: number;
+  usage: AiTokenUsage;
+} | {
+  type: 'resolver:completed';
+  filePath: string;
+  stepCount: number;
+};
+//#endregion
+export { ConflictProgressEvent };

package/dist/types/events.js

@@ -0,0 +1 @@
+export{};

package/dist/types/resolution.d.ts

@@ -0,0 +1,48 @@
+import { AiTokenUsage } from "@gitkraken/shared-tools";
+
+//#region src/types/resolution.d.ts
+type ResolutionStrategy = 'ai' | 'take-ours' | 'take-theirs' | 'skipped';
+type ResolvedChunk = {
+  markerIndex: number;
+  strategy: 'ours' | 'theirs';
+} | {
+  markerIndex: number;
+  strategy: 'merged';
+  content: string;
+};
+interface Resolution {
+  filePath: string;
+  content: string;
+  strategy: ResolutionStrategy;
+  confidence: number;
+  description: string;
+  note?: string;
+  chunks?: ResolvedChunk[];
+  metrics?: ResolutionMetrics;
+}
+interface ResolutionRefs {
+  ours: string;
+  theirs: string;
+  base?: string;
+}
+interface ThreeWayDiff {
+  oursDiff: string;
+  theirsDiff: string;
+}
+interface ResolutionContext {
+  commitMessage?: string;
+  prDescription?: string;
+  previousResolutions?: Resolution[];
+  fileNeighbors?: string[];
+  refs?: ResolutionRefs;
+  threeWayDiff?: ThreeWayDiff;
+  metadata?: Record<string, unknown>;
+}
+interface ResolutionMetrics extends AiTokenUsage {
+  stepCount?: number;
+  toolCallCount?: number;
+  durationMs?: number;
+  metadata?: Record<string, unknown>;
+}
+//#endregion
+export { Resolution, ResolutionContext, ResolutionMetrics, ResolutionRefs, ResolutionStrategy, ResolvedChunk, ThreeWayDiff };

package/dist/types/resolution.js

@@ -0,0 +1 @@
+export{};

package/dist/types/step.d.ts

@@ -0,0 +1,17 @@
+import { ResolverConfig } from "../ports/model.js";
+import { Resolution } from "./resolution.js";
+
+//#region src/types/step.d.ts
+interface StepResult {
+  resolutions: Resolution[];
+  errors: {
+    filePath: string;
+    error: Error;
+  }[];
+}
+interface StepConfig extends ResolverConfig {
+  excludeFiles?: string[];
+  fallbackStrategy?: 'take-ours' | 'take-theirs';
+}
+//#endregion
+export { StepConfig, StepResult };

package/dist/types/step.js

@@ -0,0 +1 @@
+export{};

package/dist/types/tool.d.ts

@@ -0,0 +1,18 @@
+//#region src/types/tool.d.ts
+interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+interface ToolCall {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+}
+interface ToolResult {
+  toolCallId: string;
+  content: string;
+  isError?: boolean;
+}
+//#endregion
+export { ToolCall, ToolDefinition, ToolResult };

package/dist/types/tool.js

@@ -0,0 +1 @@
+export{};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@gitkraken/conflict-tools",
+  "version": "0.0.1-beta.1",
+  "description": "AI-powered git conflict resolution.",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Axosoft, LLC dba GitKraken",
+  "engines": {
+    "node": ">= 22"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "picomatch": "^4.0.4",
+    "@gitkraken/shared-tools": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/picomatch": "^4.0.3",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  },
+  "scripts": {
+    "build": "tsdown --config-loader=unrun",
+    "build:dev": "tsdown --config tsdown.dev.config.ts --config-loader=unrun",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}