shadow-claw 1.27.0 → 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/commands/skills-index.mjs

@@ -8,8 +8,12 @@ import crypto from "node:crypto";
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 import matter from "gray-matter";
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
 /**
  * Computes a standardized sha256:{hex} digest from Buffer or string.
  */
@@ -64,30 +68,86 @@ export async function generateSkillsIndex(
   const wellKnownDirRel = options.outDir || ".well-known/agent-skills";
 
   // 1. Read metadata from shadow-claw.config.json or package.json
-  let siteName = path.basename(resolvedRoot);
-  let siteDescription =
-    "Agent skills and tools collection, powered by ShadowClaw.";
-
-  const configPath = path.join(resolvedRoot, "shadow-claw.config.json");
-  if (await pathExists(configPath)) {
-    try {
-      const configStr = await readFile(configPath, "utf8");
-      const config = JSON.parse(configStr);
-      if (config.site?.title) siteName = config.site.title;
-      if (config.site?.description) siteDescription = config.site.description;
-    } catch {}
-  } else {
-    const pkgPath = path.join(resolvedRoot, "package.json");
-    if (await pathExists(pkgPath)) {
+  const metadataRoot = options.metadataRoot
+    ? path.resolve(options.metadataRoot)
+    : resolvedRoot;
+
+  let siteName = options.siteName;
+  let siteDescription = options.siteDescription;
+
+  const parent1 = path.dirname(metadataRoot);
+  const parent2 = path.dirname(parent1);
+
+  const configCandidates = [
+    options.configPath,
+    path.join(metadataRoot, "shadow-claw.config.json"),
+    path.join(metadataRoot, "shadow-claw-config.json"),
+    path.join(metadataRoot, "site-config.json"),
+    path.join(parent1, "shadow-claw.config.json"),
+    path.join(parent1, "shadow-claw-config.json"),
+    path.join(parent1, "site-config.json"),
+    path.join(parent2, "shadow-claw.config.json"),
+    path.join(parent2, "shadow-claw-config.json"),
+    path.join(parent2, "site-config.json"),
+  ].filter(Boolean);
+
+  let loadedConfig = null;
+  for (const candidate of configCandidates) {
+    if (await pathExists(candidate)) {
       try {
-        const pkgStr = await readFile(pkgPath, "utf8");
-        const pkg = JSON.parse(pkgStr);
-        if (pkg.name) siteName = pkg.name;
-        if (pkg.description) siteDescription = pkg.description;
+        const configStr = await readFile(candidate, "utf8");
+        loadedConfig = JSON.parse(configStr);
+        break;
       } catch {}
     }
   }
 
+  if (loadedConfig) {
+    if (!siteName && loadedConfig.site?.title)
+      siteName = loadedConfig.site.title;
+    if (!siteDescription && loadedConfig.site?.description) {
+      siteDescription = loadedConfig.site.description;
+    }
+  }
+
+  if (!siteName || !siteDescription) {
+    const pkgCandidates = [
+      path.join(metadataRoot, "package.json"),
+      path.join(parent1, "package.json"),
+      path.join(parent2, "package.json"),
+    ];
+    for (const pkgPath of pkgCandidates) {
+      if (await pathExists(pkgPath)) {
+        try {
+          const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+          if (!siteName && pkg.name) siteName = pkg.name;
+          if (!siteDescription && pkg.description) {
+            siteDescription = pkg.description;
+          }
+          break;
+        } catch {}
+      }
+    }
+  }
+
+  if (!siteName) {
+    siteName = path.basename(metadataRoot);
+    if (siteName === "public" || siteName === "dist") {
+      siteName = path.basename(parent1);
+      if (
+        (siteName === "public" || siteName === "dist") &&
+        path.basename(parent2)
+      ) {
+        siteName = path.basename(parent2);
+      }
+    }
+  }
+
+  if (!siteDescription) {
+    siteDescription =
+      "Agent skills and tools collection, powered by ShadowClaw.";
+  }
+
   // 2. Discover Tools (.agents/tools/**/*.json)
   const toolsDir = path.join(resolvedRoot, ".agents", "tools");
   const toolFiles = await findFilesRecursively(toolsDir, (name) =>
@@ -249,6 +309,61 @@ export async function generateSkillsIndex(
     });
   }
 
+  // 4b. Discover Bundled Skills from Toolchain (if requested or enabled)
+  const defaultToolchainRoot = path.resolve(__dirname, "../..");
+  const bundledSkillsDir = options.bundledSkillsDir
+    ? path.resolve(options.bundledSkillsDir)
+    : options.toolchainRoot
+      ? path.join(path.resolve(options.toolchainRoot), ".agents", "skills")
+      : options.includeBundled
+        ? path.join(defaultToolchainRoot, ".agents", "skills")
+        : null;
+
+  if (
+    bundledSkillsDir &&
+    (await pathExists(bundledSkillsDir)) &&
+    bundledSkillsDir !== skillsDir
+  ) {
+    const bundledSkillFiles = await findFilesRecursively(
+      bundledSkillsDir,
+      (name) => name === "SKILL.md",
+    );
+    for (const fullSkillPath of bundledSkillFiles) {
+      const relFromBundled = path.relative(bundledSkillsDir, fullSkillPath);
+      const relFromRoot = path.join(".agents", "skills", relFromBundled);
+      const relUrl = path.posix.normalize(
+        path.posix.relative(
+          wellKnownDirRel,
+          relFromRoot.split(path.sep).join(path.posix.sep),
+        ),
+      );
+      const rawContent = await readFile(fullSkillPath);
+      const digest = computeSha256(rawContent);
+
+      let frontmatter = {};
+      try {
+        const parsed = matter(rawContent.toString("utf8"));
+        frontmatter = parsed.data || {};
+      } catch {}
+
+      const parentDirName = path.basename(path.dirname(fullSkillPath));
+      const skillName = frontmatter.name || parentDirName;
+      const skillDesc = frontmatter.description || "";
+
+      if (discoveredSkills.some((s) => s.name === skillName)) {
+        continue;
+      }
+
+      discoveredSkills.push({
+        name: skillName,
+        type: "skill-md",
+        description: skillDesc,
+        url: relUrl,
+        digest,
+      });
+    }
+  }
+
   // 5. Construct Index Document
   const indexDoc = {
     $schema: "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
@@ -319,7 +434,11 @@ export async function runSkillsIndexCommand(dir, options = {}) {
   const targetDir = dir ? path.resolve(dir) : process.cwd();
   console.log(`Generating Agent Skills Discovery index for ${targetDir}...`);
 
-  const result = await generateSkillsIndex(targetDir, options);
+  const result = await generateSkillsIndex(targetDir, {
+    includeBundled: options.bundled !== false,
+    ...options,
+    configPath: options.config || options.configPath,
+  });
   const count = result.skills ? result.skills.length : 0;
   console.log(
     `Indexed ${count} skill(s) into .well-known/agent-skills/index.json`,

package/bin/commands/skills-index.test.mjs

@@ -158,4 +158,86 @@ metadata:
     await generateSkillsIndex(tempDir, { outFile: customOut });
     expect(fs.existsSync(customOut)).toBe(true);
   });
+
+  it("resolves site metadata from parent directory when indexing a subfolder like dist/public", async () => {
+    await writeFile(
+      path.join(tempDir, "shadow-claw.config.json"),
+      JSON.stringify({
+        site: {
+          title: "My Custom Knowledge Hub",
+          description: "A custom description for testing metadata resolution.",
+        },
+      }),
+      "utf8",
+    );
+
+    const distPublicDir = path.join(tempDir, "dist", "public");
+    const skillDir = path.join(
+      distPublicDir,
+      ".agents",
+      "skills",
+      "main",
+      "custom",
+    );
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(
+      path.join(skillDir, "SKILL.md"),
+      "---\nname: custom\ndescription: Custom skill.\n---\n",
+      "utf8",
+    );
+
+    const res = await generateSkillsIndex(distPublicDir, { write: false });
+    expect(res.name).toBe("My Custom Knowledge Hub");
+    expect(res.description).toBe(
+      "A custom description for testing metadata resolution.",
+    );
+    expect(res.skills).toHaveLength(1);
+    expect(res.skills[0].name).toBe("custom");
+    expect(res.skills[0].url).toBe("../../.agents/skills/main/custom/SKILL.md");
+  });
+
+  it("discovers bundled skills when toolchainRoot is provided and merges them without duplicates", async () => {
+    const mockToolchain = path.join(tempDir, "toolchain");
+    const bundledSkillDir = path.join(
+      mockToolchain,
+      ".agents",
+      "skills",
+      "main",
+      "skill-creator",
+    );
+    await mkdir(bundledSkillDir, { recursive: true });
+    await writeFile(
+      path.join(bundledSkillDir, "SKILL.md"),
+      "---\nname: skill-creator\ndescription: Bundled skill creator.\n---\n",
+      "utf8",
+    );
+
+    const mockContent = path.join(tempDir, "content");
+    const contentSkillDir = path.join(
+      mockContent,
+      ".agents",
+      "skills",
+      "main",
+      "my-skill",
+    );
+    await mkdir(contentSkillDir, { recursive: true });
+    await writeFile(
+      path.join(contentSkillDir, "SKILL.md"),
+      "---\nname: my-skill\ndescription: Custom skill.\n---\n",
+      "utf8",
+    );
+
+    const res = await generateSkillsIndex(mockContent, {
+      toolchainRoot: mockToolchain,
+      write: false,
+    });
+    expect(res.skills).toHaveLength(2);
+    expect(res.skills.map((s) => s.name)).toEqual(
+      expect.arrayContaining(["my-skill", "skill-creator"]),
+    );
+    const creatorSkill = res.skills.find((s) => s.name === "skill-creator");
+    expect(creatorSkill.url).toBe(
+      "../../.agents/skills/main/skill-creator/SKILL.md",
+    );
+  });
 });