@google/jules-merge 0.0.1

package/dist/cli/init.command.mjs

@@ -0,0 +1,159 @@
+// src/cli/init.command.ts
+import { defineCommand } from "citty";
+
+// src/init/init-spec.ts
+import { z } from "zod";
+var InitInputSchema = z.object({
+  outputDir: z.string().min(1).default("."),
+  workflowName: z.string().min(1).default("jules-merge-check"),
+  baseBranch: z.string().min(1).default("main"),
+  force: z.boolean().default(false)
+});
+var InitErrorCode = z.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/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/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);
+    }
+  }
+}
+
+// src/cli/init.command.ts
+var init_command_default = defineCommand({
+  meta: {
+    name: "init",
+    description: "Generate a GitHub Actions workflow for merge conflict detection."
+  },
+  args: {
+    "output-dir": {
+      type: "string",
+      description: "Directory to write .github/workflows/ into (defaults to .)",
+      default: "."
+    },
+    "workflow-name": {
+      type: "string",
+      description: "Workflow filename (without .yml)",
+      default: "jules-merge-check"
+    },
+    "base-branch": {
+      type: "string",
+      description: "Base branch to check against",
+      default: "main"
+    },
+    force: {
+      type: "boolean",
+      description: "Overwrite existing workflow file",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const input = InitInputSchema.parse({
+      outputDir: args["output-dir"],
+      workflowName: args["workflow-name"],
+      baseBranch: args["base-branch"],
+      force: args.force
+    });
+    const handler = new InitHandler;
+    const result = await handler.execute(input);
+    if (result.success) {
+      console.log(`✅ Created ${result.data.filePath}`);
+    } else {
+      console.error(`❌ ${result.error.message}`);
+      if (result.error.suggestion) {
+        console.error(`   ${result.error.suggestion}`);
+      }
+      process.exit(1);
+    }
+  }
+});
+export {
+  init_command_default as default
+};

package/dist/core/src/activities/client.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+import { Activity } from '../types.js';
+import { ActivityStorage } from '../storage/types.js';
+import { ActivityClient, ListOptions, SelectOptions } from './types.js';
+/**
+ * Interface for the network layer used by the activity client.
+ * Abstracts away the details of polling and fetching from the API.
+ * @internal
+ */
+export interface NetworkClient {
+    rawStream(): AsyncIterable<Activity>;
+    listActivities(options?: ListOptions): Promise<{
+        activities: Activity[];
+        nextPageToken?: string;
+    }>;
+    fetchActivity(activityId: string): Promise<Activity>;
+}
+/**
+ * The default implementation of the ActivityClient.
+ * Implements a "local-first" architecture where activities are fetched from
+ * the network, cached locally, and then served from the cache.
+ */
+export declare class DefaultActivityClient implements ActivityClient {
+    private storage;
+    private network;
+    constructor(storage: ActivityStorage, network: NetworkClient);
+    /**
+     * Re-hydrates plain artifact objects from storage into rich class instances.
+     * JSON serialization loses class information (methods), so we need to restore it.
+     *
+     * **Behavior:**
+     * - Iterates through artifacts in an activity.
+     * - If an artifact is a plain object (not a class instance), it's re-instantiated.
+     * - Handles backward compatibility: if an artifact is already a class instance, it's skipped.
+     *
+     * @param activity The activity from storage, potentially with plain artifacts.
+     * @returns The same activity with its artifacts guaranteed to be class instances.
+     */
+    private _hydrateActivityArtifacts;
+    /**
+     * Returns an async iterable of all activities.
+     *
+     * **Behavior:**
+     * - Always syncs new activities from the network first (via hydrate).
+     * - Then yields all activities from local storage.
+     *
+     * This ensures callers always get the complete, up-to-date history
+     * rather than potentially stale cached data.
+     */
+    history(): AsyncIterable<Activity>;
+    /**
+     * Syncs new activities from the network to local cache.
+     *
+     * **Optimization Strategy:**
+     * Activities are immutable - once downloaded, they never change.
+     * We use the Jules API's pageToken (nanosecond timestamp) to fetch
+     * only activities newer than our latest cached one.
+     *
+     * **Behavior:**
+     * - Empty cache: Fetches all activities (no pageToken)
+     * - Has cached activities: Constructs pageToken from latest createTime,
+     *   fetches only newer activities
+     * - Frozen session (> 30 days): Skips API call entirely
+     *
+     * @returns The number of new activities synced.
+     */
+    hydrate(): Promise<number>;
+    /**
+     * Returns an async iterable of new activities from the network.
+     * This method polls the network and updates the local storage.
+     *
+     * **Side Effects:**
+     * - Polls the network continuously.
+     * - Appends new activities to local storage (write-through caching).
+     *
+     * **Logic:**
+     * - Reads the latest activity from storage to determine the "high-water mark".
+     * - Ignores incoming activities older than or equal to the high-water mark.
+     */
+    updates(): AsyncIterable<Activity>;
+    /**
+     * Returns a combined stream of history and updates.
+     * This is the primary method for consuming the activity stream.
+     *
+     * **Behavior:**
+     * 1. Yields all historical activities from local storage (offline capable).
+     * 2. Switches to `updates()` to yield new activities from the network (real-time).
+     */
+    stream(): AsyncIterable<Activity>;
+    /**
+     * Queries local storage for activities matching the given options.
+     */
+    select(options?: SelectOptions): Promise<Activity[]>;
+    /**
+     * Lists activities from the network directly.
+     * @param options Pagination options.
+     */
+    list(options?: ListOptions): Promise<{
+        activities: Activity[];
+        nextPageToken?: string;
+    }>;
+    /**
+     * Gets a single activity by ID.
+     * Implements a "read-through" caching strategy.
+     *
+     * **Logic:**
+     * 1. Checks local storage. If found, returns it immediately (fast).
+     * 2. If missing, fetches from the network.
+     * 3. Persists the fetched activity to storage (future reads will hit cache).
+     * 4. Returns the activity.
+     *
+     * **Side Effects:**
+     * - May perform a network request.
+     * - May write to local storage.
+     */
+    get(activityId: string): Promise<Activity>;
+}

package/dist/core/src/activities/summary.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+import type { Activity, ActivitySummary } from '../types.js';
+/**
+ * Creates a concise summary for an activity.
+ * @param activity The activity to summarize.
+ * @returns A summary of the activity.
+ */
+export declare function toSummary(activity: Activity): ActivitySummary;

package/dist/core/src/activities/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ */
+import { Activity } from '../types.js';
+/**
+ * Standard pagination options for network requests.
+ */
+export interface ListOptions {
+    pageSize?: number;
+    pageToken?: string;
+    filter?: string;
+}
+/**
+ * Options for filtering activities locally.
+ */
+export interface SelectOptions {
+    after?: string;
+    before?: string;
+    type?: string;
+    limit?: number;
+    order?: 'asc' | 'desc';
+}
+/**
+ * Interface for managing session activities.
+ * This interface handles both local caching and network synchronization.
+ */
+export interface ActivityClient {
+    /**
+     * COLD STREAM: Yields all known past activities from local storage.
+     * Ends immediately after yielding the last known activity.
+     * Does NOT open a network connection.
+     */
+    history(): AsyncIterable<Activity>;
+    /**
+     * HOT STREAM: Yields ONLY future activities as they arrive from the network.
+     * Blocks indefinitely.
+     */
+    updates(): AsyncIterable<Activity>;
+    /**
+     * HYBRID STREAM: Yields full history(), then seamlessly switches to updates().
+     * The standard choice for most applications.
+     */
+    stream(): AsyncIterable<Activity>;
+    /**
+     * LOCAL QUERY: Performs rich filtering against local storage only.
+     * Fast, but might be incomplete if not synced.
+     */
+    select(options?: SelectOptions): Promise<Activity[]>;
+    /**
+     * NETWORK LIST: Honest wrapper around standard REST pagination.
+     * Uses opaque tokens.
+     */
+    list(options?: ListOptions): Promise<{
+        activities: Activity[];
+        nextPageToken?: string;
+    }>;
+    /**
+     * NETWORK GET: Fetches a specific activity from the network and caches it.
+     */
+    get(activityId: string): Promise<Activity>;
+    /**
+     * NETWORK SYNC: Fetches all activities from the network and caches them.
+     * Useful when you suspect the cache is stale.
+     * @returns The number of activities synced.
+     */
+    hydrate(): Promise<number>;
+}

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

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+export type RateLimitRetryConfig = {
+    maxRetryTimeMs: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+};
+export type ApiClientOptions = {
+    apiKey: string | undefined;
+    baseUrl: string;
+    requestTimeoutMs: number;
+    rateLimitRetry?: Partial<RateLimitRetryConfig>;
+    maxConcurrentRequests?: number;
+};
+export type ApiRequestOptions = {
+    method?: 'GET' | 'POST';
+    body?: Record<string, unknown>;
+    query?: Record<string, any>;
+    headers?: Record<string, string>;
+    _isRetry?: boolean;
+};
+/**
+ * A simple internal API client to handle HTTP requests to the Jules API.
+ * @internal
+ */
+export declare class ApiClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    private readonly rateLimitConfig;
+    private readonly semaphore;
+    constructor(options: ApiClientOptions);
+    request<T>(endpoint: string, options?: ApiRequestOptions): Promise<T>;
+    private resolveUrl;
+    private fetchWithTimeout;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+import type { RestMediaArtifact, RestBashOutputArtifact, GitPatch, ParsedChangeSet, ParsedFile, GeneratedFile, GeneratedFiles } from './types.js';
+import { Platform } from './platform/types.js';
+/**
+ * Parses a unified diff string and extracts file information.
+ * @internal
+ */
+export declare function parseUnidiff(patch?: string | null): ParsedFile[];
+/**
+ * Parses a unified diff and extracts file information including content.
+ * @internal
+ */
+export declare function parseUnidiffWithContent(patch?: string | null): GeneratedFile[];
+/**
+ * Creates a GeneratedFiles helper object from an array of GeneratedFile.
+ * @internal
+ */
+export declare function createGeneratedFiles(files: GeneratedFile[]): GeneratedFiles;
+/**
+ * Represents a media artifact (e.g. image) produced by an activity.
+ * Provides helper methods for saving and viewing the media.
+ */
+export declare class MediaArtifact {
+    readonly type = "media";
+    readonly data: string;
+    readonly format: string;
+    private platform;
+    private activityId?;
+    constructor(artifact: RestMediaArtifact['media'], platform: Platform, activityId?: string);
+    /**
+     * Saves the media artifact to a file.
+     *
+     * **Side Effects:**
+     * - Node.js: Writes the file to disk (overwrites if exists).
+     * - Browser: Saves the file to the 'artifacts' object store in IndexedDB.
+     *
+     * @param filepath The path where the file should be saved.
+     */
+    save(filepath: string): Promise<void>;
+    /**
+     * Converts the media artifact to a data URL.
+     * Useful for displaying images in a browser.
+     *
+     * **Data Transformation:**
+     * - Prefixes the base64 data with `data:<mimeType>;base64,`.
+     *
+     * @returns A valid Data URI string.
+     */
+    toUrl(): string;
+}
+/**
+ * Represents the output of a bash command executed by the agent.
+ */
+export declare class BashArtifact {
+    readonly type = "bashOutput";
+    readonly command: string;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number | null;
+    constructor(artifact: RestBashOutputArtifact['bashOutput']);
+    /**
+     * Formats the bash output as a string, mimicking a terminal session.
+     *
+     * **Data Transformation:**
+     * - Combines `stdout` and `stderr`.
+     * - Formats the command with a `$` prompt.
+     * - Appends the exit code.
+     */
+    toString(): string;
+}
+/**
+ * Represents a set of code changes (unified diff) produced by an activity.
+ * Provides a helper method to parse the diff into structured data.
+ */
+export declare class ChangeSetArtifact {
+    readonly type: "changeSet";
+    readonly source: string;
+    readonly gitPatch: GitPatch;
+    constructor(source: string, gitPatch: GitPatch);
+    /**
+     * Parses the unified diff and returns structured file change information.
+     *
+     * **Data Transformation:**
+     * - Extracts file paths from diff headers.
+     * - Determines change type (created/modified/deleted) from /dev/null markers.
+     * - Counts additions (+) and deletions (-) in hunks.
+     *
+     * @returns Parsed diff with file paths, change types, and line counts.
+     */
+    parsed(): ParsedChangeSet;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+import { CachedSession } from './storage/types.js';
+export type CacheTier = 'hot' | 'warm' | 'frozen';
+/**
+ * Determines the cache tier for a session based on its state and age.
+ *
+ * Strategy:
+ * - **Frozen (Tier 3):** > 30 days old. Immutable.
+ * - **Warm (Tier 2):** Terminal state + Verified < 24h ago. High read performance.
+ * - **Hot (Tier 1):** Active or Stale. Requires network sync.
+ */
+export declare function determineCacheTier(cached: CachedSession, now?: number): CacheTier;
+/**
+ * Helper to check if a cached session is valid to return immediately.
+ * Returns true if the session is Frozen or Warm.
+ */
+export declare function isCacheValid(cached: CachedSession | undefined, now?: number): cached is CachedSession;