@storacha/clawracha 0.0.1 → 0.0.2

package/dist/handlers/apply.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 type { ClockConnection, NameView, ValueView } from "@storacha/ucn/pail/api";
+import type { Block } from "multiformats";
+import type { PailOp } from "../types/index.js";
+import type { WorkspaceBlockstore } from "../blockstore/index.js";
+export interface ApplyResult {
+    current: ValueView | null;
+    revisionBlocks: Block[];
+}
+export declare function applyPendingOps(blocks: WorkspaceBlockstore, name: NameView, current: ValueView | null, pendingOps: PailOp[], options?: {
+    remotes?: ClockConnection[];
+}): Promise<ApplyResult>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/handlers/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/handlers/apply.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EACR,SAAS,EACV,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,KAAK,EAAE,CAAC;CACzB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,eAAe,EAAE,CAAA;CAAE,GACxC,OAAO,CAAC,WAAW,CAAC,CA+CtB"}

package/dist/handlers/apply.js

@@ -0,0 +1,50 @@
+/**
+ * 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 { MemoryBlockstore, withCache } from "@storacha/ucn/block";
+export async function applyPendingOps(blocks, name, current, pendingOps, options) {
+    const revisionBlocks = [];
+    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) => {
+        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/dist/handlers/process.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 type { BlockFetcher, ValueView } from "@storacha/ucn/pail/api";
+import type { Block } from "multiformats";
+import type { FileChange, PailOp } from "../types/index.js";
+/** 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>;
+export declare function processChanges(changes: FileChange[], workspace: string, current: ValueView | null, blocks: BlockFetcher, sink: BlockSink, store?: BlockStore): Promise<PailOp[]>;
+//# sourceMappingURL=process.d.ts.map

package/dist/handlers/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/handlers/process.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,YAAY,EAEZ,SAAS,EACV,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAM5D,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExD,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAIzD,wBAAsB,cAAc,CAClC,OAAO,EAAE,UAAU,EAAE,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,EACf,KAAK,CAAC,EAAE,UAAU,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CAiFnB"}

package/dist/handlers/process.js

@@ -0,0 +1,82 @@
+/**
+ * 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 { Revision } from "@storacha/ucn/pail";
+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";
+const isMarkdown = (filePath) => filePath.endsWith(".md");
+export async function processChanges(changes, workspace, current, blocks, sink, store) {
+    const pendingOps = [];
+    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 = null;
+        const reader = file.blocks.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            root = value.cid;
+            await sink(value);
+        }
+        if (!root) {
+            throw new Error(`Failed to encode file: ${file.path}`);
+        }
+        files.push({ path: file.path, rootCID: root });
+    }
+    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,
+            });
+        }
+    }
+    // --- 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,
+        });
+    }
+    // --- 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/dist/handlers/remote.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 type { CID } from "multiformats/cid";
+import type { BlockFetcher, ValueView } from "@storacha/ucn/pail/api";
+export declare function applyRemoteChanges(changedPaths: string[], entries: Map<string, CID>, workspace: string, options?: {
+    gateway?: string;
+    blocks?: BlockFetcher;
+    current?: ValueView;
+}): Promise<void>;
+//# sourceMappingURL=remote.d.ts.map

package/dist/handlers/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/handlers/remote.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAOtE,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB,GACA,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/dist/handlers/remote.js

@@ -0,0 +1,48 @@
+/**
+ * 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 * as mdsync from "../mdsync/index.js";
+const DEFAULT_GATEWAY = "https://storacha.link";
+const isMarkdown = (filePath) => filePath.endsWith(".md");
+export async function applyRemoteChanges(changedPaths, entries, workspace, options) {
+    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) {
+                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/dist/index.d.ts

@@ -1,10 +1,10 @@
 /**
  * @storacha/clawracha - OpenClaw plugin for Storacha workspace sync
  */
-export * from "./types.js";
+export * from "./types/index.js";
 export * from "./blockstore/index.js";
-export { encodeWorkspaceFile, encodeFiles } from "./encoder.js";
-export { diffEntries, encodedToEntries, diffRemoteChanges } from "./differ.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";
 export { default as plugin } from "./plugin.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,10 +1,10 @@
 /**
  * @storacha/clawracha - OpenClaw plugin for Storacha workspace sync
  */
-export * from "./types.js";
+export * from "./types/index.js";
 export * from "./blockstore/index.js";
-export { encodeWorkspaceFile, encodeFiles } from "./encoder.js";
-export { diffEntries, encodedToEntries, diffRemoteChanges } from "./differ.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)

package/dist/mdsync/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * mdsync — CRDT markdown storage on top of UCN Pail.
+ *
+ * Stores RGA-backed markdown trees at Pail keys. Each key's value is a
+ * MarkdownEntry containing:
+ *   - The current RGA tree (full document state)
+ *   - An RGA of MarkdownEvents (causal history scoped to this key)
+ *   - The last changeset applied (for incremental replay during merge)
+ *
+ * On read, if the Pail has multiple heads (concurrent writes), we resolve
+ * by walking from the common ancestor forward, replaying each branch's
+ * changesets and merging event RGAs — analogous to how Pail itself resolves
+ * concurrent root updates.
+ */
+import { BlockFetcher, ValueView } from "@storacha/ucn/pail/api";
+import { Block, CID } from "multiformats";
+interface MarkdownResult {
+    mdEntryCid: CID;
+    additions: Block[];
+}
+/**
+ * First put into an empty Pail (v0 = no existing revision).
+ * Returns the markdown entry CID and blocks to store. Caller is
+ * responsible for creating the Pail revision via Revision.v0Put.
+ */
+export declare const v0Put: (newMarkdown: string) => Promise<MarkdownResult>;
+/**
+ * Put markdown content at a key in an existing Pail.
+ *
+ * If the key doesn't exist, creates an initial entry. If it does exist,
+ * resolves the current value (merging concurrent heads if needed), computes
+ * an RGA changeset against the resolved tree, applies it, and stores the
+ * updated entry.
+ *
+ * Returns the markdown entry CID and blocks to store. Caller is
+ * responsible for creating the Pail revision via Revision.put.
+ */
+export declare const put: (blocks: BlockFetcher, current: ValueView, key: string, newMarkdown: string) => Promise<MarkdownResult>;
+/**
+ * Get the current markdown string for a key, resolving concurrent heads.
+ * Returns undefined if the key doesn't exist.
+ */
+export declare const get: (blocks: BlockFetcher, current: ValueView, key: string) => Promise<string | undefined>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/mdsync/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mdsync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EACL,YAAY,EAGZ,SAAS,EACV,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAoJ1C,UAAU,cAAc;IACtB,UAAU,EAAE,GAAG,CAAC;IAChB,SAAS,EAAE,KAAK,EAAE,CAAC;CACpB;AAyBD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAChB,aAAa,MAAM,KAClB,OAAO,CAAC,cAAc,CAExB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG,GACd,QAAQ,YAAY,EACpB,SAAS,SAAS,EAClB,KAAK,MAAM,EACX,aAAa,MAAM,KAClB,OAAO,CAAC,cAAc,CA+BxB,CAAC;AA6RF;;;GAGG;AACH,eAAO,MAAM,GAAG,GACd,QAAQ,YAAY,EACpB,SAAS,SAAS,EAClB,KAAK,MAAM,KACV,OAAO,CAAC,MAAM,GAAG,SAAS,CAM5B,CAAC"}