@storacha/clawracha 0.0.4 → 0.0.6

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@storacha/clawracha",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "OpenClaw plugin for Storacha workspace sync via UCN Pail",
   "type": "module",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
   "main": "dist/plugin.js",
   "types": "dist/plugin.d.ts",
   "openclaw": {

package/src/blockstore/disk.ts

@@ -1,57 +0,0 @@
-/**
- * Filesystem-backed blockstore — the one thing UCN doesn't ship.
- * Persists blocks to .storacha/blocks/ in workspace.
- */
-
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import type { Link, Block, Version } from "multiformats";
-import { decode } from "multiformats/block";
-import * as raw from "multiformats/codecs/raw";
-import { sha256 } from "multiformats/hashes/sha2";
-
-export class DiskBlockstore {
-  private dir: string;
-  private initialized = false;
-
-  constructor(workspacePath: string) {
-    this.dir = path.join(workspacePath, ".storacha", "blocks");
-  }
-
-  private async ensureDir(): Promise<void> {
-    if (!this.initialized) {
-      await fs.mkdir(this.dir, { recursive: true });
-      this.initialized = true;
-    }
-  }
-
-  private cidPath(cid: Link<unknown, number, number, Version>): string {
-    return path.join(this.dir, cid.toString());
-  }
-
-  async get<
-    T = unknown,
-    C extends number = number,
-    A extends number = number,
-    V extends Version = 1
-  >(link: Link<T, C, A, V>): Promise<Block<T, C, A, V> | undefined> {
-    try {
-      const bytes = new Uint8Array(await fs.readFile(this.cidPath(link)));
-      // Return a minimal block — decoder doesn't matter for storage, the CID is the truth
-      return { cid: link, bytes, links: () => [] } as unknown as Block<
-        T,
-        C,
-        A,
-        V
-      >;
-    } catch (err: any) {
-      if (err.code === "ENOENT") return undefined;
-      throw err;
-    }
-  }
-
-  async put(block: Block): Promise<void> {
-    await this.ensureDir();
-    await fs.writeFile(this.cidPath(block.cid), block.bytes);
-  }
-}

package/src/blockstore/index.ts

@@ -1,23 +0,0 @@
-/**
- * Blockstore layer — thin wrapper around @storacha/ucn/block
- *
- * UCN provides: MemoryBlockstore, LRUBlockstore, GatewayBlockFetcher,
- * TieredBlockFetcher, withCache.
- *
- * We add: DiskBlockstore (filesystem persistence) and a pre-configured
- * tiered setup for workspace sync.
- */
-
-export {
-  MemoryBlockstore,
-  LRUBlockstore,
-  GatewayBlockFetcher,
-  TieredBlockFetcher,
-  withCache,
-} from "@storacha/ucn/block";
-
-export { DiskBlockstore } from "./disk.js";
-export {
-  createWorkspaceBlockstore,
-  type WorkspaceBlockstore,
-} from "./workspace.js";

package/src/blockstore/workspace.ts

@@ -1,41 +0,0 @@
-/**
- * Pre-configured blockstore for workspace sync:
- * Memory (LRU) → Disk → Gateway, with cache promotion.
- */
-
-import {
-  LRUBlockstore,
-  GatewayBlockFetcher,
-  TieredBlockFetcher,
-  withCache,
-} from "@storacha/ucn/block";
-import { DiskBlockstore } from "./disk.js";
-import type { Block } from "multiformats";
-
-export interface WorkspaceBlockstore {
-  get: TieredBlockFetcher["get"];
-  put: (block: Block) => Promise<void>;
-}
-
-export function createWorkspaceBlockstore(
-  workspacePath: string,
-  options?: { gateway?: string; lruMax?: number }
-): WorkspaceBlockstore {
-  const memory = new LRUBlockstore(options?.lruMax ?? 1024);
-  const disk = new DiskBlockstore(workspacePath);
-  const gateway = new GatewayBlockFetcher(options?.gateway);
-
-  // Reads: memory → disk → gateway, with cache promotion to memory
-  const fetcher = withCache(
-    new TieredBlockFetcher(memory, disk, gateway),
-    memory
-  );
-
-  return {
-    get: fetcher.get.bind(fetcher),
-    async put(block: Block) {
-      await memory.put(block);
-      await disk.put(block);
-    },
-  };
-}

package/src/handlers/apply.ts

@@ -1,79 +0,0 @@
-/**
- * Pure function to apply pending pail operations (puts/dels) and publish.
- *
- * Cycle: operation → publish → return value.
- * Bootstraps with v0Put when no current value exists.
- */
-
-import { Revision } from "@storacha/ucn/pail";
-import * as Batch from "@storacha/ucn/pail/batch";
-import type {
-  ClockConnection,
-  NameView,
-  ValueView,
-} from "@storacha/ucn/pail/api";
-import type { Block } from "multiformats";
-import { MemoryBlockstore, withCache } from "@storacha/ucn/block";
-
-import type { PailOp } from "../types/index.js";
-import type { WorkspaceBlockstore } from "../blockstore/index.js";
-
-export interface ApplyResult {
-  current: ValueView | null;
-  revisionBlocks: Block[];
-}
-
-export async function applyPendingOps(
-  blocks: WorkspaceBlockstore,
-  name: NameView,
-  current: ValueView | null,
-  pendingOps: PailOp[],
-  options?: { remotes?: ClockConnection[] },
-): Promise<ApplyResult> {
-  const revisionBlocks: Block[] = [];
-  let ops = [...pendingOps];
-
-  // Local cache so each step can read blocks produced by previous steps
-  const cache = new MemoryBlockstore();
-  const fetcher = withCache(blocks, cache);
-
-  const accumulate = (additions: Block[]) => {
-    for (const block of additions) {
-      cache.put(block);
-    }
-    revisionBlocks.push(...additions);
-  };
-
-  if (!current) {
-    const firstPut = ops.find((op) => op.type === "put" && op.value);
-    if (firstPut?.value) {
-      const result = await Revision.v0Put(fetcher, firstPut.key, firstPut.value);
-      accumulate(result.additions);
-
-      const pubResult = await Revision.publish(fetcher, name, result.revision, { remotes: options?.remotes });
-      accumulate(pubResult.additions);
-      current = pubResult.value;
-
-      ops = ops.filter((op) => op !== firstPut);
-    }
-  }
-
-  if (ops.length > 0 && current) {
-    const batcher = await Batch.create(fetcher, current);
-    for (const op of ops) {
-      if (op.type === "put" && op.value) {
-        await batcher.put(op.key, op.value);
-      } else if (op.type === "del") {
-        await batcher.del(op.key);
-      }
-    }
-    const result = await batcher.commit();
-    accumulate(result.additions);
-
-    const pubResult = await Revision.publish(fetcher, name, result.revision, { remotes: options?.remotes });
-    accumulate(pubResult.additions);
-    current = pubResult.value;
-  }
-
-  return { current, revisionBlocks };
-}

package/src/handlers/process.ts

@@ -1,118 +0,0 @@
-/**
- * Pure function to diff file changes against pail state and produce ops.
- *
- * Markdown files (.md) are handled via mdsync — CRDT merge rather than
- * whole-file UnixFS replacement. Regular files go through encodeFiles.
- */
-
-import { CID } from "multiformats/cid";
-import { Revision } from "@storacha/ucn/pail";
-import type {
-  BlockFetcher,
-  UnknownLink,
-  ValueView,
-} from "@storacha/ucn/pail/api";
-import type { Block } from "multiformats";
-import type { FileChange, PailOp } from "../types/index.js";
-import { encodeFiles } from "../utils/encoder.js";
-import * as mdsync from "../mdsync/index.js";
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-
-/** Callback to persist a block to the CAR file for upload. */
-export type BlockSink = (block: Block) => Promise<void>;
-
-/** Callback to persist a block to the local blockstore for future reads. */
-export type BlockStore = (block: Block) => Promise<void>;
-
-const isMarkdown = (filePath: string) => filePath.endsWith(".md");
-
-export async function processChanges(
-  changes: FileChange[],
-  workspace: string,
-  current: ValueView | null,
-  blocks: BlockFetcher,
-  sink: BlockSink,
-  store?: BlockStore,
-): Promise<PailOp[]> {
-  const pendingOps: PailOp[] = [];
-
-  const mdChanges = changes.filter((c) => isMarkdown(c.path));
-  const regularChanges = changes.filter((c) => !isMarkdown(c.path));
-
-  // --- Regular files (UnixFS encode) ---
-  const toEncode = regularChanges
-    .filter((c) => c.type !== "unlink")
-    .map((c) => c.path);
-
-  const encoded = await encodeFiles(workspace, toEncode);
-
-  const files = [];
-  for (const file of encoded) {
-    let root: UnknownLink | null = null;
-    const reader = file.blocks.getReader();
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      root = value.cid;
-      await sink(value as unknown as Block);
-    }
-    if (!root) {
-      throw new Error(`Failed to encode file: ${file.path}`);
-    }
-    files.push({ path: file.path, rootCID: root as UnknownLink });
-  }
-
-  for (const file of files) {
-    const existing = current
-      ? await Revision.get(blocks, current, file.path)
-      : null;
-    if (!existing || !existing.equals(file.rootCID)) {
-      pendingOps.push({
-        type: "put",
-        key: file.path,
-        value: file.rootCID as CID,
-      });
-    }
-  }
-
-  // --- Markdown files (CRDT merge via mdsync) ---
-  const mdPuts = mdChanges.filter((c) => c.type !== "unlink");
-  for (const change of mdPuts) {
-    const content = await fs.readFile(
-      path.join(workspace, change.path),
-      "utf-8",
-    );
-    const { mdEntryCid, additions } = current
-      ? await mdsync.put(blocks, current, change.path, content)
-      : await mdsync.v0Put(content);
-
-    // Sink blocks to CAR for upload, and store locally for future resolveValue calls.
-    for (const block of additions) {
-      await sink(block);
-      if (store) await store(block);
-    }
-
-    pendingOps.push({
-      type: "put",
-      key: change.path,
-      value: mdEntryCid as CID,
-    });
-  }
-
-  // --- Deletes (both regular and markdown) ---
-  const toDelete = changes
-    .filter((c) => c.type === "unlink")
-    .map((c) => c.path);
-
-  for (const deletePath of toDelete) {
-    const existing = current
-      ? await Revision.get(blocks, current, deletePath)
-      : null;
-    if (existing) {
-      pendingOps.push({ type: "del", key: deletePath });
-    }
-  }
-
-  return pendingOps;
-}

package/src/handlers/remote.ts

@@ -1,61 +0,0 @@
-/**
- * Apply remote changes to local filesystem.
- *
- * Regular files are fetched from the IPFS gateway (handles UnixFS reassembly).
- * Markdown files (.md) are resolved via mdsync CRDT merge — the tiered
- * blockstore's gateway layer handles fetching any missing blocks.
- */
-
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import type { CID } from "multiformats/cid";
-import type { BlockFetcher, ValueView } from "@storacha/ucn/pail/api";
-import * as mdsync from "../mdsync/index.js";
-
-const DEFAULT_GATEWAY = "https://storacha.link";
-
-const isMarkdown = (filePath: string) => filePath.endsWith(".md");
-
-export async function applyRemoteChanges(
-  changedPaths: string[],
-  entries: Map<string, CID>,
-  workspace: string,
-  options?: {
-    gateway?: string;
-    blocks?: BlockFetcher;
-    current?: ValueView;
-  },
-): Promise<void> {
-  const gateway = options?.gateway ?? DEFAULT_GATEWAY;
-
-  for (const relativePath of changedPaths) {
-    const cid = entries.get(relativePath);
-    const fullPath = path.join(workspace, relativePath);
-
-    if (!cid) {
-      // Deleted remotely
-      try {
-        await fs.unlink(fullPath);
-      } catch (err: any) {
-        if (err.code !== "ENOENT") throw err;
-      }
-    } else if (isMarkdown(relativePath) && options?.blocks && options?.current) {
-      // Markdown: resolve via mdsync CRDT merge.
-      // The blockstore's lowest tier is a gateway fetcher, so any blocks
-      // we don't have locally will be fetched transparently.
-      const content = await mdsync.get(options.blocks, options.current, relativePath);
-      if (content != null) {
-        await fs.mkdir(path.dirname(fullPath), { recursive: true });
-        await fs.writeFile(fullPath, content);
-      }
-    } else {
-      // Regular file: fetch full file from gateway (handles UnixFS reassembly)
-      const res = await fetch(`${gateway}/ipfs/${cid}`);
-      if (!res.ok) {
-        throw new Error(`Gateway fetch failed for ${cid}: ${res.status}`);
-      }
-      await fs.mkdir(path.dirname(fullPath), { recursive: true });
-      await fs.writeFile(fullPath, new Uint8Array(await res.arrayBuffer()));
-    }
-  }
-}

package/src/index.ts

@@ -1,13 +0,0 @@
-/**
- * @storacha/clawracha - OpenClaw plugin for Storacha workspace sync
- */
-
-export * from "./types/index.js";
-export * from "./blockstore/index.js";
-export { encodeWorkspaceFile, encodeFiles } from "./utils/encoder.js";
-export { diffEntries, diffRemoteChanges } from "./utils/differ.js";
-export { SyncEngine } from "./sync.js";
-export { FileWatcher } from "./watcher.js";
-
-// Re-export plugin definition (default export)
-export { default as plugin } from "./plugin.js";