@aprovan/hardcopy 0.1.0

package/src/hardcopy/views.ts

@@ -0,0 +1,199 @@
+import { join } from "path";
+import { mkdir, writeFile, readFile, rm, readdir, stat } from "fs/promises";
+import { setDocContent, setDocAttrs, getDocContent } from "../crdt";
+import { renderNode, parseFile } from "../format";
+import type { ViewConfig } from "../config";
+import type { Node, IndexState } from "../types";
+import type { Hardcopy } from "./core";
+import type { RefreshResult } from "./types";
+
+export async function getViews(this: Hardcopy): Promise<string[]> {
+  const config = await this.loadConfig();
+  return config.views.map((v) => v.path);
+}
+
+export async function refreshView(
+  this: Hardcopy,
+  viewPath: string,
+  options: { clean?: boolean } = {},
+): Promise<RefreshResult> {
+  const config = await this.loadConfig();
+  const view = config.views.find((v) => v.path === viewPath);
+  if (!view) throw new Error(`View not found: ${viewPath}`);
+
+  const viewDir = join(this.root, view.path);
+  await mkdir(viewDir, { recursive: true });
+
+  const db = this.getDatabase();
+
+  const params: Record<string, unknown> = {};
+  const me = process.env["HARDCOPY_ME"] ?? process.env["GITHUB_USER"];
+  if (me) params["me"] = me;
+
+  const nodes = await db.queryViewNodes(
+    view.query,
+    Object.keys(params).length ? params : undefined,
+  );
+
+  const indexState: IndexState = {
+    loaded: nodes.length,
+    pageSize: 10,
+    lastFetch: new Date().toISOString(),
+    ttl: 300,
+  };
+
+  await writeFile(
+    join(viewDir, ".index"),
+    JSON.stringify(indexState, null, 2),
+  );
+
+  const expectedFiles = new Set<string>();
+
+  for (const node of nodes) {
+    const renderedPaths = await renderNodeToFile.call(this, node, view, viewDir);
+    for (const p of renderedPaths) {
+      expectedFiles.add(p);
+    }
+  }
+
+  const existingFiles = await listViewFiles(viewDir);
+  const orphanedFiles = existingFiles.filter((f) => !expectedFiles.has(f));
+
+  if (options.clean && orphanedFiles.length > 0) {
+    await cleanupOrphanedFiles.call(this, viewDir, orphanedFiles);
+  }
+
+  return {
+    rendered: expectedFiles.size,
+    orphaned: orphanedFiles,
+    cleaned: options.clean ?? false,
+  };
+}
+
+async function renderNodeToFile(
+  this: Hardcopy,
+  node: Node,
+  view: ViewConfig,
+  viewDir: string,
+): Promise<string[]> {
+  const renderedPaths: string[] = [];
+  const crdt = this.getCRDTStore();
+  const db = this.getDatabase();
+
+  for (const renderConfig of view.render) {
+    const filePath = resolveRenderPath(renderConfig.path, node);
+    const fullPath = join(viewDir, filePath);
+    await mkdir(join(fullPath, ".."), { recursive: true });
+
+    let content: string;
+    if (renderConfig.template) {
+      content = renderNode(node, renderConfig.template);
+    } else if (renderConfig.type) {
+      content = renderNode({ ...node, type: renderConfig.type });
+    } else {
+      content = renderNode(node);
+    }
+
+    const doc = await crdt.loadOrCreate(node.id);
+    const body = (node.attrs["body"] as string) ?? "";
+    setDocContent(doc, body);
+    setDocAttrs(doc, node.attrs as Record<string, unknown>);
+    await crdt.save(node.id, doc);
+
+    await writeFile(fullPath, content);
+
+    const fileStat = await stat(fullPath);
+    await db.upsertNode({ ...node, syncedAt: fileStat.mtimeMs });
+
+    renderedPaths.push(filePath);
+  }
+
+  return renderedPaths;
+}
+
+function resolveRenderPath(template: string, node: Node): string {
+  return template.replace(/\{\{([^}]+)\}\}/g, (_, path: string) => {
+    const parts = path.trim().split(".");
+    let current: unknown = { ...node, ...node.attrs };
+    for (const part of parts) {
+      if (current === null || current === undefined) return "";
+      current = (current as Record<string, unknown>)[part];
+    }
+    return String(current ?? "");
+  });
+}
+
+export async function listViewFiles(viewDir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function walk(dir: string, base: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const relPath = base ? `${base}/${entry.name}` : entry.name;
+      if (entry.name.startsWith(".")) continue;
+
+      if (entry.isDirectory()) {
+        await walk(join(dir, entry.name), relPath);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        files.push(relPath);
+      }
+    }
+  }
+
+  await walk(viewDir, "");
+  return files;
+}
+
+async function cleanupOrphanedFiles(
+  this: Hardcopy,
+  viewDir: string,
+  orphanedFiles: string[],
+): Promise<void> {
+  for (const relPath of orphanedFiles) {
+    const fullPath = join(viewDir, relPath);
+    await syncFileBeforeDelete.call(this, fullPath);
+
+    try {
+      await rm(fullPath);
+      console.log(`Deleted orphaned file: ${relPath}`);
+    } catch (err) {
+      console.error(`Failed to delete ${relPath}: ${err}`);
+    }
+  }
+}
+
+async function syncFileBeforeDelete(
+  this: Hardcopy,
+  fullPath: string,
+): Promise<void> {
+  try {
+    const content = await readFile(fullPath, "utf-8");
+    const parsed = parseFile(content, "generic");
+    const nodeId = (parsed.attrs._id ?? parsed.attrs.id) as string | undefined;
+
+    if (!nodeId) return;
+
+    const crdt = this.getCRDTStore();
+    const doc = await crdt.load(nodeId);
+
+    if (!doc) return;
+
+    const crdtContent = getDocContent(doc);
+    if (parsed.body !== crdtContent) {
+      console.warn(
+        `Warning: File for ${nodeId} has local changes that may be lost. ` +
+          `Run 'hardcopy push' first to preserve changes.`,
+      );
+    }
+
+    await crdt.delete(nodeId);
+  } catch {
+    // File might not be parseable, skip sync
+  }
+}

package/src/hardcopy.ts

@@ -0,0 +1 @@
+export * from "./hardcopy/index";

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from "./types";
+export * from "./provider";
+export * from "./format";
+export * from "./config";
+export * from "./db";
+export * from "./crdt";
+export * from "./hardcopy";
+export * from "./providers";
+export * from "./conflict";
+export * from "./conflict-store";
+export * from "./merge";
+export * from "./llm-merge";
+export { createMcpServer, serveMcp } from "./mcp-server";

package/src/llm-merge.ts

@@ -0,0 +1,109 @@
+/**
+ * LLM-based merge for conflicts that can't be auto-resolved.
+ *
+ * Uses an OpenAI-compatible endpoint (e.g., copilot-proxy) to intelligently
+ * merge conflicting changes by understanding semantic intent.
+ */
+
+export interface LLMMergeOptions {
+  /** OpenAI-compatible API base URL (default: OPENAI_BASE_URL or http://localhost:6433) */
+  baseURL?: string;
+  /** Model to use (default: OPENAI_MODEL or gpt-4o) */
+  model?: string;
+  /** API key for authentication (default: OPENAI_API_KEY) */
+  apiKey?: string;
+  /** Temperature for generation (default: 0) */
+  temperature?: number;
+}
+
+interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+interface ChatCompletionResponse {
+  choices: Array<{
+    message: {
+      content: string;
+    };
+  }>;
+}
+
+const MERGE_SYSTEM_PROMPT = `You are a precise text merge assistant. Your task is to intelligently merge two versions of text that have both been modified from a common base.
+
+Rules:
+1. Preserve ALL meaningful changes from both versions
+2. When both versions change the same content differently, combine the intents (e.g., if one adds bold and one restructures, do both)
+3. Never lose information - if text was added on either side, include it
+4. Maintain consistent formatting and style
+5. Output ONLY the merged text, no explanations or markdown code blocks`;
+
+/**
+ * Attempts to merge conflicting text using an LLM.
+ *
+ * @param base - The common ancestor text
+ * @param local - The local (your) version
+ * @param remote - The remote (their) version
+ * @param options - LLM configuration options
+ * @returns The merged text, or null if the LLM call fails
+ */
+export async function llmMergeText(
+  base: string,
+  local: string,
+  remote: string,
+  options: LLMMergeOptions = {},
+): Promise<string | null> {
+  const baseURL =
+    options.baseURL ?? process.env.OPENAI_BASE_URL ?? "http://localhost:6433";
+  const model = options.model ?? process.env.OPENAI_MODEL ?? "gpt-4o";
+  const apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+  const temperature = options.temperature ?? 0;
+
+  const messages: ChatMessage[] = [
+    { role: "system", content: MERGE_SYSTEM_PROMPT },
+    {
+      role: "user",
+      content: `Merge these two versions that diverged from a common base.
+
+=== BASE (original) ===
+${base}
+
+=== LOCAL (my changes) ===
+${local}
+
+=== REMOTE (their changes) ===
+${remote}
+
+=== MERGED OUTPUT ===`,
+    },
+  ];
+
+  try {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+
+    const response = await fetch(`${baseURL}/chat/completions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        model,
+        messages,
+        temperature,
+        max_tokens: 4096,
+      }),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const data = (await response.json()) as ChatCompletionResponse;
+    return data.choices?.[0]?.message?.content ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/mcp-server.ts

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { Hardcopy } from "./hardcopy";
+
+export function createMcpServer(root: string): Server {
+  const server = new Server(
+    { name: "hardcopy", version: "0.1.0" },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "hardcopy_sync",
+        description: "Sync all configured remote sources to local database",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "hardcopy_status",
+        description: "Show sync status including changed files and conflicts",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "hardcopy_refresh",
+        description: "Refresh local files from database for a view pattern",
+        inputSchema: {
+          type: "object",
+          properties: {
+            pattern: {
+              type: "string",
+              description:
+                "View pattern to refresh (supports glob, e.g. docs/issues)",
+            },
+            clean: {
+              type: "boolean",
+              description: "Remove files that no longer match the view",
+              default: false,
+            },
+            syncFirst: {
+              type: "boolean",
+              description: "Sync data from remote before refreshing",
+              default: false,
+            },
+          },
+          required: ["pattern"],
+        },
+      },
+      {
+        name: "hardcopy_diff",
+        description:
+          "Show local changes vs synced state for files matching pattern",
+        inputSchema: {
+          type: "object",
+          properties: {
+            pattern: {
+              type: "string",
+              description: "File pattern to check (supports glob)",
+            },
+          },
+        },
+      },
+      {
+        name: "hardcopy_push",
+        description: "Push local changes to remote sources",
+        inputSchema: {
+          type: "object",
+          properties: {
+            pattern: {
+              type: "string",
+              description: "File pattern to push (supports glob)",
+            },
+            force: {
+              type: "boolean",
+              description: "Push even if conflicts are detected",
+              default: false,
+            },
+          },
+        },
+      },
+      {
+        name: "hardcopy_conflicts",
+        description: "List all unresolved conflicts",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "hardcopy_resolve",
+        description: "Resolve a specific conflict",
+        inputSchema: {
+          type: "object",
+          properties: {
+            nodeId: {
+              type: "string",
+              description: "The node ID of the conflict to resolve",
+            },
+            resolution: {
+              type: "object",
+              description:
+                'Map of field names to resolution choice ("local" or "remote")',
+              additionalProperties: {
+                type: "string",
+                enum: ["local", "remote"],
+              },
+            },
+          },
+          required: ["nodeId", "resolution"],
+        },
+      },
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+
+    const hc = new Hardcopy({ root });
+
+    try {
+      await hc.initialize();
+      await hc.loadConfig();
+
+      switch (name) {
+        case "hardcopy_sync":
+          return await handleSync(hc);
+        case "hardcopy_status":
+          return await handleStatus(hc);
+        case "hardcopy_refresh":
+          return await handleRefresh(hc, args as unknown as RefreshArgs);
+        case "hardcopy_diff":
+          return await handleDiff(hc, args as unknown as DiffArgs);
+        case "hardcopy_push":
+          return await handlePush(hc, args as unknown as PushArgs);
+        case "hardcopy_conflicts":
+          return await handleConflicts(hc);
+        case "hardcopy_resolve":
+          return await handleResolve(hc, args as unknown as ResolveArgs);
+        default:
+          throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+      }
+    } catch (error) {
+      if (error instanceof McpError) throw error;
+      throw new McpError(
+        ErrorCode.InternalError,
+        `Failed to execute ${name}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      await hc.close();
+    }
+  });
+
+  return server;
+}
+
+interface RefreshArgs {
+  pattern: string;
+  clean?: boolean;
+  syncFirst?: boolean;
+}
+
+interface DiffArgs {
+  pattern?: string;
+}
+
+interface PushArgs {
+  pattern?: string;
+  force?: boolean;
+}
+
+interface ResolveArgs {
+  nodeId: string;
+  resolution: Record<string, "local" | "remote">;
+}
+
+async function handleSync(hc: Hardcopy) {
+  const stats = await hc.sync();
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            synced: { nodes: stats.nodes, edges: stats.edges },
+            errors: stats.errors,
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+async function handleStatus(hc: Hardcopy) {
+  const status = await hc.status();
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            nodes: status.totalNodes,
+            edges: status.totalEdges,
+            byType: status.nodesByType,
+            changedFiles: status.changedFiles.map((f) => ({
+              path: f.path,
+              status: f.status,
+              nodeId: f.nodeId,
+            })),
+            conflicts: status.conflicts.map((c) => ({
+              nodeId: c.nodeId,
+              fields: c.fields.map((f) => f.field),
+            })),
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+async function handleRefresh(hc: Hardcopy, args: RefreshArgs) {
+  const { pattern, clean = false, syncFirst = false } = args;
+
+  if (syncFirst) {
+    await hc.sync();
+  }
+
+  const views = await hc.getViews();
+  const matching = views.filter(
+    (v) =>
+      v === pattern || v.startsWith(pattern) || pattern.includes("*"),
+  );
+
+  if (matching.length === 0) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(
+            { error: `No views match pattern: ${pattern}`, available: views },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+
+  const results: Array<{
+    view: string;
+    rendered: number;
+    orphaned: number;
+    cleaned: boolean;
+  }> = [];
+  for (const view of matching) {
+    const result = await hc.refreshView(view, { clean });
+    results.push({
+      view,
+      rendered: result.rendered,
+      orphaned: result.orphaned.length,
+      cleaned: result.cleaned,
+    });
+  }
+
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(results, null, 2) }],
+  };
+}
+
+async function handleDiff(hc: Hardcopy, args: DiffArgs) {
+  const diffs = await hc.diff(args.pattern);
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          diffs.map((d) => ({
+            nodeId: d.nodeId,
+            nodeType: d.nodeType,
+            filePath: d.filePath,
+            changes: d.changes.map((c) => ({
+              field: c.field,
+              old: truncate(c.oldValue),
+              new: truncate(c.newValue),
+            })),
+          })),
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+async function handlePush(hc: Hardcopy, args: PushArgs) {
+  const stats = await hc.push(args.pattern, { force: args.force });
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            pushed: stats.pushed,
+            skipped: stats.skipped,
+            conflicts: stats.conflicts,
+            errors: stats.errors,
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+async function handleConflicts(hc: Hardcopy) {
+  const conflicts = await hc.listConflicts();
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          conflicts.map((c) => ({
+            nodeId: c.nodeId,
+            nodeType: c.nodeType,
+            filePath: c.filePath,
+            fields: c.fields.map((f) => ({
+              field: f.field,
+              status: f.status,
+              canAutoMerge: f.canAutoMerge,
+            })),
+          })),
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+async function handleResolve(hc: Hardcopy, args: ResolveArgs) {
+  await hc.resolveConflict(args.nodeId, args.resolution);
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify({ resolved: args.nodeId }, null, 2),
+      },
+    ],
+  };
+}
+
+function truncate(value: unknown, maxLen = 100): string {
+  const str = typeof value === "string" ? value : JSON.stringify(value);
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen) + "...";
+}
+
+export async function serveMcp(root: string): Promise<void> {
+  const server = createMcpServer(root);
+  const transport = new StdioServerTransport();
+  console.error("Hardcopy MCP Server running on stdio");
+  await server.connect(transport);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  serveMcp(process.cwd()).catch((error) => {
+    console.error("Fatal error in MCP server:", error);
+    process.exit(1);
+  });
+}