@storacha/clawracha 0.1.23 → 0.2.1

package/dist/commands.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Extracted command logic for Storacha workspace sync.
+ *
+ * Shared by CLI commands (thin wrappers in plugin.ts) and the
+ * interactive `onboard` command.
+ */
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { DeviceConfig, SyncPluginConfig } from "./types/index.js";
+import { SyncEngine } from "./sync.js";
+import { FileWatcher } from "./watcher.js";
+export interface WorkspaceSync {
+    engine: SyncEngine;
+    watcher: FileWatcher;
+    workspace: string;
+    agentId: string;
+}
+export declare function loadDeviceConfig(workspace: string): Promise<DeviceConfig | null>;
+export declare function saveDeviceConfig(workspace: string, config: DeviceConfig): Promise<void>;
+export declare function requestWorkspaceUpdate(workspace: string, agentId: string, gatewayConfig: NonNullable<OpenClawConfig["gateway"]>): Promise<void>;
+export declare function startWorkspaceSync(workspace: string, agentId: string, pluginConfig: Partial<SyncPluginConfig>, initialAdd: boolean, logger: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+}): Promise<WorkspaceSync | null>;
+export interface InitResult {
+    alreadyInitialized: boolean;
+    setupComplete: boolean;
+    agentDID: string;
+    agentKey: string;
+}
+export interface SetupResult {
+    agentDID: string;
+    spaceDID: string | undefined;
+}
+export interface JoinResult {
+    agentDID: string;
+    spaceDID: string | undefined;
+    pullCount: number;
+}
+export declare function doInit(workspace: string): Promise<InitResult>;
+export declare function doSetup(workspace: string, agentId: string, delegationArg: string, pluginConfig: Partial<SyncPluginConfig>, gatewayConfig?: NonNullable<OpenClawConfig["gateway"]>): Promise<SetupResult>;
+export declare function doJoin(workspace: string, agentId: string, uploadDelegationArg: string, nameDelegationArg: string, pluginConfig: Partial<SyncPluginConfig>, gatewayConfig?: NonNullable<OpenClawConfig["gateway"]>): Promise<JoinResult>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAS3C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GACpD,OAAO,CAAC,IAAI,CAAC,CAqCf;AAID,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,EACvC,UAAU,EAAE,OAAO,EACnB,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACnE,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAmC/B;AAID,MAAM,WAAW,UAAU;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAsB,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAsBnE;AAED,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,EACvC,aAAa,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GACrD,OAAO,CAAC,WAAW,CAAC,CA0CtB;AAED,wBAAsB,MAAM,CAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,mBAAmB,EAAE,MAAM,EAC3B,iBAAiB,EAAE,MAAM,EACzB,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,EACvC,aAAa,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GACrD,OAAO,CAAC,UAAU,CAAC,CA8CrB"}

package/dist/commands.js

@@ -0,0 +1,185 @@
+/**
+ * Extracted command logic for Storacha workspace sync.
+ *
+ * Shared by CLI commands (thin wrappers in plugin.ts) and the
+ * interactive `onboard` command.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { SyncEngine } from "./sync.js";
+import { FileWatcher } from "./watcher.js";
+import { encodeDelegation, readDelegationArg, } from "./utils/delegation.js";
+import { Agent } from "@storacha/ucn/pail";
+// --- Config helpers ---
+export 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;
+    }
+}
+export 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));
+}
+export async function requestWorkspaceUpdate(workspace, agentId, gatewayConfig) {
+    const DEFAULT_GATEWAY_PORT = 18789;
+    let port = DEFAULT_GATEWAY_PORT;
+    if (typeof gatewayConfig.port === "number" &&
+        Number.isFinite(gatewayConfig.port) &&
+        gatewayConfig.port > 0) {
+        port = gatewayConfig.port;
+    }
+    const url = `http://127.0.0.1:${port}/api/channels/clawracha/workspace-update`;
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    const token = gatewayConfig.auth?.token ?? gatewayConfig.auth?.password;
+    if (token) {
+        headers["Authorization"] = `Bearer ${token}`;
+    }
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ agentId, workspace }),
+        });
+        if (!res.ok) {
+            console.warn(`Warning: Failed to notify gateway (${res.status}). Restart the gateway to pick up changes.`);
+        }
+    }
+    catch (err) {
+        console.warn(`Warning: Could not reach gateway at ${url}: ${err.message}. Restart the gateway to pick up changes.`);
+    }
+}
+// --- Sync lifecycle ---
+export async function startWorkspaceSync(workspace, agentId, pluginConfig, initialAdd, logger) {
+    const deviceConfig = await loadDeviceConfig(workspace);
+    if (!deviceConfig || !deviceConfig.setupComplete) {
+        return null;
+    }
+    const engine = new SyncEngine(workspace);
+    await engine.init(deviceConfig);
+    const watcher = new FileWatcher({
+        workspace,
+        config: {
+            enabled: true,
+            watchPatterns: pluginConfig.watchPatterns ?? ["**/*"],
+            ignorePatterns: pluginConfig.ignorePatterns ?? [
+                ".storacha/**",
+                "node_modules/**",
+                ".git/**",
+                "dist/**",
+            ],
+        },
+        onChanges: async (changes) => {
+            await engine.processChanges(changes);
+            await engine.sync();
+            const nameArchive = await engine.exportNameArchive();
+            const updatedConfig = { ...deviceConfig, nameArchive };
+            await saveDeviceConfig(workspace, updatedConfig);
+        },
+        initialAdd,
+    });
+    await watcher.start();
+    logger.info(`[${agentId}] Started syncing workspace: ${workspace}`);
+    return { engine, watcher, workspace, agentId };
+}
+// --- Core command logic ---
+export async function doInit(workspace) {
+    const existing = await loadDeviceConfig(workspace);
+    if (existing?.agentKey) {
+        const agent = Agent.parse(existing.agentKey);
+        return {
+            alreadyInitialized: true,
+            setupComplete: !!existing.setupComplete,
+            agentDID: agent.did(),
+            agentKey: existing.agentKey,
+        };
+    }
+    const agent = await Agent.generate();
+    const agentKey = Agent.format(agent);
+    await saveDeviceConfig(workspace, { agentKey });
+    return {
+        alreadyInitialized: false,
+        setupComplete: false,
+        agentDID: agent.did(),
+        agentKey,
+    };
+}
+export async function doSetup(workspace, agentId, delegationArg, pluginConfig, gatewayConfig) {
+    const deviceConfig = await loadDeviceConfig(workspace);
+    if (!deviceConfig?.agentKey) {
+        throw new Error("Not initialized. Run init first.");
+    }
+    if (deviceConfig.setupComplete) {
+        const agent = Agent.parse(deviceConfig.agentKey);
+        return { agentDID: agent.did(), spaceDID: deviceConfig.spaceDID };
+    }
+    const delegation = await readDelegationArg(delegationArg);
+    const spaceDID = delegation.capabilities[0]?.with;
+    const { ok: archiveBytes } = await delegation.archive();
+    if (!archiveBytes)
+        throw new Error("Failed to archive delegation");
+    deviceConfig.uploadDelegation = encodeDelegation(archiveBytes);
+    deviceConfig.spaceDID = spaceDID ?? undefined;
+    deviceConfig.setupComplete = true;
+    await saveDeviceConfig(workspace, deviceConfig);
+    // One-shot sync: scan existing files, upload, stop
+    const sync = await startWorkspaceSync(workspace, agentId, pluginConfig, true, console);
+    if (!sync)
+        throw new Error("Failed to start sync engine");
+    await sync.watcher.waitForReady();
+    await sync.watcher.stop();
+    await sync.watcher.forceFlush();
+    await sync.engine.stop();
+    if (gatewayConfig) {
+        await requestWorkspaceUpdate(workspace, agentId, gatewayConfig);
+    }
+    const agent = Agent.parse(deviceConfig.agentKey);
+    return { agentDID: agent.did(), spaceDID: spaceDID ?? undefined };
+}
+export async function doJoin(workspace, agentId, uploadDelegationArg, nameDelegationArg, pluginConfig, gatewayConfig) {
+    const deviceConfig = await loadDeviceConfig(workspace);
+    if (!deviceConfig?.agentKey) {
+        throw new Error("Not initialized. Run init first.");
+    }
+    if (deviceConfig.setupComplete) {
+        const agent = Agent.parse(deviceConfig.agentKey);
+        return { agentDID: agent.did(), spaceDID: deviceConfig.spaceDID, pullCount: 0 };
+    }
+    const uploadDelegation = await readDelegationArg(uploadDelegationArg);
+    const nameDelegation = await readDelegationArg(nameDelegationArg);
+    const spaceDID = uploadDelegation.capabilities[0]?.with;
+    const { ok: uploadArchive } = await uploadDelegation.archive();
+    if (!uploadArchive)
+        throw new Error("Failed to archive upload delegation");
+    const { ok: nameArchiveBytes } = await nameDelegation.archive();
+    if (!nameArchiveBytes)
+        throw new Error("Failed to archive name delegation");
+    deviceConfig.uploadDelegation = encodeDelegation(uploadArchive);
+    deviceConfig.nameDelegation = encodeDelegation(nameArchiveBytes);
+    deviceConfig.spaceDID = spaceDID ?? undefined;
+    deviceConfig.setupComplete = true;
+    await saveDeviceConfig(workspace, deviceConfig);
+    // One-shot sync: pull remote, stop
+    const sync = await startWorkspaceSync(workspace, agentId, pluginConfig, false, console);
+    if (!sync)
+        throw new Error("Failed to start sync engine");
+    const pullCount = await sync.engine.pullRemote();
+    await sync.watcher.stop();
+    await sync.watcher.forceFlush();
+    await sync.engine.stop();
+    if (gatewayConfig) {
+        await requestWorkspaceUpdate(workspace, agentId, gatewayConfig);
+    }
+    const agent = Agent.parse(deviceConfig.agentKey);
+    return { agentDID: agent.did(), spaceDID: spaceDID ?? undefined, pullCount };
+}

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

@@ -1 +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;AAsJ1C,UAAU,cAAc;IACtB,UAAU,EAAE,GAAG,CAAC;IAChB,SAAS,EAAE,KAAK,EAAE,CAAC;CACpB;AAyBD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAU,aAAa,MAAM,KAAG,OAAO,CAAC,cAAc,CAEvE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG,GACd,QAAQ,YAAY,EACpB,SAAS,SAAS,EAClB,KAAK,MAAM,EACX,aAAa,MAAM,KAClB,OAAO,CAAC,cAAc,GAAG,IAAI,CAkC/B,CAAC;AA0RF;;;GAGG;AACH,eAAO,MAAM,GAAG,GACd,QAAQ,YAAY,EACpB,SAAS,SAAS,EAClB,KAAK,MAAM,KACV,OAAO,CAAC,MAAM,GAAG,SAAS,CAM5B,CAAC"}
+{"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;AAuJ1C,UAAU,cAAc;IACtB,UAAU,EAAE,GAAG,CAAC;IAChB,SAAS,EAAE,KAAK,EAAE,CAAC;CACpB;AAyBD;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAU,aAAa,MAAM,KAAG,OAAO,CAAC,cAAc,CAEvE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG,GACd,QAAQ,YAAY,EACpB,SAAS,SAAS,EAClB,KAAK,MAAM,EACX,aAAa,MAAM,KAClB,OAAO,CAAC,cAAc,GAAG,IAAI,CAkC/B,CAAC;AAkSF;;;GAGG;AACH,eAAO,MAAM,GAAG,GACd,QAAQ,YAAY,EACpB,SAAS,SAAS,EAClB,KAAK,MAAM,KACV,OAAO,CAAC,MAAM,GAAG,SAAS,CAM5B,CAAC"}

package/dist/mdsync/index.js

@@ -16,7 +16,7 @@ import { MemoryBlockstore, withCache } from "@storacha/ucn/block";
 import * as CRDT from "@web3-storage/pail/crdt";
 import { CID } from "multiformats";
 import * as cbor from "@ipld/dag-cbor";
-import { fromMarkdown, encodeTree, encodeRGA, RGA, decodeRGA, decodeTree, computeChangeSet, applyRGAChangeSet, encodeChangeSet, decodeChangeSet, toMarkdown, } from "@storacha/md-merge";
+import { fromMarkdown, encodeTree, encodeRGA, RGA, decodeRGA, decodeTree, computeChangeSet, applyRGAChangeSet, encodeChangeSet, decodeChangeSet, toMarkdown, mergeRGATrees, } from "@storacha/md-merge";
 import * as Pail from "@web3-storage/pail";
 import { decode, encode } from "multiformats/block";
 import { sha256 } from "multiformats/hashes/sha2";
@@ -318,15 +318,26 @@ const resolveValue = async (blocks, current, key) => {
             const newMDEntry = await getMarkdownEntry(blocks, mdEntryCid);
             if (newMDEntry.type === "initial") {
                 // First write for this key — bootstrap from the stored entry.
+                const newEventRGA = await getEventRGAFromCID(blocks, newMDEntry.events);
+                const newRoot = await getRGATreeFromRootCID(blocks, newMDEntry.root, newEventRGA);
                 if (mdEntry) {
-                    throw new Error(`Expected no existing markdown entry for initial event, found ${mdEntryCid}`);
+                    // Concurrent initial — two branches independently created this key.
+                    // Merge event histories and merge the two RGA trees.
+                    mdEntry.events.merge(newEventRGA);
+                    const comparator = makeComparator(mdEntry.events);
+                    mdEntry = {
+                        type: "initial",
+                        events: mdEntry.events,
+                        root: mergeRGATrees(mdEntry.root, newRoot, comparator),
+                    };
+                }
+                else {
+                    mdEntry = {
+                        type: "initial",
+                        events: newEventRGA,
+                        root: newRoot,
+                    };
                 }
-                const eventRGA = await getEventRGAFromCID(blocks, newMDEntry.events);
-                mdEntry = {
-                    type: "initial",
-                    events: eventRGA,
-                    root: await getRGATreeFromRootCID(blocks, newMDEntry.root, eventRGA),
-                };
             }
             else {
                 // Update — merge event histories, then apply the changeset.

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,EAIlB,MAAM,qBAAqB,CAAC;AAmJ7B,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,iBAAiB,QAqmBpD"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,qBAAqB,CAAC;AAkC7B,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,iBAAiB,QAspBpD"}

package/dist/plugin.js

@@ -6,107 +6,22 @@
  * - CLI commands for setup and management (openclaw clawracha ...)
  * - Agent tools for manual sync control
  */
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
 import { json as consumeJson } from "stream/consumers";
 import { SyncEngine } from "./sync.js";
-import { FileWatcher } from "./watcher.js";
 import { createStorachaClient } from "./utils/client.js";
-import { decodeDelegation, encodeDelegation, readDelegationArg, } from "./utils/delegation.js";
+import { decodeDelegation, encodeDelegation, } from "./utils/delegation.js";
 import { resolveAgentWorkspace, getAgentIds } from "./utils/workspace.js";
 import { Agent, Name } from "@storacha/ucn/pail";
 import { extract } from "@storacha/client/delegation";
 import * as z from "zod";
 import { spaceAccess } from "@storacha/client/capability/access";
+import { loadDeviceConfig, startWorkspaceSync, doInit, doSetup, doJoin, } from "./commands.js";
 const activeSyncers = new Map();
 // --- Config helpers ---
 const UpdateParams = z.object({
     agentId: z.string(),
     workspace: z.string(),
 });
-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;
-    }
-}
-async function requestWorkspaceUpdate(workspace, agentId, gatewayConfig) {
-    // Mirror resolveGatewayPort from openclaw core
-    const DEFAULT_GATEWAY_PORT = 18789;
-    let port = DEFAULT_GATEWAY_PORT;
-    if (typeof gatewayConfig.port === "number" &&
-        Number.isFinite(gatewayConfig.port) &&
-        gatewayConfig.port > 0) {
-        port = gatewayConfig.port;
-    }
-    const url = `http://127.0.0.1:${port}/api/channels/clawracha/workspace-update`;
-    const headers = {
-        "Content-Type": "application/json",
-    };
-    // Auth: /api/channels/ routes get gateway auth middleware
-    const token = gatewayConfig.auth?.token ?? gatewayConfig.auth?.password;
-    if (token) {
-        headers["Authorization"] = `Bearer ${token}`;
-    }
-    try {
-        const res = await fetch(url, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({ agentId, workspace }),
-        });
-        if (!res.ok) {
-            console.warn(`Warning: Failed to notify gateway (${res.status}). Restart the gateway to pick up changes.`);
-        }
-    }
-    catch (err) {
-        console.warn(`Warning: Could not reach gateway at ${url}: ${err.message}. Restart the gateway to pick up changes.`);
-    }
-}
-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));
-}
-// --- Service helpers ---
-async function startWorkspaceSync(workspace, agentId, pluginConfig, initialAdd, logger) {
-    const deviceConfig = await loadDeviceConfig(workspace);
-    if (!deviceConfig || !deviceConfig.setupComplete) {
-        return null;
-    }
-    const engine = new SyncEngine(workspace);
-    await engine.init(deviceConfig);
-    const watcher = new FileWatcher({
-        workspace,
-        config: {
-            enabled: true,
-            watchPatterns: pluginConfig.watchPatterns ?? ["**/*"],
-            ignorePatterns: pluginConfig.ignorePatterns ?? [
-                ".storacha/**",
-                "node_modules/**",
-                ".git/**",
-                "dist/**",
-            ],
-        },
-        onChanges: async (changes) => {
-            await engine.processChanges(changes);
-            await engine.sync();
-            const nameArchive = await engine.exportNameArchive();
-            const updatedConfig = { ...deviceConfig, nameArchive };
-            await saveDeviceConfig(workspace, updatedConfig);
-        },
-        initialAdd,
-    });
-    await watcher.start();
-    logger.info(`[${agentId}] Started syncing workspace: ${workspace}`);
-    return { engine, watcher, workspace, agentId };
-}
 // --- Plugin entry ---
 export default function plugin(api) {
     const pluginConfig = (api.pluginConfig ?? {});
@@ -271,12 +186,11 @@ export default function plugin(api) {
             .action(async (opts) => {
             try {
                 const { agentId, workspace } = requireAgent(opts.agent);
-                const existing = await loadDeviceConfig(workspace);
-                if (existing?.agentKey) {
-                    const agent = Agent.parse(existing.agentKey);
+                const result = await doInit(workspace);
+                if (result.alreadyInitialized) {
                     console.log(`Agent already initialized for ${agentId}.`);
-                    console.log(`Agent DID: ${agent.did()}`);
-                    if (existing.setupComplete) {
+                    console.log(`Agent DID: ${result.agentDID}`);
+                    if (result.setupComplete) {
                         console.log(`\nSetup is complete. Use \`openclaw clawracha status --agent ${agentId}\` to check sync state.`);
                     }
                     else {
@@ -286,11 +200,8 @@ export default function plugin(api) {
                     }
                     return;
                 }
-                const agent = await Agent.generate();
-                const agentKey = Agent.format(agent);
-                await saveDeviceConfig(workspace, { agentKey });
                 console.log(`🔥 Agent initialized for ${agentId}!`);
-                console.log(`Agent DID: ${agent.did()}`);
+                console.log(`Agent DID: ${result.agentDID}`);
                 console.log("\nNext step — choose one:");
                 console.log(`  New workspace:  openclaw clawracha setup <delegation> --agent ${agentId}`);
                 console.log(`  Join existing:  openclaw clawracha join <upload> <name> --agent ${agentId}`);
@@ -315,40 +226,10 @@ export default function plugin(api) {
                     console.error(`Run \`openclaw clawracha init --agent ${agentId}\` first.`);
                     process.exit(1);
                 }
-                if (deviceConfig.setupComplete) {
-                    console.log("Setup already complete.");
-                    return;
-                }
-                const delegation = await readDelegationArg(delegationArg);
-                const spaceDID = delegation.capabilities[0]?.with;
-                const { ok: archiveBytes } = await delegation.archive();
-                if (!archiveBytes) {
-                    throw new Error("Failed to archive delegation");
-                }
-                deviceConfig.uploadDelegation = encodeDelegation(archiveBytes);
-                deviceConfig.spaceDID = spaceDID ?? undefined;
-                deviceConfig.setupComplete = true;
-                await saveDeviceConfig(workspace, deviceConfig);
-                // Initial upload: scan all existing workspace files and sync to Storacha
-                const sync = await startWorkspaceSync(workspace, agentId, pluginConfig, true, console);
-                if (!sync) {
-                    throw new Error("Failed to start sync engine");
-                }
-                // Wait for initial files to flush through, then stop the watcher
-                await sync.watcher.waitForReady();
-                await sync.watcher.stop();
-                // force out changes then stop the engine, which will wait for last
-                // sync to complete
-                await sync.watcher.forceFlush();
-                await sync.engine.stop();
-                // post to the endpoint to tell the service to start syncing this space
-                if (config.gateway) {
-                    await requestWorkspaceUpdate(workspace, agentId, config.gateway);
-                }
-                const agent = Agent.parse(deviceConfig.agentKey);
+                const result = await doSetup(workspace, agentId, delegationArg, pluginConfig, config.gateway);
                 console.log(`🔥 Storacha workspace ready for ${agentId}!`);
-                console.log(`Agent DID: ${agent.did()}`);
-                console.log(`Space: ${spaceDID ?? "unknown"}`);
+                console.log(`Agent DID: ${result.agentDID}`);
+                console.log(`Space: ${result.spaceDID ?? "unknown"}`);
                 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).");
@@ -375,43 +256,11 @@ export default function plugin(api) {
                     console.error(`Run \`openclaw clawracha init --agent ${agentId}\` first.`);
                     process.exit(1);
                 }
-                if (deviceConfig.setupComplete) {
-                    console.log("Setup already complete.");
-                    return;
-                }
-                const uploadDelegation = await readDelegationArg(uploadArg);
-                const nameDelegation = await readDelegationArg(nameArg);
-                const spaceDID = uploadDelegation.capabilities[0]?.with;
-                const { ok: uploadArchive } = await uploadDelegation.archive();
-                if (!uploadArchive)
-                    throw new Error("Failed to archive upload delegation");
-                const { ok: nameArchiveBytes } = await nameDelegation.archive();
-                if (!nameArchiveBytes)
-                    throw new Error("Failed to archive name delegation");
-                deviceConfig.uploadDelegation = encodeDelegation(uploadArchive);
-                deviceConfig.nameDelegation = encodeDelegation(nameArchiveBytes);
-                deviceConfig.spaceDID = spaceDID ?? undefined;
-                deviceConfig.setupComplete = true;
-                await saveDeviceConfig(workspace, deviceConfig);
-                // Pull remote state before watcher starts
-                const sync = await startWorkspaceSync(workspace, agentId, pluginConfig, false, console);
-                let pullCount = 0;
-                if (!sync) {
-                    throw new Error("Failed to start sync engine");
-                }
-                pullCount = await sync.engine.pullRemote();
-                await sync.watcher.stop();
-                await sync.watcher.forceFlush();
-                await sync.engine.stop();
-                // post to the endpoint to tell the service to start syncing this space
-                if (config.gateway) {
-                    await requestWorkspaceUpdate(workspace, agentId, config.gateway);
-                }
-                const agent = Agent.parse(deviceConfig.agentKey);
+                const result = await doJoin(workspace, agentId, uploadArg, nameArg, pluginConfig, config.gateway);
                 console.log(`🔥 Joined existing Storacha workspace for ${agentId}!`);
-                console.log(`Agent DID: ${agent.did()}`);
-                console.log(`Space: ${spaceDID ?? "unknown"}`);
-                console.log(`Pulled ${pullCount} files from remote.`);
+                console.log(`Agent DID: ${result.agentDID}`);
+                console.log(`Space: ${result.spaceDID ?? "unknown"}`);
+                console.log(`Pulled ${result.pullCount} files from remote.`);
                 console.log("\nSync is now active (no gateway restart needed).");
             }
             catch (err) {
@@ -584,5 +433,84 @@ export default function plugin(api) {
                 process.exit(1);
             }
         });
+        // --- onboard ---
+        clawracha
+            .command("onboard")
+            .description("Interactive guided setup for Storacha workspace sync")
+            .requiredOption("--agent <id>", "Agent ID")
+            .action(async (opts) => {
+            const { promptMultiline, choose } = await import("./prompts.js");
+            try {
+                const { agentId, workspace } = requireAgent(opts.agent);
+                console.log("🔥 Welcome to Clawracha — Storacha workspace sync!\n");
+                // Step 1: Init
+                console.log("Step 1: Agent Identity");
+                const initResult = await doInit(workspace);
+                if (initResult.alreadyInitialized) {
+                    console.log("  Agent already initialized.");
+                    if (initResult.setupComplete) {
+                        console.log(`  Setup is already complete! Use \`openclaw clawracha status --agent ${agentId}\` to check sync.\n`);
+                        return;
+                    }
+                }
+                else {
+                    console.log("  ✅ Agent identity generated!");
+                }
+                console.log(`  Agent DID: ${initResult.agentDID}\n`);
+                // Step 2: Path choice
+                const choice = await choose("Are you setting up a NEW workspace or JOINING an existing one?", ["NEW workspace", "JOIN existing"]);
+                if (choice === "NEW workspace") {
+                    // --- Setup path ---
+                    console.log("\n📦 New Workspace Setup\n");
+                    console.log("You need a Storacha upload delegation for this agent.");
+                    console.log("On a machine with the Storacha CLI, run:\n");
+                    console.log(`  storacha delegation create ${initResult.agentDID} --base64\n`);
+                    const delegationInput = await promptMultiline("Paste your upload delegation here:");
+                    if (!delegationInput) {
+                        console.error("No delegation provided. Aborting.");
+                        process.exit(1);
+                    }
+                    console.log("\n⏳ Setting up workspace...");
+                    const result = await doSetup(workspace, agentId, delegationInput, pluginConfig, config.gateway);
+                    console.log(`\n🔥 Storacha workspace ready for ${agentId}!`);
+                    console.log(`  Agent DID: ${result.agentDID}`);
+                    console.log(`  Space: ${result.spaceDID ?? "unknown"}`);
+                    console.log("\nTo add another device, run:");
+                    console.log(`  openclaw clawracha grant <their-DID> --agent ${agentId}`);
+                    console.log("\nSync is now active! 🎉");
+                }
+                else {
+                    // --- Join path ---
+                    console.log("\n🤝 Join Existing Workspace\n");
+                    console.log("You need someone with access to grant you delegations.");
+                    console.log("Ask them to run:\n");
+                    console.log(`  openclaw clawracha grant ${initResult.agentDID} --agent <their-agent-id>\n`);
+                    console.log("They'll get two delegations to share with you.\n");
+                    const uploadInput = await promptMultiline("Paste the upload delegation here:");
+                    if (!uploadInput) {
+                        console.error("No upload delegation provided. Aborting.");
+                        process.exit(1);
+                    }
+                    const nameInput = await promptMultiline("Paste the name delegation here:");
+                    if (!nameInput) {
+                        console.error("No name delegation provided. Aborting.");
+                        process.exit(1);
+                    }
+                    console.log("\n⏳ Joining workspace...");
+                    const result = await doJoin(workspace, agentId, uploadInput, nameInput, pluginConfig, config.gateway);
+                    console.log(`\n🔥 Joined Storacha workspace for ${agentId}!`);
+                    console.log(`  Agent DID: ${result.agentDID}`);
+                    console.log(`  Space: ${result.spaceDID ?? "unknown"}`);
+                    console.log(`  Pulled ${result.pullCount} files from remote.`);
+                    console.log("\nSync is now active! 🎉");
+                }
+            }
+            catch (err) {
+                console.error(`\n❌ Error: ${err.message}`);
+                if (err.stack)
+                    console.error(err.stack);
+                process.exit(1);
+            }
+        });
     }, { commands: ["clawracha"] });
 }

package/dist/prompts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Interactive prompt helpers using Node.js built-in readline/promises.
+ * Zero external dependencies.
+ */
+export declare function prompt(question: string): Promise<string>;
+export declare function promptMultiline(question: string): Promise<string>;
+export declare function choose(question: string, options: string[]): Promise<string>;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,wBAAsB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ9D;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUvE;AAED,wBAAsB,MAAM,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,MAAM,CAAC,CAoBjB"}

package/dist/prompts.js

@@ -0,0 +1,49 @@
+/**
+ * Interactive prompt helpers using Node.js built-in readline/promises.
+ * Zero external dependencies.
+ */
+import * as readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+export async function prompt(question) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = await rl.question(question);
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function promptMultiline(question) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        console.log(question);
+        console.log("(Paste the value and press Enter)");
+        const answer = await rl.question("> ");
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function choose(question, options) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        console.log(question);
+        options.forEach((opt, i) => console.log(`  ${i + 1}) ${opt}`));
+        while (true) {
+            const answer = await rl.question("Choice: ");
+            const num = parseInt(answer.trim(), 10);
+            if (num >= 1 && num <= options.length) {
+                return options[num - 1];
+            }
+            const match = options.find((o) => o.toLowerCase() === answer.trim().toLowerCase());
+            if (match)
+                return match;
+            console.log(`Please enter 1-${options.length}.`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storacha/clawracha",
-  "version": "0.1.23",
+  "version": "0.2.1",
   "description": "OpenClaw plugin for Storacha workspace sync via UCN Pail",
   "type": "module",
   "files": [
@@ -29,7 +29,7 @@
     "@ipld/car": "^5.2.0",
     "@ipld/dag-cbor": "^9.2.5",
     "@storacha/client": "^2.0.4",
-    "@storacha/md-merge": "0.6.0",
+    "@storacha/md-merge": "0.7.0",
     "@storacha/ucn": "1.1.1-rc.3",
     "@storacha/upload-client": "^1.3.9",
     "@ucanto/interface": "^11.0.1",