@vellumai/assistant 0.6.3 → 0.6.4

package/src/skills/clawhub.ts

@@ -23,7 +23,7 @@ function getClawhubProjectRoot(): string {
 }
 
 // Validate slug format (alphanumeric, hyphens, dots, underscores; optional namespace with single slash)
-function validateSlug(slug: string): boolean {
+export function validateSlug(slug: string): boolean {
   return /^[a-zA-Z0-9]([a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)?)?$/.test(
     slug,
   );
@@ -312,18 +312,37 @@ export async function clawhubSearch(
       };
     }
   } catch {
-    // CLI outputs text: "slug vVersion  DisplayName  (score)"
+    // CLI outputs text — fall through to line parser below.
   }
 
-  // Parse text output lines: "slug vVersion  Display Name  (score)"
+  // Parse text output lines. The CLI format varies by version:
+  //   With version: "slug v1.0.0  Display Name  (3.459)"
+  //   Without version: "slug  Display Name  (3.459)"
   const skills: ClawhubSearchResultItem[] = [];
   for (const line of result.stdout.split("\n")) {
-    const match = line.match(/^(\S+)\s+v(\S+)\s+(.+?)\s+\([\d.]+\)\s*$/);
-    if (match) {
+    // Try format with version first
+    const withVersion = line.match(/^(\S+)\s+v(\S+)\s+(.+?)\s+\([\d.]+\)\s*$/);
+    if (withVersion) {
       skills.push({
-        slug: match[1],
-        version: match[2],
-        name: match[3].trim(),
+        slug: withVersion[1],
+        version: withVersion[2],
+        name: withVersion[3].trim(),
+        description: "",
+        author: "",
+        stars: 0,
+        installs: 0,
+        createdAt: 0,
+        source: "clawhub",
+      });
+      continue;
+    }
+    // Try format without version
+    const withoutVersion = line.match(/^(\S+)\s+(.+?)\s+\([\d.]+\)\s*$/);
+    if (withoutVersion) {
+      skills.push({
+        slug: withoutVersion[1],
+        version: "",
+        name: withoutVersion[2].trim(),
         description: "",
         author: "",
         stars: 0,
@@ -420,12 +439,18 @@ export async function clawhubInspect(
     }
     try {
       const parsed = JSON.parse(result.stdout);
-      // Normalize the raw inspect response to our interface
+      // Normalize the raw inspect response to our interface.
+      // The CLI nests skill metadata under `parsed.skill` and files
+      // under `parsed.version.files`. Fall back to top-level fields
+      // for older CLI versions that used a flat structure.
+      const ps = parsed.skill ?? parsed;
+      const rawStats = ps.stats ?? parsed.stats;
+      const rawFiles = parsed.version?.files ?? parsed.files ?? null;
       const data: ClawhubInspectResult = {
         skill: {
-          slug: parsed.slug ?? slug,
-          displayName: parsed.displayName ?? parsed.name ?? slug,
-          summary: parsed.summary ?? parsed.description ?? "",
+          slug: ps.slug ?? slug,
+          displayName: ps.displayName ?? ps.name ?? slug,
+          summary: ps.summary ?? ps.description ?? "",
         },
         owner: parsed.owner
           ? {
@@ -434,26 +459,24 @@ export async function clawhubInspect(
               image: parsed.owner.image ?? parsed.owner.avatar ?? undefined,
             }
           : null,
-        stats: parsed.stats
+        stats: rawStats
           ? {
-              stars: parsed.stats.stars ?? 0,
-              installs:
-                parsed.stats.installsAllTime ?? parsed.stats.installs ?? 0,
-              downloads:
-                parsed.stats.downloadsAllTime ?? parsed.stats.downloads ?? 0,
-              versions: parsed.stats.versions ?? 0,
+              stars: rawStats.stars ?? 0,
+              installs: rawStats.installsAllTime ?? rawStats.installs ?? 0,
+              downloads: rawStats.downloadsAllTime ?? rawStats.downloads ?? 0,
+              versions: rawStats.versions ?? 0,
             }
           : null,
-        createdAt: parsed.createdAt ?? null,
-        updatedAt: parsed.updatedAt ?? null,
+        createdAt: ps.createdAt ?? parsed.createdAt ?? null,
+        updatedAt: ps.updatedAt ?? parsed.updatedAt ?? null,
         latestVersion: parsed.latestVersion
           ? {
               version: parsed.latestVersion.version ?? "",
               changelog: parsed.latestVersion.changelog ?? undefined,
             }
           : null,
-        files: Array.isArray(parsed.files)
-          ? parsed.files.map((f: Record<string, unknown>) => ({
+        files: Array.isArray(rawFiles)
+          ? rawFiles.map((f: Record<string, unknown>) => ({
               path: (f.path as string) ?? "",
               size: (f.size as number) ?? 0,
               contentType: (f.contentType as string) ?? undefined,
@@ -475,6 +498,44 @@ export async function clawhubInspect(
   }
 }
 
+/**
+ * Fetch a single file's content from a published clawhub skill.
+ * Calls `npx clawhub inspect <slug> --json --file <filePath>` and returns
+ * the file content string, or `null` on failure.
+ */
+export async function clawhubInspectFile(
+  slug: string,
+  filePath: string,
+): Promise<string | null> {
+  if (!validateSlug(slug)) return null;
+
+  try {
+    const result = await runClawhub([
+      "inspect",
+      slug,
+      "--json",
+      "--file",
+      filePath,
+    ]);
+    if (result.exitCode !== 0) return null;
+
+    try {
+      const parsed = JSON.parse(result.stdout);
+      // The CLI returns the file content in one of these fields
+      const content =
+        parsed.skillMdContent ??
+        parsed.fileContents?.[filePath] ??
+        parsed.file?.content ??
+        null;
+      return typeof content === "string" ? content : null;
+    } catch {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
 export async function clawhubCheckUpdates(): Promise<ClawhubUpdateCheckItem[]> {
   // This is a placeholder -- clawhub doesn't have a dedicated check-updates command
   // For now return empty; will be implemented when the CLI supports it

package/src/skills/skill-file-provider.ts

@@ -0,0 +1,40 @@
+import type { SlimSkillResponse } from "../daemon/message-types/skills.js";
+import type { SkillFileEntry } from "./catalog-files.js";
+
+/**
+ * A file provider can resolve file listings and single-file content for
+ * skills that are NOT installed locally. Each origin (vellum catalog,
+ * skills.sh, clawhub) implements this interface.
+ */
+export interface SkillFileProvider {
+  /**
+   * Return true if this provider can handle the given skill id.
+   * Called synchronously — must not perform I/O.
+   */
+  canHandle(skillId: string): boolean;
+
+  /**
+   * List all files in the skill directory. Returns entries with
+   * `content: null` (content is fetched on demand via `readFileContent`).
+   * Returns `null` if the skill doesn't exist in this provider.
+   */
+  listFiles(skillId: string): Promise<SkillFileEntry[] | null>;
+
+  /**
+   * Read a single file's content. `relativePath` has already been
+   * sanitized by the caller (sanitizeRelativePath + hasHiddenOrSkippedSegment).
+   * Returns `null` if the file doesn't exist.
+   */
+  readFileContent(
+    skillId: string,
+    sanitizedPath: string,
+  ): Promise<SkillFileEntry | null>;
+
+  /**
+   * Synthesize a SlimSkillResponse for an uninstalled skill in this
+   * provider. Used by getSkill/getSkillFiles when the skill isn't in
+   * the local catalog. Returns `null` if the provider can't produce
+   * metadata for this skill.
+   */
+  toSlimSkill(skillId: string): Promise<SlimSkillResponse | null>;
+}

package/src/skills/skillssh-files.ts

@@ -0,0 +1,395 @@
+/**
+ * skillssh-files — SkillFileProvider for skills.sh (GitHub-hosted) skills.
+ *
+ * Lists files and reads individual file content via the GitHub Contents API
+ * and Tree API, without downloading or installing the skill locally.
+ *
+ * Path resolution (conventional `skills/<slug>/` with tree-search fallback)
+ * mirrors the logic in `fetchSkillFromGitHub` from `skillssh-registry.ts`,
+ * but only collects metadata (no file content on listing) and fetches
+ * content on demand for individual files.
+ */
+
+import { basename } from "node:path";
+
+import type { SlimSkillResponse } from "../daemon/message-types/skills.js";
+import {
+  isTextMimeType as isTextMime,
+  MAX_INLINE_TEXT_SIZE,
+} from "../runtime/routes/workspace-utils.js";
+import { getLogger } from "../util/logger.js";
+import type { SkillFileEntry } from "./catalog-files.js";
+import {
+  hasHiddenOrSkippedSegment,
+  sanitizeRelativePath,
+  SKIP_DIRS,
+} from "./catalog-files.js";
+import type { SkillFileProvider } from "./skill-file-provider.js";
+import type { GitHubContentsEntry } from "./skillssh-registry.js";
+import {
+  findSkillDirInTree,
+  githubHeaders,
+  resolveSkillSource,
+} from "./skillssh-registry.js";
+
+const log = getLogger("skillssh-files");
+
+// ─── Path resolution cache ──────────────────────────────────────────────────
+
+interface CacheEntry {
+  dirPath: string;
+  expiresAt: number;
+}
+
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * In-memory cache for resolved skill directory paths. Keyed by
+ * `${owner}/${repo}/${skillSlug}` so repeated requests don't re-probe the
+ * GitHub Contents/Tree APIs.
+ */
+const dirPathCache = new Map<string, CacheEntry>();
+
+function cacheKey(owner: string, repo: string, skillSlug: string): string {
+  return `${owner}/${repo}/${skillSlug}`;
+}
+
+function getCachedDirPath(
+  owner: string,
+  repo: string,
+  skillSlug: string,
+): string | null {
+  const key = cacheKey(owner, repo, skillSlug);
+  const entry = dirPathCache.get(key);
+  if (!entry) return null;
+  if (Date.now() > entry.expiresAt) {
+    dirPathCache.delete(key);
+    return null;
+  }
+  return entry.dirPath;
+}
+
+function setCachedDirPath(
+  owner: string,
+  repo: string,
+  skillSlug: string,
+  dirPath: string,
+): void {
+  const key = cacheKey(owner, repo, skillSlug);
+  dirPathCache.set(key, { dirPath, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+
+// Exported for testing only
+export function clearDirPathCache(): void {
+  dirPathCache.clear();
+}
+
+// ─── Binary classification ──────────────────────────────────────────────────
+
+/**
+ * Classify a file as binary from its name alone. Mirrors the
+ * `classifyByName` pattern in `catalog-files.ts`.
+ */
+function classifyByName(name: string): boolean {
+  const mime = Bun.file(name).type;
+  return !isTextMime(mime, name);
+}
+
+// ─── Skill directory resolution ─────────────────────────────────────────────
+
+/**
+ * Resolve the directory path for a skill in a GitHub repo. Tries the
+ * conventional `skills/<slug>/` path first, falls back to tree search.
+ * Returns null if the skill cannot be located.
+ */
+async function resolveSkillDir(
+  owner: string,
+  repo: string,
+  skillSlug: string,
+  ref?: string,
+): Promise<string | null> {
+  // Check cache first
+  const cached = getCachedDirPath(owner, repo, skillSlug);
+  if (cached !== null) return cached;
+
+  const headers = githubHeaders();
+  const conventionalPath = `skills/${encodeURIComponent(skillSlug)}`;
+
+  const probeUrl = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/contents/${conventionalPath}${ref ? `?ref=${encodeURIComponent(ref)}` : ""}`;
+
+  const probeResponse = await fetch(probeUrl, {
+    headers,
+    signal: AbortSignal.timeout(15_000),
+  });
+
+  if (probeResponse.ok) {
+    setCachedDirPath(owner, repo, skillSlug, conventionalPath);
+    return conventionalPath;
+  }
+
+  if (probeResponse.status === 404) {
+    // Fall back to tree search
+    const treeRef = ref ?? "HEAD";
+    const foundPath = await findSkillDirInTree(
+      owner,
+      repo,
+      skillSlug,
+      treeRef,
+      headers,
+    );
+    if (foundPath) {
+      setCachedDirPath(owner, repo, skillSlug, foundPath);
+      return foundPath;
+    }
+    return null;
+  }
+
+  // Non-404 error — log and return null
+  log.warn(
+    { status: probeResponse.status, owner, repo, skillSlug },
+    "GitHub Contents API returned non-2xx during skill dir probe",
+  );
+  return null;
+}
+
+// ─── Recursive directory listing ────────────────────────────────────────────
+
+/**
+ * Recursively list files in a GitHub directory via the Contents API.
+ * Collects `SkillFileEntry` objects with `content: null`. Skips hidden
+ * files, `node_modules`, `__pycache__`, `.git` (same filtering as
+ * `walkSkillDir` in `catalog-files.ts`).
+ */
+async function listGitHubDir(
+  owner: string,
+  repo: string,
+  dirPath: string,
+  prefix: string,
+  ref: string | undefined,
+  headers: Record<string, string>,
+): Promise<SkillFileEntry[]> {
+  let apiUrl = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/contents/${dirPath}`;
+  if (ref) {
+    apiUrl += `?ref=${encodeURIComponent(ref)}`;
+  }
+
+  const response = await fetch(apiUrl, {
+    headers,
+    signal: AbortSignal.timeout(15_000),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `GitHub Contents API error: HTTP ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const entries = (await response.json()) as GitHubContentsEntry[];
+  if (!Array.isArray(entries)) return [];
+
+  const result: SkillFileEntry[] = [];
+
+  for (const entry of entries) {
+    // Skip hidden files/dirs (same as walkSkillDir)
+    if (entry.name.startsWith(".")) continue;
+
+    const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+    if (entry.type === "dir") {
+      // Skip well-known heavyweight directories
+      if (SKIP_DIRS.has(entry.name)) continue;
+
+      const subEntries = await listGitHubDir(
+        owner,
+        repo,
+        `${dirPath}/${entry.name}`,
+        relativePath,
+        ref,
+        headers,
+      );
+      result.push(...subEntries);
+      continue;
+    }
+
+    if (entry.type !== "file") continue;
+
+    result.push({
+      path: relativePath,
+      name: basename(relativePath),
+      size: 0, // GitHub Contents API directory listings don't include size
+      mimeType: "",
+      isBinary: classifyByName(entry.name),
+      content: null,
+    });
+  }
+
+  return result;
+}
+
+// ─── Provider implementation ────────────────────────────────────────────────
+
+export function createSkillsShProvider(): SkillFileProvider {
+  return {
+    canHandle(skillId: string): boolean {
+      return skillId.split("/").length >= 3;
+    },
+
+    async listFiles(skillId: string): Promise<SkillFileEntry[] | null> {
+      let source;
+      try {
+        source = resolveSkillSource(skillId);
+      } catch {
+        return null;
+      }
+
+      try {
+        const dirPath = await resolveSkillDir(
+          source.owner,
+          source.repo,
+          source.skillSlug,
+          source.ref,
+        );
+        if (!dirPath) return null;
+
+        const headers = githubHeaders();
+        const entries = await listGitHubDir(
+          source.owner,
+          source.repo,
+          dirPath,
+          "",
+          source.ref,
+          headers,
+        );
+        entries.sort((a, b) => a.path.localeCompare(b.path));
+        return entries;
+      } catch (err) {
+        log.warn({ err, skillId }, "Failed to list files for skills.sh skill");
+        return null;
+      }
+    },
+
+    async readFileContent(
+      skillId: string,
+      sanitizedPath: string,
+    ): Promise<SkillFileEntry | null> {
+      // Re-validate the path even though the caller should have sanitized
+      const safe = sanitizeRelativePath(sanitizedPath);
+      if (!safe) return null;
+      if (hasHiddenOrSkippedSegment(safe)) return null;
+
+      let source;
+      try {
+        source = resolveSkillSource(skillId);
+      } catch {
+        return null;
+      }
+
+      try {
+        const dirPath = await resolveSkillDir(
+          source.owner,
+          source.repo,
+          source.skillSlug,
+          source.ref,
+        );
+        if (!dirPath) return null;
+
+        const headers = githubHeaders();
+        const filePath = `${dirPath}/${safe}`;
+
+        // Fetch the file entry via GitHub Contents API
+        let apiUrl = `https://api.github.com/repos/${encodeURIComponent(source.owner)}/${encodeURIComponent(source.repo)}/contents/${filePath}`;
+        if (source.ref) {
+          apiUrl += `?ref=${encodeURIComponent(source.ref)}`;
+        }
+
+        const response = await fetch(apiUrl, {
+          headers,
+          signal: AbortSignal.timeout(15_000),
+        });
+
+        if (!response.ok) return null;
+
+        const entry = (await response.json()) as GitHubContentsEntry & {
+          size?: number;
+        };
+
+        // Ensure it's a file, not a directory
+        if (entry.type !== "file") return null;
+
+        const name = basename(safe);
+        const isBinary = classifyByName(name);
+
+        // Return null content for binary files
+        if (isBinary) {
+          return {
+            path: safe,
+            name,
+            size: entry.size ?? 0,
+            mimeType: "",
+            isBinary: true,
+            content: null,
+          };
+        }
+
+        // For text files, check size and fetch content
+        const size = entry.size ?? 0;
+        if (size > MAX_INLINE_TEXT_SIZE) {
+          return {
+            path: safe,
+            name,
+            size,
+            mimeType: "",
+            isBinary: false,
+            content: null,
+          };
+        }
+
+        // Fetch the actual file content via download_url
+        if (!entry.download_url) return null;
+
+        const contentResponse = await fetch(entry.download_url, {
+          headers,
+          signal: AbortSignal.timeout(10_000),
+        });
+
+        if (!contentResponse.ok) return null;
+
+        const content = await contentResponse.text();
+
+        return {
+          path: safe,
+          name,
+          size: content.length,
+          mimeType: "",
+          isBinary: false,
+          content,
+        };
+      } catch (err) {
+        log.warn(
+          { err, skillId, path: sanitizedPath },
+          "Failed to read file content for skills.sh skill",
+        );
+        return null;
+      }
+    },
+
+    async toSlimSkill(skillId: string): Promise<SlimSkillResponse | null> {
+      try {
+        const source = resolveSkillSource(skillId);
+        return {
+          id: skillId,
+          name: source.skillSlug,
+          description: "",
+          kind: "catalog",
+          status: "available",
+          origin: "skillssh",
+          slug: skillId,
+          sourceRepo: `${source.owner}/${source.repo}`,
+          installs: 0,
+        };
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/src/skills/skillssh-registry.ts

@@ -189,14 +189,14 @@ export function resolveSkillSource(source: string): ResolvedSkillSource {
 
 // ─── GitHub fetch ───────────────────────────────────────────────────────────
 
-interface GitHubContentsEntry {
+export interface GitHubContentsEntry {
   name: string;
   type: "file" | "dir";
   download_url: string | null;
 }
 
 /** Build common headers for GitHub API requests (User-Agent + optional auth). */
-function githubHeaders(): Record<string, string> {
+export function githubHeaders(): Record<string, string> {
   const headers: Record<string, string> = {
     Accept: "application/vnd.github.v3+json",
     "User-Agent": "vellum-assistant",
@@ -208,7 +208,7 @@ function githubHeaders(): Record<string, string> {
   return headers;
 }
 
-interface GitHubTreeEntry {
+export interface GitHubTreeEntry {
   path: string;
   type: "blob" | "tree";
 }
@@ -217,7 +217,7 @@ interface GitHubTreeEntry {
  * Search the repo tree for a directory containing `<slug>/SKILL.md`.
  * Returns the directory path (e.g. "examples/skills-tool/skills/csv") or null.
  */
-async function findSkillDirInTree(
+export async function findSkillDirInTree(
   owner: string,
   repo: string,
   skillSlug: string,