shadow-claw 1.23.3 → 1.24.0

package/README.md

@@ -2,23 +2,43 @@
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/xt-ml/shadow-claw)
 
-A browser-native, fully-featured AI assistant. TypeScript + Web Components + IndexedDB + File System API.
+A browser-native, fully-featured AI assistant — runs as a PWA, a native desktop app, a Node.js server, and via the `shadow-claw` CLI. TypeScript + Web Components + IndexedDB + File System API.
 
 [![ShadowClaw Screenshot](https://xt-ml.github.io/shadow-claw/assets/screenshots/shadow-claw-screenshot-1920x1052.png)](https://xt-ml.github.io/shadow-claw/)
 
 ## Quick Start
 
+### 1. Launch ShadowClaw instantly without cloning the repo
+
 ```bash
-npm install && npm run dev  # Dev server → http://localhost:8888
+npx shadow-claw dev --open
 ```
 
-Open Settings, select a provider (or use browser Prompt API), and start chatting.
+Open Settings, select your AI provider (or use the in-browser Prompt API / local models), and start chatting.
+
+### 2. Scaffold a Project or Knowledge Hub
+
+Create a custom template with pages and site configuration:
+
+```bash
+npx shadow-claw init my-assistant
+cd my-assistant
+npx shadow-claw dev --open
+```
+
+### 3. From Source (Contributing / Development)
+
+```bash
+git clone https://github.com/xt-ml/shadow-claw.git
+cd shadow-claw
+npm install && npm run dev  # Dev server → http://localhost:8888
+```
 
-**Desktop:** `npm run electron` or `npm run electron:build` for distributable.
+**Desktop App:** `npm run electron` or `npm run electron:build` for distributable installer.
 
 ## What is ShadowClaw?
 
-A fully-functional agent runtime that runs entirely in the browser—no AI processing on a server. Built with TypeScript, it provides:
+A fully-functional agent runtime built on browser-native technology — the orchestration and tool-use loop run client-side, with AI inference routing to remote APIs, local servers, or in-browser models depending on your configuration. Built with TypeScript, it provides:
 
 - **Multi-model support**: OpenRouter, Anthropic, Google Gemini, AWS Bedrock, Ollama, Llamafile, Mesh LLM, Transformers.js, and browser-native Prompt API
 - **Web Components UI**: Native Custom Elements + TC39 Signals for reactive updates
@@ -378,6 +398,23 @@ npm run electron:build:win   # Build Electron for Windows
 npm run electron:build:mac   # Build Electron for macOS
 ```
 
+### CLI Runtime Commands
+
+The `shadow-claw` CLI connects to a running server or browser clients to interact with active sessions:
+
+```bash
+npx shadow-claw clients                              # List connected browser/Electron clients
+npx shadow-claw send "your prompt" --client <id>    # Send a message to a connected client
+npx shadow-claw backup                               # Trigger OPFS workspace backup
+npx shadow-claw backup list                          # List available backup snapshots
+npx shadow-claw backup delete --backup-id <id>      # Delete a backup snapshot
+npx shadow-claw tasks --client <id>                  # List scheduled tasks on a client
+npx shadow-claw webrtc listen                        # Start headless WebRTC DataChannel daemon
+npx shadow-claw peer-id                              # Get or generate persistent CLI Peer ID
+```
+
+Commands support `--transport webrtc` for direct peer-to-peer DataChannel execution with connected browser clients. Control plane authentication uses `SHADOWCLAW_CONTROL_TOKEN` (env) or `--token` flag. The control plane endpoint and token are printed to the console on server start.
+
 ## License
 
 AGPLv3. Core logic derived from [openbrowserclaw](https://github.com/sachaa/openbrowserclaw) (MIT).

package/bin/assert-version-bump.mjs

@@ -4,12 +4,12 @@ import { execSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
 
-function parseSemver(v) {
+export function parseSemver(v) {
   const clean = String(v || "")
     .trim()
     .replace(/^[v^~]/, "");
@@ -26,7 +26,7 @@ function parseSemver(v) {
   };
 }
 
-function compareSemver(a, b) {
+export function compareSemver(a, b) {
   const pa = parseSemver(a);
   const pb = parseSemver(b);
   if (!pa || !pb) return String(a).localeCompare(String(b));
@@ -43,6 +43,47 @@ function compareSemver(a, b) {
   return 0;
 }
 
+export async function assertVersionBump({
+  localPkgVersion,
+  localLockVersion,
+  pkgName,
+  publishedVersion,
+  silent = false,
+}) {
+  if (!silent) {
+    console.log(`Checking version bump for package "${pkgName}"...`);
+    console.log(`- Local package.json version     : ${localPkgVersion}`);
+  }
+
+  if (localLockVersion) {
+    if (!silent) {
+      console.log(`- Local package-lock.json version: ${localLockVersion}`);
+    }
+    if (localPkgVersion !== localLockVersion) {
+      throw new Error(
+        `Version mismatch: package.json (${localPkgVersion}) does not match package-lock.json (${localLockVersion})!`,
+      );
+    }
+  }
+
+  if (publishedVersion) {
+    if (!silent) {
+      console.log(`- Published npm registry version : ${publishedVersion}`);
+    }
+    const cmp = compareSemver(localPkgVersion, publishedVersion);
+    if (cmp <= 0) {
+      throw new Error(
+        `Version assertion failed: Local version (${localPkgVersion}) must be greater than published npm version (${publishedVersion}). Please bump the version before publishing.`,
+      );
+    }
+    if (!silent) {
+      console.log(
+        `✓ Version assertion passed: ${localPkgVersion} > ${publishedVersion}`,
+      );
+    }
+  }
+}
+
 async function main() {
   const pkgJsonPath = path.join(rootDir, "package.json");
   const lockJsonPath = path.join(rootDir, "package-lock.json");
@@ -57,21 +98,6 @@ async function main() {
   const localPkgVersion = pkg.version;
   const localLockVersion = lock?.version;
 
-  console.log(`Checking version bump for package "${pkgName}"...`);
-  console.log(`- Local package.json version     : ${localPkgVersion}`);
-  if (localLockVersion) {
-    console.log(`- Local package-lock.json version: ${localLockVersion}`);
-    if (localPkgVersion !== localLockVersion) {
-      console.error(
-        `\n[FATAL] Version mismatch: package.json (${localPkgVersion}) does not match package-lock.json (${localLockVersion})!`,
-      );
-      console.error(
-        `Run "npm install" or "npm version" to synchronize package-lock.json.`,
-      );
-      process.exit(1);
-    }
-  }
-
   let publishedVersion = null;
   try {
     const rawOut = execSync(`npm view ${pkgName} version --json`, {
@@ -98,25 +124,21 @@ async function main() {
     );
   }
 
-  if (publishedVersion) {
-    console.log(`- Published npm registry version : ${publishedVersion}`);
-    const cmp = compareSemver(localPkgVersion, publishedVersion);
-    if (cmp <= 0) {
-      console.error(
-        `\n[FATAL] Version assertion failed: Local version (${localPkgVersion}) must be greater than published npm version (${publishedVersion}).`,
-      );
-      console.error(
-        `Please bump the version in package.json and package-lock.json (e.g. "npm version patch|minor|major") before publishing.\n`,
-      );
-      process.exit(1);
-    }
-    console.log(
-      `✓ Version assertion passed: ${localPkgVersion} > ${publishedVersion}`,
-    );
-  }
+  await assertVersionBump({
+    localPkgVersion,
+    localLockVersion,
+    pkgName,
+    publishedVersion,
+  });
 }
 
-main().catch((err) => {
-  console.error("Version assertion check failed:", err);
-  process.exit(1);
-});
+const isMainModule =
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isMainModule) {
+  main().catch((err) => {
+    console.error(`\n[FATAL] ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/bin/assert-version-bump.test.mjs

@@ -1,16 +1,79 @@
 import { describe, it, expect } from "@jest/globals";
-import { execFile } from "node:child_process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFile);
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const scriptPath = path.join(__dirname, "assert-version-bump.mjs");
+import {
+  parseSemver,
+  compareSemver,
+  assertVersionBump,
+} from "./assert-version-bump.mjs";
 
 describe("assert-version-bump", () => {
-  it("runs successfully when local version is greater than published version", async () => {
-    const { stdout } = await execFileAsync(process.execPath, [scriptPath]);
-    expect(stdout).toContain("Checking version bump for package");
+  describe("parseSemver", () => {
+    it("parses valid semver strings correctly", () => {
+      expect(parseSemver("1.23.4")).toEqual({
+        major: 1,
+        minor: 23,
+        patch: 4,
+        prerelease: null,
+        raw: "1.23.4",
+      });
+      expect(parseSemver("v2.0.0-beta.1")).toEqual({
+        major: 2,
+        minor: 0,
+        patch: 0,
+        prerelease: "beta.1",
+        raw: "2.0.0-beta.1",
+      });
+    });
+
+    it("returns null for invalid semver strings", () => {
+      expect(parseSemver("invalid")).toBeNull();
+      expect(parseSemver("")).toBeNull();
+    });
+  });
+
+  describe("compareSemver", () => {
+    it("correctly compares semver versions", () => {
+      expect(compareSemver("1.23.4", "1.23.3")).toBe(1);
+      expect(compareSemver("2.0.0", "1.99.99")).toBe(1);
+      expect(compareSemver("1.23.3", "1.23.3")).toBe(0);
+      expect(compareSemver("1.23.2", "1.23.3")).toBe(-1);
+    });
+  });
+
+  describe("assertVersionBump", () => {
+    it("passes when local version is greater than published version", async () => {
+      await expect(
+        assertVersionBump({
+          localPkgVersion: "1.23.4",
+          localLockVersion: "1.23.4",
+          pkgName: "shadow-claw",
+          publishedVersion: "1.23.3",
+          silent: true,
+        }),
+      ).resolves.toBeUndefined();
+    });
+
+    it("throws when local version is equal to published version", async () => {
+      await expect(
+        assertVersionBump({
+          localPkgVersion: "1.23.3",
+          localLockVersion: "1.23.3",
+          pkgName: "shadow-claw",
+          publishedVersion: "1.23.3",
+          silent: true,
+        }),
+      ).rejects.toThrow("Version assertion failed");
+    });
+
+    it("throws when package.json does not match package-lock.json", async () => {
+      await expect(
+        assertVersionBump({
+          localPkgVersion: "1.23.4",
+          localLockVersion: "1.23.3",
+          pkgName: "shadow-claw",
+          publishedVersion: "1.23.2",
+          silent: true,
+        }),
+      ).rejects.toThrow("Version mismatch");
+    });
   });
 });

package/bin/cli.mjs

@@ -8,6 +8,12 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 
 import { runBuild } from "./build/build.mjs";
+import { runClientsCommand } from "./commands/clients.mjs";
+import { runSendCommand } from "./commands/send.mjs";
+import { runBackupCommand } from "./commands/backup.mjs";
+import { runTasksCommand } from "./commands/tasks.mjs";
+import { runPeerIdCommand } from "./commands/peer-id.mjs";
+import { runWebRtcListenCommand } from "./commands/webrtc-listen.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -421,4 +427,164 @@ slug: "home"
     }
   });
 
+// ---------------------------------------------------------------------------
+// PEER-ID / WEBRTC COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("peer-id [action] [customId]")
+  .alias("webrtc-peer-id")
+  .description(
+    "Get, generate, or renew the WebRTC CLI peer ID stored in .cache/cli-peer-id",
+  )
+  .option(
+    "-r, --renew",
+    "Force renewal / generation of a new WebRTC CLI peer ID",
+  )
+  .option("--set <id>", "Set a specific custom WebRTC CLI peer ID")
+  .option("--cache-dir <dir>", "Custom cache directory (defaults to .cache)")
+  .option("-q, --quiet", "Output only the peer ID string")
+  .option("--json", "Output peer ID and file path as JSON")
+  .action(async (action, customId, options) => {
+    const opts = { ...options };
+    if (customId && !opts.set) {
+      opts.set = customId;
+    }
+    await runPeerIdCommand(action, opts);
+  });
+
+program
+  .command("webrtc [action] [customId]")
+  .description(
+    "Manage WebRTC CLI configuration and peer identity (.cache/cli-peer-id)\n\n" +
+      "  Actions:\n" +
+      "    (default)  Show or generate the CLI peer ID\n" +
+      "    listen     Register as a live PeerJS peer — browser tabs can then\n" +
+      "               connect directly without a control-plane connection",
+  )
+  .option(
+    "-r, --renew",
+    "Force renewal / generation of a new WebRTC CLI peer ID",
+  )
+  .option("--set <id>", "Set a specific custom WebRTC CLI peer ID")
+  .option("--cache-dir <dir>", "Custom cache directory (defaults to .cache)")
+  .option("-q, --quiet", "Output only the peer ID string")
+  .option("--json", "Output peer ID and file path as JSON")
+  // listen-specific options
+  .option("--host <host>", "PeerJS signaling server host (for listen)")
+  .option("--port <port>", "PeerJS signaling server port (for listen)", "8888")
+  .option("--path <path>", "PeerJS signaling server path (for listen)", "/")
+  .option(
+    "--secure",
+    "Use TLS (wss://) for the signaling server (for listen)",
+    false,
+  )
+  .option(
+    "--trusted-peer <id>",
+    "Accept connections only from this peer ID (repeatable, for listen)",
+    (v, prev) => (prev ? [...prev, v] : [v]),
+    [],
+  )
+  .option("--verbose", "Verbose connection logging (for listen)", false)
+  .option("--renew-peer-id", "Renew CLI peer ID before listening", false)
+  .action(async (action, customId, options) => {
+    if (action === "listen") {
+      await runWebRtcListenCommand(options);
+      return;
+    }
+    const opts = { ...options };
+    if (customId && !opts.set) {
+      opts.set = customId;
+    }
+    await runPeerIdCommand(action, opts);
+  });
+
+// ---------------------------------------------------------------------------
+// CLIENTS COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("clients")
+  .description("List connected / registered browser and Electron clients")
+  .option("--host <host>", "Control plane host")
+  .option("--port <port>", "Control plane port")
+  .option("--token <token>", "Control token")
+  .option("--transport <transport>", "Transport to use: http | webrtc", "http")
+  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .option(
+    "--renew-peer-id",
+    "Renew WebRTC CLI peer ID before connecting",
+    false,
+  )
+  .option("--cache-dir <dir>", "Custom cache directory")
+  .action(async (options) => {
+    await runClientsCommand(options);
+  });
+
+// ---------------------------------------------------------------------------
+// SEND COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("send <message>")
+  .description("Send a message/prompt to a connected client")
+  .option("--client <id>", "Target client ID (defaults to first available)")
+  .option("--group <groupId>", "Target conversation group ID")
+  .option("--host <host>", "Control plane host")
+  .option("--port <port>", "Control plane port")
+  .option("--token <token>", "Control token")
+  .option("--transport <transport>", "Transport to use: http | webrtc", "http")
+  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .option("--renew-peer-id", "Renew WebRTC CLI peer ID before sending", false)
+  .option("--cache-dir <dir>", "Custom cache directory")
+  .action(async (message, options) => {
+    await runSendCommand(message, options);
+  });
+
+// ---------------------------------------------------------------------------
+// BACKUP COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("backup [action]")
+  .description(
+    "Trigger or manage client workspace backups (trigger | list | delete)",
+  )
+  .option("--client <id>", "Client ID")
+  .option("--backup-id <id>", "Backup ID (for delete)")
+  .option("--group <groupId>", "Specific workspace group ID")
+  .option("--host <host>", "Control plane host")
+  .option("--port <port>", "Control plane port")
+  .option("--token <token>", "Control token")
+  .option("--transport <transport>", "Transport to use: http | webrtc", "http")
+  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .option(
+    "--renew-peer-id",
+    "Renew WebRTC CLI peer ID before connecting",
+    false,
+  )
+  .option("--cache-dir <dir>", "Custom cache directory")
+  .action(async (action, options) => {
+    await runBackupCommand(action || "trigger", options);
+  });
+
+// ---------------------------------------------------------------------------
+// TASKS COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("tasks")
+  .description("List scheduled tasks on a connected client")
+  .option("--client <id>", "Target client ID")
+  .option("--group <groupId>", "Filter tasks by conversation group ID")
+  .option("--host <host>", "Control plane host")
+  .option("--port <port>", "Control plane port")
+  .option("--token <token>", "Control token")
+  .option("--transport <transport>", "Transport to use: http | webrtc", "http")
+  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .option(
+    "--renew-peer-id",
+    "Renew WebRTC CLI peer ID before connecting",
+    false,
+  )
+  .option("--cache-dir <dir>", "Custom cache directory")
+  .action(async (options) => {
+    await runTasksCommand(options);
+  });
+
 program.parse(process.argv);

package/bin/cli.test.mjs

@@ -49,6 +49,66 @@ describe("shadow-claw CLI", () => {
     expect(stdout).toContain("run");
     expect(stdout).toContain("serve");
     expect(stdout).toContain("init");
+    expect(stdout).toContain("clients");
+    expect(stdout).toContain("send");
+    expect(stdout).toContain("backup");
+    expect(stdout).toContain("tasks");
+    expect(stdout).toContain("peer-id");
+    expect(stdout).toContain("webrtc");
+  });
+
+  it("manages WebRTC CLI peer ID with peer-id command", async () => {
+    const cacheDir = path.join(tempDir, ".cache");
+
+    // 1. Get/generate new peer ID
+    const { stdout: out1 } = await execFileAsync(process.execPath, [
+      cliPath,
+      "peer-id",
+      "--cache-dir",
+      cacheDir,
+      "--json",
+    ]);
+    const json1 = JSON.parse(out1);
+    expect(json1.peerId).toMatch(/^cli-[0-9a-z]+$/);
+    expect(json1.renewed).toBe(true);
+
+    // 2. Subsequent call returns existing peer ID
+    const { stdout: out2 } = await execFileAsync(process.execPath, [
+      cliPath,
+      "peer-id",
+      "--cache-dir",
+      cacheDir,
+      "-q",
+    ]);
+    expect(out2.trim()).toBe(json1.peerId);
+
+    // 3. Renew peer ID
+    const { stdout: out3 } = await execFileAsync(process.execPath, [
+      cliPath,
+      "peer-id",
+      "--renew",
+      "--cache-dir",
+      cacheDir,
+      "--json",
+    ]);
+    const json3 = JSON.parse(out3);
+    expect(json3.peerId).not.toBe(json1.peerId);
+    expect(json3.renewed).toBe(true);
+
+    // 4. Set custom peer ID
+    const { stdout: out4 } = await execFileAsync(process.execPath, [
+      cliPath,
+      "peer-id",
+      "--set",
+      "my-custom-cli-peer",
+      "--cache-dir",
+      cacheDir,
+      "-q",
+    ]);
+    expect(out4.trim()).toBe("my-custom-cli-peer");
+
+    const saved = await readFile(path.join(cacheDir, "cli-peer-id"), "utf8");
+    expect(saved.trim()).toBe("my-custom-cli-peer");
   });
 
   it("initializes a new template with init command", async () => {

package/bin/commands/backup.mjs

@@ -0,0 +1,70 @@
+/**
+ * ShadowClaw CLI — `backup` command
+ * Triggers or lists workspace backups.
+ */
+
+import { CliControlClient } from "../utils/control-client.mjs";
+
+export async function runBackupCommand(action = "trigger", options = {}) {
+  const client = new CliControlClient(options);
+
+  try {
+    if (action === "list") {
+      const backups = await client.listBackups(options.client);
+      if (!backups || backups.length === 0) {
+        console.log("No backups found.");
+        return;
+      }
+
+      console.log(`Available backups (${backups.length}):\n`);
+      backups.forEach((b, idx) => {
+        const dateStr = new Date(b.timestamp).toISOString();
+        const sizeMb = (b.totalBytes / (1024 * 1024)).toFixed(2);
+        console.log(`  ${idx + 1}. [${b.id}] Client: ${b.clientId}`);
+        console.log(`     Date:  ${dateStr}`);
+        console.log(`     Files: ${b.fileCount} (${sizeMb} MB)\n`);
+      });
+      return;
+    }
+
+    if (action === "delete") {
+      if (!options.backupId) {
+        console.error("Error: --backup-id is required for delete action.");
+        process.exitCode = 1;
+        return;
+      }
+      await client.deleteBackup(options.backupId, options.client);
+      console.log(`Backup ${options.backupId} deleted.`);
+      return;
+    }
+
+    // Default: Trigger backup
+    let targetClientId = options.client;
+    if (!targetClientId) {
+      const clients = await client.listClients();
+      if (!clients || clients.length === 0) {
+        console.error("Error: No clients are connected to back up.");
+        process.exitCode = 1;
+        return;
+      }
+      targetClientId = clients[0].clientId;
+    }
+
+    console.log(`Requesting backup from client ${targetClientId}...`);
+    const result = await client.sendCommand(targetClientId, "trigger-backup", {
+      groupId: options.group,
+      token: client.token,
+    });
+
+    if (result.success) {
+      console.log("Backup completed successfully.");
+      console.log(JSON.stringify(result.data, null, 2));
+    } else {
+      console.error(`Backup failed: ${result.error}`);
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    console.error(`Error executing backup command: ${err.message}`);
+    process.exitCode = 1;
+  }
+}

package/bin/commands/clients.mjs

@@ -0,0 +1,41 @@
+/**
+ * ShadowClaw CLI — `clients` command
+ * Lists connected clients and their capabilities.
+ */
+
+import { CliControlClient } from "../utils/control-client.mjs";
+
+export async function runClientsCommand(options = {}) {
+  const client = new CliControlClient(options);
+  try {
+    const clients = await client.listClients();
+
+    if (!clients || clients.length === 0) {
+      console.log("No clients currently registered or connected.");
+      return;
+    }
+
+    console.log(`Connected / registered clients (${clients.length}):\n`);
+    clients.forEach((c, idx) => {
+      const lastSeenSec = Math.max(
+        0,
+        Math.floor((Date.now() - c.lastSeen) / 1000),
+      );
+      const lastSeenStr =
+        lastSeenSec < 60
+          ? `${lastSeenSec}s ago`
+          : `${Math.floor(lastSeenSec / 60)}m ago`;
+
+      console.log(`  ${idx + 1}. ${c.deviceLabel} (id: ${c.clientId})`);
+      if (c.peerId) {
+        console.log(`     Peer ID:      ${c.peerId}`);
+      }
+      console.log(`     Capabilities: ${c.capabilities.join(", ") || "none"}`);
+      console.log(`     Version:      ${c.version}`);
+      console.log(`     Last seen:    ${lastSeenStr}\n`);
+    });
+  } catch (err) {
+    console.error(`Error fetching clients: ${err.message}`);
+    process.exitCode = 1;
+  }
+}