shadow-claw 1.27.1 → 1.28.0

package/bin/cli.test.mjs

@@ -60,6 +60,12 @@ describe("shadow-claw CLI", () => {
       "--help",
     ]);
     expect(stdout).toContain("Usage: shadow-claw");
+    expect(stdout).toContain("Development:");
+    expect(stdout).toContain("Server:");
+    expect(stdout).toContain("Control Plane & Client Bridge:");
+    expect(stdout).toContain("WebRTC:");
+    expect(stdout).toContain("Project:");
+    expect(stdout).toContain("Help & Utility:");
     expect(stdout).toContain("build");
     expect(stdout).toContain("dev");
     expect(stdout).toContain("run");
@@ -75,6 +81,27 @@ describe("shadow-claw CLI", () => {
     expect(stdout).toContain("mcp");
   });
 
+  it("groups subcommand options into logical categories in help", async () => {
+    const { stdout: devHelp } = await execFileAsync(process.execPath, [
+      cliPath,
+      "dev",
+      "--help",
+    ]);
+    expect(devHelp).toContain("Server & Network Options:");
+    expect(devHelp).toContain("Site & Build Options:");
+    expect(devHelp).toContain("Security & Proxy Options:");
+    expect(devHelp).toContain("TLS / HTTPS Options:");
+    expect(devHelp).toContain("Storage & Database Options:");
+
+    const { stdout: webrtcHelp } = await execFileAsync(process.execPath, [
+      cliPath,
+      "webrtc",
+      "--help",
+    ]);
+    expect(webrtcHelp).toContain("Identity Options:");
+    expect(webrtcHelp).toContain("Signaling & Listener Options");
+  });
+
   it("outputs server command help with server --help and aliases", async () => {
     const { stdout: outServer } = await execFileAsync(process.execPath, [
       cliPath,

package/bin/commands/mcp.mjs

@@ -8,8 +8,23 @@
 
 import readline from "node:readline";
 import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { CliControlClient } from "../utils/control-client.mjs";
 
+const __mcp_dirname = path.dirname(fileURLToPath(import.meta.url));
+function getCliVersion() {
+  try {
+    const pkgPath = path.resolve(__mcp_dirname, "../../package.json");
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      if (pkg.version) return pkg.version;
+    }
+  } catch {}
+  return "1.27.1";
+}
+
 export const CLI_BUILTIN_TOOLS = [
   {
     name: "shadowclaw_list_clients",
@@ -105,6 +120,30 @@ export const CLI_BUILTIN_TOOLS = [
       },
     },
   },
+  {
+    name: "shadowclaw_send_notification",
+    description:
+      "Broadcast an OS-level push notification to subscribed devices via Web Push (VAPID), or send to a specific registered client. Works even when the client browser tab is closed, asleep, or running in the background.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Notification title (default: 'ShadowClaw').",
+        },
+        body: {
+          type: "string",
+          description: "The notification body message text.",
+        },
+        clientId: {
+          type: "string",
+          description:
+            "Target client ID, prefix, or device label of a specific client that has registered in the past. If omitted, broadcasts to all subscribed devices.",
+        },
+      },
+      required: ["body"],
+    },
+  },
 ];
 
 export function createCliMcpEngine(options = {}) {
@@ -115,7 +154,7 @@ export function createCliMcpEngine(options = {}) {
 
   const serverInfo = {
     name: "shadow-claw",
-    version: "1.25.0",
+    version: options.version || getCliVersion(),
   };
 
   const capabilities = {
@@ -193,6 +232,12 @@ export function createCliMcpEngine(options = {}) {
           Array.isArray(res.data.tools)
         ) {
           for (const t of res.data.tools) {
+            if (
+              t.name === "send_notification" ||
+              t.name.startsWith("shadowclaw_")
+            ) {
+              continue;
+            }
             if (!toolDefMap.has(t.name)) {
               toolDefMap.set(t.name, t);
               toolSupportingClientsMap.set(t.name, []);
@@ -316,7 +361,9 @@ export function createCliMcpEngine(options = {}) {
           combined.set(t.name, t);
         }
         for (const t of relayed) {
-          combined.set(t.name, t);
+          if (!combined.has(t.name)) {
+            combined.set(t.name, t);
+          }
         }
 
         const sortedTools = Array.from(combined.values()).sort((a, b) =>
@@ -541,6 +588,89 @@ export function createCliMcpEngine(options = {}) {
           };
         }
 
+        if (
+          toolName === "shadowclaw_send_notification" ||
+          toolName === "send_notification"
+        ) {
+          const body = String(args.body || "").trim();
+          if (!body) {
+            return {
+              jsonrpc: "2.0",
+              id: reqId,
+              result: {
+                resultType: "complete",
+                isError: true,
+                content: [
+                  {
+                    type: "text",
+                    text: "Error: Notification 'body' parameter cannot be empty.",
+                  },
+                ],
+                _meta: { "io.modelcontextprotocol/serverInfo": serverInfo },
+              },
+            };
+          }
+
+          const title = String(args.title || "ShadowClaw").trim();
+          const targetClientId =
+            typeof args.clientId === "string" && args.clientId.trim()
+              ? args.clientId.trim()
+              : undefined;
+
+          try {
+            const res = await client.broadcastNotification({
+              title,
+              body,
+              ...(targetClientId ? { clientId: targetClientId } : {}),
+            });
+            const sentCount = res?.sent ?? 0;
+            const failedCount = res?.failed ?? 0;
+            let msg;
+
+            if (res?.notFound) {
+              msg = `Warning: No push subscriptions found for client '${targetClientId}'. Ensure push notifications were registered by this client in ShadowClaw Settings.`;
+            } else if (res?.noSubscribers) {
+              msg =
+                "Warning: Push notification broadcast completed, but no devices are currently subscribed to push notifications. Ensure push notifications are enabled in ShadowClaw Settings on the client first.";
+            } else if (targetClientId) {
+              msg = `Push notification sent to client '${targetClientId}': ${sentCount} recipient(s) delivered, ${failedCount} failed.`;
+            } else {
+              msg = `Push notification broadcast sent: ${sentCount} recipient(s) delivered, ${failedCount} failed.`;
+            }
+
+            return {
+              jsonrpc: "2.0",
+              id: reqId,
+              result: {
+                resultType: "complete",
+                isError: false,
+                content: [{ type: "text", text: msg }],
+                _meta: {
+                  ...res,
+                  ...(targetClientId ? { targetClientId } : {}),
+                  "io.modelcontextprotocol/serverInfo": serverInfo,
+                },
+              },
+            };
+          } catch (err) {
+            return {
+              jsonrpc: "2.0",
+              id: reqId,
+              result: {
+                resultType: "complete",
+                isError: true,
+                content: [
+                  {
+                    type: "text",
+                    text: `Failed to send push notification: ${err.message}`,
+                  },
+                ],
+                _meta: { "io.modelcontextprotocol/serverInfo": serverInfo },
+              },
+            };
+          }
+        }
+
         // Relayed interactive ask_user tool with MRTR response fulfillment if provided
         if (
           toolName === "ask_user" &&

package/bin/commands/mcp.test.mjs

@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   describe,
   it,
@@ -8,6 +11,11 @@ import {
 } from "@jest/globals";
 import { createCliMcpEngine } from "./mcp.mjs";
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, "../../package.json"), "utf8"),
+);
+
 describe("CLI MCP Engine (createCliMcpEngine)", () => {
   let errorSpy;
 
@@ -41,6 +49,7 @@ describe("CLI MCP Engine (createCliMcpEngine)", () => {
     expect(res.id).toBe(1);
     expect(res.result.protocolVersion).toBe("2026-07-28");
     expect(res.result.serverInfo.name).toBe("shadow-claw");
+    expect(res.result.serverInfo.version).toBe(pkg.version);
   });
 
   it("processes tools/list including built-in and client tools", async () => {
@@ -82,7 +91,164 @@ describe("CLI MCP Engine (createCliMcpEngine)", () => {
     const toolNames = res.result.tools.map((t) => t.name);
     expect(toolNames).toContain("shadowclaw_list_clients");
     expect(toolNames).toContain("shadowclaw_send_message");
+    expect(toolNames).toContain("shadowclaw_send_notification");
     expect(toolNames).toContain("read_file");
+
+    const notifTool = res.result.tools.find(
+      (t) => t.name === "shadowclaw_send_notification",
+    );
+    expect(notifTool.inputSchema.properties).toHaveProperty("clientId");
+  });
+
+  it("processes tools/call for shadowclaw_send_notification directly via broadcastNotification", async () => {
+    const mockClient = {
+      listClients: jest.fn().mockResolvedValue([]),
+      broadcastNotification: jest.fn().mockResolvedValue({
+        sent: 2,
+        failed: 0,
+      }),
+    };
+
+    const engine = createCliMcpEngine({ client: mockClient });
+    const res = await engine.handleMessage({
+      jsonrpc: "2.0",
+      id: 30,
+      method: "tools/call",
+      params: {
+        name: "shadowclaw_send_notification",
+        arguments: { title: "Custom Alert", body: "Server push message" },
+      },
+    });
+
+    expect(res).toBeDefined();
+    expect(res.result.resultType).toBe("complete");
+    expect(res.result.isError).toBe(false);
+    expect(res.result.content[0].text).toContain(
+      "2 recipient(s) delivered, 0 failed",
+    );
+    expect(mockClient.broadcastNotification).toHaveBeenCalledWith({
+      title: "Custom Alert",
+      body: "Server push message",
+    });
+  });
+
+  it("processes tools/call for send_notification alias directly via broadcastNotification", async () => {
+    const mockClient = {
+      listClients: jest.fn().mockResolvedValue([]),
+      broadcastNotification: jest.fn().mockResolvedValue({
+        sent: 1,
+        failed: 0,
+      }),
+    };
+
+    const engine = createCliMcpEngine({ client: mockClient });
+    const res = await engine.handleMessage({
+      jsonrpc: "2.0",
+      id: 31,
+      method: "tools/call",
+      params: {
+        name: "send_notification",
+        arguments: { body: "Fallback push" },
+      },
+    });
+
+    expect(res).toBeDefined();
+    expect(res.result.resultType).toBe("complete");
+    expect(res.result.isError).toBe(false);
+    expect(mockClient.broadcastNotification).toHaveBeenCalledWith({
+      title: "ShadowClaw",
+      body: "Fallback push",
+    });
+  });
+
+  it("handles empty body validation for shadowclaw_send_notification", async () => {
+    const mockClient = {
+      listClients: jest.fn().mockResolvedValue([]),
+      broadcastNotification: jest.fn(),
+    };
+
+    const engine = createCliMcpEngine({ client: mockClient });
+    const res = await engine.handleMessage({
+      jsonrpc: "2.0",
+      id: 32,
+      method: "tools/call",
+      params: {
+        name: "shadowclaw_send_notification",
+        arguments: { body: "" },
+      },
+    });
+
+    expect(res).toBeDefined();
+    expect(res.result.isError).toBe(true);
+    expect(res.result.content[0].text).toContain("cannot be empty");
+    expect(mockClient.broadcastNotification).not.toHaveBeenCalled();
+  });
+
+  it("targets a specific client in shadowclaw_send_notification", async () => {
+    const mockClient = {
+      listClients: jest.fn().mockResolvedValue([]),
+      broadcastNotification: jest.fn().mockResolvedValue({
+        sent: 1,
+        failed: 0,
+      }),
+    };
+
+    const engine = createCliMcpEngine({ client: mockClient });
+    const res = await engine.handleMessage({
+      jsonrpc: "2.0",
+      id: 33,
+      method: "tools/call",
+      params: {
+        name: "shadowclaw_send_notification",
+        arguments: {
+          title: "Direct Alert",
+          body: "Direct push message",
+          clientId: "client-target-99",
+        },
+      },
+    });
+
+    expect(res).toBeDefined();
+    expect(res.result.isError).toBe(false);
+    expect(res.result.content[0].text).toContain(
+      "Push notification sent to client 'client-target-99': 1 recipient(s) delivered, 0 failed.",
+    );
+    expect(mockClient.broadcastNotification).toHaveBeenCalledWith({
+      title: "Direct Alert",
+      body: "Direct push message",
+      clientId: "client-target-99",
+    });
+  });
+
+  it("handles notFound warning when targeted client has no push subscriptions", async () => {
+    const mockClient = {
+      listClients: jest.fn().mockResolvedValue([]),
+      broadcastNotification: jest.fn().mockResolvedValue({
+        sent: 0,
+        failed: 0,
+        notFound: true,
+      }),
+    };
+
+    const engine = createCliMcpEngine({ client: mockClient });
+    const res = await engine.handleMessage({
+      jsonrpc: "2.0",
+      id: 34,
+      method: "tools/call",
+      params: {
+        name: "shadowclaw_send_notification",
+        arguments: {
+          body: "Alert",
+          clientId: "missing-client-id",
+        },
+      },
+    });
+
+    expect(res).toBeDefined();
+    expect(res.result.isError).toBe(false);
+    expect(res.result.content[0].text).toContain(
+      "No push subscriptions found for client 'missing-client-id'",
+    );
   });
 
   it("processes tools/call for shadowclaw_send_message", async () => {

package/bin/utils/control-client.mjs

@@ -271,4 +271,21 @@ export class CliControlClient {
     });
     return data;
   }
+
+  async broadcastNotification({ title = "ShadowClaw", body, clientId } = {}) {
+    const data = await this._request({
+      path: "/push/broadcast",
+      method: "POST",
+      body: {
+        title,
+        body,
+        ...(clientId ? { clientId } : {}),
+      },
+    });
+    return data;
+  }
+
+  async sendNotification(options) {
+    return this.broadcastNotification(options);
+  }
 }

package/bin/utils/control-client.test.mjs

@@ -35,6 +35,10 @@ describe("CliControlClient", () => {
       token,
     });
 
+    app.post("/push/broadcast", (req, res) => {
+      res.json({ sent: 1, failed: 0, received: req.body });
+    });
+
     await new Promise((resolve) => {
       server.listen(0, "127.0.0.1", () => {
         port = server.address().port;
@@ -90,4 +94,46 @@ describe("CliControlClient", () => {
     expect(client2.protocol).toBe("https");
     delete process.env.SHADOWCLAW_HTTPS;
   });
+
+  it("broadcasts push notifications via broadcastNotification", async () => {
+    const client = new CliControlClient({
+      host: "127.0.0.1",
+      port,
+      token,
+    });
+
+    const result = await client.broadcastNotification({
+      title: "Test Title",
+      body: "Test Body",
+    });
+
+    expect(result).toBeDefined();
+    expect(result.sent).toBe(1);
+    expect(result.received).toEqual({
+      title: "Test Title",
+      body: "Test Body",
+    });
+  });
+
+  it("sends targeted push notification with clientId via sendNotification", async () => {
+    const client = new CliControlClient({
+      host: "127.0.0.1",
+      port,
+      token,
+    });
+
+    const result = await client.sendNotification({
+      title: "Targeted Alert",
+      body: "Hello specific client",
+      clientId: "client-target-42",
+    });
+
+    expect(result).toBeDefined();
+    expect(result.sent).toBe(1);
+    expect(result.received).toEqual({
+      title: "Targeted Alert",
+      body: "Hello specific client",
+      clientId: "client-target-42",
+    });
+  });
 });

package/bin/version.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import { readFile, writeFile, stat } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "..");
+
+export const DISALLOWED_KEYWORDS = new Set([
+  "major",
+  "minor",
+  "patch",
+  "premajor",
+  "preminor",
+  "prepatch",
+  "prerelease",
+  "from-git",
+]);
+
+export const USAGE_NOTICE = `
+Usage: npm run version [<newversion>]
+
+Note: Only explicit semantic version strings (e.g. 1.28.0) are supported.
+Keyword commands (major, minor, patch, premajor, preminor, prepatch, prerelease, from-git) are not supported.
+
+Standard npm version syntax for reference:
+  npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]
+`.trim();
+
+export async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function parseSemverString(v) {
+  const clean = String(v || "")
+    .trim()
+    .replace(/^v/, "");
+  const match = clean.match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/,
+  );
+  if (!match) return null;
+  return clean;
+}
+
+export function validateVersionArg(arg) {
+  if (!arg) return null;
+  const lower = arg.toLowerCase().trim();
+  if (lower === "--help" || lower === "-h") {
+    return { isHelp: true };
+  }
+  if (DISALLOWED_KEYWORDS.has(lower)) {
+    return {
+      error: `Error: Keyword command "${arg}" is not supported by npm run version.\n\n${USAGE_NOTICE}`,
+    };
+  }
+  const clean = parseSemverString(arg);
+  if (!clean) {
+    return {
+      error: `Error: Invalid version string "${arg}". Expected a valid semantic version (e.g. 1.28.0).\n\n${USAGE_NOTICE}`,
+    };
+  }
+  return { version: clean };
+}
+
+export async function getVersionMap(targetRoot = rootDir) {
+  const pkg = JSON.parse(
+    await readFile(path.join(targetRoot, "package.json"), "utf8"),
+  );
+  let npmVer = "";
+  try {
+    npmVer = execSync("npm -v", { encoding: "utf8" }).trim();
+  } catch {}
+
+  return {
+    [pkg.name]: pkg.version,
+    ...(npmVer ? { npm: npmVer } : {}),
+    ...process.versions,
+  };
+}
+
+export async function syncWellKnownVersions(newVersion, targetRoot = rootDir) {
+  const filesToSync = [
+    path.join(targetRoot, ".well-known/mcp.json"),
+    path.join(targetRoot, ".well-known/mcp/server-card.json"),
+    path.join(targetRoot, "dist/public/.well-known/mcp.json"),
+    path.join(targetRoot, "dist/public/.well-known/mcp/server-card.json"),
+  ];
+
+  const updatedFiles = [];
+  for (const filePath of filesToSync) {
+    if (await pathExists(filePath)) {
+      try {
+        const content = await readFile(filePath, "utf8");
+        const json = JSON.parse(content);
+        if (json.version !== newVersion) {
+          json.version = newVersion;
+          await writeFile(
+            filePath,
+            JSON.stringify(json, null, 2) + "\n",
+            "utf8",
+          );
+          updatedFiles.push(path.relative(targetRoot, filePath));
+        }
+      } catch (err) {
+        console.warn(`Warning: Could not update version in ${filePath}:`, err);
+      }
+    }
+  }
+  return updatedFiles;
+}
+
+export async function runVersion(args = process.argv.slice(2), options = {}) {
+  const isLifecycle =
+    options.isLifecycle ??
+    (process.env.npm_command === "version" &&
+      process.env.npm_lifecycle_event === "version");
+  const targetRoot = options.rootDir || rootDir;
+  const execOptions = options.execOptions || {
+    cwd: targetRoot,
+    stdio: options.stdio || "inherit",
+  };
+
+  // 1. If running under npm's lifecycle hook (npm version <newver> triggered this script)
+  if (isLifecycle) {
+    const pkg = JSON.parse(
+      await readFile(path.join(targetRoot, "package.json"), "utf8"),
+    );
+    const newVersion = pkg.version;
+    const updated = await syncWellKnownVersions(newVersion, targetRoot);
+    if (
+      updated.length > 0 &&
+      (await pathExists(path.join(targetRoot, ".git")))
+    ) {
+      try {
+        execSync(
+          `git add .well-known/mcp.json .well-known/mcp/server-card.json`,
+          { cwd: targetRoot, stdio: "pipe" },
+        );
+      } catch {}
+    }
+    return { version: newVersion, updated };
+  }
+
+  // 2. Direct CLI invocation
+  const targetArg = args.find((a) => !a.startsWith("--")) || args[0];
+
+  // No arguments passed -> list versions mimicking `npm version`
+  if (!targetArg) {
+    const versionMap = await getVersionMap(targetRoot);
+    if (execOptions.stdio === "inherit") {
+      console.log(versionMap);
+    }
+    return { action: "list", versions: versionMap };
+  }
+
+  const validation = validateVersionArg(targetArg);
+  if (validation.isHelp) {
+    if (execOptions.stdio === "inherit") {
+      console.log(USAGE_NOTICE);
+    }
+    return { action: "help", message: USAGE_NOTICE };
+  }
+
+  if (validation.error) {
+    throw new Error(validation.error);
+  }
+
+  const cleanVersion = validation.version;
+
+  // Run npm version --no-git-tag-version --allow-same-version --ignore-scripts
+  execSync(
+    `npm version ${cleanVersion} --no-git-tag-version --allow-same-version --ignore-scripts`,
+    execOptions,
+  );
+
+  // Sync .well-known JSON discovery files
+  const updated = await syncWellKnownVersions(cleanVersion, targetRoot);
+
+  if (execOptions.stdio === "inherit") {
+    console.log(`v${cleanVersion}`);
+    if (updated.length > 0) {
+      console.log(
+        `Updated .well-known discovery versions: ${updated.join(", ")}`,
+      );
+    }
+  }
+
+  return { version: cleanVersion, updated };
+}
+
+const isMainModule =
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isMainModule) {
+  runVersion().catch((err) => {
+    console.error(`\n${err.message}\n`);
+    process.exit(1);
+  });
+}