@storacha/clawracha 0.0.2 → 0.0.3

package/README.md

@@ -21,14 +21,41 @@ openclaw plugins install @storacha/clawracha
 
 ## Setup
 
-```bash
-# Initialize sync for this workspace
-openclaw storacha init
+Setup is done via slash commands in your chat session with the agent (not CLI commands).
+
+### New workspace (first device)
+
+```
+/storacha-init <upload-delegation-b64>
+```
+
+Creates a fresh workspace with a new UCN Name. You'll need an upload delegation from a Storacha space owner.
+
+### Join an existing workspace (additional devices)
+
+```
+/storacha-join <upload-delegation-b64> <name-delegation-b64>
+```
+
+Joins an existing workspace from another device. Both delegations are required — get them by running `/storacha-grant` on the existing device. The join command pulls all remote files before the watcher starts, so your local workspace is fully synced from the start.
 
-# Import a delegation from a space owner
-openclaw storacha delegate <base64-delegation>
+### Grant access to another device
 
-# Restart gateway to start syncing
+```
+/storacha-grant <target-agent-DID>
+```
+
+Generates upload and name delegations for the target device. The target device uses these with `/storacha-join`.
+
+### Check status
+
+```
+/storacha-status
+```
+
+After setup, restart the gateway to start syncing:
+
+```bash
 openclaw gateway restart
 ```
 
@@ -108,7 +135,7 @@ The plugin provides tools for manual sync control:
 
 The plugin stores data in `.storacha/` within the workspace:
 
-- `config.json` - Agent key, delegation, name archive (NOT synced)
+- `config.json` - Agent key, delegations, name archive (NOT synced)
 - `blocks/` - Local block cache (NOT synced)
 
 Add `.storacha/` to your `.gitignore`.

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -44,10 +44,16 @@ async function saveDeviceConfig(workspace, config) {
  * Plugin entry — called by OpenClaw when the plugin is loaded.
  */
 export default function plugin(api) {
+    // Capture plugin-specific config at registration time
+    const pluginConfig = (api.pluginConfig ?? {});
     // Register background service
     api.registerService({
         id: "storacha-sync",
         async start(ctx) {
+            if (pluginConfig.enabled === false) {
+                ctx.logger.info("Storacha sync disabled via config.");
+                return;
+            }
             workspaceDir = ctx.workspaceDir;
             const workspace = workspaceDir;
             if (!workspace) {
@@ -66,8 +72,8 @@ export default function plugin(api) {
                 workspace,
                 config: {
                     enabled: true,
-                    watchPatterns: ["**/*"],
-                    ignorePatterns: [
+                    watchPatterns: pluginConfig.watchPatterns ?? ["**/*"],
+                    ignorePatterns: pluginConfig.ignorePatterns ?? [
                         ".storacha/**",
                         "node_modules/**",
                         ".git/**",
@@ -84,7 +90,7 @@ export default function plugin(api) {
                     await saveDeviceConfig(workspace, updatedConfig);
                 },
             });
-            fileWatcher.start();
+            await fileWatcher.start();
             ctx.logger.info("Started watching workspace");
         },
         async stop(ctx) {

package/dist/watcher.d.ts

@@ -21,7 +21,7 @@ export declare class FileWatcher {
     /**
      * Start watching the workspace
      */
-    start(): void;
+    start(): Promise<void>;
     /**
      * Stop watching
      */

package/dist/watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAErE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,cAAc;IAKnC;;OAEG;IACH,KAAK,IAAI,IAAI;IA+Bb;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;OAEG;IACH,OAAO,CAAC,YAAY;IAmBpB;;OAEG;YACW,KAAK;IAanB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAOlC"}
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAErE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoBD,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,cAAc;IAKnC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmC5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;OAEG;IACH,OAAO,CAAC,YAAY;IAmBpB;;OAEG;YACW,KAAK;IAanB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAOlC"}

package/dist/watcher.js

@@ -5,7 +5,27 @@
  * before triggering sync.
  */
 import chokidar from "chokidar";
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
+/**
+ * Read .clawrachaignore from workspace root (gitignore-style).
+ * Returns parsed patterns, or empty array if file doesn't exist.
+ */
+async function readIgnoreFile(workspace) {
+    const ignorePath = path.join(workspace, ".clawrachaignore");
+    try {
+        const content = await fs.readFile(ignorePath, "utf-8");
+        return content
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line && !line.startsWith("#"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
 export class FileWatcher {
     watcher = null;
     pendingChanges = new Map();
@@ -19,15 +39,18 @@ export class FileWatcher {
     /**
      * Start watching the workspace
      */
-    start() {
+    async start() {
         if (this.watcher)
             return;
         const { workspace, config } = this.options;
+        // Read workspace-level ignore file
+        const userIgnored = await readIgnoreFile(workspace);
         // Build watch patterns
         const watchPaths = config.watchPatterns.map((p) => path.join(workspace, p));
         // Build ignore patterns
         const ignored = [
             ...config.ignorePatterns,
+            ...userIgnored,
             ".storacha/**", // Always ignore our own data
         ];
         this.watcher = chokidar.watch(watchPaths, {

package/openclaw.plugin.json

@@ -5,7 +5,7 @@
   "description": "Sync OpenClaw workspaces to Storacha via UCN Pail",
   "entry": "./src/plugin.ts",
   "skills": [],
-  "config": {
+  "configSchema": {
     "type": "object",
     "properties": {
       "enabled": {
@@ -16,7 +16,7 @@
       "watchPatterns": {
         "type": "array",
         "items": { "type": "string" },
-        "default": ["**/*.md"],
+        "default": ["**/*"],
         "description": "Glob patterns to watch for sync"
       },
       "ignorePatterns": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storacha/clawracha",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "OpenClaw plugin for Storacha workspace sync via UCN Pail",
   "type": "module",
   "main": "dist/plugin.js",

package/src/plugin.ts

@@ -15,7 +15,7 @@ import type {
   OpenClawPluginServiceContext,
   AnyAgentTool,
 } from "openclaw/plugin-sdk";
-import type { DeviceConfig } from "./types/index.js";
+import type { DeviceConfig, SyncPluginConfig } from "./types/index.js";
 import { SyncEngine } from "./sync.js";
 import { FileWatcher } from "./watcher.js";
 import { createStorachaClient } from "./utils/client.js";
@@ -58,10 +58,18 @@ async function saveDeviceConfig(
  * Plugin entry — called by OpenClaw when the plugin is loaded.
  */
 export default function plugin(api: OpenClawPluginApi) {
+  // Capture plugin-specific config at registration time
+  const pluginConfig = (api.pluginConfig ?? {}) as Partial<SyncPluginConfig>;
+
   // Register background service
   api.registerService({
     id: "storacha-sync",
     async start(ctx: OpenClawPluginServiceContext) {
+      if (pluginConfig.enabled === false) {
+        ctx.logger.info("Storacha sync disabled via config.");
+        return;
+      }
+
       workspaceDir = ctx.workspaceDir;
       const workspace = workspaceDir;
       if (!workspace) {
@@ -85,8 +93,8 @@ export default function plugin(api: OpenClawPluginApi) {
         workspace,
         config: {
           enabled: true,
-          watchPatterns: ["**/*"],
-          ignorePatterns: [
+          watchPatterns: pluginConfig.watchPatterns ?? ["**/*"],
+          ignorePatterns: pluginConfig.ignorePatterns ?? [
             ".storacha/**",
             "node_modules/**",
             ".git/**",
@@ -104,7 +112,7 @@ export default function plugin(api: OpenClawPluginApi) {
         },
       });
 
-      fileWatcher.start();
+      await fileWatcher.start();
       ctx.logger.info("Started watching workspace");
     },
 

package/src/watcher.ts

@@ -6,6 +6,7 @@
  */
 
 import chokidar from "chokidar";
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { FileChange, SyncPluginConfig } from "./types/index.js";
 
@@ -16,6 +17,24 @@ export interface WatcherOptions {
   debounceMs?: number;
 }
 
+/**
+ * Read .clawrachaignore from workspace root (gitignore-style).
+ * Returns parsed patterns, or empty array if file doesn't exist.
+ */
+async function readIgnoreFile(workspace: string): Promise<string[]> {
+  const ignorePath = path.join(workspace, ".clawrachaignore");
+  try {
+    const content = await fs.readFile(ignorePath, "utf-8");
+    return content
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+  } catch (err: any) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
 export class FileWatcher {
   private watcher: chokidar.FSWatcher | null = null;
   private pendingChanges: Map<string, FileChange> = new Map();
@@ -31,17 +50,21 @@ export class FileWatcher {
   /**
    * Start watching the workspace
    */
-  start(): void {
+  async start(): Promise<void> {
     if (this.watcher) return;
 
     const { workspace, config } = this.options;
 
+    // Read workspace-level ignore file
+    const userIgnored = await readIgnoreFile(workspace);
+
     // Build watch patterns
     const watchPaths = config.watchPatterns.map((p) => path.join(workspace, p));
 
     // Build ignore patterns
     const ignored = [
       ...config.ignorePatterns,
+      ...userIgnored,
       ".storacha/**", // Always ignore our own data
     ];