@vellumai/assistant 0.6.3 → 0.6.4

package/src/__tests__/skills-files-catalog-fallback.test.ts

@@ -1,21 +1,24 @@
 /**
- * Tests for `getSkillFiles` catalog fallback.
+ * Tests for `getSkillFiles` provider chain fallback.
  *
  * When a skill id isn't resolvable via `findSkillById` (i.e. not installed
  * locally, not bundled, not a managed skill), `getSkillFiles` falls back to
- * the Vellum catalog via `readCatalogSkillFiles`. Catalog fallback entries
- * carry `content: null` because the catalog-files helper defers content
- * fetching to a follow-up per-file endpoint. When a skill IS resolved by
+ * the provider chain (vellum catalog → skills.sh → clawhub). Each provider
+ * is tried in order until one returns data. When a skill IS resolved by
  * `findSkillById` but its on-disk directory is missing, `getSkillFiles`
- * returns a 404 without falling through to the catalog so the listing and
- * detail responses agree on `isInstalled`.
+ * returns a 404 without falling through to the provider chain so the
+ * listing and detail responses agree on `isInstalled`.
  *
  * Coverage:
  *   - Uninstalled catalog skill: returns `{ skill: catalog/vellum/available, files }` with `content: null` for every entry.
- *   - Neither installed nor in catalog: returns 404.
+ *   - Neither installed nor handled by any provider: returns 404.
  *   - Installed skill: preserves the disk-read behavior with inline `content`.
- *   - Installed skill with missing directory: returns 404 without consulting the catalog.
+ *   - Installed skill with missing directory: returns 404 without consulting providers.
  *   - `catalogSkillToSlim` mapping: `metadata.vellum["display-name"]` wins over `cs.name`.
+ *   - skills.sh-shaped ID not in vellum catalog returns files from skills.sh provider.
+ *   - clawhub-shaped ID not in vellum catalog returns files from clawhub provider.
+ *   - ID that no provider handles returns 404.
+ *   - Provider priority: vellum provider is tried before skills.sh/clawhub.
  */
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
@@ -24,8 +27,9 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import type { SkillSummary } from "../config/skills.js";
+import type { SlimSkillResponse } from "../daemon/message-types/skills.js";
 import type { SkillFileEntry } from "../skills/catalog-files.js";
-import type { CatalogSkill } from "../skills/catalog-install.js";
+import type { SkillFileProvider } from "../skills/skill-file-provider.js";
 
 // ---------------------------------------------------------------------------
 // Mock state — mutated by individual tests via reset helpers below
@@ -37,9 +41,45 @@ type ResolvedSkillEntry = {
 };
 
 let mockResolvedStates: ResolvedSkillEntry[] = [];
-let mockCatalog: CatalogSkill[] = [];
-let mockCatalogFiles: SkillFileEntry[] | null = null;
-const catalogFilesCalls: string[] = [];
+
+// Per-provider mock state
+let mockVellumProvider: SkillFileProvider;
+let mockSkillsshProvider: SkillFileProvider;
+let mockClawhubProvider: SkillFileProvider;
+
+// Track which providers were consulted
+const providerCalls: Array<{
+  provider: string;
+  method: string;
+  skillId: string;
+}> = [];
+
+function makeNoopProvider(name: string): SkillFileProvider {
+  return {
+    canHandle(_skillId: string): boolean {
+      return false;
+    },
+    async listFiles(skillId: string): Promise<SkillFileEntry[] | null> {
+      providerCalls.push({ provider: name, method: "listFiles", skillId });
+      return null;
+    },
+    async readFileContent(
+      skillId: string,
+      _path: string,
+    ): Promise<SkillFileEntry | null> {
+      providerCalls.push({
+        provider: name,
+        method: "readFileContent",
+        skillId,
+      });
+      return null;
+    },
+    async toSlimSkill(skillId: string): Promise<SlimSkillResponse | null> {
+      providerCalls.push({ provider: name, method: "toSlimSkill", skillId });
+      return null;
+    },
+  };
+}
 
 // ---------------------------------------------------------------------------
 // Module mocks — must be declared before importing the module under test
@@ -77,16 +117,51 @@ mock.module("../skills/install-meta.js", () => ({
 }));
 
 mock.module("../skills/catalog-cache.js", () => ({
-  getCatalog: async () => mockCatalog,
+  getCatalog: async () => [],
 }));
 
+// The provider factory functions are called once at module init and the
+// returned objects are captured in the `fileProviders` array. To allow
+// per-test mock reassignment, return proxy objects that delegate every
+// method call to the CURRENT value of the mutable mock variable.
 mock.module("../skills/catalog-files.js", () => ({
-  readCatalogSkillFiles: async (skillId: string) => {
-    catalogFilesCalls.push(skillId);
-    return mockCatalogFiles;
-  },
+  catalogSkillToSlim: () => ({}),
+  createVellumCatalogProvider: () => ({
+    canHandle: (id: string) => mockVellumProvider.canHandle(id),
+    listFiles: (id: string) => mockVellumProvider.listFiles(id),
+    readFileContent: (id: string, p: string) =>
+      mockVellumProvider.readFileContent(id, p),
+    toSlimSkill: (id: string) => mockVellumProvider.toSlimSkill(id),
+  }),
+  hasHiddenOrSkippedSegment: () => false,
+  readCatalogSkillFiles: async () => null,
+  readCatalogSkillFileContent: async () => null,
+  sanitizeRelativePath: (p: string) => p,
+  SKIP_DIRS: new Set(["node_modules", "__pycache__", ".git"]),
+}));
+
+mock.module("../skills/skillssh-files.js", () => ({
+  createSkillsShProvider: () => ({
+    canHandle: (id: string) => mockSkillsshProvider.canHandle(id),
+    listFiles: (id: string) => mockSkillsshProvider.listFiles(id),
+    readFileContent: (id: string, p: string) =>
+      mockSkillsshProvider.readFileContent(id, p),
+    toSlimSkill: (id: string) => mockSkillsshProvider.toSlimSkill(id),
+  }),
+}));
+
+mock.module("../skills/clawhub-files.js", () => ({
+  createClawhubProvider: () => ({
+    canHandle: (id: string) => mockClawhubProvider.canHandle(id),
+    listFiles: (id: string) => mockClawhubProvider.listFiles(id),
+    readFileContent: (id: string, p: string) =>
+      mockClawhubProvider.readFileContent(id, p),
+    toSlimSkill: (id: string) => mockClawhubProvider.toSlimSkill(id),
+  }),
 }));
 
+mock.module("../skills/skill-file-provider.js", () => ({}));
+
 mock.module("../skills/catalog-install.js", () => ({
   installSkillLocally: async () => {},
   upsertSkillsIndex: () => {},
@@ -154,7 +229,10 @@ mock.module("../daemon/handlers/shared.js", () => ({
 // Import after mocks
 // ---------------------------------------------------------------------------
 
-import { getSkillFiles } from "../daemon/handlers/skills.js";
+import {
+  _resetFileProvidersForTest,
+  getSkillFiles,
+} from "../daemon/handlers/skills.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -194,25 +272,19 @@ function makeSummary(overrides: Partial<SkillSummary>): SkillSummary {
 // Tests
 // ---------------------------------------------------------------------------
 
-describe("getSkillFiles — catalog fallback", () => {
+describe("getSkillFiles — provider chain fallback", () => {
   beforeEach(() => {
     mockResolvedStates = [];
-    mockCatalog = [];
-    mockCatalogFiles = null;
-    catalogFilesCalls.length = 0;
+    providerCalls.length = 0;
+    mockVellumProvider = makeNoopProvider("vellum");
+    mockSkillsshProvider = makeNoopProvider("skillssh");
+    mockClawhubProvider = makeNoopProvider("clawhub");
+    // Force provider chain re-creation from the (mocked) factory functions
+    _resetFileProvidersForTest();
   });
 
-  test("returns catalog skill with files (content: null) when skill is uninstalled but present in catalog", async () => {
-    mockCatalog = [
-      {
-        id: "acme-seo",
-        name: "acme-seo",
-        description: "SEO helper",
-        emoji: "\u{1F50D}",
-        metadata: { vellum: { "display-name": "Acme SEO" } },
-      },
-    ];
-    mockCatalogFiles = [
+  test("returns catalog skill with files (content: null) when skill is uninstalled but present in vellum catalog", async () => {
+    const mockFiles: SkillFileEntry[] = [
       {
         path: "SKILL.md",
         name: "SKILL.md",
@@ -231,6 +303,21 @@ describe("getSkillFiles — catalog fallback", () => {
       },
     ];
 
+    mockVellumProvider = {
+      canHandle: () => true,
+      listFiles: async () => mockFiles,
+      readFileContent: async () => null,
+      toSlimSkill: async () => ({
+        id: "acme-seo",
+        name: "Acme SEO",
+        description: "SEO helper",
+        emoji: "\u{1F50D}",
+        kind: "catalog",
+        origin: "vellum",
+        status: "available",
+      }),
+    };
+
     const result = await getSkillFiles("acme-seo", dummyCtx);
 
     expect("error" in result).toBe(false);
@@ -249,20 +336,17 @@ describe("getSkillFiles — catalog fallback", () => {
     for (const entry of result.files) {
       expect(entry.content).toBeNull();
     }
-    // Files should be sorted by path via localeCompare (not codepoint) —
-    // so "assets/logo.png" sorts before "SKILL.md" under default collation.
+    // Files should be sorted by path via localeCompare
     expect(result.files.map((f) => f.path)).toEqual(
       [...result.files.map((f) => f.path)].sort((a, b) => a.localeCompare(b)),
     );
     expect(new Set(result.files.map((f) => f.path))).toEqual(
       new Set(["SKILL.md", "assets/logo.png"]),
     );
-    expect(catalogFilesCalls).toEqual(["acme-seo"]);
   });
 
-  test("returns 404 when skill is neither installed nor in the catalog", async () => {
+  test("returns 404 when skill is neither installed nor handled by any provider", async () => {
     mockResolvedStates = [];
-    mockCatalog = [];
 
     const result = await getSkillFiles("ghost-skill", dummyCtx);
 
@@ -270,18 +354,15 @@ describe("getSkillFiles — catalog fallback", () => {
     if (!("error" in result)) return;
     expect(result.status).toBe(404);
     expect(result.error).toContain("ghost-skill");
-    expect(catalogFilesCalls).toEqual([]);
   });
 
-  test("returns 404 when skill is in catalog but readCatalogSkillFiles returns null", async () => {
-    mockCatalog = [
-      {
-        id: "broken-skill",
-        name: "broken-skill",
-        description: "",
-      },
-    ];
-    mockCatalogFiles = null;
+  test("returns 404 with 'files unavailable' when vellum provider canHandle returns true but listFiles returns null", async () => {
+    mockVellumProvider = {
+      canHandle: () => true,
+      listFiles: async () => null,
+      readFileContent: async () => null,
+      toSlimSkill: async () => null,
+    };
 
     const result = await getSkillFiles("broken-skill", dummyCtx);
 
@@ -289,9 +370,10 @@ describe("getSkillFiles — catalog fallback", () => {
     if (!("error" in result)) return;
     expect(result.status).toBe(404);
     expect(result.error).toContain("broken-skill");
+    expect(result.error).toContain("unavailable");
   });
 
-  test("installed skill returns inline disk content (no catalog call)", async () => {
+  test("installed skill returns inline disk content (no provider fallback)", async () => {
     // Create a real temp directory for the installed-skill path to read.
     const workspaceRoot = mkdtempSync(
       join(tmpdir(), "vellum-skill-files-test-"),
@@ -327,9 +409,6 @@ describe("getSkillFiles — catalog fallback", () => {
       expect("error" in result).toBe(false);
       if ("error" in result) return;
 
-      // Catalog fallback should NOT have been consulted for an installed skill.
-      expect(catalogFilesCalls).toEqual([]);
-
       expect(result.files).toHaveLength(2);
       const skillMd = result.files.find((f) => f.path === "SKILL.md");
       const notes = result.files.find((f) => f.path === "notes.txt");
@@ -349,14 +428,7 @@ describe("getSkillFiles — catalog fallback", () => {
     }
   });
 
-  test("returns 404 without catalog fallback when installed skill directory is missing on disk", async () => {
-    // `findSkillById` resolves the skill (resolver lists it as installed)
-    // but the on-disk directoryPath does not exist — simulates a corrupted
-    // install, mid-delete race, or external unmount. The handler must
-    // return 404 so the listing response (`kind: "installed"`) and the
-    // detail response stay consistent; falling through to the catalog
-    // would flip the detail to `kind: "catalog"` and break the
-    // client-side `isInstalled` contract.
+  test("returns 404 without provider fallback when installed skill directory is missing on disk", async () => {
     mockResolvedStates = [
       {
         summary: makeSummary({
@@ -370,26 +442,30 @@ describe("getSkillFiles — catalog fallback", () => {
         state: "enabled",
       },
     ];
-    // Even if the same id is present in the catalog, the handler must NOT
-    // fall through — return 404 instead to avoid masking the missing
-    // install directory with a catalog response.
-    mockCatalog = [
-      {
+    // Even if a provider would handle this id, the handler must NOT
+    // fall through — return 404 instead.
+    mockVellumProvider = {
+      canHandle: () => true,
+      listFiles: async () => [
+        {
+          path: "SKILL.md",
+          name: "SKILL.md",
+          size: 10,
+          mimeType: "",
+          isBinary: false,
+          content: null,
+        },
+      ],
+      readFileContent: async () => null,
+      toSlimSkill: async () => ({
         id: "ghost-installed",
-        name: "ghost-installed",
-        description: "Also present in catalog",
-      },
-    ];
-    mockCatalogFiles = [
-      {
-        path: "SKILL.md",
-        name: "SKILL.md",
-        size: 10,
-        mimeType: "",
-        isBinary: false,
-        content: null,
-      },
-    ];
+        name: "Ghost",
+        description: "",
+        kind: "catalog",
+        origin: "vellum",
+        status: "available",
+      }),
+    };
 
     const result = await getSkillFiles("ghost-installed", dummyCtx);
 
@@ -398,19 +474,22 @@ describe("getSkillFiles — catalog fallback", () => {
     expect(result.status).toBe(404);
     expect(result.error).toContain("ghost-installed");
     expect(result.error).toContain("directory missing");
-    // Catalog fallback must not have been consulted.
-    expect(catalogFilesCalls).toEqual([]);
   });
 
   test("catalogSkillToSlim falls back to cs.name when metadata.vellum.display-name is absent", async () => {
-    mockCatalog = [
-      {
+    mockVellumProvider = {
+      canHandle: () => true,
+      listFiles: async () => [],
+      readFileContent: async () => null,
+      toSlimSkill: async () => ({
         id: "plain-skill",
         name: "plain-skill",
         description: "Minimal",
-      },
-    ];
-    mockCatalogFiles = [];
+        kind: "catalog",
+        origin: "vellum",
+        status: "available",
+      }),
+    };
 
     const result = await getSkillFiles("plain-skill", dummyCtx);
 
@@ -423,15 +502,19 @@ describe("getSkillFiles — catalog fallback", () => {
   });
 
   test("catalogSkillToSlim prefers metadata.vellum.display-name over cs.name", async () => {
-    mockCatalog = [
-      {
+    mockVellumProvider = {
+      canHandle: () => true,
+      listFiles: async () => [],
+      readFileContent: async () => null,
+      toSlimSkill: async () => ({
         id: "fancy-skill",
-        name: "raw-fancy-name",
+        name: "Pretty Fancy Name",
         description: "",
-        metadata: { vellum: { "display-name": "Pretty Fancy Name" } },
-      },
-    ];
-    mockCatalogFiles = [];
+        kind: "catalog",
+        origin: "vellum",
+        status: "available",
+      }),
+    };
 
     const result = await getSkillFiles("fancy-skill", dummyCtx);
 
@@ -439,6 +522,211 @@ describe("getSkillFiles — catalog fallback", () => {
     if ("error" in result) return;
     expect(result.skill.name).toBe("Pretty Fancy Name");
   });
+
+  test("skills.sh-shaped ID not in vellum catalog returns files from skills.sh provider", async () => {
+    // Vellum provider doesn't handle this ID
+    mockVellumProvider = {
+      canHandle: () => false,
+      listFiles: async () => null,
+      readFileContent: async () => null,
+      toSlimSkill: async () => null,
+    };
+
+    const skillsshFiles: SkillFileEntry[] = [
+      {
+        path: "SKILL.md",
+        name: "SKILL.md",
+        size: 100,
+        mimeType: "",
+        isBinary: false,
+        content: null,
+      },
+    ];
+    mockSkillsshProvider = {
+      canHandle: (id: string) => id.split("/").length >= 3,
+      listFiles: async () => skillsshFiles,
+      readFileContent: async () => null,
+      toSlimSkill: async (id: string) => ({
+        id,
+        name: "my-skill",
+        description: "",
+        kind: "catalog",
+        origin: "skillssh",
+        status: "available",
+        slug: id,
+        sourceRepo: "owner/repo",
+        installs: 0,
+      }),
+    };
+
+    const result = await getSkillFiles("owner/repo/my-skill", dummyCtx);
+
+    expect("error" in result).toBe(false);
+    if ("error" in result) return;
+    expect(result.skill.origin).toBe("skillssh");
+    expect(result.files).toHaveLength(1);
+    expect(result.files[0].path).toBe("SKILL.md");
+  });
+
+  test("clawhub-shaped ID not in vellum catalog returns files from clawhub provider", async () => {
+    // Vellum and skills.sh providers don't handle this ID
+    mockVellumProvider = {
+      canHandle: () => false,
+      listFiles: async () => null,
+      readFileContent: async () => null,
+      toSlimSkill: async () => null,
+    };
+    mockSkillsshProvider = {
+      canHandle: () => false,
+      listFiles: async () => null,
+      readFileContent: async () => null,
+      toSlimSkill: async () => null,
+    };
+
+    const clawhubFiles: SkillFileEntry[] = [
+      {
+        path: "SKILL.md",
+        name: "SKILL.md",
+        size: 200,
+        mimeType: "",
+        isBinary: false,
+        content: null,
+      },
+      {
+        path: "lib/utils.js",
+        name: "utils.js",
+        size: 500,
+        mimeType: "",
+        isBinary: false,
+        content: null,
+      },
+    ];
+    mockClawhubProvider = {
+      canHandle: () => true,
+      listFiles: async () => clawhubFiles,
+      readFileContent: async () => null,
+      toSlimSkill: async () => ({
+        id: "cool-tool",
+        name: "Cool Tool",
+        description: "A clawhub skill",
+        kind: "catalog",
+        origin: "clawhub",
+        status: "available",
+        slug: "cool-tool",
+        author: "someone",
+        stars: 5,
+        installs: 10,
+        reports: 0,
+        version: "",
+      }),
+    };
+
+    const result = await getSkillFiles("cool-tool", dummyCtx);
+
+    expect("error" in result).toBe(false);
+    if ("error" in result) return;
+    expect(result.skill.origin).toBe("clawhub");
+    expect(result.files).toHaveLength(2);
+  });
+
+  test("ID that no provider handles returns 404", async () => {
+    // All providers return canHandle=false
+    mockVellumProvider = makeNoopProvider("vellum");
+    mockSkillsshProvider = makeNoopProvider("skillssh");
+    mockClawhubProvider = makeNoopProvider("clawhub");
+
+    const result = await getSkillFiles("unknown-origin-skill", dummyCtx);
+
+    expect("error" in result).toBe(true);
+    if (!("error" in result)) return;
+    expect(result.status).toBe(404);
+  });
+
+  test("provider priority — vellum provider is tried before skills.sh and clawhub", async () => {
+    // All three providers claim to handle this ID, but vellum should win
+    const vellumListFilesCalls: string[] = [];
+    const skillsshListFilesCalls: string[] = [];
+    const clawhubListFilesCalls: string[] = [];
+
+    mockVellumProvider = {
+      canHandle: () => true,
+      listFiles: async (skillId: string) => {
+        vellumListFilesCalls.push(skillId);
+        return [
+          {
+            path: "SKILL.md",
+            name: "SKILL.md",
+            size: 10,
+            mimeType: "",
+            isBinary: false,
+            content: null,
+          },
+        ];
+      },
+      readFileContent: async () => null,
+      toSlimSkill: async () => ({
+        id: "contested-skill",
+        name: "Vellum Contested",
+        description: "",
+        kind: "catalog",
+        origin: "vellum",
+        status: "available",
+      }),
+    };
+    mockSkillsshProvider = {
+      canHandle: () => true,
+      listFiles: async (skillId: string) => {
+        skillsshListFilesCalls.push(skillId);
+        return [];
+      },
+      readFileContent: async () => null,
+      toSlimSkill: async () => ({
+        id: "contested-skill",
+        name: "Skillssh Contested",
+        description: "",
+        kind: "catalog",
+        origin: "skillssh",
+        status: "available",
+        slug: "contested-skill",
+        sourceRepo: "",
+        installs: 0,
+      }),
+    };
+    mockClawhubProvider = {
+      canHandle: () => true,
+      listFiles: async (skillId: string) => {
+        clawhubListFilesCalls.push(skillId);
+        return [];
+      },
+      readFileContent: async () => null,
+      toSlimSkill: async () => ({
+        id: "contested-skill",
+        name: "Clawhub Contested",
+        description: "",
+        kind: "catalog",
+        origin: "clawhub",
+        status: "available",
+        slug: "contested-skill",
+        author: "",
+        stars: 0,
+        installs: 0,
+        reports: 0,
+        version: "",
+      }),
+    };
+
+    const result = await getSkillFiles("contested-skill", dummyCtx);
+
+    expect("error" in result).toBe(false);
+    if ("error" in result) return;
+    // Vellum provider should have been used
+    expect(result.skill.origin).toBe("vellum");
+    expect(result.skill.name).toBe("Vellum Contested");
+    // Vellum was called, but skills.sh and clawhub were NOT called
+    expect(vellumListFilesCalls).toEqual(["contested-skill"]);
+    expect(skillsshListFilesCalls).toEqual([]);
+    expect(clawhubListFilesCalls).toEqual([]);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/__tests__/skills.test.ts

@@ -549,19 +549,21 @@ describe("bundled browser skill", () => {
     );
   });
 
-  test("browser skill has a valid tool manifest with 14 tools", () => {
+  test("browser skill has a valid tool manifest with all browser tools", () => {
     const catalog = loadSkillCatalog();
     const browserSkill = catalog.find((s) => s.id === "browser");
     expect(browserSkill).toBeDefined();
     expect(browserSkill!.toolManifest).toBeDefined();
     expect(browserSkill!.toolManifest!.present).toBe(true);
     expect(browserSkill!.toolManifest!.valid).toBe(true);
-    expect(browserSkill!.toolManifest!.toolCount).toBe(14);
+    expect(browserSkill!.toolManifest!.toolCount).toBe(17);
     expect(browserSkill!.toolManifest!.toolNames).toEqual([
       "browser_navigate",
       "browser_snapshot",
       "browser_screenshot",
       "browser_close",
+      "browser_attach",
+      "browser_detach",
       "browser_click",
       "browser_type",
       "browser_press_key",
@@ -572,6 +574,7 @@ describe("bundled browser skill", () => {
       "browser_extract",
       "browser_wait_for_download",
       "browser_fill_credential",
+      "browser_status",
     ]);
   });
 });