@aprovan/hardcopy 0.1.0

package/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "hardcopy": {
+      "command": "hardcopy",
+      "args": ["mcp-serve"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@aprovan/hardcopy",
+  "version": "0.1.0",
+  "description": "Keep everything close at hand",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "hardcopy": "./dist/cli.js"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.14.0",
+    "@typescript-eslint/parser": "^8.14.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-tsdoc": "^0.5.0",
+    "lint-staged": "^13.0.3",
+    "prettier": "^2.7.1",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "2.1.5"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": "eslint --fix",
+    "*.{js,jsx,ts,tsx,md,scss}": "prettier --write"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@libsql/client": "^0.17.0",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.6.2",
+    "commander": "^14.0.3",
+    "gray-matter": "^4.0.3",
+    "libsql": "^0.5.22",
+    "loro-crdt": "^1.10.6",
+    "minimatch": "^10.2.2",
+    "yaml": "^2.8.2"
+  },
+  "scripts": {
+    "hardcopy": "tsx src/cli.ts",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "setup:graphqlite": "tsx scripts/install-graphqlite.ts",
+    "postinstall": "tsx scripts/install-graphqlite.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"**/*.ts?(x)\"",
+    "lint:fix": "eslint --fix \"**/*.ts?(x)\"",
+    "format": "prettier --write .",
+    "hardcopy:hard-refresh": "pnpm hardcopy:sync && pnpm hardcopy:refresh",
+    "hardcopy:sync": "pnpm hardcopy sync",
+    "hardcopy:status": "pnpm hardcopy status",
+    "hardcopy:refresh": "pnpm hardcopy refresh 'docs/**'",
+    "hardcopy:diff": "pnpm hardcopy diff 'docs/**'",
+    "hardcopy:push": "pnpm hardcopy push 'docs/**'"
+  }
+}

package/scripts/install-graphqlite.ts

@@ -0,0 +1,156 @@
+#!/usr/bin/env tsx
+/**
+ * Downloads the GraphQLite SQLite extension for the current platform.
+ * Run with: pnpm setup:graphqlite
+ */
+
+import { createWriteStream, existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = join(__dirname, "..");
+
+const RELEASE_BASE =
+  "https://github.com/colliery-io/graphqlite/releases/latest/download";
+
+interface PlatformAsset {
+  filename: string;
+  sha256: string;
+}
+
+const ASSETS: Record<string, PlatformAsset> = {
+  "darwin-arm64": {
+    filename: "graphqlite-macos-arm64.dylib",
+    sha256: "a3e50c0bb133005ee0a00f1b881e9c964caef2fcfb76854b8fb800b05eab554d",
+  },
+  "darwin-x64": {
+    filename: "graphqlite-macos-x86_64.dylib",
+    sha256: "cdb517283d6de3dcb97e248b0edcc064a17bb34c6ac9296ced65da260ff0c5ec",
+  },
+  "linux-arm64": {
+    filename: "graphqlite-linux-aarch64.so",
+    sha256: "d86a0ca3c3415f1de529a1be847389544f5c3ab9557313dc08c32c3c7cbc318c",
+  },
+  "linux-x64": {
+    filename: "graphqlite-linux-x86_64.so",
+    sha256: "113ff2efe432d6910fed41c58da73a9bf656e7fd822bfe61c166c80b109a1300",
+  },
+  "win32-x64": {
+    filename: "graphqlite-windows-x86_64.dll",
+    sha256: "55ee805e3e26cba644f1970342e150cf1ce528eb4a513ca50835c825a02a21ea",
+  },
+};
+
+function getPlatformKey(): string {
+  const platform = process.platform;
+  const arch = process.arch;
+  return `${platform}-${arch}`;
+}
+
+function getExtensionDir(): string {
+  return join(PROJECT_ROOT, ".hardcopy", "extensions");
+}
+
+function getExtensionPath(filename: string): string {
+  return join(getExtensionDir(), filename);
+}
+
+async function downloadFile(url: string, dest: string): Promise<void> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download ${url}: ${response.status} ${response.statusText}`,
+    );
+  }
+  if (!response.body) {
+    throw new Error(`No body in response from ${url}`);
+  }
+
+  const dir = dirname(dest);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const fileStream = createWriteStream(dest);
+  // @ts-expect-error Node streams compatibility
+  await pipeline(response.body, fileStream);
+}
+
+async function computeSha256(path: string): Promise<string> {
+  const data = await readFile(path);
+  return createHash("sha256").update(data).digest("hex");
+}
+
+async function verifyChecksum(
+  path: string,
+  expected: string,
+): Promise<boolean> {
+  const actual = await computeSha256(path);
+  return actual === expected;
+}
+
+async function main(): Promise<void> {
+  const platformKey = getPlatformKey();
+  const asset = ASSETS[platformKey];
+
+  if (!asset) {
+    console.error(`Unsupported platform: ${platformKey}`);
+    console.error(`Supported platforms: ${Object.keys(ASSETS).join(", ")}`);
+    console.error("\nYou may need to build GraphQLite from source:");
+    console.error("  https://github.com/colliery-io/graphqlite");
+    process.exit(1);
+  }
+
+  const destPath = getExtensionPath(asset.filename);
+
+  // Check if already installed and valid
+  if (existsSync(destPath)) {
+    console.log(`Checking existing installation at ${destPath}...`);
+    const valid = await verifyChecksum(destPath, asset.sha256);
+    if (valid) {
+      console.log("GraphQLite extension already installed and verified.");
+      printEnvHint(destPath);
+      return;
+    }
+    console.log("Checksum mismatch, re-downloading...");
+    unlinkSync(destPath);
+  }
+
+  const url = `${RELEASE_BASE}/${asset.filename}`;
+  console.log(`Downloading GraphQLite for ${platformKey}...`);
+  console.log(`  URL: ${url}`);
+  console.log(`  Destination: ${destPath}`);
+
+  await downloadFile(url, destPath);
+
+  // Verify checksum
+  console.log("Verifying checksum...");
+  const valid = await verifyChecksum(destPath, asset.sha256);
+  if (!valid) {
+    unlinkSync(destPath);
+    console.error("Checksum verification failed!");
+    console.error(`Expected: ${asset.sha256}`);
+    console.error(`Got: ${await computeSha256(destPath)}`);
+    process.exit(1);
+  }
+
+  console.log("GraphQLite extension installed successfully!");
+  printEnvHint(destPath);
+}
+
+function printEnvHint(path: string): void {
+  console.log("\n--- Setup Complete ---");
+  console.log("The extension will be auto-discovered at runtime.");
+  console.log(`Location: ${path}`);
+  console.log("\nAlternatively, set the environment variable:");
+  console.log(`  export GRAPHQLITE_EXTENSION_PATH="${path}"`);
+}
+
+main().catch((err) => {
+  console.error("Installation failed:", err);
+  process.exit(1);
+});

package/src/cli.ts

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "process";
+import { minimatch } from "minimatch";
+import { Hardcopy, initHardcopy } from "./hardcopy";
+import { serveMcp } from "./mcp-server";
+
+const program = new Command();
+
+program
+  .name("hardcopy")
+  .description("Local-remote sync system")
+  .version("0.1.0");
+
+program
+  .command("init")
+  .description("Initialize hardcopy in current directory")
+  .action(async () => {
+    const root = process.cwd();
+    await initHardcopy(root);
+    console.log("Initialized hardcopy at", root);
+  });
+
+program
+  .command("sync")
+  .description("Sync all sources")
+  .action(async () => {
+    const hc = new Hardcopy({ root: process.cwd() });
+    await hc.initialize();
+    try {
+      const stats = await hc.sync();
+      console.log(`Synced ${stats.nodes} nodes, ${stats.edges} edges`);
+      if (stats.errors.length > 0) {
+        console.error("Errors:", stats.errors.join("\n"));
+      }
+    } finally {
+      await hc.close();
+    }
+  });
+
+program
+  .command("refresh <pattern>")
+  .description("Refresh views matching pattern (supports glob, e.g. docs/*)")
+  .option("--clean", "Remove files that no longer match the view", false)
+  .option("--sync-first", "Sync data from remote before refreshing", false)
+  .action(
+    async (
+      pattern: string,
+      options: { clean: boolean; syncFirst: boolean },
+    ) => {
+      const hc = new Hardcopy({ root: process.cwd() });
+      await hc.initialize();
+      try {
+        const allViews = await hc.getViews();
+        const matchingViews = allViews.filter(
+          (v) => v === pattern || minimatch(v, pattern),
+        );
+
+        if (matchingViews.length === 0) {
+          console.error(`No views match pattern: ${pattern}`);
+          console.log("Available views:", allViews.join(", "));
+          process.exit(1);
+        }
+
+        if (options.syncFirst) {
+          console.log("Syncing from remote...");
+          const stats = await hc.sync();
+          console.log(`Synced ${stats.nodes} nodes, ${stats.edges} edges`);
+        }
+
+        for (const view of matchingViews) {
+          const result = await hc.refreshView(view, { clean: options.clean });
+          console.log(`Refreshed view: ${view} (${result.rendered} files)`);
+
+          if (result.orphaned.length > 0) {
+            if (result.cleaned) {
+              console.log(`  Cleaned ${result.orphaned.length} orphaned files`);
+            } else {
+              console.log(
+                `  Found ${result.orphaned.length} orphaned files. ` +
+                  `Use --clean to remove them:`,
+              );
+              for (const file of result.orphaned.slice(0, 5)) {
+                console.log(`    - ${file}`);
+              }
+              if (result.orphaned.length > 5) {
+                console.log(`    ... and ${result.orphaned.length - 5} more`);
+              }
+            }
+          }
+        }
+      } finally {
+        await hc.close();
+      }
+    },
+  );
+
+program
+  .command("status")
+  .description("Show sync status and changed files")
+  .option("-s, --short", "Show short status (files only)")
+  .action(async (options: { short?: boolean }) => {
+    const hc = new Hardcopy({ root: process.cwd() });
+    await hc.initialize();
+    try {
+      await hc.loadConfig();
+      const status = await hc.status();
+
+      if (options.short) {
+        // Git-like short status
+        for (const file of status.changedFiles) {
+          const marker = file.status === "new" ? "A" : "M";
+          console.log(`${marker}  ${file.path}`);
+        }
+        return;
+      }
+
+      // Full status
+      if (status.changedFiles.length > 0) {
+        console.log("Changes not pushed:");
+        console.log('  (use "hardcopy push <file>" to push changes)');
+        console.log('  (use "hardcopy diff <file>" to see changes)\n');
+        for (const file of status.changedFiles) {
+          const marker = file.status === "new" ? "new file:" : "modified:";
+          console.log(`        ${marker}   ${file.path}`);
+        }
+        console.log();
+      } else {
+        console.log("No local changes\n");
+      }
+
+      if (status.conflicts.length > 0) {
+        console.log("Conflicts:");
+        console.log('  (use "hardcopy conflicts" to list details)\n');
+        for (const conflict of status.conflicts) {
+          const fields = conflict.fields.map((f) => f.field).join(", ");
+          console.log(`        conflict:   ${conflict.nodeId} (${fields})`);
+        }
+        console.log();
+      }
+
+      console.log(
+        `Synced: ${status.totalNodes} nodes, ${status.totalEdges} edges`,
+      );
+      console.log("By type:");
+      for (const [type, count] of Object.entries(status.nodesByType)) {
+        console.log(`  ${type}: ${count}`);
+      }
+    } finally {
+      await hc.close();
+    }
+  });
+
+program
+  .command("push [pattern]")
+  .description("Push local changes to remotes (supports glob patterns)")
+  .option("--dry-run", "Show what would be pushed without actually pushing")
+  .option("--force", "Push even if conflicts are detected", false)
+  .action(
+    async (
+      pattern?: string,
+      options?: { dryRun?: boolean; force?: boolean },
+    ) => {
+      const hc = new Hardcopy({ root: process.cwd() });
+      await hc.initialize();
+      try {
+        await hc.loadConfig();
+
+        if (options?.dryRun) {
+          const diffs = await hc.diff(pattern);
+          if (diffs.length === 0) {
+            console.log("No changes to push");
+            return;
+          }
+          console.log("Would push the following changes:");
+          for (const diff of diffs) {
+            console.log(`\n${diff.nodeId} (${diff.nodeType}):`);
+            for (const change of diff.changes) {
+              console.log(`  ${change.field}: ${formatChange(change)}`);
+            }
+          }
+          return;
+        }
+
+        const stats = await hc.push(pattern, { force: options?.force });
+        console.log(
+          `Pushed ${stats.pushed} changes, skipped ${stats.skipped}, conflicts ${stats.conflicts}`,
+        );
+        if (stats.conflicts > 0) {
+          const conflicts = await hc.listConflicts();
+          const resolved = await resolveConflictsInteractive(
+            hc,
+            conflicts.map((c) => c.nodeId),
+          );
+          if (resolved.length > 0) {
+            const retry = await hc.push(pattern, { force: options?.force });
+            console.log(
+              `Retry push: pushed ${retry.pushed}, skipped ${retry.skipped}, conflicts ${retry.conflicts}`,
+            );
+          }
+        }
+        if (stats.errors.length > 0) {
+          console.error("Errors:");
+          for (const err of stats.errors) {
+            console.error(`  ${err}`);
+          }
+        }
+      } finally {
+        await hc.close();
+      }
+    },
+  );
+
+program
+  .command("conflicts")
+  .description("List unresolved conflicts")
+  .action(async () => {
+    const hc = new Hardcopy({ root: process.cwd() });
+    await hc.initialize();
+    try {
+      const conflicts = await hc.listConflicts();
+      if (conflicts.length === 0) {
+        console.log("No conflicts");
+        return;
+      }
+      for (const conflict of conflicts) {
+        const fields = conflict.fields.map((f) => f.field).join(", ");
+        console.log(`${conflict.nodeId} (${fields})`);
+      }
+    } finally {
+      await hc.close();
+    }
+  });
+
+program
+  .command("resolve <nodeId>")
+  .description("Resolve conflicts interactively")
+  .action(async (nodeId: string) => {
+    const hc = new Hardcopy({ root: process.cwd() });
+    await hc.initialize();
+    try {
+      await resolveConflictsInteractive(hc, [nodeId]);
+    } finally {
+      await hc.close();
+    }
+  });
+
+async function resolveConflictsInteractive(
+  hc: Hardcopy,
+  nodeIds: string[],
+): Promise<string[]> {
+  const rl = createInterface({ input, output });
+  const resolved: string[] = [];
+  try {
+    for (const nodeId of nodeIds) {
+      const detail = await hc.getConflictDetail(nodeId);
+      if (!detail) continue;
+      const conflict = detail.info;
+
+      console.log(`\nConflict: ${nodeId}`);
+      console.log(`Artifact: ${detail.artifactPath}`);
+      if (detail.body.trim()) {
+        console.log(detail.body.trim());
+      }
+
+      const resolution: Record<string, "local" | "remote"> = {};
+
+      for (const field of conflict.fields) {
+        if (field.status !== "diverged") continue;
+        let answer = "";
+        while (!answer) {
+          const response = await rl.question(
+            `Resolve ${field.field} for ${nodeId} (l=local, r=remote, s=skip): `,
+          );
+          const normalized = response.trim().toLowerCase();
+          if (normalized === "l" || normalized === "local") {
+            resolution[field.field] = "local";
+            answer = "local";
+          } else if (normalized === "r" || normalized === "remote") {
+            resolution[field.field] = "remote";
+            answer = "remote";
+          } else if (normalized === "s" || normalized === "skip") {
+            answer = "skip";
+          }
+        }
+      }
+
+      if (Object.keys(resolution).length === 0) {
+        console.log(`No fields resolved for ${nodeId}`);
+        continue;
+      }
+
+      await hc.resolveConflict(nodeId, resolution);
+      console.log(`Resolved conflict: ${nodeId}`);
+      resolved.push(nodeId);
+    }
+  } finally {
+    rl.close();
+  }
+  return resolved;
+}
+
+program
+  .command("diff [pattern]")
+  .description("Show local changes vs synced state (supports glob patterns)")
+  .option("--all", "Check all files, not just recently modified")
+  .action(async (pattern?: string, options?: { all?: boolean }) => {
+    const hc = new Hardcopy({ root: process.cwd() });
+    await hc.initialize();
+    try {
+      await hc.loadConfig();
+      const diffs = await hc.diff(pattern, { smart: !options?.all });
+      if (diffs.length === 0) {
+        console.log("No changes detected");
+        return;
+      }
+      for (const diff of diffs) {
+        console.log(`\n${diff.nodeId} (${diff.nodeType}):`);
+        console.log(`  File: ${diff.filePath}`);
+        for (const change of diff.changes) {
+          console.log(`  ${change.field}: ${formatChange(change)}`);
+        }
+      }
+    } finally {
+      await hc.close();
+    }
+  });
+
+function formatChange(change: {
+  field: string;
+  oldValue: unknown;
+  newValue: unknown;
+}): string {
+  const old =
+    typeof change.oldValue === "string"
+      ? change.oldValue.slice(0, 50) +
+        (change.oldValue.length > 50 ? "..." : "")
+      : JSON.stringify(change.oldValue);
+  const newVal =
+    typeof change.newValue === "string"
+      ? change.newValue.slice(0, 50) +
+        (change.newValue.length > 50 ? "..." : "")
+      : JSON.stringify(change.newValue);
+  return `${old} → ${newVal}`;
+}
+
+program
+  .command("mcp-serve")
+  .description("Start MCP server for LLM tool integration")
+  .action(async () => {
+    await serveMcp(process.cwd());
+  });
+
+program.parse();

package/src/config.ts

@@ -0,0 +1,104 @@
+import { readFile } from "fs/promises";
+import yaml from "yaml";
+
+export interface LinkConfig {
+  edge: string;
+  to: string;
+  match: string;
+}
+
+export interface SourceConfig {
+  name: string;
+  provider: string;
+  orgs?: string[];
+  repositories?: { path: string }[];
+  links?: LinkConfig[];
+  [key: string]: unknown;
+}
+
+export interface RenderConfig {
+  path: string;
+  type?: string;
+  template?: string;
+  args?: Record<string, unknown>;
+}
+
+export interface ViewConfig {
+  path: string;
+  description?: string;
+  query: string;
+  partition?: {
+    by: string;
+    fallback?: string;
+  };
+  render: RenderConfig[];
+}
+
+export interface Config {
+  sources: SourceConfig[];
+  views: ViewConfig[];
+}
+
+export async function loadConfig(path: string): Promise<Config> {
+  const content = await readFile(path, "utf-8");
+  return parseConfig(content);
+}
+
+export function parseConfig(content: string): Config {
+  const parsed = yaml.parse(content);
+  return validateConfig(parsed);
+}
+
+function validateConfig(data: unknown): Config {
+  if (!data || typeof data !== "object") {
+    throw new Error("Config must be an object");
+  }
+
+  const config = data as Record<string, unknown>;
+
+  return {
+    sources: validateSources(config["sources"]),
+    views: validateViews(config["views"]),
+  };
+}
+
+function validateSources(data: unknown): SourceConfig[] {
+  if (!Array.isArray(data)) {
+    return [];
+  }
+  return data.map((s, i) => {
+    if (!s || typeof s !== "object") {
+      throw new Error(`Source ${i} must be an object`);
+    }
+    const source = s as Record<string, unknown>;
+    if (typeof source["name"] !== "string") {
+      throw new Error(`Source ${i} must have a name`);
+    }
+    if (typeof source["provider"] !== "string") {
+      throw new Error(`Source ${i} must have a provider`);
+    }
+    return source as unknown as SourceConfig;
+  });
+}
+
+function validateViews(data: unknown): ViewConfig[] {
+  if (!Array.isArray(data)) {
+    return [];
+  }
+  return data.map((v, i) => {
+    if (!v || typeof v !== "object") {
+      throw new Error(`View ${i} must be an object`);
+    }
+    const view = v as Record<string, unknown>;
+    if (typeof view["path"] !== "string") {
+      throw new Error(`View ${i} must have a path`);
+    }
+    if (typeof view["query"] !== "string") {
+      throw new Error(`View ${i} must have a query`);
+    }
+    if (!Array.isArray(view["render"])) {
+      throw new Error(`View ${i} must have render configs`);
+    }
+    return view as unknown as ViewConfig;
+  });
+}