@vellumai/assistant 0.4.26 → 0.4.29

package/src/skills/clawhub.ts

@@ -1,10 +1,16 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
 
-import { getLogger } from '../util/logger.js';
-import { getWorkspaceSkillsDir } from '../util/platform.js';
+import { getLogger } from "../util/logger.js";
+import { getWorkspaceSkillsDir } from "../util/platform.js";
 
-const log = getLogger('clawhub');
+const log = getLogger("clawhub");
 
 // Managed skills directory — where installed skill folders live
 function getManagedSkillsDir(): string {
@@ -19,7 +25,9 @@ function getClawhubProjectRoot(): string {
 
 // Validate slug format (alphanumeric, hyphens, dots, underscores; optional namespace with single slash)
 function validateSlug(slug: string): boolean {
-  return /^[a-zA-Z0-9]([a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)?)?$/.test(slug);
+  return /^[a-zA-Z0-9]([a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)?)?$/.test(
+    slug,
+  );
 }
 
 // ─── Content hash verification (trust-on-first-use) ──────────────────────────
@@ -32,26 +40,33 @@ interface IntegrityRecord {
 type IntegrityManifest = Record<string, IntegrityRecord>;
 
 function getIntegrityPath(): string {
-  return join(getManagedSkillsDir(), '.integrity.json');
+  return join(getManagedSkillsDir(), ".integrity.json");
 }
 
 export function loadIntegrityManifest(): IntegrityManifest {
   const path = getIntegrityPath();
   if (!existsSync(path)) return {};
   try {
-    return JSON.parse(readFileSync(path, 'utf-8')) as IntegrityManifest;
+    return JSON.parse(readFileSync(path, "utf-8")) as IntegrityManifest;
   } catch {
-    log.warn('Failed to parse integrity manifest, starting fresh');
+    log.warn("Failed to parse integrity manifest, starting fresh");
     return {};
   }
 }
 
 function saveIntegrityManifest(manifest: IntegrityManifest): void {
-  writeFileSync(getIntegrityPath(), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+  writeFileSync(
+    getIntegrityPath(),
+    JSON.stringify(manifest, null, 2) + "\n",
+    "utf-8",
+  );
 }
 
 /** Collect all file contents in a directory tree, sorted by relative path for determinism. */
-function collectFileContents(dir: string, prefix = ''): Array<{ relPath: string; content: Buffer }> {
+function collectFileContents(
+  dir: string,
+  prefix = "",
+): Array<{ relPath: string; content: Buffer }> {
   const results: Array<{ relPath: string; content: Buffer }> = [];
   if (!existsSync(dir)) return results;
 
@@ -78,16 +93,16 @@ function computeSkillHash(skillDir: string): string | null {
   const files = collectFileContents(skillDir);
   if (files.length === 0) return null;
 
-  const hasher = new Bun.CryptoHasher('sha256');
+  const hasher = new Bun.CryptoHasher("sha256");
   for (const file of files) {
     // Length-prefix each segment to prevent boundary ambiguity collisions
-    const pathBuf = Buffer.from(file.relPath, 'utf-8');
+    const pathBuf = Buffer.from(file.relPath, "utf-8");
     hasher.update(`${pathBuf.length}:`);
     hasher.update(pathBuf);
     hasher.update(`${file.content.length}:`);
     hasher.update(file.content);
   }
-  return `v2:${hasher.digest('hex')}`;
+  return `v2:${hasher.digest("hex")}`;
 }
 
 /**
@@ -102,7 +117,7 @@ export function verifyAndRecordSkillHash(slug: string): void {
   const skillDir = join(getManagedSkillsDir(), slug);
   const hash = computeSkillHash(skillDir);
   if (!hash) {
-    log.warn({ slug }, 'Could not compute content hash for installed skill');
+    log.warn({ slug }, "Could not compute content hash for installed skill");
     return;
   }
 
@@ -113,34 +128,40 @@ export function verifyAndRecordSkillHash(slug: string): void {
     const storedHash = existing.sha256;
 
     // Guard against corrupted manifest entries where sha256 is not a string
-    if (typeof storedHash !== 'string') {
+    if (typeof storedHash !== "string") {
       log.warn(
         { slug },
-        'Integrity manifest entry has non-string sha256 — re-recording hash',
+        "Integrity manifest entry has non-string sha256 — re-recording hash",
       );
     } else if (/^[0-9a-f]{64}$/.test(storedHash)) {
       // Legacy v1 hash: plain hex SHA-256, no version prefix — silently migrate
       log.info(
         { slug },
-        'Migrating skill integrity hash from v1 to v2 format (silent re-record)',
+        "Migrating skill integrity hash from v1 to v2 format (silent re-record)",
       );
-    } else if (!storedHash.startsWith('v2:')) {
+    } else if (!storedHash.startsWith("v2:")) {
       // Unknown format (not v1 hex, not v2: prefix) — warn about integrity mismatch
       log.warn(
         { slug, stored: storedHash, actual: hash },
-        'Stored hash has unrecognized format — possible integrity mismatch. Re-recording.',
+        "Stored hash has unrecognized format — possible integrity mismatch. Re-recording.",
       );
     } else if (storedHash !== hash) {
       log.warn(
         { slug, expected: storedHash, actual: hash },
-        'Skill content hash changed — content differs from previous install. ' +
-          'This is expected for updates but could indicate CDN tampering.',
+        "Skill content hash changed — content differs from previous install. " +
+          "This is expected for updates but could indicate CDN tampering.",
       );
     } else {
-      log.info({ slug }, 'Skill content hash verified — matches previous install');
+      log.info(
+        { slug },
+        "Skill content hash verified — matches previous install",
+      );
     }
   } else {
-    log.info({ slug, sha256: hash }, 'Recorded initial content hash for skill (trust-on-first-use)');
+    log.info(
+      { slug, sha256: hash },
+      "Recorded initial content hash for skill (trust-on-first-use)",
+    );
   }
 
   // Always store the latest hash
@@ -165,7 +186,7 @@ export interface ClawhubSearchResultItem {
   version: string;
   createdAt: number;
   /** Where this skill comes from: "vellum" (first-party) or "clawhub" (community). */
-  source: 'vellum' | 'clawhub';
+  source: "vellum" | "clawhub";
 }
 
 export interface ClawhubSearchResult {
@@ -185,21 +206,24 @@ export interface ClawhubUpdateCheckItem {
 }
 
 // Helper to run clawhub commands
-async function runClawhub(args: string[], opts?: { cwd?: string; timeout?: number }): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+async function runClawhub(
+  args: string[],
+  opts?: { cwd?: string; timeout?: number },
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   const cwd = opts?.cwd ?? getClawhubProjectRoot();
   const timeout = opts?.timeout ?? 60000;
 
   // Ensure managed skills dir exists
-  const { mkdirSync } = await import('node:fs');
+  const { mkdirSync } = await import("node:fs");
   mkdirSync(cwd, { recursive: true });
 
-  log.info({ args, cwd }, 'Running clawhub command');
+  log.info({ args, cwd }, "Running clawhub command");
 
-  const proc = Bun.spawn(['npx', 'clawhub', ...args], {
+  const proc = Bun.spawn(["npx", "clawhub", ...args], {
     cwd,
-    env: { ...process.env, CLAWHUB_DISABLE_TELEMETRY: '1' },
-    stdout: 'pipe',
-    stderr: 'pipe',
+    env: { ...process.env, CLAWHUB_DISABLE_TELEMETRY: "1" },
+    stdout: "pipe",
+    stderr: "pipe",
   });
 
   let timer: ReturnType<typeof setTimeout>;
@@ -223,23 +247,30 @@ async function runClawhub(args: string[], opts?: { cwd?: string; timeout?: numbe
 
   const exitCode = await proc.exited;
 
-  log.info({ exitCode, stdoutLen: stdout.length, stderrLen: stderr.length }, 'clawhub command completed');
+  log.info(
+    { exitCode, stdoutLen: stdout.length, stderrLen: stderr.length },
+    "clawhub command completed",
+  );
 
   return { stdout, stderr, exitCode };
 }
 
-export async function clawhubInstall(slug: string, opts?: { version?: string }): Promise<ClawhubInstallResult> {
+export async function clawhubInstall(
+  slug: string,
+  opts?: { version?: string },
+): Promise<ClawhubInstallResult> {
   if (!validateSlug(slug)) {
     return { success: false, error: `Invalid skill slug: ${slug}` };
   }
 
   const installSlug = opts?.version ? `${slug}@${opts.version}` : slug;
-  const args = ['install', installSlug, '--force']; // non-interactive
+  const args = ["install", installSlug, "--force"]; // non-interactive
 
   try {
     const result = await runClawhub(args);
     if (result.exitCode !== 0) {
-      const error = result.stderr.trim() || result.stdout.trim() || 'Unknown error';
+      const error =
+        result.stderr.trim() || result.stdout.trim() || "Unknown error";
       return { success: false, error };
     }
     verifyAndRecordSkillHash(slug);
@@ -250,11 +281,14 @@ export async function clawhubInstall(slug: string, opts?: { version?: string }):
   }
 }
 
-export async function clawhubUpdate(name: string): Promise<ClawhubUpdateResult> {
+export async function clawhubUpdate(
+  name: string,
+): Promise<ClawhubUpdateResult> {
   try {
-    const result = await runClawhub(['update', name, '--force']);
+    const result = await runClawhub(["update", name, "--force"]);
     if (result.exitCode !== 0) {
-      const error = result.stderr.trim() || result.stdout.trim() || 'Unknown error';
+      const error =
+        result.stderr.trim() || result.stdout.trim() || "Unknown error";
       return { success: false, error };
     }
     verifyAndRecordSkillHash(name);
@@ -265,14 +299,16 @@ export async function clawhubUpdate(name: string): Promise<ClawhubUpdateResult>
   }
 }
 
-export async function clawhubSearch(query: string): Promise<ClawhubSearchResult> {
+export async function clawhubSearch(
+  query: string,
+): Promise<ClawhubSearchResult> {
   // Empty query: use explore (browse trending) instead of search
   if (!query.trim()) {
     return clawhubExplore();
   }
 
   try {
-    const result = await runClawhub(['search', query, '--limit', '25']);
+    const result = await runClawhub(["search", query, "--limit", "25"]);
     if (result.exitCode !== 0) {
       return { skills: [] };
     }
@@ -280,10 +316,20 @@ export async function clawhubSearch(query: string): Promise<ClawhubSearchResult>
     try {
       const parsed = JSON.parse(result.stdout);
       if (Array.isArray(parsed)) {
-        return { skills: parsed.map((s: ClawhubSearchResultItem) => ({ ...s, source: s.source ?? 'clawhub' as const })) };
+        return {
+          skills: parsed.map((s: ClawhubSearchResultItem) => ({
+            ...s,
+            source: s.source ?? ("clawhub" as const),
+          })),
+        };
       }
       if (parsed.skills && Array.isArray(parsed.skills)) {
-        return { skills: parsed.skills.map((s: ClawhubSearchResultItem) => ({ ...s, source: s.source ?? 'clawhub' as const })) };
+        return {
+          skills: parsed.skills.map((s: ClawhubSearchResultItem) => ({
+            ...s,
+            source: s.source ?? ("clawhub" as const),
+          })),
+        };
       }
     } catch {
       // CLI outputs text: "slug vVersion  DisplayName  (score)"
@@ -291,35 +337,45 @@ export async function clawhubSearch(query: string): Promise<ClawhubSearchResult>
 
     // Parse text output lines: "slug vVersion  Display Name  (score)"
     const skills: ClawhubSearchResultItem[] = [];
-    for (const line of result.stdout.split('\n')) {
+    for (const line of result.stdout.split("\n")) {
       const match = line.match(/^(\S+)\s+v(\S+)\s+(.+?)\s+\([\d.]+\)\s*$/);
       if (match) {
         skills.push({
           slug: match[1],
           version: match[2],
           name: match[3].trim(),
-          description: '',
-          author: '',
+          description: "",
+          author: "",
           stars: 0,
           installs: 0,
           createdAt: 0,
-          source: 'clawhub',
+          source: "clawhub",
         });
       }
     }
     return { skills };
   } catch (err) {
-    log.warn({ err }, 'clawhub search failed');
+    log.warn({ err }, "clawhub search failed");
     return { skills: [] };
   }
 }
 
-export async function clawhubExplore(opts?: { limit?: number; sort?: string }): Promise<ClawhubSearchResult> {
+export async function clawhubExplore(opts?: {
+  limit?: number;
+  sort?: string;
+}): Promise<ClawhubSearchResult> {
   const limit = String(opts?.limit ?? 25);
-  const sort = opts?.sort ?? 'installsAllTime';
+  const sort = opts?.sort ?? "installsAllTime";
 
   try {
-    const result = await runClawhub(['explore', '--json', '--limit', limit, '--sort', sort]);
+    const result = await runClawhub([
+      "explore",
+      "--json",
+      "--limit",
+      limit,
+      "--sort",
+      sort,
+    ]);
     if (result.exitCode !== 0) {
       return { skills: [] };
     }
@@ -329,24 +385,27 @@ export async function clawhubExplore(opts?: { limit?: number; sort?: string }):
       if (!Array.isArray(items)) return { skills: [] };
 
       // Normalize explore response to ClawhubSearchResultItem shape
-      const skills: ClawhubSearchResultItem[] = items.map((item: Record<string, unknown>) => ({
-        name: (item.displayName as string) ?? (item.slug as string) ?? '',
-        slug: (item.slug as string) ?? '',
-        description: (item.summary as string) ?? '',
-        author: (item.author as string) ?? '',
-        stars: (item.stats as Record<string, number>)?.stars ?? 0,
-        installs: (item.stats as Record<string, number>)?.installsAllTime ?? 0,
-        version: (item.tags as Record<string, string>)?.latest ?? '',
-        createdAt: (item.createdAt as number) ?? 0,
-        source: 'clawhub',
-      }));
+      const skills: ClawhubSearchResultItem[] = items.map(
+        (item: Record<string, unknown>) => ({
+          name: (item.displayName as string) ?? (item.slug as string) ?? "",
+          slug: (item.slug as string) ?? "",
+          description: (item.summary as string) ?? "",
+          author: (item.author as string) ?? "",
+          stars: (item.stats as Record<string, number>)?.stars ?? 0,
+          installs:
+            (item.stats as Record<string, number>)?.installsAllTime ?? 0,
+          version: (item.tags as Record<string, string>)?.latest ?? "",
+          createdAt: (item.createdAt as number) ?? 0,
+          source: "clawhub",
+        }),
+      );
       return { skills };
     } catch {
       // parse failure
     }
     return { skills: [] };
   } catch (err) {
-    log.warn({ err }, 'clawhub explore failed');
+    log.warn({ err }, "clawhub explore failed");
     return { skills: [] };
   }
 }
@@ -354,7 +413,12 @@ export async function clawhubExplore(opts?: { limit?: number; sort?: string }):
 export interface ClawhubInspectResult {
   skill: { slug: string; displayName: string; summary: string };
   owner: { handle: string; displayName: string; image?: string } | null;
-  stats: { stars: number; installs: number; downloads: number; versions: number } | null;
+  stats: {
+    stars: number;
+    installs: number;
+    downloads: number;
+    versions: number;
+  } | null;
   createdAt: number | null;
   updatedAt: number | null;
   latestVersion: { version: string; changelog?: string } | null;
@@ -362,15 +426,25 @@ export interface ClawhubInspectResult {
   skillMdContent: string | null;
 }
 
-export async function clawhubInspect(slug: string): Promise<{ data?: ClawhubInspectResult; error?: string }> {
+export async function clawhubInspect(
+  slug: string,
+): Promise<{ data?: ClawhubInspectResult; error?: string }> {
   if (!validateSlug(slug)) {
     return { error: `Invalid skill slug: ${slug}` };
   }
 
   try {
-    const result = await runClawhub(['inspect', slug, '--json', '--files', '--file', 'SKILL.md']);
+    const result = await runClawhub([
+      "inspect",
+      slug,
+      "--json",
+      "--files",
+      "--file",
+      "SKILL.md",
+    ]);
     if (result.exitCode !== 0) {
-      const error = result.stderr.trim() || result.stdout.trim() || 'Unknown error';
+      const error =
+        result.stderr.trim() || result.stdout.trim() || "Unknown error";
       return { error };
     }
     try {
@@ -380,35 +454,49 @@ export async function clawhubInspect(slug: string): Promise<{ data?: ClawhubInsp
         skill: {
           slug: parsed.slug ?? slug,
           displayName: parsed.displayName ?? parsed.name ?? slug,
-          summary: parsed.summary ?? parsed.description ?? '',
+          summary: parsed.summary ?? parsed.description ?? "",
         },
-        owner: parsed.owner ? {
-          handle: parsed.owner.handle ?? parsed.owner.username ?? '',
-          displayName: parsed.owner.displayName ?? parsed.owner.name ?? '',
-          image: parsed.owner.image ?? parsed.owner.avatar ?? undefined,
-        } : null,
-        stats: parsed.stats ? {
-          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,
-        } : null,
+        owner: parsed.owner
+          ? {
+              handle: parsed.owner.handle ?? parsed.owner.username ?? "",
+              displayName: parsed.owner.displayName ?? parsed.owner.name ?? "",
+              image: parsed.owner.image ?? parsed.owner.avatar ?? undefined,
+            }
+          : null,
+        stats: parsed.stats
+          ? {
+              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,
+            }
+          : null,
         createdAt: parsed.createdAt ?? null,
         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>) => ({
-          path: (f.path as string) ?? '',
-          size: (f.size as number) ?? 0,
-          contentType: (f.contentType as string) ?? undefined,
-        })) : null,
-        skillMdContent: parsed.skillMdContent ?? parsed.fileContents?.['SKILL.md'] ?? parsed.file?.content ?? 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>) => ({
+              path: (f.path as string) ?? "",
+              size: (f.size as number) ?? 0,
+              contentType: (f.contentType as string) ?? undefined,
+            }))
+          : null,
+        skillMdContent:
+          parsed.skillMdContent ??
+          parsed.fileContents?.["SKILL.md"] ??
+          parsed.file?.content ??
+          null,
       };
       return { data };
     } catch {
-      return { error: 'Failed to parse inspect output' };
+      return { error: "Failed to parse inspect output" };
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/src/skills/include-graph.ts

@@ -1,4 +1,4 @@
-import type { SkillSummary } from '../config/skills.js';
+import type { SkillSummary } from "../config/skills.js";
 
 export interface IncludeGraphResult {
   /** Ordered list of all skill IDs visited during traversal (including the root). */
@@ -8,7 +8,9 @@ export interface IncludeGraphResult {
 /**
  * Build an index of skills by their exact ID for O(1) lookup.
  */
-export function indexCatalogById(catalog: SkillSummary[]): Map<string, SkillSummary> {
+export function indexCatalogById(
+  catalog: SkillSummary[],
+): Map<string, SkillSummary> {
   const index = new Map<string, SkillSummary>();
   for (const skill of catalog) {
     index.set(skill.id, skill);
@@ -42,19 +44,22 @@ export interface IncludeValidationSuccess {
 
 export interface IncludeValidationError {
   ok: false;
-  error: 'missing';
+  error: "missing";
   missingChildId: string;
   parentId: string;
-  path: string[];  // full path from root to the parent that referenced the missing child
+  path: string[]; // full path from root to the parent that referenced the missing child
 }
 
 export interface IncludeValidationCycleError {
   ok: false;
-  error: 'cycle';
-  cyclePath: string[];  // the IDs forming the cycle, e.g. ['a', 'b', 'c', 'a']
+  error: "cycle";
+  cyclePath: string[]; // the IDs forming the cycle, e.g. ['a', 'b', 'c', 'a']
 }
 
-export type IncludeValidationResult = IncludeValidationSuccess | IncludeValidationError | IncludeValidationCycleError;
+export type IncludeValidationResult =
+  | IncludeValidationSuccess
+  | IncludeValidationError
+  | IncludeValidationCycleError;
 
 /**
  * Validate the include graph starting from the given root skill ID.
@@ -66,23 +71,25 @@ export function validateIncludes(
   catalogIndex: Map<string, SkillSummary>,
 ): IncludeValidationResult {
   const visited: string[] = [];
-  type State = 'unseen' | 'visiting' | 'done';
+  type State = "unseen" | "visiting" | "done";
   const state = new Map<string, State>();
-  const ancestry: string[] = [];  // current DFS path for cycle reporting
+  const ancestry: string[] = []; // current DFS path for cycle reporting
 
-  function dfs(id: string): IncludeValidationError | IncludeValidationCycleError | null {
-    const currentState = state.get(id) ?? 'unseen';
+  function dfs(
+    id: string,
+  ): IncludeValidationError | IncludeValidationCycleError | null {
+    const currentState = state.get(id) ?? "unseen";
 
-    if (currentState === 'done') return null;
+    if (currentState === "done") return null;
 
-    if (currentState === 'visiting') {
+    if (currentState === "visiting") {
       // Found a cycle — build the cycle path from the point where id first appears
       const cycleStart = ancestry.indexOf(id);
       const cyclePath = [...ancestry.slice(cycleStart), id];
-      return { ok: false, error: 'cycle', cyclePath };
+      return { ok: false, error: "cycle", cyclePath };
     }
 
-    state.set(id, 'visiting');
+    state.set(id, "visiting");
     ancestry.push(id);
     visited.push(id);
 
@@ -92,7 +99,7 @@ export function validateIncludes(
         if (!catalogIndex.has(childId)) {
           return {
             ok: false,
-            error: 'missing',
+            error: "missing",
             missingChildId: childId,
             parentId: id,
             path: [...ancestry],
@@ -104,7 +111,7 @@ export function validateIncludes(
     }
 
     ancestry.pop();
-    state.set(id, 'done');
+    state.set(id, "done");
     return null;
   }