vellum 0.0.16 → 0.2.0

package/src/skills/managed-store.ts

@@ -0,0 +1,233 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getWorkspaceSkillsDir } from '../util/platform.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('managed-store');
+
+// ─── Validation ──────────────────────────────────────────────────────────────
+
+const VALID_SKILL_ID = /^[a-z0-9][a-z0-9._-]*$/;
+
+export function validateManagedSkillId(id: string): string | null {
+  if (!id || typeof id !== 'string') return 'skill_id is required';
+  if (id.includes('..') || id.includes('/') || id.includes('\\')) {
+    return 'skill_id must not contain path traversal characters';
+  }
+  if (!VALID_SKILL_ID.test(id)) {
+    return 'skill_id must start with a lowercase letter or digit and contain only lowercase letters, digits, dots, hyphens, and underscores';
+  }
+  return null;
+}
+
+// ─── Path helpers ────────────────────────────────────────────────────────────
+
+export function getManagedSkillsDir(): string {
+  return getWorkspaceSkillsDir();
+}
+
+export function getManagedSkillDir(id: string): string {
+  return join(getManagedSkillsDir(), id);
+}
+
+function getSkillsIndexPath(): string {
+  return join(getManagedSkillsDir(), 'SKILLS.md');
+}
+
+// ─── SKILL.md generation ─────────────────────────────────────────────────────
+
+export interface BuildSkillMarkdownInput {
+  name: string;
+  description: string;
+  bodyMarkdown: string;
+  emoji?: string;
+  userInvocable?: boolean;
+  disableModelInvocation?: boolean;
+  includes?: string[];
+}
+
+export function buildSkillMarkdown(input: BuildSkillMarkdownInput): string {
+  const esc = (s: string) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+  const lines: string[] = ['---'];
+  lines.push(`name: "${esc(input.name)}"`);
+  lines.push(`description: "${esc(input.description)}"`);
+  if (input.emoji) {
+    lines.push(`emoji: "${esc(input.emoji)}"`);
+  }
+  if (input.userInvocable === false) {
+    lines.push('user-invocable: false');
+  }
+  if (input.disableModelInvocation === true) {
+    lines.push('disable-model-invocation: true');
+  }
+  if (input.includes && input.includes.length > 0) {
+    lines.push(`includes: ${JSON.stringify(input.includes)}`);
+  }
+  lines.push('---');
+  lines.push('');
+  lines.push(input.bodyMarkdown);
+  // Ensure trailing newline
+  const content = lines.join('\n');
+  return content.endsWith('\n') ? content : content + '\n';
+}
+
+// ─── Atomic write ────────────────────────────────────────────────────────────
+
+function atomicWriteFile(filePath: string, content: string): void {
+  const dir = dirname(filePath);
+  const tmpPath = join(dir, `.tmp-${randomUUID()}`);
+  writeFileSync(tmpPath, content, 'utf-8');
+  renameSync(tmpPath, filePath);
+}
+
+// ─── SKILLS.md index management ──────────────────────────────────────────────
+
+function readIndexLines(): string[] {
+  const indexPath = getSkillsIndexPath();
+  if (!existsSync(indexPath)) return [];
+  return readFileSync(indexPath, 'utf-8').split('\n');
+}
+
+function writeIndexLines(lines: string[]): void {
+  const content = lines.join('\n');
+  atomicWriteFile(getSkillsIndexPath(), content.endsWith('\n') ? content : content + '\n');
+}
+
+function indexEntryRegex(id: string): RegExp {
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Match both - and * bullets, optional backticks, optional markdown link wrapping,
+  // and optional /SKILL.md suffix (inside or outside link parens)
+  return new RegExp(`^[-*]\\s+(?:\`)?(?:\\[.*?\\]\\()?${escaped}(?:/SKILL\\.md)?(?:\\))?(?:\`)?\\s*$`);
+}
+
+export function upsertSkillsIndexEntry(id: string): void {
+  const lines = readIndexLines();
+  const pattern = indexEntryRegex(id);
+  if (lines.some((line) => pattern.test(line))) {
+    return; // already present
+  }
+  // Append new entry
+  const nonEmpty = lines.filter((l) => l.trim());
+  nonEmpty.push(`- ${id}`);
+  writeIndexLines(nonEmpty);
+  log.info({ id }, 'Added managed skill to SKILLS.md index');
+}
+
+export function removeSkillsIndexEntry(id: string): void {
+  const lines = readIndexLines();
+  const pattern = indexEntryRegex(id);
+  const filtered = lines.filter((line) => !pattern.test(line));
+  if (filtered.length === lines.length) {
+    return; // not found
+  }
+  writeIndexLines(filtered.filter((l) => l.trim()));
+  log.info({ id }, 'Removed managed skill from SKILLS.md index');
+}
+
+// ─── Create / Delete ─────────────────────────────────────────────────────────
+
+export interface CreateManagedSkillParams {
+  id: string;
+  name: string;
+  description: string;
+  bodyMarkdown: string;
+  emoji?: string;
+  userInvocable?: boolean;
+  disableModelInvocation?: boolean;
+  overwrite?: boolean;
+  addToIndex?: boolean;
+  includes?: string[];
+}
+
+export interface CreateManagedSkillResult {
+  created: boolean;
+  path: string;
+  indexUpdated: boolean;
+  error?: string;
+}
+
+export function createManagedSkill(params: CreateManagedSkillParams): CreateManagedSkillResult {
+  const validationError = validateManagedSkillId(params.id);
+  if (validationError) {
+    return { created: false, path: '', indexUpdated: false, error: validationError };
+  }
+
+  if (!params.name || !params.name.trim()) {
+    return { created: false, path: '', indexUpdated: false, error: 'name is required' };
+  }
+  if (!params.description || !params.description.trim()) {
+    return { created: false, path: '', indexUpdated: false, error: 'description is required' };
+  }
+
+  const skillDir = getManagedSkillDir(params.id);
+  const skillFilePath = join(skillDir, 'SKILL.md');
+
+  if (existsSync(skillFilePath) && !params.overwrite) {
+    return {
+      created: false,
+      path: skillFilePath,
+      indexUpdated: false,
+      error: `Managed skill "${params.id}" already exists. Set overwrite=true to replace it.`,
+    };
+  }
+
+  const content = buildSkillMarkdown({
+    name: params.name,
+    description: params.description,
+    bodyMarkdown: params.bodyMarkdown,
+    emoji: params.emoji,
+    userInvocable: params.userInvocable,
+    disableModelInvocation: params.disableModelInvocation,
+    includes: params.includes,
+  });
+
+  mkdirSync(skillDir, { recursive: true });
+  atomicWriteFile(skillFilePath, content);
+  log.info({ id: params.id, path: skillFilePath }, 'Created managed skill');
+
+  let indexUpdated = false;
+  if (params.addToIndex !== false) {
+    upsertSkillsIndexEntry(params.id);
+    indexUpdated = true;
+  }
+
+  return { created: true, path: skillFilePath, indexUpdated };
+}
+
+export interface DeleteManagedSkillResult {
+  deleted: boolean;
+  indexUpdated: boolean;
+  error?: string;
+}
+
+export function deleteManagedSkill(
+  id: string,
+  removeFromIndex = true,
+): DeleteManagedSkillResult {
+  const validationError = validateManagedSkillId(id);
+  if (validationError) {
+    return { deleted: false, indexUpdated: false, error: validationError };
+  }
+
+  const skillDir = getManagedSkillDir(id);
+  if (!existsSync(skillDir)) {
+    return { deleted: false, indexUpdated: false, error: `Managed skill "${id}" not found` };
+  }
+
+  rmSync(skillDir, { recursive: true });
+  log.info({ id, path: skillDir }, 'Deleted managed skill');
+
+  let indexUpdated = false;
+  if (removeFromIndex) {
+    try {
+      removeSkillsIndexEntry(id);
+      indexUpdated = true;
+    } catch (err) {
+      // Best-effort: skill dir is already gone, don't fail the whole delete
+      log.warn({ id, err }, 'Failed to update skills index after deleting managed skill');
+    }
+  }
+
+  return { deleted: true, indexUpdated };
+}

package/src/skills/path-classifier.ts

@@ -0,0 +1,128 @@
+import { realpathSync, existsSync } from 'node:fs';
+import { basename, dirname, resolve, normalize, sep } from 'node:path';
+import { getWorkspaceSkillsDir } from '../util/platform.js';
+import { getBundledSkillsDir } from '../config/skills.js';
+
+/**
+ * Returns the managed skills root directory. Managed skills are user-installed
+ * skills that live under ~/.vellum/workspace/skills.
+ */
+export function getManagedSkillsRoot(): string {
+  return normalizeDirPath(getWorkspaceSkillsDir());
+}
+
+/**
+ * Returns the bundled skills root directory. Bundled skills ship with the
+ * application binary and are read-only.
+ */
+export function getBundledSkillsRoot(): string {
+  return normalizeDirPath(getBundledSkillsDir());
+}
+
+/**
+ * Normalizes a directory path to a canonical form suitable for prefix
+ * comparison. Resolves relative segments and ensures a trailing separator
+ * so that "/foo/bar" won't false-match "/foo/barbaz".
+ *
+ * When the path exists on disk, realpath is used to resolve symlinks.
+ * Otherwise resolve() is used for pure lexical normalization.
+ */
+export function normalizeDirPath(dirPath: string): string {
+  // If the path exists, resolve symlinks directly
+  if (existsSync(dirPath)) {
+    const resolved = realpathSync(dirPath);
+    const normalized = normalize(resolved);
+    return normalized.endsWith(sep) ? normalized : normalized + sep;
+  }
+
+  // Walk up to find the nearest existing ancestor and resolve through it
+  // (mirrors normalizeFilePath behavior for consistency)
+  const absPath = resolve(dirPath);
+  const segments: string[] = [];
+  let current = absPath;
+  while (current !== dirname(current)) {
+    if (existsSync(current)) {
+      const realBase = realpathSync(current);
+      const tail = segments.reduceRight((acc, seg) => acc + sep + seg, '');
+      const full = normalize(realBase + tail);
+      return full.endsWith(sep) ? full : full + sep;
+    }
+    segments.push(basename(current));
+    current = dirname(current);
+  }
+
+  // Nothing on the path exists — fall back to pure lexical resolution
+  const normalized = normalize(absPath);
+  return normalized.endsWith(sep) ? normalized : normalized + sep;
+}
+
+/**
+ * Normalizes an absolute file path for comparison. Resolves symlinks
+ * through the nearest existing ancestor so that a symlinked parent
+ * directory is detected even when the leaf file doesn't exist yet.
+ */
+export function normalizeFilePath(filePath: string): string {
+  if (existsSync(filePath)) {
+    return realpathSync(filePath);
+  }
+
+  // Walk up until we find an ancestor that exists on disk, resolve it,
+  // then re-append the tail segments. This catches symlinked parent dirs.
+  const resolved = resolve(filePath);
+  const segments: string[] = [];
+  let current = resolved;
+  while (current !== dirname(current)) {
+    if (existsSync(current)) {
+      const realBase = realpathSync(current);
+      return segments.reduceRight((acc, seg) => acc + sep + seg, realBase);
+    }
+    segments.push(basename(current));
+    current = dirname(current);
+  }
+
+  // Nothing on the path exists — fall back to pure lexical resolution
+  return resolved;
+}
+
+/**
+ * Returns all known skill root directories as normalized paths with trailing
+ * separators. Additional roots (e.g. workspace-local skill directories) can
+ * be passed via the `extraRoots` parameter.
+ */
+export function getSkillRoots(extraRoots?: string[]): string[] {
+  const roots = [
+    getManagedSkillsRoot(),
+    getBundledSkillsRoot(),
+  ];
+  if (extraRoots) {
+    for (const root of extraRoots) {
+      roots.push(normalizeDirPath(root));
+    }
+  }
+  return roots;
+}
+
+/**
+ * Checks whether an absolute path falls under any known skill directory.
+ *
+ * Returns true if the path is inside the managed skills dir, the bundled
+ * skills dir, or any of the provided extra roots. The check is
+ * symlink-safe: both the candidate path and the skill roots are resolved
+ * through realpath when the paths exist on disk.
+ *
+ * @param absPath  - The absolute path to classify.
+ * @param extraRoots - Optional additional skill root directories to check.
+ * @returns true if the path is inside any skill directory.
+ */
+export function isSkillSourcePath(absPath: string, extraRoots?: string[]): boolean {
+  const normalizedPath = normalizeFilePath(absPath);
+  const roots = getSkillRoots(extraRoots);
+
+  for (const root of roots) {
+    if (normalizedPath.startsWith(root)) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/skills/slash-commands.ts

@@ -0,0 +1,174 @@
+import type { SkillSummary } from '../config/skills.js';
+import type { ResolvedSkill } from '../config/skill-state.js';
+
+/**
+ * Parse whether user input starts with a slash-like command token.
+ *
+ * Rules:
+ * - Trim leading whitespace.
+ * - Only inspect the first whitespace-delimited token.
+ * - A candidate token must begin with `/`.
+ * - Return `none` for empty input.
+ */
+
+export function extractLeadingToken(input: string): string | null {
+  const trimmed = input.trimStart();
+  if (!trimmed) return null;
+  const firstToken = trimmed.split(/\s/)[0];
+  return firstToken || null;
+}
+
+export function parseSlashCandidate(input: string): { kind: 'none' | 'candidate'; token?: string } {
+  const token = extractLeadingToken(input);
+  if (!token || !token.startsWith('/')) {
+    return { kind: 'none' };
+  }
+  if (isPathLikeSlashToken(token)) {
+    return { kind: 'none' };
+  }
+  const id = token.slice(1);
+  if (!isValidSlashSkillId(id)) {
+    return { kind: 'none' };
+  }
+  return { kind: 'candidate', token };
+}
+
+/** Validate that a slash skill ID starts with alphanumeric and contains only [A-Za-z0-9._-] */
+export function isValidSlashSkillId(id: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id);
+}
+
+/** Detect filesystem-like paths: tokens containing more than one `/` */
+export function isPathLikeSlashToken(token: string): boolean {
+  // Count slashes — a single leading `/` is expected, but any additional `/` means it's a path
+  const slashCount = token.split('/').length - 1;
+  return slashCount > 1;
+}
+
+// ─── Invocable slash skill catalog ──────────────────────────────────────────
+
+export interface InvocableSlashSkill {
+  canonicalId: string;
+  name: string;
+  summary: SkillSummary;
+}
+
+/**
+ * Build a map of slash-invocable skills keyed by lowercase ID for
+ * case-insensitive lookup. Only includes skills that are `userInvocable`
+ * and whose resolved state is not `disabled`.
+ */
+export function buildInvocableSlashCatalog(
+  catalog: SkillSummary[],
+  resolvedStates: ResolvedSkill[],
+): Map<string, InvocableSlashSkill> {
+  const stateById = new Map<string, ResolvedSkill>();
+  for (const rs of resolvedStates) {
+    stateById.set(rs.summary.id, rs);
+  }
+
+  const result = new Map<string, InvocableSlashSkill>();
+  for (const skill of catalog) {
+    if (!skill.userInvocable) continue;
+    const resolved = stateById.get(skill.id);
+    if (!resolved || resolved.state === 'disabled') continue;
+    result.set(skill.id.toLowerCase(), {
+      canonicalId: skill.id,
+      name: skill.name,
+      summary: skill,
+    });
+  }
+  return result;
+}
+
+// ─── Slash command resolution ────────────────────────────────────────────────
+
+export type SlashResolution =
+  | { kind: 'none' }
+  | { kind: 'known'; skillId: string; trailingArgs: string }
+  | { kind: 'unknown'; requestedId: string; message: string };
+
+/**
+ * Resolve user input against the invocable slash catalog.
+ *
+ * Returns:
+ * - `none` if input is not a slash candidate (normal text, path, etc.)
+ * - `known` if the slash ID matches an invocable skill (case-insensitive)
+ * - `unknown` if it's a valid slash candidate but no matching skill exists
+ */
+export function resolveSlashSkillCommand(
+  input: string,
+  catalog: Map<string, InvocableSlashSkill>,
+): SlashResolution {
+  const candidate = parseSlashCandidate(input);
+  if (candidate.kind === 'none') {
+    return { kind: 'none' };
+  }
+
+  const token = candidate.token!;
+  const requestedId = token.slice(1);
+  const lookupKey = requestedId.toLowerCase();
+
+  // Extract trailing args: everything after the first token
+  const trimmed = input.trimStart();
+  const firstSpaceIdx = trimmed.search(/\s/);
+  const trailingArgs = firstSpaceIdx === -1 ? '' : trimmed.slice(firstSpaceIdx).trim();
+
+  const match = catalog.get(lookupKey);
+  if (match) {
+    return { kind: 'known', skillId: match.canonicalId, trailingArgs };
+  }
+
+  const availableIds = Array.from(catalog.values())
+    .map((s) => s.canonicalId)
+    .sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
+  return {
+    kind: 'unknown',
+    requestedId,
+    message: formatUnknownSlashSkillMessage(requestedId, availableIds),
+  };
+}
+
+/**
+ * Build a deterministic error message for an unknown slash command.
+ */
+export function formatUnknownSlashSkillMessage(
+  requestedId: string,
+  availableSkillIds: string[],
+): string {
+  const lines = [`Unknown command \`/${requestedId}\`.`];
+  if (availableSkillIds.length > 0) {
+    lines.push('');
+    lines.push('Available slash commands:');
+    for (const id of availableSkillIds) {
+      lines.push(`- \`/${id}\``);
+    }
+  } else {
+    lines.push('');
+    lines.push('No slash commands are currently available.');
+  }
+  return lines.join('\n');
+}
+
+// ─── Prompt rewrite for known slash commands ─────────────────────────────────
+
+/**
+ * Rewrite user input for a known slash command into a model-facing prompt
+ * that explicitly instructs the model to invoke the skill.
+ */
+export function rewriteKnownSlashCommandPrompt(params: {
+  rawInput: string;
+  skillId: string;
+  skillName: string;
+  trailingArgs: string;
+}): string {
+  const lines = [
+    `The user invoked the slash command \`/${params.skillId}\`.`,
+    `Please invoke the "${params.skillName}" skill (ID: ${params.skillId}).`,
+  ];
+  if (params.trailingArgs) {
+    lines.push('');
+    lines.push(`User arguments: ${params.trailingArgs}`);
+  }
+  return lines.join('\n');
+}

package/src/skills/tool-manifest.ts

@@ -0,0 +1,165 @@
+import { readFileSync } from 'node:fs';
+import type { SkillToolManifest, SkillToolEntry } from '../config/skills.js';
+
+const VALID_RISK_LEVELS = new Set(['low', 'medium', 'high']);
+const VALID_EXECUTION_TARGETS = new Set(['host', 'sandbox']);
+
+/**
+ * Parse and validate a raw TOOLS.json payload into a typed SkillToolManifest.
+ * Throws descriptive errors for any validation failure.
+ */
+export function parseToolManifest(raw: unknown): SkillToolManifest {
+  if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error('TOOLS.json must be a JSON object');
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  // Validate version
+  if (!('version' in obj)) {
+    throw new Error('TOOLS.json is missing required field "version"');
+  }
+  if (obj.version !== 1) {
+    throw new Error(`TOOLS.json "version" must be 1, got: ${JSON.stringify(obj.version)}`);
+  }
+
+  // Validate tools array
+  if (!('tools' in obj)) {
+    throw new Error('TOOLS.json is missing required field "tools"');
+  }
+  if (!Array.isArray(obj.tools)) {
+    throw new Error('TOOLS.json "tools" must be an array');
+  }
+  if (obj.tools.length === 0) {
+    throw new Error('TOOLS.json "tools" must contain at least one tool entry');
+  }
+
+  const tools: SkillToolEntry[] = [];
+  const seenNames = new Set<string>();
+
+  for (let i = 0; i < obj.tools.length; i++) {
+    const entry = obj.tools[i];
+    const prefix = `TOOLS.json tools[${i}]`;
+    const tool = parseToolEntry(entry, prefix);
+
+    if (seenNames.has(tool.name)) {
+      throw new Error(`${prefix}: duplicate tool name "${tool.name}"`);
+    }
+    seenNames.add(tool.name);
+
+    tools.push(tool);
+  }
+
+  return { version: 1, tools };
+}
+
+function parseToolEntry(raw: unknown, prefix: string): SkillToolEntry {
+  if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${prefix}: each tool entry must be a JSON object`);
+  }
+
+  const entry = raw as Record<string, unknown>;
+
+  // name
+  if (!('name' in entry) || typeof entry.name !== 'string') {
+    throw new Error(`${prefix}: missing or non-string "name"`);
+  }
+  const name = entry.name.trim();
+  if (name.length === 0) {
+    throw new Error(`${prefix}: "name" must be a non-empty string`);
+  }
+
+  // description
+  if (!('description' in entry) || typeof entry.description !== 'string') {
+    throw new Error(`${prefix}: missing or non-string "description"`);
+  }
+  const description = entry.description.trim();
+  if (description.length === 0) {
+    throw new Error(`${prefix}: "description" must be a non-empty string`);
+  }
+
+  // category
+  if (!('category' in entry) || typeof entry.category !== 'string') {
+    throw new Error(`${prefix}: missing or non-string "category"`);
+  }
+  const category = entry.category.trim();
+  if (category.length === 0) {
+    throw new Error(`${prefix}: "category" must be a non-empty string`);
+  }
+
+  // risk
+  if (!('risk' in entry) || typeof entry.risk !== 'string') {
+    throw new Error(`${prefix}: missing or non-string "risk"`);
+  }
+  if (!VALID_RISK_LEVELS.has(entry.risk)) {
+    throw new Error(`${prefix}: "risk" must be one of "low", "medium", "high", got: "${entry.risk}"`);
+  }
+  const risk = entry.risk as SkillToolEntry['risk'];
+
+  // input_schema
+  if (!('input_schema' in entry) || entry.input_schema === null || typeof entry.input_schema !== 'object' || Array.isArray(entry.input_schema)) {
+    throw new Error(`${prefix}: missing or non-object "input_schema"`);
+  }
+  const input_schema = entry.input_schema as Record<string, unknown>;
+
+  // executor
+  if (!('executor' in entry) || typeof entry.executor !== 'string') {
+    throw new Error(`${prefix}: missing or non-string "executor"`);
+  }
+  const executor = entry.executor;
+  if (executor.length === 0) {
+    throw new Error(`${prefix}: "executor" must be a non-empty string`);
+  }
+  validateExecutorPath(executor, prefix);
+
+  // execution_target
+  if (!('execution_target' in entry) || typeof entry.execution_target !== 'string') {
+    throw new Error(`${prefix}: missing or non-string "execution_target"`);
+  }
+  if (!VALID_EXECUTION_TARGETS.has(entry.execution_target)) {
+    throw new Error(`${prefix}: "execution_target" must be one of "host", "sandbox", got: "${entry.execution_target}"`);
+  }
+  const execution_target = entry.execution_target as SkillToolEntry['execution_target'];
+
+  return { name, description, category, risk, input_schema, executor, execution_target };
+}
+
+/**
+ * Enforce that executor paths are relative and don't escape the skill directory.
+ * Rejects absolute paths and paths containing `../`.
+ */
+function validateExecutorPath(executor: string, prefix: string): void {
+  if (executor.startsWith('/')) {
+    throw new Error(`${prefix}: "executor" must be a relative path, got absolute path: "${executor}"`);
+  }
+  // Reject path traversal sequences
+  const segments = executor.split('/');
+  for (const segment of segments) {
+    if (segment === '..') {
+      throw new Error(`${prefix}: "executor" must not contain ".." path segments: "${executor}"`);
+    }
+  }
+}
+
+/**
+ * Read and parse a TOOLS.json file from disk.
+ */
+export function parseToolManifestFile(filePath: string): SkillToolManifest {
+  let content: string;
+  try {
+    content = readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to read TOOLS.json at "${filePath}": ${message}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to parse TOOLS.json at "${filePath}" as JSON: ${message}`);
+  }
+
+  return parseToolManifest(parsed);
+}