@storacha/clawracha 0.0.1

package/dist/fs.js

@@ -0,0 +1,27 @@
+/**
+ * Graceful filesystem — drop-in replacement for node:fs/promises.
+ * Handles EMFILE/ENFILE by queuing and retrying on platforms with low fd limits.
+ */
+import * as rawFs from "node:fs";
+import gracefulFs from "graceful-fs";
+// Patch the global fs module (skip if already patched or in test environments)
+try {
+  gracefulFs.gracefulify(rawFs);
+} catch {
+  // gracefulify can fail in some runtimes (e.g. vitest) where fs properties
+  // are non-configurable. The promises API still works fine without patching.
+}
+// Re-export the promises API
+const fs = rawFs.promises;
+export default fs;
+export const {
+  readFile,
+  writeFile,
+  mkdir,
+  readdir,
+  stat,
+  unlink,
+  access,
+  rm,
+  mkdtemp,
+} = fs;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @storacha/clawracha - OpenClaw plugin for Storacha workspace sync
+ */
+export * from "./types.js";
+export * from "./blockstore/index.js";
+export { encodeWorkspaceFile, encodeFiles } from "./encoder.js";
+export { diffEntries, encodedToEntries, diffRemoteChanges } from "./differ.js";
+export { SyncEngine } from "./sync.js";
+export { FileWatcher } from "./watcher.js";
+export { default as plugin } from "./plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

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

package/dist/plugin.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OpenClaw Plugin Entry Point
+ *
+ * Registers:
+ * - Background service for file watching and sync
+ * - Agent tools for manual sync control
+ * - Slash commands for setup
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+/**
+ * Plugin entry — called by OpenClaw when the plugin is loaded.
+ */
+export default function plugin(api: OpenClawPluginApi): void;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,qBAAqB,CAAC;AAuC7B;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,iBAAiB,QAyMpD"}

package/dist/plugin.js

@@ -0,0 +1,220 @@
+/**
+ * OpenClaw Plugin Entry Point
+ *
+ * Registers:
+ * - Background service for file watching and sync
+ * - Agent tools for manual sync control
+ * - Slash commands for setup
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { SyncEngine } from "./sync.js";
+import { FileWatcher } from "./watcher.js";
+// Global state
+let syncEngine = null;
+let fileWatcher = null;
+let workspaceDir;
+/**
+ * Load device config from .storacha/config.json
+ */
+async function loadDeviceConfig(workspace) {
+    const configPath = path.join(workspace, ".storacha", "config.json");
+    try {
+        const content = await fs.readFile(configPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Save device config
+ */
+async function saveDeviceConfig(workspace, config) {
+    const configDir = path.join(workspace, ".storacha");
+    await fs.mkdir(configDir, { recursive: true });
+    const configPath = path.join(configDir, "config.json");
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+}
+/**
+ * Plugin entry — called by OpenClaw when the plugin is loaded.
+ */
+export default function plugin(api) {
+    // Register background service
+    api.registerService({
+        id: "storacha-sync",
+        async start(ctx) {
+            workspaceDir = ctx.workspaceDir;
+            const workspace = workspaceDir;
+            if (!workspace) {
+                ctx.logger.warn("No workspace directory configured");
+                return;
+            }
+            const deviceConfig = await loadDeviceConfig(workspace);
+            if (!deviceConfig) {
+                ctx.logger.info("No device config found. Run /storacha-init first.");
+                return;
+            }
+            syncEngine = new SyncEngine(workspace);
+            await syncEngine.init(deviceConfig);
+            fileWatcher = new FileWatcher({
+                workspace,
+                config: {
+                    enabled: true,
+                    watchPatterns: ["**/*"],
+                    ignorePatterns: [
+                        ".storacha/**",
+                        "node_modules/**",
+                        ".git/**",
+                        "dist/**",
+                    ],
+                },
+                onChanges: async (changes) => {
+                    if (!syncEngine)
+                        return;
+                    await syncEngine.processChanges(changes);
+                    await syncEngine.sync();
+                    const nameArchive = await syncEngine.exportNameArchive();
+                    const updatedConfig = { ...deviceConfig, nameArchive };
+                    await saveDeviceConfig(workspace, updatedConfig);
+                },
+            });
+            fileWatcher.start();
+            ctx.logger.info("Started watching workspace");
+        },
+        async stop(ctx) {
+            if (fileWatcher) {
+                await fileWatcher.stop();
+                fileWatcher = null;
+            }
+            syncEngine = null;
+            ctx.logger.info("Stopped");
+        },
+    });
+    // Register agent tools
+    api.registerTool({
+        name: "storacha_sync_status",
+        label: "Storacha Sync Status",
+        description: "Get the current Storacha workspace sync status",
+        parameters: { type: "object", properties: {} },
+        execute: async () => {
+            if (!syncEngine) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Sync not initialized. Run /storacha-init first.",
+                        },
+                    ],
+                    details: null,
+                };
+            }
+            const status = await syncEngine.status();
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(status, null, 2) },
+                ],
+                details: status,
+            };
+        },
+    });
+    api.registerTool({
+        name: "storacha_sync_now",
+        label: "Storacha Sync Now",
+        description: "Trigger an immediate workspace sync to Storacha",
+        parameters: { type: "object", properties: {} },
+        execute: async () => {
+            if (!syncEngine) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Sync not initialized. Run /storacha-init first.",
+                        },
+                    ],
+                    details: null,
+                };
+            }
+            await syncEngine.sync();
+            const status = await syncEngine.status();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: true, status }, null, 2),
+                    },
+                ],
+                details: status,
+            };
+        },
+    });
+    // Register slash commands
+    api.registerCommand({
+        name: "storacha-init",
+        description: "Initialize Storacha sync for this workspace",
+        handler: async (ctx) => {
+            const workspace = workspaceDir;
+            if (!workspace)
+                return { text: "No workspace configured." };
+            const { Agent } = await import("@storacha/ucn/pail");
+            const agent = await Agent.generate();
+            const agentKey = Agent.format(agent);
+            const config = { agentKey };
+            await saveDeviceConfig(workspace, config);
+            return {
+                text: [
+                    "🔥 Storacha sync initialized!",
+                    `Agent DID: \`${agent.did()}\``,
+                    "",
+                    "Next: get a delegation from a space owner, then run /storacha-delegate",
+                ].join("\n"),
+            };
+        },
+    });
+    api.registerCommand({
+        name: "storacha-delegate",
+        description: "Import a delegation to sync with a Storacha space",
+        acceptsArgs: true,
+        handler: async (ctx) => {
+            const workspace = workspaceDir;
+            if (!workspace)
+                return { text: "No workspace configured." };
+            const delegationB64 = ctx.args?.trim();
+            if (!delegationB64)
+                return { text: "Usage: /storacha-delegate <base64-delegation>" };
+            const config = await loadDeviceConfig(workspace);
+            if (!config)
+                return { text: "Not initialized. Run /storacha-init first." };
+            config.delegation = delegationB64;
+            await saveDeviceConfig(workspace, config);
+            return {
+                text: "✅ Delegation imported! Restart the gateway to start syncing.",
+            };
+        },
+    });
+    api.registerCommand({
+        name: "storacha-status",
+        description: "Show Storacha sync status",
+        handler: async (ctx) => {
+            const workspace = workspaceDir;
+            if (!workspace)
+                return { text: "No workspace configured." };
+            const config = await loadDeviceConfig(workspace);
+            if (!config)
+                return { text: "Not initialized. Run /storacha-init first." };
+            const lines = [
+                "🔥 Storacha Sync Status",
+                `Agent: configured`,
+                `Delegation: ${config.delegation ? "imported" : "not set"}`,
+                `Name Archive: ${config.nameArchive ? "saved" : "not created"}`,
+            ];
+            if (syncEngine) {
+                const status = await syncEngine.status();
+                lines.push(`Running: ${status.running}`, `Last Sync: ${status.lastSync ? new Date(status.lastSync).toISOString() : "never"}`, `Entries: ${status.entryCount}`, `Pending: ${status.pendingChanges}`);
+            }
+            return { text: lines.join("\n") };
+        },
+    });
+}

package/dist/sync.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Sync engine - orchestrates the full sync loop
+ *
+ * 1. Watch for file changes
+ * 2. Encode changed files to root CIDs
+ * 3. Diff local vs pail entries → put/del ops
+ * 4. Generate UCN revision via batch (puts) + individual ops (dels)
+ * 5. Upload all blocks as CAR
+ * 6. Apply remote changes to local filesystem
+ */
+import type { SyncState, FileChange, DeviceConfig } from "./types.js";
+import { type PailEntries } from "./differ.js";
+export declare class SyncEngine {
+    private workspace;
+    private blocks;
+    private name;
+    private current;
+    private pendingOps;
+    private allBlocks;
+    private running;
+    private lastSync;
+    constructor(workspace: string);
+    /**
+     * Initialize sync engine with device config
+     */
+    init(config: DeviceConfig): Promise<void>;
+    /**
+     * Process a batch of file changes
+     */
+    processChanges(changes: FileChange[]): Promise<void>;
+    /**
+     * Execute sync: generate revision, publish, upload, apply remote changes
+     */
+    sync(): Promise<void>;
+    /**
+     * Create CAR and upload to Storacha
+     */
+    private uploadCAR;
+    /**
+     * Get current pail entries as map
+     */
+    getPailEntries(): Promise<PailEntries>;
+    /**
+     * Apply remote changes to local filesystem
+     */
+    private applyRemoteChanges;
+    status(): Promise<SyncState>;
+    exportNameArchive(): Promise<string>;
+    private storeBlocks;
+}
+//# sourceMappingURL=sync.d.ts.map

package/dist/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAU,YAAY,EAAE,MAAM,YAAY,CAAC;AAO9E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAiBlE,qBAAa,UAAU;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAuB;gBAE3B,SAAS,EAAE,MAAM;IAK7B;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB/C;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqC1D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA4H3B;;OAEG;YACW,SAAS;IAwCvB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAc5C;;OAEG;YACW,kBAAkB;IAsB1B,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC;IAW5B,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;YAM5B,WAAW;CAK1B"}

package/dist/sync.js

@@ -0,0 +1,290 @@
+/**
+ * Sync engine - orchestrates the full sync loop
+ *
+ * 1. Watch for file changes
+ * 2. Encode changed files to root CIDs
+ * 3. Diff local vs pail entries → put/del ops
+ * 4. Generate UCN revision via batch (puts) + individual ops (dels)
+ * 5. Upload all blocks as CAR
+ * 6. Apply remote changes to local filesystem
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { CarWriter } from "@ipld/car/writer";
+// UCN Pail imports
+import { Agent, Name, Revision, Value } from "@storacha/ucn/pail";
+import * as Batch from "@storacha/ucn/pail/batch";
+import { createWorkspaceBlockstore, } from "./blockstore/index.js";
+import { encodeFiles } from "./encoder.js";
+import { diffRemoteChanges } from "./differ.js";
+export class SyncEngine {
+    workspace;
+    blocks;
+    name = null;
+    current = null;
+    pendingOps = [];
+    allBlocks = []; // Accumulate blocks for CAR upload
+    running = false;
+    lastSync = null;
+    constructor(workspace) {
+        this.workspace = workspace;
+        this.blocks = createWorkspaceBlockstore(workspace);
+    }
+    /**
+     * Initialize sync engine with device config
+     */
+    async init(config) {
+        const agent = Agent.parse(config.agentKey);
+        if (config.nameArchive) {
+            const archiveBytes = Buffer.from(config.nameArchive, "base64");
+            this.name = await Name.extract(agent, archiveBytes);
+        }
+        else {
+            this.name = await Name.create(agent);
+        }
+        try {
+            const result = await Revision.resolve(this.blocks, this.name);
+            this.current = result.value;
+            await this.storeBlocks(result.additions);
+        }
+        catch (err) {
+            if (err.code === "ERR_NO_VALUE") {
+                this.current = null;
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    /**
+     * Process a batch of file changes
+     */
+    async processChanges(changes) {
+        const toEncode = changes
+            .filter((c) => c.type !== "unlink")
+            .map((c) => c.path);
+        const toDelete = changes
+            .filter((c) => c.type === "unlink")
+            .map((c) => c.path);
+        // Encode changed files
+        const encoded = await encodeFiles(this.workspace, toEncode);
+        // Accumulate file blocks for CAR upload only (not persisted to blockstore)
+        // TODO: spill to temporary CAR file if memory becomes an issue
+        for (const file of encoded) {
+            this.allBlocks.push(...file.blocks);
+        }
+        // Check current pail state to skip no-ops
+        const currentEntries = await this.getPailEntries();
+        // Generate puts for changed files (skip if CID unchanged)
+        for (const file of encoded) {
+            const existing = currentEntries.get(file.path);
+            if (!existing || !existing.equals(file.rootCID)) {
+                this.pendingOps.push({ type: 'put', key: file.path, value: file.rootCID });
+            }
+        }
+        // Generate dels for removed files (skip if not in pail)
+        for (const deletePath of toDelete) {
+            if (currentEntries.has(deletePath)) {
+                this.pendingOps.push({ type: 'del', key: deletePath });
+            }
+        }
+    }
+    /**
+     * Execute sync: generate revision, publish, upload, apply remote changes
+     */
+    async sync() {
+        if (!this.name) {
+            throw new Error("Sync engine not initialized");
+        }
+        const beforeEntries = await this.getPailEntries();
+        const revisionBlocks = [];
+        // Separate puts and dels (batch only supports puts)
+        const puts = this.pendingOps.filter((op) => op.type === "put" && op.value);
+        const dels = this.pendingOps.filter((op) => op.type === "del");
+        // Process puts with batch
+        if (puts.length > 0) {
+            if (this.current) {
+                const batcher = await Batch.create(this.blocks, this.current);
+                for (const op of puts) {
+                    if (op.value)
+                        await batcher.put(op.key, op.value);
+                }
+                const result = await batcher.commit();
+                revisionBlocks.push(...result.additions);
+                await this.storeBlocks(result.additions);
+                const opResult = result.revision.operation;
+                this.current = Value.create(this.name, opResult.root, [
+                    result.revision,
+                ]);
+            }
+            else {
+                // First revision - v0Put
+                const firstPut = puts[0];
+                if (firstPut.value) {
+                    const result = await Revision.v0Put(this.blocks, firstPut.key, firstPut.value);
+                    revisionBlocks.push(...result.additions);
+                    await this.storeBlocks(result.additions);
+                    const opResult = result.revision.operation;
+                    this.current = Value.create(this.name, opResult.root, [
+                        result.revision,
+                    ]);
+                    // Batch remaining puts
+                    if (puts.length > 1) {
+                        const batcher = await Batch.create(this.blocks, this.current);
+                        for (const op of puts.slice(1)) {
+                            if (op.value)
+                                await batcher.put(op.key, op.value);
+                        }
+                        const batchResult = await batcher.commit();
+                        revisionBlocks.push(...batchResult.additions);
+                        await this.storeBlocks(batchResult.additions);
+                        const batchOpResult = batchResult.revision.operation;
+                        this.current = Value.create(this.name, batchOpResult.root, [
+                            batchResult.revision,
+                        ]);
+                    }
+                }
+            }
+        }
+        // Process dels individually (batch doesn't support del)
+        if (dels.length > 0 && this.current) {
+            for (const op of dels) {
+                const result = await Revision.del(this.blocks, this.current, op.key);
+                revisionBlocks.push(...result.additions);
+                await this.storeBlocks(result.additions);
+                const opResult = result.revision.operation;
+                this.current = Value.create(this.name, opResult.root, [
+                    result.revision,
+                ]);
+            }
+        }
+        this.pendingOps = [];
+        // Publish to network
+        if (this.current && this.current.revision.length > 0) {
+            const latestRevision = this.current.revision[this.current.revision.length - 1];
+            const pubResult = await Revision.publish(this.blocks, this.name, latestRevision);
+            revisionBlocks.push(...pubResult.additions);
+            await this.storeBlocks(pubResult.additions);
+            this.current = pubResult.value;
+        }
+        else {
+            // Just pull remote
+            try {
+                const result = await Revision.resolve(this.blocks, this.name, {
+                    base: this.current ?? undefined,
+                });
+                await this.storeBlocks(result.additions);
+                this.current = result.value;
+            }
+            catch (err) {
+                if (err.code !== "ERR_NO_VALUE")
+                    throw err;
+            }
+        }
+        // Combine all blocks and upload as CAR
+        const allUploadBlocks = [...this.allBlocks, ...revisionBlocks];
+        if (allUploadBlocks.length > 0) {
+            await this.uploadCAR(allUploadBlocks);
+            this.allBlocks = []; // Clear accumulated blocks
+        }
+        // Apply remote changes
+        const afterEntries = await this.getPailEntries();
+        const remoteChanges = diffRemoteChanges(beforeEntries, afterEntries);
+        if (remoteChanges.length > 0) {
+            await this.applyRemoteChanges(remoteChanges, afterEntries);
+        }
+        this.lastSync = Date.now();
+    }
+    /**
+     * Create CAR and upload to Storacha
+     */
+    async uploadCAR(blocks) {
+        if (blocks.length === 0)
+            return;
+        // Find root CID (last block is typically the root)
+        const rootCID = blocks[blocks.length - 1].cid;
+        // Create CAR
+        const { writer, out } = CarWriter.create([rootCID]);
+        // Collect CAR bytes
+        const chunks = [];
+        const collectPromise = (async () => {
+            for await (const chunk of out) {
+                chunks.push(chunk);
+            }
+        })();
+        // Write blocks
+        for (const block of blocks) {
+            await writer.put(block);
+        }
+        await writer.close();
+        await collectPromise;
+        const carBytes = new Uint8Array(chunks.reduce((acc, c) => acc + c.length, 0));
+        let offset = 0;
+        for (const chunk of chunks) {
+            carBytes.set(chunk, offset);
+            offset += chunk.length;
+        }
+        // TODO: Upload to Storacha using client.uploadCAR
+        // For now, just log
+        console.log(`[storacha-sync] Would upload CAR: ${blocks.length} blocks, ${carBytes.length} bytes, root: ${rootCID}`);
+    }
+    /**
+     * Get current pail entries as map
+     */
+    async getPailEntries() {
+        const entries = new Map();
+        if (!this.current)
+            return entries;
+        for await (const [key, value] of Revision.entries(this.blocks, this.current)) {
+            const cid = value;
+            if (cid)
+                entries.set(key, cid);
+        }
+        return entries;
+    }
+    /**
+     * Apply remote changes to local filesystem
+     */
+    async applyRemoteChanges(changedPaths, entries) {
+        for (const relativePath of changedPaths) {
+            const cid = entries.get(relativePath);
+            if (!cid) {
+                // Deleted remotely
+                const fullPath = path.join(this.workspace, relativePath);
+                try {
+                    await fs.unlink(fullPath);
+                    console.log(`[storacha-sync] Deleted: ${relativePath}`);
+                }
+                catch (err) {
+                    if (err.code !== "ENOENT")
+                        throw err;
+                }
+            }
+            else {
+                // Changed remotely - TODO: fetch and reconstruct
+                console.log(`[storacha-sync] Remote change: ${relativePath} → ${cid}`);
+            }
+        }
+    }
+    async status() {
+        const entries = await this.getPailEntries();
+        return {
+            running: this.running,
+            lastSync: this.lastSync,
+            root: this.current?.root ?? null,
+            entryCount: entries.size,
+            pendingChanges: this.pendingOps.length,
+        };
+    }
+    async exportNameArchive() {
+        if (!this.name)
+            throw new Error("Sync engine not initialized");
+        const bytes = await this.name.archive();
+        return Buffer.from(bytes).toString("base64");
+    }
+    async storeBlocks(blocks) {
+        for (const block of blocks) {
+            await this.blocks.put(block);
+        }
+    }
+}