@google/jules-merge 0.0.1

package/README.md

@@ -0,0 +1,201 @@
+# Jules Merge
+
+Detect and surface merge conflicts between a coding agent's changes and the base branch — before or during CI.
+
+## Check for conflicts in CI
+
+```bash
+npx @google/jules-merge check-conflicts \
+  --repo your-org/your-repo \
+  --pr 42 \
+  --sha abc123
+```
+
+When a merge has already been attempted, `check-conflicts` reads conflict markers from the filesystem and returns structured JSON with the affected files, their conflict markers, and a task directive that tells the agent exactly what to resolve.
+
+## Check for conflicts proactively
+
+```bash
+npx @google/jules-merge check-conflicts \
+  --session 7439826373470093109 \
+  --repo your-org/your-repo
+```
+
+This queries the Jules SDK for the session's changed files and compares them against recent commits on the base branch. If files overlap, it returns the remote file content (`remoteShadowContent`) so the agent can resolve conflicts without needing `git pull`.
+
+## Generate a CI workflow
+
+```bash
+npx @google/jules-merge init
+```
+
+Writes `.github/workflows/jules-merge-check.yml` to your repo. The workflow runs on every pull request: it attempts a merge, and if conflicts exist, runs `check-conflicts` to produce structured output that Jules can act on.
+
+```bash
+npx @google/jules-merge init --base-branch develop --force
+```
+
+## Installation
+
+```bash
+npm i @google/jules-merge
+```
+
+For session-based checks, set authentication:
+
+```
+JULES_API_KEY         Required for session mode.
+GITHUB_TOKEN          Required. GitHub PAT with repo access.
+```
+
+Or use GitHub App authentication:
+
+```
+GITHUB_APP_ID                   App ID
+GITHUB_APP_PRIVATE_KEY_BASE64   Base64-encoded private key
+GITHUB_APP_INSTALLATION_ID      Installation ID
+```
+
+## CLI Reference
+
+### `jules-merge check-conflicts`
+
+Detect merge conflicts. Mode is inferred from the arguments provided.
+
+```
+jules-merge check-conflicts [options]
+
+Session mode (proactive):
+  --session <id>     Jules session ID
+  --repo <owner/repo>
+  --base <branch>    Base branch (default: main)
+
+Git mode (CI failure):
+  --pr <number>      Pull request number
+  --sha <sha>        Failing commit SHA
+  --repo <owner/repo>
+```
+
+**Session mode** queries the Jules SDK for changed files and compares them against remote commits. Returns `remoteShadowContent` for each conflicting file.
+
+**Git mode** reads `git status` for unmerged files and extracts conflict markers. Returns a `taskDirective` with resolution instructions.
+
+### `jules-merge init`
+
+Generate a GitHub Actions workflow for automated conflict detection.
+
+```
+jules-merge init [options]
+
+Options:
+  --output-dir <dir>         Directory to write into (default: .)
+  --workflow-name <name>     Filename without .yml (default: jules-merge-check)
+  --base-branch <branch>     Branch to check against (default: main)
+  --force                    Overwrite existing file
+```
+
+## Programmatic API
+
+All handlers are exported for use in scripts, CI pipelines, or other packages.
+
+```ts
+import {
+  SessionCheckHandler,
+  GitCheckHandler,
+  InitHandler,
+} from '@google/jules-merge';
+```
+
+### `SessionCheckHandler`
+
+Compares a Jules session's changed files against remote commits on the base branch.
+
+```ts
+const handler = new SessionCheckHandler(octokit, julesClient);
+const result = await handler.execute({
+  sessionId: '7439826373470093109',
+  repo: 'your-org/your-repo',
+  base: 'main',
+});
+
+if (result.success && result.data.status === 'conflict') {
+  for (const conflict of result.data.conflicts) {
+    console.log(`${conflict.filePath}: ${conflict.conflictReason}`);
+    console.log(conflict.remoteShadowContent);
+  }
+}
+```
+
+Returns `{ status: 'clean' | 'conflict', conflicts: [...] }` on success. Each conflict includes `filePath`, `conflictReason`, and `remoteShadowContent`.
+
+### `GitCheckHandler`
+
+Reads conflict markers from the local filesystem after a failed merge.
+
+```ts
+const handler = new GitCheckHandler();
+const result = await handler.execute({
+  repo: 'your-org/your-repo',
+  pullRequestNumber: 42,
+  failingCommitSha: 'abc123',
+});
+
+if (result.success) {
+  console.log(result.data.taskDirective);
+  for (const file of result.data.affectedFiles) {
+    console.log(`${file.filePath}: ${file.gitConflictMarkers}`);
+  }
+}
+```
+
+Returns `{ taskDirective, priority, affectedFiles: [...] }` on success. Each file includes `filePath`, `baseCommitSha`, and `gitConflictMarkers`.
+
+### `InitHandler`
+
+Generates a GitHub Actions workflow file.
+
+```ts
+const handler = new InitHandler();
+const result = await handler.execute({
+  outputDir: '.',
+  workflowName: 'jules-merge-check',
+  baseBranch: 'main',
+  force: false,
+});
+
+if (result.success) {
+  console.log(`Created: ${result.data.filePath}`);
+}
+```
+
+Returns `{ filePath, content }` on success.
+
+### `buildWorkflowYaml`
+
+Generate the workflow YAML string without writing to disk.
+
+```ts
+import { buildWorkflowYaml } from '@google/jules-merge';
+
+const yaml = buildWorkflowYaml({
+  workflowName: 'merge-check',
+  baseBranch: 'main',
+});
+```
+
+## MCP Server
+
+The package exposes an MCP server with two tools:
+
+- **`check_conflicts`** — Detects merge conflicts (session or git mode)
+- **`init_workflow`** — Generates a CI workflow file
+
+```bash
+jules-merge mcp
+```
+
+## License
+
+Apache-2.0
+
+> **Note:** This is not an officially supported Google product. This project is not eligible for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).

package/dist/cli/check-conflicts.command.mjs

@@ -0,0 +1,387 @@
+// src/cli/check-conflicts.command.ts
+import { defineCommand } from "citty";
+
+// src/conflicts/session-spec.ts
+import { z } from "zod";
+var SessionCheckInputSchema = z.object({
+  sessionId: z.string().min(1, "Session ID is required"),
+  repo: z.string().min(1).refine((s) => s.includes("/"), "Must be in owner/repo format"),
+  base: z.string().default("main")
+});
+var SessionCheckErrorCode = z.enum([
+  "SESSION_QUERY_FAILED",
+  "GITHUB_API_ERROR",
+  "RATE_LIMIT_EXCEEDED",
+  "UNKNOWN_ERROR"
+]);
+
+// src/shared/result.ts
+function ok(data) {
+  return { success: true, data };
+}
+function fail(code, message, recoverable = false, suggestion) {
+  return { success: false, error: { code, message, recoverable, suggestion } };
+}
+
+// src/shared/session.ts
+import { jules } from "@google/jules-sdk";
+async function getSessionChangedFiles(client, sessionId) {
+  const session = client.session(sessionId);
+  await session.activities.hydrate();
+  const snapshot = await session.snapshot();
+  const isBusy = isBusyState(snapshot.state);
+  if (isBusy) {
+    return aggregateFromActivities(snapshot.activities ?? []);
+  }
+  const changeSet = typeof snapshot.changeSet === "function" ? snapshot.changeSet() : undefined;
+  if (!changeSet)
+    return [];
+  const parsed = changeSet.parsed();
+  return parsed.files.map((f) => ({
+    path: f.path,
+    changeType: f.changeType
+  }));
+}
+function isBusyState(state) {
+  const busy = new Set([
+    "queued",
+    "planning",
+    "inProgress",
+    "in_progress"
+  ]);
+  return busy.has(state);
+}
+function aggregateFromActivities(activities) {
+  const fileMap = new Map;
+  for (const activity of activities) {
+    for (const artifact of activity.artifacts) {
+      if (artifact.type === "changeSet") {
+        const parsed = artifact.parsed();
+        for (const file of parsed.files) {
+          const existing = fileMap.get(file.path);
+          if (existing) {
+            existing.latestChangeType = file.changeType;
+          } else {
+            fileMap.set(file.path, {
+              firstChangeType: file.changeType,
+              latestChangeType: file.changeType
+            });
+          }
+        }
+      }
+    }
+  }
+  const result = [];
+  for (const [path, info] of fileMap) {
+    if (info.firstChangeType === "created" && info.latestChangeType === "deleted") {
+      continue;
+    }
+    const netType = info.firstChangeType === "created" ? "created" : info.latestChangeType;
+    result.push({ path, changeType: netType });
+  }
+  return result;
+}
+
+// src/shared/github.ts
+import { Octokit } from "@octokit/rest";
+import { createAppAuth } from "@octokit/auth-app";
+function createOctokit() {
+  const appId = process.env.GITHUB_APP_ID;
+  const privateKeyBase64 = process.env.GITHUB_APP_PRIVATE_KEY_BASE64;
+  const privateKeyRaw = process.env.GITHUB_APP_PRIVATE_KEY;
+  const installationId = process.env.GITHUB_APP_INSTALLATION_ID;
+  if (appId && (privateKeyBase64 || privateKeyRaw) && installationId) {
+    const privateKey = privateKeyBase64 ? Buffer.from(privateKeyBase64, "base64").toString("utf-8") : privateKeyRaw;
+    return new Octokit({
+      authStrategy: createAppAuth,
+      auth: {
+        appId,
+        privateKey,
+        installationId: Number(installationId)
+      }
+    });
+  }
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  if (token) {
+    return new Octokit({ auth: token });
+  }
+  throw new Error("GitHub auth not configured. Set GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY + GITHUB_APP_INSTALLATION_ID for App auth, or GITHUB_TOKEN for PAT auth.");
+}
+async function compareCommits(octokit, owner, repo, base, head) {
+  const { data } = await octokit.repos.compareCommits({
+    owner,
+    repo,
+    base,
+    head
+  });
+  return (data.files ?? []).map((f) => f.filename);
+}
+async function getFileContent(octokit, owner, repo, path, ref) {
+  try {
+    const { data } = await octokit.repos.getContent({
+      owner,
+      repo,
+      path,
+      ref
+    });
+    if ("content" in data && typeof data.content === "string") {
+      return Buffer.from(data.content, "base64").toString("utf-8");
+    }
+    return "";
+  } catch (error) {
+    if (error?.status === 404) {
+      return "";
+    }
+    throw error;
+  }
+}
+
+// src/conflicts/session-handler.ts
+class SessionCheckHandler {
+  octokit;
+  julesClient;
+  constructor(octokit, julesClient) {
+    this.octokit = octokit;
+    this.julesClient = julesClient;
+  }
+  async execute(input) {
+    try {
+      const [owner, repo] = input.repo.split("/");
+      let sessionPaths;
+      try {
+        const sessionFiles = await getSessionChangedFiles(this.julesClient, input.sessionId);
+        sessionPaths = sessionFiles.map((f) => f.path);
+      } catch (error) {
+        return fail("SESSION_QUERY_FAILED", `Failed to query session ${input.sessionId}: ${error.message}`, true, "Verify the session ID is correct and JULES_API_KEY is set.");
+      }
+      let remoteFiles;
+      try {
+        remoteFiles = await compareCommits(this.octokit, owner, repo, input.base, "HEAD");
+      } catch (error) {
+        return fail("GITHUB_API_ERROR", `Failed to compare commits: ${error.message}`, true, "Check GITHUB_TOKEN and repository access.");
+      }
+      const remoteSet = new Set(remoteFiles);
+      const overlapping = sessionPaths.filter((f) => remoteSet.has(f));
+      if (overlapping.length === 0) {
+        return ok({
+          status: "clean",
+          message: "No conflicts detected.",
+          conflicts: []
+        });
+      }
+      const conflicts = await Promise.all(overlapping.map(async (filePath) => {
+        const remoteShadowContent = await getFileContent(this.octokit, owner, repo, filePath, input.base);
+        return {
+          filePath,
+          conflictReason: "Remote commit modified this file since branch creation.",
+          remoteShadowContent
+        };
+      }));
+      return ok({
+        status: "conflict",
+        message: `The remote ${input.base} branch has advanced. Rebase required for ${overlapping.join(", ")}.`,
+        conflicts
+      });
+    } catch (error) {
+      return fail("UNKNOWN_ERROR", error instanceof Error ? error.message : String(error), false);
+    }
+  }
+}
+
+// src/conflicts/git-spec.ts
+import { z as z2 } from "zod";
+var GitCheckInputSchema = z2.object({
+  repo: z2.string().min(1).refine((s) => s.includes("/"), "Must be in owner/repo format"),
+  pullRequestNumber: z2.number().int().positive(),
+  failingCommitSha: z2.string().min(1)
+});
+var GitCheckErrorCode = z2.enum([
+  "NO_UNMERGED_FILES",
+  "GIT_STATUS_FAILED",
+  "FILE_READ_FAILED",
+  "UNKNOWN_ERROR"
+]);
+
+// src/conflicts/git-handler.ts
+import { readFile } from "node:fs/promises";
+
+// src/shared/git.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile);
+async function gitStatusUnmerged(cwd) {
+  try {
+    const { stdout } = await execFileAsync("git", ["status", "--porcelain"], { cwd });
+    const files = stdout.split(`
+`).filter((line) => line.startsWith("UU ")).map((line) => line.slice(3).trim());
+    return { ok: true, data: files };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function gitMergeBase(head, base, cwd) {
+  try {
+    const { stdout } = await execFileAsync("git", ["merge-base", head, base], { cwd });
+    return { ok: true, data: stdout.trim() };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/conflicts/git-handler.ts
+class GitCheckHandler {
+  async execute(input) {
+    try {
+      const statusResult = await gitStatusUnmerged();
+      if (!statusResult.ok) {
+        return fail("GIT_STATUS_FAILED", `Failed to get git status: ${statusResult.error}`, true, "Ensure git is available and the working directory is a repository.");
+      }
+      const unmergedFiles = statusResult.data;
+      if (unmergedFiles.length === 0) {
+        return fail("NO_UNMERGED_FILES", "No unmerged files found. The merge conflict may have already been resolved.", false);
+      }
+      const affectedFiles = await Promise.all(unmergedFiles.map(async (filePath) => {
+        let content;
+        try {
+          content = await readFile(filePath, "utf-8");
+        } catch (error) {
+          return {
+            filePath,
+            baseCommitSha: "",
+            gitConflictMarkers: `[Error reading file: ${error.message}]`
+          };
+        }
+        const markers = extractConflictMarkers(content);
+        return {
+          filePath,
+          baseCommitSha: "",
+          gitConflictMarkers: markers
+        };
+      }));
+      const mergeBaseResult = await gitMergeBase(input.failingCommitSha, "HEAD");
+      const baseSha = mergeBaseResult.ok ? mergeBaseResult.data : "unknown";
+      for (const file of affectedFiles) {
+        file.baseCommitSha = baseSha;
+      }
+      const taskDirective = [
+        `MERGE CONFLICT RESOLUTION REQUIRED for PR #${input.pullRequestNumber}.`,
+        `Failing commit: ${input.failingCommitSha}.`,
+        `${affectedFiles.length} file(s) have unresolved conflicts.`,
+        `Review the gitConflictMarkers for each file and rewrite the code to resolve all conflicts.`
+      ].join(`
+`);
+      return ok({
+        taskDirective,
+        priority: "critical",
+        affectedFiles
+      });
+    } catch (error) {
+      return fail("UNKNOWN_ERROR", error instanceof Error ? error.message : String(error), false);
+    }
+  }
+}
+function extractConflictMarkers(content) {
+  const lines = content.split(`
+`);
+  const blocks = [];
+  let inConflict = false;
+  let currentBlock = [];
+  for (const line of lines) {
+    if (line.startsWith("<<<<<<<")) {
+      inConflict = true;
+      currentBlock = [line];
+    } else if (line.startsWith(">>>>>>>") && inConflict) {
+      currentBlock.push(line);
+      blocks.push(currentBlock.join(`
+`));
+      inConflict = false;
+      currentBlock = [];
+    } else if (inConflict) {
+      currentBlock.push(line);
+    }
+  }
+  return blocks.join(`
+---
+`);
+}
+
+// src/cli/check-conflicts.command.ts
+var check_conflicts_command_default = defineCommand({
+  meta: {
+    name: "check-conflicts",
+    description: "Check for merge conflicts between a Jules session and the remote base branch, or parse an existing CI merge failure."
+  },
+  args: {
+    session: {
+      type: "string",
+      description: "Jules session ID (triggers session mode)"
+    },
+    repo: {
+      type: "string",
+      description: "Repository in owner/repo format"
+    },
+    base: {
+      type: "string",
+      description: "Base branch (session mode only)",
+      default: "main"
+    },
+    pr: {
+      type: "string",
+      description: "Pull request number (triggers git mode)"
+    },
+    sha: {
+      type: "string",
+      description: "Failing commit SHA (git mode only)"
+    }
+  },
+  async run({ args }) {
+    const isSessionMode = !!args.session;
+    const isGitMode = !!args.pr;
+    if (!isSessionMode && !isGitMode) {
+      console.error("Either --session (session mode) or --pr (git mode) is required.");
+      process.exit(2);
+    }
+    if (isSessionMode && isGitMode) {
+      console.error("Cannot use both --session and --pr. Pick one mode.");
+      process.exit(2);
+    }
+    let result;
+    if (isSessionMode) {
+      if (!args.repo) {
+        console.error("--repo is required in session mode.");
+        process.exit(2);
+      }
+      const input = SessionCheckInputSchema.parse({
+        sessionId: args.session,
+        repo: args.repo,
+        base: args.base
+      });
+      const handler = new SessionCheckHandler(createOctokit(), jules);
+      result = await handler.execute(input);
+    } else {
+      if (!args.repo || !args.sha) {
+        console.error("--repo and --sha are required in git mode.");
+        process.exit(2);
+      }
+      const input = GitCheckInputSchema.parse({
+        repo: args.repo,
+        pullRequestNumber: parseInt(args.pr, 10),
+        failingCommitSha: args.sha
+      });
+      const handler = new GitCheckHandler;
+      result = await handler.execute(input);
+    }
+    process.stdout.write(JSON.stringify(result, null, 2) + `
+`);
+    process.exit(result.success ? 0 : 1);
+  }
+});
+export {
+  check_conflicts_command_default as default
+};

package/dist/cli/index.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { readdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import { defineCommand, runMain } from "citty";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+async function discoverCommands() {
+  const commands = {};
+  const files = readdirSync(__dirname2).filter((f) => f.endsWith(".command.ts") || f.endsWith(".command.js") || f.endsWith(".command.mjs"));
+  for (const file of files) {
+    const name = file.replace(/\.command\.(ts|js|mjs)$/, "");
+    const mod = await import(pathToFileURL(join(__dirname2, file)).href);
+    commands[name] = mod.default;
+  }
+  return commands;
+}
+var subCommands = await discoverCommands();
+var main = defineCommand({
+  meta: {
+    name: "jules-merge",
+    version: "0.0.1",
+    description: "Predictive conflict detection for parallel AI agents"
+  },
+  subCommands
+});
+runMain(main);