@google/jules-merge 0.0.1

package/dist/core/src/utils/page-token.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Utilities for constructing and parsing Jules API pageTokens.
+ *
+ * The Jules API uses nanosecond timestamps as pageTokens for activity pagination.
+ * This allows us to construct tokens from cached activity createTimes,
+ * enabling efficient incremental syncing without re-downloading existing activities.
+ *
+ * @module
+ */
+/**
+ * Converts a Jules API pageToken back to a Date.
+ * Useful for debugging and logging.
+ *
+ * @param token - The pageToken string (nanosecond timestamp)
+ * @returns The corresponding Date object
+ *
+ * @example
+ * ```typescript
+ * const date = pageTokenToDate("1704448500999999000");
+ * // Returns Date for 2024-01-05T10:05:00.999Z
+ * ```
+ */
+export declare function pageTokenToDate(token: string): Date;
+/**
+ * Checks if a session's activities are "frozen" (no new activities possible).
+ * A session is considered frozen if its last activity is older than the threshold.
+ *
+ * @param lastActivityCreateTime - The createTime of the most recent activity
+ * @param thresholdDays - Number of days after which a session is frozen (default: 30)
+ * @returns true if the session is frozen and no API call is needed
+ *
+ * @example
+ * ```typescript
+ * const isFrozen = isSessionFrozen("2024-01-05T10:05:00Z");
+ * if (isFrozen) {
+ *   // Skip API call - no new activities will ever appear
+ * }
+ * ```
+ */
+export declare function isSessionFrozen(lastActivityCreateTime: string, thresholdDays?: number): boolean;

package/dist/core/src/utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The internal engine for jules.all()
+ *
+ * @param items - Data to process
+ * @param mapper - Async function (item) => result
+ * @param options - Configuration options
+ */
+export declare function pMap<T, R>(items: T[], mapper: (item: T, index: number) => Promise<R>, options?: {
+    concurrency?: number;
+    stopOnError?: boolean;
+    delayMs?: number;
+}): Promise<R[]>;

package/dist/index.mjs

@@ -0,0 +1,395 @@
+// 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";
+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/init/init-spec.ts
+import { z as z3 } from "zod";
+var InitInputSchema = z3.object({
+  outputDir: z3.string().min(1).default("."),
+  workflowName: z3.string().min(1).default("jules-merge-check"),
+  baseBranch: z3.string().min(1).default("main"),
+  force: z3.boolean().default(false)
+});
+var InitErrorCode = z3.enum([
+  "DIRECTORY_NOT_FOUND",
+  "FILE_ALREADY_EXISTS",
+  "WRITE_FAILED",
+  "UNKNOWN_ERROR"
+]);
+// src/init/init-handler.ts
+import { mkdir, writeFile, access, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+// src/init/templates.ts
+function buildWorkflowYaml(options) {
+  return `# Generated by jules-merge init
+# This workflow checks for merge conflicts on pull requests.
+name: ${options.workflowName}
+
+on:
+  pull_request:
+    branches: [${options.baseBranch}]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  check-conflicts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Attempt merge
+        id: merge
+        continue-on-error: true
+        run: |
+          git config user.name "github-actions"
+          git config user.email "github-actions@github.com"
+          git fetch origin \${{ github.event.pull_request.base.ref }}
+          git merge origin/\${{ github.event.pull_request.base.ref }} --no-commit --no-ff || true
+
+      - name: Check for conflicts
+        run: |
+          npx @google/jules-merge check-conflicts \\
+            --repo \${{ github.repository }} \\
+            --pr \${{ github.event.pull_request.number }} \\
+            --sha \${{ github.event.pull_request.head.sha }}
+`;
+}
+
+// src/init/init-handler.ts
+class InitHandler {
+  async execute(input) {
+    try {
+      const outputDir = resolve(input.outputDir);
+      try {
+        const stats = await stat(outputDir);
+        if (!stats.isDirectory()) {
+          return fail("DIRECTORY_NOT_FOUND", `${outputDir} is not a directory.`, true, "Provide a valid directory path with --output-dir.");
+        }
+      } catch {
+        return fail("DIRECTORY_NOT_FOUND", `Directory does not exist: ${outputDir}`, true, "Create the directory first or provide a valid path.");
+      }
+      const workflowDir = join(outputDir, ".github", "workflows");
+      const filePath = join(workflowDir, `${input.workflowName}.yml`);
+      if (!input.force) {
+        try {
+          await access(filePath);
+          return fail("FILE_ALREADY_EXISTS", `Workflow file already exists: ${filePath}`, true, "Use --force to overwrite.");
+        } catch {}
+      }
+      const content = buildWorkflowYaml({
+        workflowName: input.workflowName,
+        baseBranch: input.baseBranch
+      });
+      try {
+        await mkdir(workflowDir, { recursive: true });
+        await writeFile(filePath, content, "utf-8");
+      } catch (error) {
+        return fail("WRITE_FAILED", `Failed to write workflow file: ${error.message}`, true);
+      }
+      return ok({ filePath, content });
+    } catch (error) {
+      return fail("UNKNOWN_ERROR", error instanceof Error ? error.message : String(error), false);
+    }
+  }
+}
+export {
+  ok,
+  getSessionChangedFiles,
+  fail,
+  jules as createJulesClient,
+  buildWorkflowYaml,
+  SessionCheckInputSchema,
+  SessionCheckHandler,
+  SessionCheckErrorCode,
+  InitInputSchema,
+  InitHandler,
+  InitErrorCode,
+  GitCheckInputSchema,
+  GitCheckHandler,
+  GitCheckErrorCode
+};

package/dist/merge/src/__tests__/conflicts/git-handler.test.d.ts

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

package/dist/merge/src/__tests__/conflicts/git-spec.test.d.ts

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

package/dist/merge/src/__tests__/conflicts/session-handler.test.d.ts

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

package/dist/merge/src/__tests__/conflicts/session-spec.test.d.ts

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

package/dist/merge/src/__tests__/init/init-handler.test.d.ts

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

package/dist/merge/src/__tests__/init/init-spec.test.d.ts

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

package/dist/merge/src/__tests__/init/templates.test.d.ts

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

package/dist/merge/src/__tests__/shared/git.test.d.ts

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

package/dist/merge/src/__tests__/shared/github.test.d.ts

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

package/dist/merge/src/__tests__/shared/session.test.d.ts

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

package/dist/merge/src/cli/check-conflicts.command.d.ts

@@ -0,0 +1,24 @@
+declare const _default: import("citty").CommandDef<{
+    session: {
+        type: "string";
+        description: string;
+    };
+    repo: {
+        type: "string";
+        description: string;
+    };
+    base: {
+        type: "string";
+        description: string;
+        default: string;
+    };
+    pr: {
+        type: "string";
+        description: string;
+    };
+    sha: {
+        type: "string";
+        description: string;
+    };
+}>;
+export default _default;

package/dist/merge/src/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/merge/src/cli/init.command.d.ts

@@ -0,0 +1,23 @@
+declare const _default: import("citty").CommandDef<{
+    'output-dir': {
+        type: "string";
+        description: string;
+        default: string;
+    };
+    'workflow-name': {
+        type: "string";
+        description: string;
+        default: string;
+    };
+    'base-branch': {
+        type: "string";
+        description: string;
+        default: string;
+    };
+    force: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;
+export default _default;

package/dist/merge/src/conflicts/git-handler.d.ts

@@ -0,0 +1,4 @@
+import type { GitCheckSpec, GitCheckInput, GitCheckResult } from './git-spec.js';
+export declare class GitCheckHandler implements GitCheckSpec {
+    execute(input: GitCheckInput): Promise<GitCheckResult>;
+}

package/dist/merge/src/conflicts/git-spec.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export declare const GitCheckInputSchema: z.ZodObject<{
+    repo: z.ZodEffects<z.ZodString, string, string>;
+    pullRequestNumber: z.ZodNumber;
+    failingCommitSha: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+    pullRequestNumber: number;
+    failingCommitSha: string;
+}, {
+    repo: string;
+    pullRequestNumber: number;
+    failingCommitSha: string;
+}>;
+export type GitCheckInput = z.infer<typeof GitCheckInputSchema>;
+export declare const GitCheckErrorCode: z.ZodEnum<["NO_UNMERGED_FILES", "GIT_STATUS_FAILED", "FILE_READ_FAILED", "UNKNOWN_ERROR"]>;
+export type GitCheckErrorCode = z.infer<typeof GitCheckErrorCode>;
+export interface GitCheckData {
+    taskDirective: string;
+    priority: 'standard' | 'critical';
+    affectedFiles: Array<{
+        filePath: string;
+        baseCommitSha: string;
+        gitConflictMarkers: string;
+    }>;
+}
+export interface GitCheckSuccess {
+    success: true;
+    data: GitCheckData;
+}
+export interface GitCheckFailure {
+    success: false;
+    error: {
+        code: GitCheckErrorCode;
+        message: string;
+        recoverable: boolean;
+        suggestion?: string;
+    };
+}
+export type GitCheckResult = GitCheckSuccess | GitCheckFailure;
+export interface GitCheckSpec {
+    execute(input: GitCheckInput): Promise<GitCheckResult>;
+}

package/dist/merge/src/conflicts/index.d.ts

@@ -0,0 +1,4 @@
+export * from './session-spec.js';
+export { SessionCheckHandler } from './session-handler.js';
+export * from './git-spec.js';
+export { GitCheckHandler } from './git-handler.js';

package/dist/merge/src/conflicts/session-handler.d.ts

@@ -0,0 +1,9 @@
+import type { Octokit } from '@octokit/rest';
+import type { JulesClient } from '@google/jules-sdk';
+import type { SessionCheckSpec, SessionCheckInput, SessionCheckResult } from './session-spec.js';
+export declare class SessionCheckHandler implements SessionCheckSpec {
+    private octokit;
+    private julesClient;
+    constructor(octokit: Octokit, julesClient: JulesClient);
+    execute(input: SessionCheckInput): Promise<SessionCheckResult>;
+}

package/dist/merge/src/conflicts/session-spec.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export declare const SessionCheckInputSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    repo: z.ZodEffects<z.ZodString, string, string>;
+    base: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    repo: string;
+    base: string;
+}, {
+    sessionId: string;
+    repo: string;
+    base?: string | undefined;
+}>;
+export type SessionCheckInput = z.infer<typeof SessionCheckInputSchema>;
+export declare const SessionCheckErrorCode: z.ZodEnum<["SESSION_QUERY_FAILED", "GITHUB_API_ERROR", "RATE_LIMIT_EXCEEDED", "UNKNOWN_ERROR"]>;
+export type SessionCheckErrorCode = z.infer<typeof SessionCheckErrorCode>;
+export interface SessionCheckData {
+    status: 'clean' | 'conflict';
+    message: string;
+    conflicts: Array<{
+        filePath: string;
+        conflictReason: string;
+        remoteShadowContent: string;
+    }>;
+}
+export interface SessionCheckSuccess {
+    success: true;
+    data: SessionCheckData;
+}
+export interface SessionCheckFailure {
+    success: false;
+    error: {
+        code: SessionCheckErrorCode;
+        message: string;
+        recoverable: boolean;
+        suggestion?: string;
+    };
+}
+export type SessionCheckResult = SessionCheckSuccess | SessionCheckFailure;
+export interface SessionCheckSpec {
+    execute(input: SessionCheckInput): Promise<SessionCheckResult>;
+}

package/dist/merge/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './conflicts/index.js';
+export * from './init/index.js';
+export { ok, fail } from './shared/result.js';
+export { getSessionChangedFiles, createJulesClient } from './shared/session.js';
+export type { SessionFileInfo } from './shared/session.js';

package/dist/merge/src/init/index.d.ts

@@ -0,0 +1,4 @@
+export * from './init-spec.js';
+export { InitHandler } from './init-handler.js';
+export { buildWorkflowYaml } from './templates.js';
+export type { WorkflowTemplateOptions } from './templates.js';