shadow-claw 1.23.4 → 1.24.1

package/src/subsystems/skills/discoverSkills.test.ts

@@ -0,0 +1,251 @@
+import { jest } from "@jest/globals";
+
+const mockGetGroupDir = jest.fn() as any;
+const mockReadGroupFile = jest.fn() as any;
+
+jest.unstable_mockModule("../../storage/getGroupDir.js", () => ({
+  getGroupDir: mockGetGroupDir,
+}));
+
+jest.unstable_mockModule("../../storage/readGroupFile.js", () => ({
+  readGroupFile: mockReadGroupFile,
+}));
+
+const { discoverSkills, loadSkill } = await import("./discoverSkills.js");
+const { DEFAULT_GROUP_ID } = await import("../../config/config.js");
+
+function createMockDirectoryHandle(
+  name: string,
+  children: Record<string, any> = {},
+) {
+  return {
+    kind: "directory",
+    name,
+    getDirectoryHandle: jest.fn(async (childName: string) => {
+      const child = children[childName];
+      if (!child || child.kind !== "directory") {
+        throw new Error(`Directory not found: ${childName}`);
+      }
+      return child;
+    }),
+    entries: async function* () {
+      for (const [childName, child] of Object.entries(children)) {
+        yield [childName, child];
+      }
+    },
+  };
+}
+
+function createMockFileHandle(name: string) {
+  return {
+    kind: "file",
+    name,
+  };
+}
+
+describe("discoverSkills and loadSkill", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("returns empty results when .agents or .agents/skills does not exist", async () => {
+    const root = createMockDirectoryHandle("root", {});
+    mockGetGroupDir.mockResolvedValue(root);
+
+    const result = await discoverSkills({} as any, DEFAULT_GROUP_ID);
+    expect(result.skills).toEqual([]);
+    expect(result.diagnostics).toEqual([]);
+  });
+
+  it("discovers skills from .agents/skills directory hierarchy", async () => {
+    const skillA = createMockDirectoryHandle("skill-a", {
+      "SKILL.md": createMockFileHandle("SKILL.md"),
+    });
+    const skillsDir = createMockDirectoryHandle("skills", {
+      "skill-a": skillA,
+    });
+    const agentsDir = createMockDirectoryHandle(".agents", {
+      skills: skillsDir,
+    });
+    const root = createMockDirectoryHandle("root", {
+      ".agents": agentsDir,
+    });
+
+    mockGetGroupDir.mockResolvedValue(root);
+    mockReadGroupFile.mockResolvedValue(`---
+name: skill-a
+description: First test skill
+---
+# Skill A Content
+`);
+
+    const result = await discoverSkills({} as any, DEFAULT_GROUP_ID);
+    expect(result.skills).toHaveLength(1);
+    expect(result.skills[0].name).toBe("skill-a");
+    expect(result.skills[0].description).toBe("First test skill");
+    expect(result.skills[0].path).toBe(".agents/skills/skill-a/SKILL.md");
+    expect(result.diagnostics).toEqual([]);
+  });
+
+  it("records diagnostic when duplicate skill names exist in current group", async () => {
+    const skillA1 = createMockDirectoryHandle("skill-a1", {
+      "SKILL.md": createMockFileHandle("SKILL.md"),
+    });
+    const skillA2 = createMockDirectoryHandle("skill-a2", {
+      "SKILL.md": createMockFileHandle("SKILL.md"),
+    });
+    const skillsDir = createMockDirectoryHandle("skills", {
+      "skill-a1": skillA1,
+      "skill-a2": skillA2,
+    });
+    const agentsDir = createMockDirectoryHandle(".agents", {
+      skills: skillsDir,
+    });
+    const root = createMockDirectoryHandle("root", {
+      ".agents": agentsDir,
+    });
+
+    mockGetGroupDir.mockResolvedValue(root);
+    // Both return the same name "duplicate-skill"
+    mockReadGroupFile.mockResolvedValue(`---
+name: duplicate-skill
+description: Dup skill
+---
+Body
+`);
+
+    const result = await discoverSkills({} as any, DEFAULT_GROUP_ID);
+    expect(result.skills).toHaveLength(1);
+    expect(result.diagnostics).toHaveLength(1);
+    expect(result.diagnostics[0].message).toContain(
+      "Duplicate skill name: duplicate-skill",
+    );
+  });
+
+  it("records diagnostic when skill parsing fails (invalid frontmatter)", async () => {
+    const brokenSkill = createMockDirectoryHandle("broken", {
+      "SKILL.md": createMockFileHandle("SKILL.md"),
+    });
+    const skillsDir = createMockDirectoryHandle("skills", {
+      broken: brokenSkill,
+    });
+    const agentsDir = createMockDirectoryHandle(".agents", {
+      skills: skillsDir,
+    });
+    const root = createMockDirectoryHandle("root", {
+      ".agents": agentsDir,
+    });
+
+    mockGetGroupDir.mockResolvedValue(root);
+    mockReadGroupFile.mockResolvedValue(`invalid content without frontmatter`);
+
+    const result = await discoverSkills({} as any, DEFAULT_GROUP_ID);
+    expect(result.skills).toHaveLength(0);
+    expect(result.diagnostics).toHaveLength(1);
+    expect(result.diagnostics[0].message).toBeTruthy();
+  });
+
+  it("stops and adds diagnostic when visited directories exceeds limit", async () => {
+    const deepChildren: Record<string, any> = {};
+    for (let i = 0; i <= 2001; i++) {
+      deepChildren[`dir_${i}`] = createMockDirectoryHandle(`dir_${i}`, {});
+    }
+
+    const skillsDir = createMockDirectoryHandle("skills", deepChildren);
+    const agentsDir = createMockDirectoryHandle(".agents", {
+      skills: skillsDir,
+    });
+    const root = createMockDirectoryHandle("root", {
+      ".agents": agentsDir,
+    });
+
+    mockGetGroupDir.mockResolvedValue(root);
+
+    const result = await discoverSkills({} as any, DEFAULT_GROUP_ID);
+    expect(
+      result.diagnostics.some((d) =>
+        d.message.includes("stopped after 2000 directories"),
+      ),
+    ).toBe(true);
+  });
+
+  it("scans custom group first then fallback main group", async () => {
+    const rootCustom = createMockDirectoryHandle("rootCustom", {});
+    const skillDefault = createMockDirectoryHandle("default-skill", {
+      "SKILL.md": createMockFileHandle("SKILL.md"),
+    });
+    const skillsDir = createMockDirectoryHandle("skills", {
+      "default-skill": skillDefault,
+    });
+    const agentsDir = createMockDirectoryHandle(".agents", {
+      skills: skillsDir,
+    });
+    const rootDefault = createMockDirectoryHandle("rootDefault", {
+      ".agents": agentsDir,
+    });
+
+    mockGetGroupDir.mockImplementation(async (_db: any, gId: string) => {
+      if (gId === "custom-group") return rootCustom;
+      return rootDefault;
+    });
+
+    mockReadGroupFile.mockResolvedValue(`---
+name: default-skill
+description: Default fallback
+---
+Body
+`);
+
+    const result = await discoverSkills({} as any, "custom-group");
+    expect(result.skills).toHaveLength(1);
+    expect(result.skills[0].name).toBe("default-skill");
+  });
+
+  describe("loadSkill", () => {
+    it("returns null if skill is not found", async () => {
+      const root = createMockDirectoryHandle("root", {});
+      mockGetGroupDir.mockResolvedValue(root);
+
+      const skill = await loadSkill({} as any, DEFAULT_GROUP_ID, "nonexistent");
+      expect(skill).toBeNull();
+    });
+
+    it("loads and refreshes skill with resources", async () => {
+      const helperFile = createMockFileHandle("helper.py");
+      const subFolder = createMockDirectoryHandle("scripts", {
+        "run.sh": createMockFileHandle("run.sh"),
+      });
+      const skillDir = createMockDirectoryHandle("my-skill", {
+        "SKILL.md": createMockFileHandle("SKILL.md"),
+        "helper.py": helperFile,
+        scripts: subFolder,
+      });
+      const skillsDir = createMockDirectoryHandle("skills", {
+        "my-skill": skillDir,
+      });
+      const agentsDir = createMockDirectoryHandle(".agents", {
+        skills: skillsDir,
+      });
+      const root = createMockDirectoryHandle("root", {
+        ".agents": agentsDir,
+      });
+
+      mockGetGroupDir.mockResolvedValue(root);
+      mockReadGroupFile.mockResolvedValue(`---
+name: my-skill
+description: Full loaded skill
+---
+Loaded body instructions
+`);
+
+      const loaded = await loadSkill({} as any, DEFAULT_GROUP_ID, "my-skill");
+      expect(loaded).not.toBeNull();
+      expect(loaded?.name).toBe("my-skill");
+      expect(loaded?.body).toBe("Loaded body instructions");
+      expect(loaded?.resources).toEqual([
+        ".agents/skills/my-skill/helper.py",
+        ".agents/skills/my-skill/scripts/run.sh",
+      ]);
+    });
+  });
+});

package/src/subsystems/tools/cron.test.ts

@@ -0,0 +1,64 @@
+import { matchesCron } from "./cron.js";
+
+describe("matchesCron", () => {
+  it("returns false for invalid or non-5-part expressions", () => {
+    expect(matchesCron("", new Date())).toBe(false);
+    expect(matchesCron(null as any, new Date())).toBe(false);
+    expect(matchesCron("* * *", new Date())).toBe(false);
+    expect(matchesCron("* * * * * *", new Date())).toBe(false);
+  });
+
+  it("matches wildcard expression", () => {
+    expect(matchesCron("* * * * *", new Date())).toBe(true);
+  });
+
+  it("matches exact numbers", () => {
+    // 2026-08-30 14:15:00, Sunday (day 0), August (month 8), day of month 30
+    const testDate = new Date(2026, 7, 30, 14, 15, 0); // Month is 0-indexed in JS Date: 7 = August
+
+    expect(matchesCron("15 14 30 8 0", testDate)).toBe(true);
+    expect(matchesCron("16 14 30 8 0", testDate)).toBe(false);
+  });
+
+  it("matches lists of numbers", () => {
+    const testDate = new Date(2026, 7, 30, 14, 15, 0);
+
+    expect(matchesCron("10,15,20 * * * *", testDate)).toBe(true);
+    expect(matchesCron("10,20,30 * * * *", testDate)).toBe(false);
+  });
+
+  it("matches ranges (N-M)", () => {
+    const testDate = new Date(2026, 7, 30, 14, 15, 0);
+
+    expect(matchesCron("10-20 * * * *", testDate)).toBe(true);
+    expect(matchesCron("20-30 * * * *", testDate)).toBe(false);
+  });
+
+  it("matches steps (*/N)", () => {
+    const testDate = new Date(2026, 7, 30, 14, 15, 0);
+
+    expect(matchesCron("*/5 * * * *", testDate)).toBe(true);
+    expect(matchesCron("*/7 * * * *", testDate)).toBe(false);
+  });
+
+  it("matches range with step (N-M/S)", () => {
+    const testDate = new Date(2026, 7, 30, 14, 15, 0);
+
+    expect(matchesCron("10-20/5 * * * *", testDate)).toBe(true); // 10, 15, 20 -> 15 matches
+    expect(matchesCron("10-20/4 * * * *", testDate)).toBe(false); // 10, 14, 18
+  });
+
+  it("matches start with step (N/S)", () => {
+    const testDate = new Date(2026, 7, 30, 14, 15, 0);
+
+    expect(matchesCron("5/10 * * * *", testDate)).toBe(true); // 5, 15, 25... -> 15 matches
+    expect(matchesCron("6/10 * * * *", testDate)).toBe(false);
+  });
+
+  it("handles invalid step strings", () => {
+    const testDate = new Date(2026, 7, 30, 14, 15, 0);
+
+    expect(matchesCron("*/0 * * * *", testDate)).toBe(false);
+    expect(matchesCron("*/abc * * * *", testDate)).toBe(false);
+  });
+});

package/src/subsystems/tools/declarative.test.ts

@@ -1,11 +1,45 @@
-import { describe, expect, it } from "@jest/globals";
+import { describe, expect, it, jest, beforeEach } from "@jest/globals";
 
-import { parseDeclarativeTool } from "./declarative.js";
+jest.unstable_mockModule("../../db/getConfig.js", () => ({
+  getConfig: jest.fn(),
+}));
 
-describe("parseDeclarativeTool", () => {
-  it("parses a sandboxed javascript tool definition", () => {
-    expect(
-      parseDeclarativeTool(".agents/tools/main/echo.json", {
+jest.unstable_mockModule("../../storage/getGroupDir.js", () => ({
+  getGroupDir: jest.fn(),
+}));
+
+jest.unstable_mockModule("../../storage/readGroupFile.js", () => ({
+  readGroupFile: jest.fn(),
+}));
+
+const { parseDeclarativeTool, loadDeclarativeTools, findDeclarativeTool } =
+  await import("./declarative.js");
+const { getConfig } = await import("../../db/getConfig.js");
+const { getGroupDir } = await import("../../storage/getGroupDir.js");
+const { readGroupFile } = await import("../../storage/readGroupFile.js");
+
+describe("declarative tools", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe("parseDeclarativeTool", () => {
+    it("parses a sandboxed javascript tool definition", () => {
+      expect(
+        parseDeclarativeTool(".agents/tools/main/echo.json", {
+          name: "echo",
+          description: "Echo structured input.",
+          input_schema: {
+            type: "object",
+            properties: { value: { type: "string" } },
+            required: ["value"],
+          },
+          execution: {
+            type: "javascript",
+            code: "return JSON.parse(data).value;",
+          },
+        }),
+      ).toEqual({
         name: "echo",
         description: "Echo structured input.",
         input_schema: {
@@ -17,101 +51,233 @@ describe("parseDeclarativeTool", () => {
           type: "javascript",
           code: "return JSON.parse(data).value;",
         },
-      }),
-    ).toEqual({
-      name: "echo",
-      description: "Echo structured input.",
-      input_schema: {
-        type: "object",
-        properties: { value: { type: "string" } },
-        required: ["value"],
-      },
-      execution: {
-        type: "javascript",
-        code: "return JSON.parse(data).value;",
-      },
-      path: ".agents/tools/main/echo.json",
+        path: ".agents/tools/main/echo.json",
+      });
     });
-  });
 
-  it("rejects tools without a sandbox execution recipe", () => {
-    expect(() =>
-      parseDeclarativeTool(".agents/tools/main/echo.json", {
-        name: "echo",
-        description: "Echo structured input.",
+    it("parses a bash tool definition", () => {
+      const tool = parseDeclarativeTool(".agents/tools/main/run_sh.json", {
+        name: "run_sh",
+        description: "Run bash command.",
         input_schema: { type: "object" },
-      }),
-    ).toThrow("execution");
-  });
+        execution: {
+          type: "bash",
+          command: "echo hello",
+        },
+      });
 
-  it("parses a tool executor that delegates to an existing tool", () => {
-    expect(
-      parseDeclarativeTool(".agents/tools/main/repo_status.json", {
+      expect(tool.execution).toEqual({
+        type: "bash",
+        command: "echo hello",
+      });
+    });
+
+    it("parses a tool executor that delegates to an existing tool with inputs", () => {
+      const tool = parseDeclarativeTool(".agents/tools/main/repo_status.json", {
         name: "repo_status",
         description: "Show repository status.",
         input_schema: { type: "object" },
-        execution: { type: "tool", name: "git_status" },
-      }).execution,
-    ).toEqual({ type: "tool", name: "git_status" });
+        execution: {
+          type: "tool",
+          name: "git_status",
+          input: { verbose: true },
+        },
+      });
+
+      expect(tool.execution).toEqual({
+        type: "tool",
+        name: "git_status",
+        input: { verbose: true },
+      });
+    });
+
+    it("rejects invalid value shapes", () => {
+      expect(() => parseDeclarativeTool("test.json", null)).toThrow(
+        "must be a JSON object",
+      );
+      expect(() => parseDeclarativeTool("test.json", "string")).toThrow(
+        "must be a JSON object",
+      );
+    });
+
+    it("rejects invalid tool names", () => {
+      expect(() =>
+        parseDeclarativeTool("test.json", {
+          name: "Invalid-Name!",
+          description: "desc",
+          input_schema: {},
+          execution: {},
+        }),
+      ).toThrow("Tool name is invalid");
+
+      expect(() =>
+        parseDeclarativeTool("test.json", {
+          name: "",
+          description: "desc",
+          input_schema: {},
+          execution: {},
+        }),
+      ).toThrow("Tool name is invalid");
+    });
+
+    it("rejects missing description or input schema", () => {
+      expect(() =>
+        parseDeclarativeTool("test.json", {
+          name: "valid_name",
+          description: "",
+          input_schema: {},
+          execution: {},
+        }),
+      ).toThrow("requires a description");
+
+      expect(() =>
+        parseDeclarativeTool("test.json", {
+          name: "valid_name",
+          description: "desc",
+          input_schema: null,
+          execution: {},
+        }),
+      ).toThrow("requires input_schema");
+    });
+
+    it("rejects invalid execution specifications", () => {
+      expect(() =>
+        parseDeclarativeTool("test.json", {
+          name: "valid_name",
+          description: "desc",
+          input_schema: { type: "object" },
+          execution: null,
+        }),
+      ).toThrow("requires execution");
+
+      expect(() =>
+        parseDeclarativeTool("test.json", {
+          name: "valid_name",
+          description: "desc",
+          input_schema: { type: "object" },
+          execution: { type: "unsupported" },
+        }),
+      ).toThrow("execution type must be bash, javascript, or tool");
+
+      expect(() =>
+        parseDeclarativeTool("test.json", {
+          name: "valid_name",
+          description: "desc",
+          input_schema: { type: "object" },
+          execution: { type: "tool", name: "INVALID-DELEGATE!" },
+        }),
+      ).toThrow("execution requires a valid tool name");
+
+      expect(() =>
+        parseDeclarativeTool("test.json", {
+          name: "valid_name",
+          description: "desc",
+          input_schema: { type: "object" },
+          execution: { type: "bash", command: "   " },
+        }),
+      ).toThrow("execution requires command");
+    });
   });
 
-  it("parses generate_random_number declarative tool definition", () => {
-    const raw = {
-      name: "generate_random_number",
-      description:
-        "Generate a random integer within a specified range (min through max, inclusive).",
-      input_schema: {
-        type: "object",
-        properties: {
-          min: { type: "number", description: "Minimum integer value" },
-          max: { type: "number", description: "Maximum integer value" },
+  describe("loadDeclarativeTools & findDeclarativeTool", () => {
+    it("loads declarative tools from directory tree", async () => {
+      const mockFileHandle = { kind: "file" };
+      const mockToolsDir = {
+        entries: async function* () {
+          yield ["calc.json", mockFileHandle];
+          yield ["invalid.json", mockFileHandle];
+        },
+      };
+      const mockAgentsDir = {
+        getDirectoryHandle: jest.fn().mockImplementation(async (name) => {
+          if (name === "tools") return mockToolsDir;
+          throw new Error("Not found");
+        }),
+      };
+      const mockRoot = {
+        getDirectoryHandle: jest.fn().mockImplementation(async (name) => {
+          if (name === ".agents") return mockAgentsDir;
+          throw new Error("Not found");
+        }),
+      };
+
+      (getGroupDir as jest.Mock<any>).mockResolvedValue(mockRoot);
+      (readGroupFile as jest.Mock<any>).mockImplementation(
+        async (_db: any, _gid: any, path: any) => {
+          if (path === ".agents/tools/calc.json") {
+            return JSON.stringify({
+              name: "calc",
+              description: "Calculate value",
+              input_schema: { type: "object" },
+              execution: { type: "javascript", code: "return 1;" },
+            });
+          }
+          return "{ invalid json }";
         },
-      },
-      execution: {
-        type: "javascript",
-        code: "const input = data ? JSON.parse(data) : {}; const min = typeof input.min === 'number' ? input.min : 1; const max = typeof input.max === 'number' ? input.max : 1000000; return Math.floor(Math.random() * (max - min + 1)) + min;",
-      },
-    };
-
-    expect(
-      parseDeclarativeTool(
-        ".agents/tools/main/generate_random_number.json",
-        raw,
-      ),
-    ).toEqual({
-      ...raw,
-      path: ".agents/tools/main/generate_random_number.json",
+      );
+
+      const { tools, diagnostics } = await loadDeclarativeTools({} as any);
+      expect(tools).toHaveLength(1);
+      expect(tools[0].name).toBe("calc");
+      expect(diagnostics).toHaveLength(1);
     });
-  });
 
-  it("parses tools using parameters and evaluation expression aliases", () => {
-    const raw = {
-      name: "calculate_ore_depth",
-      description: "Calculates ore depth.",
-      parameters: {
-        type: "object",
-        properties: { y: { type: "number" } },
-      },
-      evaluation: {
-        type: "javascript",
-        expression: "return { y: data ? JSON.parse(data).y : 0 };",
-      },
-    };
-
-    expect(
-      parseDeclarativeTool(".agents/tools/main/calculate_ore_depth.json", raw),
-    ).toEqual({
-      name: "calculate_ore_depth",
-      description: "Calculates ore depth.",
-      input_schema: {
-        type: "object",
-        properties: { y: { type: "number" } },
-      },
-      execution: {
-        type: "javascript",
-        code: "return { y: data ? JSON.parse(data).y : 0 };",
-      },
-      path: ".agents/tools/main/calculate_ore_depth.json",
+    it("returns empty tools when agents directory does not exist", async () => {
+      (getGroupDir as jest.Mock<any>).mockResolvedValue({
+        getDirectoryHandle: (jest.fn() as any).mockRejectedValue(
+          new Error("No .agents dir"),
+        ),
+      });
+
+      const { tools, diagnostics } = await loadDeclarativeTools({} as any);
+      expect(tools).toEqual([]);
+      expect(diagnostics).toEqual([]);
+    });
+
+    it("finds declarative tool by name when enabled", async () => {
+      const mockFileHandle = { kind: "file" };
+      const mockToolsDir = {
+        entries: async function* () {
+          yield ["my_tool.json", mockFileHandle];
+        },
+      };
+      const mockAgentsDir = {
+        getDirectoryHandle: (jest.fn() as any).mockResolvedValue(mockToolsDir),
+      };
+      const mockRoot = {
+        getDirectoryHandle: (jest.fn() as any).mockResolvedValue(mockAgentsDir),
+      };
+
+      (getGroupDir as jest.Mock<any>).mockResolvedValue(mockRoot);
+      (readGroupFile as jest.Mock<any>).mockResolvedValue(
+        JSON.stringify({
+          name: "my_tool",
+          description: "My custom tool",
+          input_schema: { type: "object" },
+          execution: { type: "javascript", code: "return true;" },
+        }),
+      );
+      (getConfig as jest.Mock<any>).mockResolvedValue(["my_tool"]);
+
+      const tool = await findDeclarativeTool({} as any, "main", "my_tool");
+      expect(tool?.name).toBe("my_tool");
+
+      // When tool is not in enabled list
+      (getConfig as jest.Mock<any>).mockResolvedValue(["other_tool"]);
+      const disabledTool = await findDeclarativeTool(
+        {} as any,
+        "main",
+        "my_tool",
+      );
+      expect(disabledTool).toBeNull();
+
+      // When searching for non-existent tool
+      const missing = await findDeclarativeTool(
+        {} as any,
+        "main",
+        "non_existent",
+      );
+      expect(missing).toBeNull();
     });
   });
 });