@aprovan/hardcopy 0.1.0

package/src/merge.ts

@@ -0,0 +1,75 @@
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { llmMergeText, type LLMMergeOptions } from "./llm-merge";
+
+export interface SemanticMergeOptions {
+  tempDir?: string;
+  filePath: string;
+  /** LLM merge options (URL, model, etc.) */
+  llmOptions?: LLMMergeOptions;
+}
+
+/**
+ * Attempts a 3-way merge using diff3, with LLM fallback for conflicts.
+ * Returns the merged text if successful, or null if merge fails entirely.
+ */
+export async function mergeText(
+  base: string,
+  local: string,
+  remote: string,
+  options: SemanticMergeOptions,
+): Promise<string | null> {
+  if (local === remote) return local;
+  if (local === base) return remote;
+  if (remote === base) return local;
+
+  // Try diff3 first
+  const diff3Result = await tryDiff3Merge(base, local, remote, options.tempDir);
+  if (diff3Result !== null) {
+    return diff3Result;
+  }
+
+  // Fall back to LLM merge for conflicts
+  return llmMergeText(base, local, remote, options.llmOptions);
+}
+
+async function tryDiff3Merge(
+  base: string,
+  local: string,
+  remote: string,
+  tempDir?: string,
+): Promise<string | null> {
+  const root = tempDir ?? join(tmpdir(), "hardcopy-merge");
+  await mkdir(root, { recursive: true });
+  const runDir = await mkdtemp(join(root, "merge-"));
+
+  const basePath = join(runDir, "base");
+  const localPath = join(runDir, "local");
+  const remotePath = join(runDir, "remote");
+
+  try {
+    await writeFile(basePath, base);
+    await writeFile(localPath, local);
+    await writeFile(remotePath, remote);
+
+    // diff3 -m: merge mode
+    // Order: local, base, remote (diff3 convention)
+    const result = spawnSync("diff3", ["-m", localPath, basePath, remotePath], {
+      encoding: "utf-8",
+    });
+
+    // Exit code 0 = clean merge, 1 = conflicts, 2 = error
+    if (result.status === 0 && typeof result.stdout === "string") {
+      return result.stdout;
+    }
+
+    // Conflicts or error - return null
+    return null;
+  } catch {
+    return null;
+  } finally {
+    await rm(runDir, { recursive: true, force: true });
+  }
+}

package/src/provider.ts

@@ -0,0 +1,40 @@
+import type {
+  Node,
+  Change,
+  FetchRequest,
+  FetchResult,
+  PushResult,
+} from "./types";
+
+export interface Tool {
+  name: string;
+  description: string;
+  parameters?: Record<string, unknown>;
+}
+
+export interface Provider {
+  name: string;
+  nodeTypes: string[];
+  edgeTypes: string[];
+
+  fetch(request: FetchRequest): Promise<FetchResult>;
+  push(node: Node, changes: Change[]): Promise<PushResult>;
+  fetchNode(nodeId: string): Promise<Node | null>;
+  getTools(): Tool[];
+}
+
+export type ProviderFactory = (config: Record<string, unknown>) => Provider;
+
+const providers = new Map<string, ProviderFactory>();
+
+export function registerProvider(name: string, factory: ProviderFactory): void {
+  providers.set(name, factory);
+}
+
+export function getProvider(name: string): ProviderFactory | undefined {
+  return providers.get(name);
+}
+
+export function listProviders(): string[] {
+  return Array.from(providers.keys());
+}

package/src/providers/a2a/index.ts

@@ -0,0 +1,166 @@
+import type { Provider, Tool } from "../../provider";
+import type {
+  Node,
+  Edge,
+  Change,
+  FetchRequest,
+  FetchResult,
+  PushResult,
+} from "../../types";
+import { registerProvider } from "../../provider";
+
+export interface A2AConfig {
+  endpoint?: string;
+  links?: {
+    edge: string;
+    to: string;
+    match: string;
+  }[];
+}
+
+export function createA2AProvider(config: A2AConfig): Provider {
+  return {
+    name: "a2a",
+    nodeTypes: ["a2a.Task", "a2a.Session", "a2a.Agent"],
+    edgeTypes: ["a2a.TRACKS", "a2a.CREATED_BY", "a2a.PART_OF"],
+
+    async fetch(request: FetchRequest): Promise<FetchResult> {
+      const nodes: Node[] = [];
+      const edges: Edge[] = [];
+
+      if (!config.endpoint) {
+        return { nodes, edges, hasMore: false };
+      }
+
+      try {
+        const response = await fetch(`${config.endpoint}/tasks`, {
+          headers: { Accept: "application/json" },
+        });
+
+        if (!response.ok) {
+          return { nodes, edges, hasMore: false };
+        }
+
+        const tasks = (await response.json()) as A2ATask[];
+
+        for (const task of tasks) {
+          const nodeId = `a2a:${task.id}`;
+          nodes.push({
+            id: nodeId,
+            type: "a2a.Task",
+            attrs: {
+              name: task.name,
+              status: task.status,
+              description: task.description,
+              created_at: task.created_at,
+              updated_at: task.updated_at,
+              meta: task.meta,
+            },
+          });
+
+          if (
+            task.meta?.github?.issue_number &&
+            task.meta?.github?.repository
+          ) {
+            edges.push({
+              type: "a2a.TRACKS",
+              fromId: nodeId,
+              toId: `github:${task.meta.github.repository}#${task.meta.github.issue_number}`,
+            });
+          }
+
+          if (task.agent_id) {
+            edges.push({
+              type: "a2a.CREATED_BY",
+              fromId: nodeId,
+              toId: `a2a:agent:${task.agent_id}`,
+            });
+          }
+
+          if (task.session_id) {
+            edges.push({
+              type: "a2a.PART_OF",
+              fromId: nodeId,
+              toId: `a2a:session:${task.session_id}`,
+            });
+          }
+        }
+      } catch {
+        // A2A endpoint not available
+      }
+
+      return { nodes, edges, hasMore: false };
+    },
+
+    async push(node: Node, changes: Change[]): Promise<PushResult> {
+      if (!config.endpoint) {
+        return { success: false, error: "No A2A endpoint configured" };
+      }
+
+      const match = node.id.match(/^a2a:(.+)$/);
+      if (!match) {
+        return { success: false, error: "Invalid A2A node ID" };
+      }
+
+      const taskId = match[1];
+      const body: Record<string, unknown> = {};
+
+      for (const change of changes) {
+        body[change.field] = change.newValue;
+      }
+
+      try {
+        const response = await fetch(`${config.endpoint}/tasks/${taskId}`, {
+          method: "PATCH",
+          body: JSON.stringify(body),
+          headers: { "Content-Type": "application/json" },
+        });
+
+        if (!response.ok) {
+          return { success: false, error: await response.text() };
+        }
+
+        return { success: true };
+      } catch (err) {
+        return { success: false, error: String(err) };
+      }
+    },
+
+    async fetchNode(_nodeId: string): Promise<Node | null> {
+      return null;
+    },
+
+    getTools(): Tool[] {
+      return [
+        { name: "a2a.createTask", description: "Create a new agent task" },
+        {
+          name: "a2a.updateTask",
+          description: "Update task status or metadata",
+        },
+        { name: "a2a.linkIssue", description: "Link task to GitHub issue" },
+      ];
+    },
+  };
+}
+
+interface A2ATask {
+  id: string;
+  name: string;
+  status: string;
+  description?: string;
+  created_at: string;
+  updated_at: string;
+  agent_id?: string;
+  session_id?: string;
+  meta?: {
+    github?: {
+      issue_number: number;
+      repository: string;
+    };
+    [key: string]: unknown;
+  };
+}
+
+registerProvider("a2a", (config) => createA2AProvider(config as A2AConfig));
+
+export { createA2AProvider as default };

package/src/providers/git/index.ts

@@ -0,0 +1,212 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import { readFile, access } from "fs/promises";
+import { join } from "path";
+import type { Provider, Tool } from "../../provider";
+import type {
+  Node,
+  Edge,
+  Change,
+  FetchRequest,
+  FetchResult,
+  PushResult,
+} from "../../types";
+import { registerProvider } from "../../provider";
+
+const execAsync = promisify(exec);
+
+export interface GitConfig {
+  repositories?: { path: string }[];
+  links?: {
+    edge: string;
+    to: string;
+    match: string;
+  }[];
+}
+
+async function execGit(cwd: string, ...args: string[]): Promise<string> {
+  const { stdout } = await execAsync(`git ${args.join(" ")}`, { cwd });
+  return stdout.trim();
+}
+
+async function getWorktrees(repoPath: string): Promise<Worktree[]> {
+  const output = await execGit(repoPath, "worktree", "list", "--porcelain");
+  const worktrees: Worktree[] = [];
+  let current: Partial<Worktree> = {};
+
+  for (const line of output.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      if (current.path) worktrees.push(current as Worktree);
+      current = { path: line.slice(9) };
+    } else if (line.startsWith("HEAD ")) {
+      current.head = line.slice(5);
+    } else if (line.startsWith("branch ")) {
+      current.branch = line.slice(7).replace("refs/heads/", "");
+    } else if (line === "bare") {
+      current.bare = true;
+    } else if (line === "detached") {
+      current.detached = true;
+    }
+  }
+
+  if (current.path) worktrees.push(current as Worktree);
+  return worktrees;
+}
+
+async function getBranches(repoPath: string): Promise<string[]> {
+  try {
+    const output = await execGit(
+      repoPath,
+      "branch",
+      "-a",
+      "--format=%(refname:short)",
+    );
+    return output.split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+async function readWorktreeMeta(
+  path: string,
+): Promise<Record<string, unknown> | null> {
+  const metaPath = join(path, ".a2a", "session.json");
+  try {
+    await access(metaPath);
+    const content = await readFile(metaPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export function createGitProvider(config: GitConfig): Provider {
+  return {
+    name: "git",
+    nodeTypes: ["git.Branch", "git.Worktree", "git.Commit"],
+    edgeTypes: ["git.TRACKS", "git.CONTAINS", "git.WORKTREE_OF"],
+
+    async fetch(request: FetchRequest): Promise<FetchResult> {
+      const nodes: Node[] = [];
+      const edges: Edge[] = [];
+
+      for (const repoConfig of config.repositories ?? []) {
+        const repoPath = repoConfig.path.replace(
+          /^~/,
+          process.env["HOME"] ?? "",
+        );
+
+        try {
+          const head = await execGit(repoPath, "rev-parse", "HEAD");
+          if (request.versionToken === head) {
+            return {
+              nodes,
+              edges,
+              hasMore: false,
+              cached: true,
+              versionToken: head,
+            };
+          }
+
+          const worktrees = await getWorktrees(repoPath);
+          const branches = await getBranches(repoPath);
+
+          for (const wt of worktrees) {
+            const nodeId = `git:worktree:${wt.path}`;
+            const meta = await readWorktreeMeta(wt.path);
+
+            nodes.push({
+              id: nodeId,
+              type: "git.Worktree",
+              attrs: {
+                path: wt.path,
+                branch: wt.branch,
+                head: wt.head,
+                bare: wt.bare,
+                detached: wt.detached,
+                meta,
+              },
+            });
+
+            if (wt.branch) {
+              edges.push({
+                type: "git.WORKTREE_OF",
+                fromId: `git:branch:${repoPath}:${wt.branch}`,
+                toId: nodeId,
+              });
+            }
+          }
+
+          for (const branch of branches) {
+            const branchNodeId = `git:branch:${repoPath}:${branch}`;
+            const worktree = worktrees.find((wt) => wt.branch === branch);
+
+            nodes.push({
+              id: branchNodeId,
+              type: "git.Branch",
+              attrs: {
+                name: branch,
+                repository: repoPath,
+                worktreePath: worktree?.path,
+              },
+            });
+
+            if (config.links) {
+              for (const link of config.links) {
+                if (link.edge === "git.TRACKS" && worktree) {
+                  const meta = await readWorktreeMeta(worktree.path);
+                  if (meta?.a2a && typeof meta.a2a === "object") {
+                    const a2aMeta = meta.a2a as Record<string, unknown>;
+                    if (a2aMeta["task_id"]) {
+                      edges.push({
+                        type: "git.TRACKS",
+                        fromId: branchNodeId,
+                        toId: `a2a:${a2aMeta["task_id"]}`,
+                      });
+                    }
+                  }
+                }
+              }
+            }
+          }
+        } catch {
+          // Skip invalid repositories
+        }
+      }
+
+      return { nodes, edges, hasMore: false };
+    },
+
+    async push(node: Node, changes: Change[]): Promise<PushResult> {
+      return { success: false, error: "Git push not implemented via provider" };
+    },
+
+    async fetchNode(_nodeId: string): Promise<Node | null> {
+      return null;
+    },
+
+    getTools(): Tool[] {
+      return [
+        { name: "git.checkout", description: "Checkout branch" },
+        { name: "git.push", description: "Push changes" },
+        { name: "git.createBranch", description: "Create new branch" },
+        {
+          name: "git.createWorktree",
+          description: "Create worktree for branch",
+        },
+      ];
+    },
+  };
+}
+
+interface Worktree {
+  path: string;
+  head?: string;
+  branch?: string;
+  bare?: boolean;
+  detached?: boolean;
+}
+
+registerProvider("git", (config) => createGitProvider(config as GitConfig));
+
+export { createGitProvider as default };