@storacha/clawracha 0.0.1

package/src/watcher.ts

@@ -0,0 +1,128 @@
+/**
+ * File watcher - monitors workspace for changes
+ *
+ * Uses chokidar to watch for file changes and batches them
+ * before triggering sync.
+ */
+
+import chokidar from "chokidar";
+import * as path from "node:path";
+import type { FileChange, SyncPluginConfig } from "./types/index.js";
+
+export interface WatcherOptions {
+  workspace: string;
+  config: SyncPluginConfig;
+  onChanges: (changes: FileChange[]) => Promise<void>;
+  debounceMs?: number;
+}
+
+export class FileWatcher {
+  private watcher: chokidar.FSWatcher | null = null;
+  private pendingChanges: Map<string, FileChange> = new Map();
+  private debounceTimer: NodeJS.Timeout | null = null;
+  private options: WatcherOptions;
+  private debounceMs: number;
+
+  constructor(options: WatcherOptions) {
+    this.options = options;
+    this.debounceMs = options.debounceMs ?? 500;
+  }
+
+  /**
+   * Start watching the workspace
+   */
+  start(): void {
+    if (this.watcher) return;
+
+    const { workspace, config } = this.options;
+
+    // Build watch patterns
+    const watchPaths = config.watchPatterns.map((p) => path.join(workspace, p));
+
+    // Build ignore patterns
+    const ignored = [
+      ...config.ignorePatterns,
+      ".storacha/**", // Always ignore our own data
+    ];
+
+    this.watcher = chokidar.watch(watchPaths, {
+      ignored,
+      persistent: true,
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 200,
+        pollInterval: 100,
+      },
+    });
+
+    this.watcher
+      .on("add", (filePath) => this.handleChange("add", filePath))
+      .on("change", (filePath) => this.handleChange("change", filePath))
+      .on("unlink", (filePath) => this.handleChange("unlink", filePath))
+      .on("error", (err) => console.error("Watcher error:", err));
+  }
+
+  /**
+   * Stop watching
+   */
+  async stop(): Promise<void> {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+  }
+
+  /**
+   * Handle a file change event
+   */
+  private handleChange(
+    type: "add" | "change" | "unlink",
+    filePath: string
+  ): void {
+    const relativePath = path.relative(this.options.workspace, filePath);
+
+    // Dedupe: later events for same path replace earlier ones
+    this.pendingChanges.set(relativePath, { type, path: relativePath });
+
+    // Debounce: wait for activity to settle before processing
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      this.flush();
+    }, this.debounceMs);
+  }
+
+  /**
+   * Flush pending changes to callback
+   */
+  private async flush(): Promise<void> {
+    if (this.pendingChanges.size === 0) return;
+
+    const changes = Array.from(this.pendingChanges.values());
+    this.pendingChanges.clear();
+
+    try {
+      await this.options.onChanges(changes);
+    } catch (err) {
+      console.error("Error processing file changes:", err);
+    }
+  }
+
+  /**
+   * Force immediate flush (for testing)
+   */
+  async forceFlush(): Promise<void> {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    await this.flush();
+  }
+}

package/test/blockstore/blockstore.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import * as raw from "multiformats/codecs/raw";
+import {
+  MemoryBlockstore,
+  DiskBlockstore,
+  createWorkspaceBlockstore,
+} from "../../src/blockstore/index.js";
+
+const createTestBlock = async (content: string) => {
+  const bytes = new TextEncoder().encode(content);
+  const hash = await sha256.digest(bytes);
+  const cid = CID.create(1, raw.code, hash);
+  return { cid, bytes };
+};
+
+describe("MemoryBlockstore (from UCN)", () => {
+  it("should store and retrieve blocks", async () => {
+    const store = new MemoryBlockstore();
+    const block = await createTestBlock("hello");
+
+    await store.put(block);
+    const retrieved = await store.get(block.cid);
+
+    expect(retrieved).toBeDefined();
+    expect(new Uint8Array(retrieved!.bytes)).toEqual(block.bytes);
+  });
+
+  it("should return undefined for missing blocks", async () => {
+    const store = new MemoryBlockstore();
+    const block = await createTestBlock("missing");
+
+    const retrieved = await store.get(block.cid);
+    expect(retrieved).toBeUndefined();
+  });
+});
+
+describe("DiskBlockstore", () => {
+  let tmpDir: string;
+  let store: DiskBlockstore;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawracha-test-"));
+    store = new DiskBlockstore(tmpDir);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("should store and retrieve blocks", async () => {
+    const block = await createTestBlock("disk-test");
+
+    await store.put(block);
+    const retrieved = await store.get(block.cid);
+
+    expect(retrieved).toBeDefined();
+    expect(new Uint8Array(retrieved!.bytes)).toEqual(block.bytes);
+  });
+
+  it("should persist blocks to disk", async () => {
+    const block = await createTestBlock("persist-test");
+
+    await store.put(block);
+
+    const store2 = new DiskBlockstore(tmpDir);
+    const retrieved = await store2.get(block.cid);
+
+    expect(retrieved).toBeDefined();
+    expect(new Uint8Array(retrieved!.bytes)).toEqual(block.bytes);
+  });
+});
+
+describe("createWorkspaceBlockstore", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawracha-ws-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("should store and retrieve via tiered blockstore", async () => {
+    const store = createWorkspaceBlockstore(tmpDir);
+    const block = await createTestBlock("workspace-test");
+
+    await store.put(block);
+    const retrieved = await store.get(block.cid);
+
+    expect(retrieved).toBeDefined();
+    expect(new Uint8Array(retrieved!.bytes)).toEqual(block.bytes);
+  });
+
+  it("should persist to disk", async () => {
+    const store = createWorkspaceBlockstore(tmpDir);
+    const block = await createTestBlock("persist-ws-test");
+
+    await store.put(block);
+
+    // Verify on disk directly
+    const disk = new DiskBlockstore(tmpDir);
+    const retrieved = await disk.get(block.cid);
+
+    expect(retrieved).toBeDefined();
+    expect(new Uint8Array(retrieved!.bytes)).toEqual(block.bytes);
+  });
+});

package/test/handlers/apply.test.ts

@@ -0,0 +1,276 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import * as raw from "multiformats/codecs/raw";
+import { connect } from "@ucanto/client";
+import * as CAR from "@ucanto/transport/car";
+import * as ed25519 from "@ucanto/principal/ed25519";
+
+import { Agent, Name, Revision } from "@storacha/ucn/pail";
+import type { ClockConnection, ValueView } from "@storacha/ucn/pail/api";
+import { MemoryBlockstore } from "@storacha/ucn/block";
+import { createServer, createService } from "@storacha/ucn/server";
+import type { HeadEvent } from "@storacha/ucn/server/api";
+import { applyPendingOps } from "../../src/handlers/apply.js";
+import type { PailOp } from "../../src/types/index.js";
+import { Block } from "@ucanto/interface";
+
+// --- Helpers ---
+
+const createTestCID = async (content: string) => {
+  const bytes = new TextEncoder().encode(content);
+  const hash = await sha256.digest(bytes);
+  return CID.create(1, raw.code, hash);
+};
+
+class MemoryHeadStorage {
+  heads: Record<string, HeadEvent[]> = {};
+
+  async get(clock: string) {
+    return this.heads[clock]
+      ? { ok: this.heads[clock] }
+      : { error: { name: "NotFound" as const, message: "Clock not found" } };
+  }
+
+  async put(clock: string, head: HeadEvent[]) {
+    this.heads[clock] = head;
+    return { ok: {} };
+  }
+}
+
+const storeBlocks = async (store: MemoryBlockstore, blocks: Array<Block>) => {
+  for (const block of blocks) {
+    await store.put(block);
+  }
+};
+
+/**
+ * Create a mock clock server and return a ClockConnection for it.
+ * Shared headStore + blockCache allow multiple agents to sync.
+ */
+const createTestEnv = async (sharedBlocks?: MemoryBlockstore) => {
+  const headStore = new MemoryHeadStorage();
+  const blockCache = sharedBlocks ?? new MemoryBlockstore();
+  const serviceId = await ed25519.generate();
+
+  const service = createService({
+    headStore: headStore,
+    blockFetcher: blockCache,
+    blockCache,
+  });
+
+  const server = createServer(serviceId, service);
+  const remote = connect({
+    id: serviceId,
+    codec: CAR.outbound,
+    channel: server,
+  }) as unknown as ClockConnection;
+
+  return { remote, headStore, blockCache };
+};
+
+/**
+ * Read all entries from a pail value.
+ */
+const getEntries = async (
+  blocks: MemoryBlockstore,
+  value: ValueView,
+): Promise<Map<string, string>> => {
+  const entries = new Map<string, string>();
+  for await (const [key, val] of Revision.entries(blocks, value)) {
+    entries.set(key, (val as CID).toString());
+  }
+  return entries;
+};
+
+// --- Tests ---
+
+describe("applyPendingOps", () => {
+  let blocks: MemoryBlockstore;
+  let remote: ClockConnection;
+
+  beforeEach(async () => {
+    blocks = new MemoryBlockstore();
+    const env = await createTestEnv();
+    remote = env.remote;
+  });
+
+  it("should handle a single put on an empty pail", async () => {
+    const agent = await Agent.generate();
+    const name = await Name.create(agent);
+    const cid = await createTestCID("file-a");
+
+    const ops: PailOp[] = [{ type: "put", key: "docs/readme.md", value: cid }];
+
+    const result = await applyPendingOps(blocks, name, null, ops, {
+      remotes: [remote],
+    });
+
+    expect(result.current).not.toBeNull();
+    expect(result.revisionBlocks.length).toBeGreaterThan(0);
+
+    // Store blocks so we can read entries
+    await storeBlocks(blocks, result.revisionBlocks);
+
+    const entries = await getEntries(blocks, result.current!);
+    expect(entries.size).toBe(1);
+    expect(entries.get("docs/readme.md")).toBe(cid.toString());
+  });
+
+  it("should handle multiple puts on an empty pail", async () => {
+    const agent = await Agent.generate();
+    const name = await Name.create(agent);
+    const cidA = await createTestCID("file-a");
+    const cidB = await createTestCID("file-b");
+    const cidC = await createTestCID("file-c");
+
+    const ops: PailOp[] = [
+      { type: "put", key: "a.txt", value: cidA },
+      { type: "put", key: "b.txt", value: cidB },
+      { type: "put", key: "c.txt", value: cidC },
+    ];
+
+    const result = await applyPendingOps(blocks, name, null, ops, {
+      remotes: [remote],
+    });
+
+    expect(result.current).not.toBeNull();
+    await storeBlocks(blocks, result.revisionBlocks);
+
+    const entries = await getEntries(blocks, result.current!);
+    expect(entries.size).toBe(3);
+    expect(entries.get("a.txt")).toBe(cidA.toString());
+    expect(entries.get("b.txt")).toBe(cidB.toString());
+    expect(entries.get("c.txt")).toBe(cidC.toString());
+  });
+
+  it("should handle puts and dels on an existing value", async () => {
+    const agent = await Agent.generate();
+    const name = await Name.create(agent);
+
+    // Bootstrap with initial entries
+    const cidA = await createTestCID("file-a");
+    const cidB = await createTestCID("file-b");
+    const init = await applyPendingOps(
+      blocks,
+      name,
+      null,
+      [
+        { type: "put", key: "a.txt", value: cidA },
+        { type: "put", key: "b.txt", value: cidB },
+      ],
+      { remotes: [remote] },
+    );
+    await storeBlocks(blocks, init.revisionBlocks);
+
+    // Now apply mixed ops: add c.txt, delete a.txt
+    const cidC = await createTestCID("file-c");
+    const result = await applyPendingOps(
+      blocks,
+      name,
+      init.current,
+      [
+        { type: "put", key: "c.txt", value: cidC },
+        { type: "del", key: "a.txt" },
+      ],
+      { remotes: [remote] },
+    );
+
+    expect(result.current).not.toBeNull();
+    await storeBlocks(blocks, result.revisionBlocks);
+
+    const entries = await getEntries(blocks, result.current!);
+    expect(entries.size).toBe(2);
+    expect(entries.has("a.txt")).toBe(false);
+    expect(entries.get("b.txt")).toBe(cidB.toString());
+    expect(entries.get("c.txt")).toBe(cidC.toString());
+  });
+
+  it("should return null current when no ops and no current", async () => {
+    const agent = await Agent.generate();
+    const name = await Name.create(agent);
+
+    const result = await applyPendingOps(blocks, name, null, [], {
+      remotes: [remote],
+    });
+
+    expect(result.current).toBeNull();
+    expect(result.revisionBlocks).toEqual([]);
+  });
+
+  it("should converge when two agents publish concurrently", async () => {
+    const sharedBlocks = new MemoryBlockstore();
+    const env = await createTestEnv(sharedBlocks);
+
+    const agentA = await Agent.generate();
+    const nameA = await Name.create(agentA);
+
+    const agentB = await Agent.generate();
+    const proof = await Name.grant(nameA, agentB.did());
+    const nameB = Name.from(agentB, [proof]);
+
+    const cid1 = await createTestCID("file-1");
+    const cid2 = await createTestCID("file-2");
+    const cid3 = await createTestCID("file-3");
+
+    // Step 1: Agent A puts first key
+    const resultA1 = await applyPendingOps(
+      sharedBlocks,
+      nameA,
+      null,
+      [{ type: "put", key: "one.txt", value: cid1 }],
+      { remotes: [env.remote] },
+    );
+    await storeBlocks(sharedBlocks, resultA1.revisionBlocks);
+
+    // Step 2: Agent B resolves to get A's value
+    const resolveB1 = await Revision.resolve(sharedBlocks, nameB, {
+      remotes: [env.remote],
+    });
+    await storeBlocks(sharedBlocks, resolveB1.additions);
+    let currentB = resolveB1.value;
+
+    // Step 3: Agent A puts second key
+    const resultA2 = await applyPendingOps(
+      sharedBlocks,
+      nameA,
+      resultA1.current,
+      [{ type: "put", key: "two.txt", value: cid2 }],
+      { remotes: [env.remote] },
+    );
+    await storeBlocks(sharedBlocks, resultA2.revisionBlocks);
+
+    // Step 4: Agent B (still on old value) puts third key and applies
+    const resultB = await applyPendingOps(
+      sharedBlocks,
+      nameB,
+      currentB,
+      [{ type: "put", key: "three.txt", value: cid3 }],
+      { remotes: [env.remote] },
+    );
+    await storeBlocks(sharedBlocks, resultB.revisionBlocks);
+
+    // Agent B should see all three keys
+    const entriesB = await getEntries(sharedBlocks, resultB.current!);
+    expect(entriesB.size).toBe(3);
+    expect(entriesB.get("one.txt")).toBe(cid1.toString());
+    expect(entriesB.get("two.txt")).toBe(cid2.toString());
+    expect(entriesB.get("three.txt")).toBe(cid3.toString());
+
+    // Step 5: Agent A resolves — should also see all three keys
+    const resolveA = await Revision.resolve(sharedBlocks, nameA, {
+      base: resultA2.current ?? undefined,
+      remotes: [env.remote],
+    });
+    await storeBlocks(sharedBlocks, resolveA.additions);
+
+    const entriesA = await getEntries(sharedBlocks, resolveA.value);
+    expect(entriesA.size).toBe(3);
+    expect(entriesA.get("one.txt")).toBe(cid1.toString());
+    expect(entriesA.get("two.txt")).toBe(cid2.toString());
+    expect(entriesA.get("three.txt")).toBe(cid3.toString());
+
+    // Both agents should have converged to the same root
+    expect(resolveA.value.root.toString()).toBe(resultB.current!.root.toString());
+  });
+});