@storacha/clawracha 0.1.1 → 0.1.3

package/dist/plugin.d.ts.map

@@ -1 +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;AAiH7B,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,iBAAiB,QAkgBpD"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,qBAAqB,CAAC;AAgH7B,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,iBAAiB,QAojBpD"}

package/dist/plugin.js

@@ -40,8 +40,7 @@ async function startWorkspaceSync(workspace, agentId, pluginConfig, logger) {
     if (!deviceConfig || !deviceConfig.setupComplete) {
         return null;
     }
-    const storachaClient = await createStorachaClient(deviceConfig);
-    const engine = new SyncEngine(storachaClient, workspace);
+    const engine = new SyncEngine(workspace);
     await engine.init(deviceConfig);
     const watcher = new FileWatcher({
         workspace,
@@ -112,6 +111,7 @@ export default function plugin(api) {
         },
         async stop(ctx) {
             for (const [workspace, sync] of activeSyncers) {
+                sync.engine.stop();
                 await sync.watcher.stop();
                 ctx.logger.info(`[${sync.agentId}] Stopped syncing: ${workspace}`);
             }
@@ -262,8 +262,7 @@ export default function plugin(api) {
                 deviceConfig.setupComplete = true;
                 await saveDeviceConfig(workspace, deviceConfig);
                 // Initial upload: scan all existing workspace files and sync to Storacha
-                const storachaClient = await createStorachaClient(deviceConfig);
-                const engine = new SyncEngine(storachaClient, workspace);
+                const engine = new SyncEngine(workspace);
                 await engine.init(deviceConfig);
                 const userIgnored = await readIgnoreFile(workspace);
                 const ignorePatterns = [
@@ -295,6 +294,7 @@ export default function plugin(api) {
                 console.log("\nRestart the gateway to start syncing: `openclaw gateway restart`");
                 console.log(`\nTo add another device, run \`openclaw clawracha grant <their-DID> --agent ${agentId}\` here,`);
                 console.log(`then \`openclaw clawracha join <upload> <name> --agent <id>\` on the other device.`);
+                console.log("\nSync is now active (no gateway restart needed).");
             }
             catch (err) {
                 console.error(`Error: ${err.message}`);
@@ -334,8 +334,7 @@ export default function plugin(api) {
                 await saveDeviceConfig(workspace, deviceConfig);
                 // Pull remote state before watcher starts
                 let pullCount = 0;
-                const storachaClient = await createStorachaClient(deviceConfig);
-                const engine = new SyncEngine(storachaClient, workspace);
+                const engine = new SyncEngine(workspace);
                 await engine.init(deviceConfig);
                 pullCount = await engine.pullRemote();
                 // Save name archive after pull
@@ -472,5 +471,51 @@ export default function plugin(api) {
                 process.exit(1);
             }
         });
+        // --- inspect ---
+        clawracha
+            .command("inspect")
+            .description("Inspect internal sync state for debugging")
+            .requiredOption("--agent <id>", "Agent ID")
+            .action(async (opts) => {
+            try {
+                const { agentId, workspace } = requireAgent(opts.agent);
+                const deviceConfig = await loadDeviceConfig(workspace);
+                if (!deviceConfig?.agentKey || !deviceConfig.setupComplete) {
+                    console.log(`Not set up. Run \`openclaw clawracha init --agent ${agentId}\` first.`);
+                    return;
+                }
+                // Use active syncer if available, otherwise spin up temporary engine
+                let engine;
+                const activeSync = activeSyncers.get(workspace);
+                if (activeSync) {
+                    engine = activeSync.engine;
+                }
+                else {
+                    engine = new SyncEngine(workspace);
+                    await engine.init(deviceConfig);
+                }
+                const state = await engine.inspect();
+                console.log(`🔥 Storacha Inspect [${agentId}]`);
+                console.log(`Workspace: ${workspace}`);
+                console.log(`Running: ${state.running}`);
+                console.log(`Root CID: ${state.root ?? "(none)"}`);
+                console.log(`Revisions: ${state.revisions.length}`);
+                for (const r of state.revisions) {
+                    console.log(`  event: ${r.event}`);
+                }
+                console.log(`\nPail entries (${state.pailKeys.length}):`);
+                for (const key of state.pailKeys) {
+                    console.log(`  ${key}`);
+                }
+                console.log(`\nPending ops (${state.pendingOps.length}):`);
+                for (const op of state.pendingOps) {
+                    console.log(`  ${op.type} ${op.key}${op.value ? ` → ${op.value}` : ""}`);
+                }
+            }
+            catch (err) {
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
+            }
+        });
     }, { commands: ["clawracha"] });
 }

package/dist/sync.d.ts

@@ -10,47 +10,70 @@
  */
 import type { SyncState, FileChange, DeviceConfig } from "./types/index.js";
 import { type PailEntries } from "./utils/differ.js";
-import { Client } from "@storacha/client";
 export declare class SyncEngine {
     private workspace;
     private blocks;
-    private name;
+    private state;
     private current;
     private pendingOps;
     private carFile;
-    private running;
     private lastSync;
-    private storachaClient;
-    constructor(storachaClient: Client, workspace: string);
+    constructor(workspace: string);
     /**
-     * Initialize sync engine with device config
+     * Initialize sync engine with device config.
+     * Creates the Storacha client and resolves the UCN name.
      */
     init(config: DeviceConfig): Promise<void>;
     /**
-     * Process a batch of file changes
+     * Require running state or throw.
+     */
+    private requireRunning;
+    /**
+     * Process a batch of file changes.
+     * Can be called even when not running (accumulates pending ops).
      */
     processChanges(changes: FileChange[]): Promise<void>;
     /**
-     * Execute sync: generate revision, publish, upload, apply remote changes
+     * Execute sync: generate revision, publish, upload, apply remote changes.
      */
     sync(): Promise<void>;
     /**
-     * Create CAR and upload to Storacha
+     * Create CAR and upload to Storacha.
      */
     private possiblyUploadCAR;
     /**
-     * Get current pail entries as map
+     * Get current pail entries as map.
      */
     getPailEntries(): Promise<PailEntries>;
     /**
-     * Apply remote changes to local filesystem
+     * Apply remote changes to local filesystem.
      */
     private applyRemoteChanges;
+    /**
+     * Mark the engine as stopped.
+     */
+    stop(): void;
     /**
      * Pull all remote state and write to local filesystem.
-     * Used by /storacha-join to overwrite local with remote before watcher starts.
+     * Used by join to overwrite local with remote before watcher starts.
      */
     pullRemote(): Promise<number>;
+    /**
+     * Inspect internal state for debugging.
+     */
+    inspect(): Promise<{
+        root: string | null;
+        revisions: {
+            event: string;
+        }[];
+        pailKeys: string[];
+        pendingOps: {
+            type: string;
+            key: string;
+            value?: string;
+        }[];
+        running: boolean;
+    }>;
     status(): Promise<SyncState>;
     exportNameArchive(): Promise<string>;
     private storeBlocks;

package/dist/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EAEV,YAAY,EACb,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C,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,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,cAAc,CAAS;gBAEnB,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAMrD;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC/C;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAe1D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD3B;;OAEG;YACW,iBAAiB;IAc/B;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAc5C;;OAEG;YACW,kBAAkB;IAWhC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IA0B7B,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC;IAW5B,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;YAM5B,WAAW;CAK1B"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EAEV,YAAY,EACb,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAWxE,qBAAa,UAAU;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,QAAQ,CAAuB;gBAE3B,SAAS,EAAE,MAAM;IAK7B;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAoC/C;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAe1D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgD3B;;OAEG;YACW,iBAAiB;IAe/B;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAc5C;;OAEG;YACW,kBAAkB;IAUhC;;OAEG;IACH,IAAI,IAAI,IAAI;IAIZ;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IA0BnC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC;QACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,SAAS,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC5D,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IAiBI,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC;IAW5B,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;YAM5B,WAAW;CAK1B"}

package/dist/sync.js

@@ -16,31 +16,32 @@ import { applyRemoteChanges } from "./handlers/remote.js";
 import { processChanges } from "./handlers/process.js";
 import { diffRemoteChanges } from "./utils/differ.js";
 import { makeTempCar } from "./utils/tempcar.js";
+import { createStorachaClient } from "./utils/client.js";
 import { decodeDelegation, encodeDelegation } from "./utils/delegation.js";
 export class SyncEngine {
     workspace;
     blocks;
-    name = null;
+    state = { running: false };
     current = null;
     pendingOps = [];
     carFile = null;
-    running = false;
     lastSync = null;
-    storachaClient;
-    constructor(storachaClient, workspace) {
-        this.storachaClient = storachaClient;
+    constructor(workspace) {
         this.workspace = workspace;
         this.blocks = createWorkspaceBlockstore(workspace);
     }
     /**
-     * Initialize sync engine with device config
+     * Initialize sync engine with device config.
+     * Creates the Storacha client and resolves the UCN name.
      */
     async init(config) {
+        const storachaClient = await createStorachaClient(config);
         const agent = Agent.parse(config.agentKey);
+        let name;
         if (config.nameArchive) {
             // Restore from previously saved archive (has full state)
             const archiveBytes = decodeDelegation(config.nameArchive);
-            this.name = await Name.extract(agent, archiveBytes);
+            name = await Name.extract(agent, archiveBytes);
         }
         else if (config.nameDelegation) {
             // Reconstruct from delegation (granted by another device)
@@ -49,14 +50,15 @@ export class SyncEngine {
             const { ok: delegation } = await extract(nameBytes);
             if (!delegation)
                 throw new Error("Failed to extract name delegation");
-            this.name = Name.from(agent, [delegation]);
+            name = Name.from(agent, [delegation]);
         }
         else {
             // First device — create a new name
-            this.name = await Name.create(agent);
+            name = await Name.create(agent);
         }
+        this.state = { running: true, name, storachaClient };
         try {
-            const result = await Revision.resolve(this.blocks, this.name);
+            const result = await Revision.resolve(this.blocks, name);
             this.current = result.value;
             await this.storeBlocks(result.additions);
         }
@@ -70,7 +72,17 @@ export class SyncEngine {
         }
     }
     /**
-     * Process a batch of file changes
+     * Require running state or throw.
+     */
+    requireRunning() {
+        if (!this.state.running) {
+            throw new Error("Sync engine not initialized");
+        }
+        return this.state;
+    }
+    /**
+     * Process a batch of file changes.
+     * Can be called even when not running (accumulates pending ops).
      */
     async processChanges(changes) {
         if (!this.carFile) {
@@ -80,18 +92,16 @@ export class SyncEngine {
         this.pendingOps.push(...pendingOps);
     }
     /**
-     * Execute sync: generate revision, publish, upload, apply remote changes
+     * Execute sync: generate revision, publish, upload, apply remote changes.
      */
     async sync() {
-        if (!this.name) {
-            throw new Error("Sync engine not initialized");
-        }
+        const { name } = this.requireRunning();
         const beforeEntries = await this.getPailEntries();
         if (this.pendingOps.length > 0) {
             if (!this.carFile) {
                 throw new Error("CAR file not initialized");
             }
-            const result = await applyPendingOps(this.blocks, this.name, this.current, this.pendingOps);
+            const result = await applyPendingOps(this.blocks, name, this.current, this.pendingOps);
             this.current = result.current;
             for (const block of result.revisionBlocks) {
                 await this.carFile.put(block);
@@ -101,7 +111,7 @@ export class SyncEngine {
         else {
             // No pending ops — just pull remote
             try {
-                const result = await Revision.resolve(this.blocks, this.name, {
+                const result = await Revision.resolve(this.blocks, name, {
                     base: this.current ?? undefined,
                 });
                 await this.storeBlocks(result.additions);
@@ -124,15 +134,16 @@ export class SyncEngine {
         this.lastSync = Date.now();
     }
     /**
-     * Create CAR and upload to Storacha
+     * Create CAR and upload to Storacha.
      */
     async possiblyUploadCAR() {
         if (this.carFile) {
+            const { storachaClient } = this.requireRunning();
             const readableCar = await this.carFile.switchToReadable();
             this.carFile = null;
             if (readableCar) {
                 try {
-                    await this.storachaClient.uploadCAR(readableCar.readable);
+                    await storachaClient.uploadCAR(readableCar.readable);
                 }
                 finally {
                     await readableCar.cleanup();
@@ -141,7 +152,7 @@ export class SyncEngine {
         }
     }
     /**
-     * Get current pail entries as map
+     * Get current pail entries as map.
      */
     async getPailEntries() {
         const entries = new Map();
@@ -155,7 +166,7 @@ export class SyncEngine {
         return entries;
     }
     /**
-     * Apply remote changes to local filesystem
+     * Apply remote changes to local filesystem.
      */
     async applyRemoteChanges(changedPaths, entries) {
         await applyRemoteChanges(changedPaths, entries, this.workspace, {
@@ -163,15 +174,20 @@ export class SyncEngine {
             current: this.current ?? undefined,
         });
     }
+    /**
+     * Mark the engine as stopped.
+     */
+    stop() {
+        this.state = { running: false };
+    }
     /**
      * Pull all remote state and write to local filesystem.
-     * Used by /storacha-join to overwrite local with remote before watcher starts.
+     * Used by join to overwrite local with remote before watcher starts.
      */
     async pullRemote() {
-        if (!this.name)
-            throw new Error("Sync engine not initialized");
+        const { name } = this.requireRunning();
         try {
-            const result = await Revision.resolve(this.blocks, this.name, {
+            const result = await Revision.resolve(this.blocks, name, {
                 base: this.current ?? undefined,
             });
             await this.storeBlocks(result.additions);
@@ -192,10 +208,29 @@ export class SyncEngine {
         this.lastSync = Date.now();
         return entries.size;
     }
+    /**
+     * Inspect internal state for debugging.
+     */
+    async inspect() {
+        const entries = await this.getPailEntries();
+        return {
+            root: this.current?.root?.toString() ?? null,
+            revisions: this.current?.revision?.map((r) => ({
+                event: r.event.cid.toString(),
+            })) ?? [],
+            pailKeys: [...entries.keys()],
+            pendingOps: this.pendingOps.map((op) => ({
+                type: op.type,
+                key: op.key,
+                value: op.value?.toString(),
+            })),
+            running: this.state.running,
+        };
+    }
     async status() {
         const entries = await this.getPailEntries();
         return {
-            running: this.running,
+            running: this.state.running,
             lastSync: this.lastSync,
             root: this.current?.root ?? null,
             entryCount: entries.size,
@@ -203,9 +238,8 @@ export class SyncEngine {
         };
     }
     async exportNameArchive() {
-        if (!this.name)
-            throw new Error("Sync engine not initialized");
-        const bytes = await this.name.archive();
+        const { name } = this.requireRunning();
+        const bytes = await name.archive();
         return encodeDelegation(bytes);
     }
     async storeBlocks(blocks) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storacha/clawracha",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "OpenClaw plugin for Storacha workspace sync via UCN Pail",
   "type": "module",
   "files": [