@enactprotocol/shared 1.2.13 → 2.0.1

package/src/resolver.ts

@@ -0,0 +1,345 @@
+/**
+ * Tool resolver - finds and loads tools from various locations
+ *
+ * Resolution order:
+ * 1. Direct file path (if provided path exists)
+ * 2. Project tools (.enact/tools/{name}/)
+ * 3. Global tools (via ~/.enact/tools.json → cache)
+ * 4. Cache (~/.enact/cache/{name}/{version}/)
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { findManifestFile, loadManifest } from "./manifest/loader";
+import { getCacheDir, getProjectEnactDir } from "./paths";
+import { getInstalledVersion, getToolCachePath } from "./registry";
+import type { ToolLocation, ToolResolution } from "./types/manifest";
+
+/**
+ * Error thrown when tool resolution fails
+ */
+export class ToolResolveError extends Error {
+  constructor(
+    message: string,
+    public readonly toolPath: string,
+    public readonly searchedLocations?: string[]
+  ) {
+    super(message);
+    this.name = "ToolResolveError";
+  }
+}
+
+/**
+ * Options for tool resolution
+ */
+export interface ResolveOptions {
+  /** Starting directory for project search (defaults to cwd) */
+  startDir?: string;
+  /** Specific version to look for in cache */
+  version?: string;
+  /** Skip project-level tools */
+  skipProject?: boolean;
+  /** Skip user-level tools */
+  skipUser?: boolean;
+  /** Skip cached tools */
+  skipCache?: boolean;
+}
+
+/**
+ * Convert tool name to directory path
+ * e.g., "acme/utils/greeter" -> "acme/utils/greeter"
+ */
+export function toolNameToPath(name: string): string {
+  // Tool names are already path-like, just normalize
+  return name.replace(/\\/g, "/");
+}
+
+/**
+ * Normalize a tool name (lowercase, forward slashes)
+ */
+export function normalizeToolName(name: string): string {
+  return name.toLowerCase().replace(/\\/g, "/").trim();
+}
+
+/**
+ * Get the tool path within a tools directory
+ */
+export function getToolPath(toolsDir: string, toolName: string): string {
+  return join(toolsDir, toolNameToPath(toolName));
+}
+
+/**
+ * Try to load a tool from a specific directory
+ *
+ * @param dir - Directory to check
+ * @param location - The location type for metadata
+ * @returns ToolResolution or null if not found/invalid
+ */
+function tryLoadFromDir(dir: string, location: ToolLocation): ToolResolution | null {
+  if (!existsSync(dir)) {
+    return null;
+  }
+
+  const manifestPath = findManifestFile(dir);
+  if (!manifestPath) {
+    return null;
+  }
+
+  try {
+    const loaded = loadManifest(manifestPath);
+    return {
+      manifest: loaded.manifest,
+      sourceDir: dir,
+      location,
+      manifestPath,
+      version: loaded.manifest.version,
+    };
+  } catch {
+    // Invalid manifest, skip
+    return null;
+  }
+}
+
+/**
+ * Resolve a tool from a file path
+ *
+ * @param filePath - Path to manifest file or directory containing manifest
+ * @returns ToolResolution
+ * @throws ToolResolveError if not found
+ */
+export function resolveToolFromPath(filePath: string): ToolResolution {
+  const absolutePath = isAbsolute(filePath) ? filePath : resolve(filePath);
+
+  // Check if it's a manifest file directly
+  if (
+    absolutePath.endsWith(".yaml") ||
+    absolutePath.endsWith(".yml") ||
+    absolutePath.endsWith(".md")
+  ) {
+    if (!existsSync(absolutePath)) {
+      throw new ToolResolveError(`Manifest file not found: ${absolutePath}`, filePath);
+    }
+
+    const loaded = loadManifest(absolutePath);
+    return {
+      manifest: loaded.manifest,
+      sourceDir: dirname(absolutePath),
+      location: "file",
+      manifestPath: absolutePath,
+      version: loaded.manifest.version,
+    };
+  }
+
+  // Treat as directory
+  const result = tryLoadFromDir(absolutePath, "file");
+  if (result) {
+    return result;
+  }
+
+  throw new ToolResolveError(`No manifest found at: ${absolutePath}`, filePath);
+}
+
+/**
+ * Resolve a tool by name, searching through standard locations
+ *
+ * @param toolName - Tool name (e.g., "acme/utils/greeter")
+ * @param options - Resolution options
+ * @returns ToolResolution
+ * @throws ToolResolveError if not found
+ */
+export function resolveTool(toolName: string, options: ResolveOptions = {}): ToolResolution {
+  const normalizedName = normalizeToolName(toolName);
+  const searchedLocations: string[] = [];
+
+  // 1. Try project tools (.enact/tools/{name}/)
+  if (!options.skipProject) {
+    const projectDir = getProjectEnactDir(options.startDir);
+    if (projectDir) {
+      const projectToolsDir = join(projectDir, "tools");
+      const toolDir = getToolPath(projectToolsDir, normalizedName);
+      searchedLocations.push(toolDir);
+
+      const result = tryLoadFromDir(toolDir, "project");
+      if (result) {
+        return result;
+      }
+    }
+  }
+
+  // 2. Try global tools (via ~/.enact/tools.json → cache)
+  if (!options.skipUser) {
+    const globalVersion = getInstalledVersion(normalizedName, "global");
+    if (globalVersion) {
+      const cachePath = getToolCachePath(normalizedName, globalVersion);
+      searchedLocations.push(cachePath);
+
+      const result = tryLoadFromDir(cachePath, "user");
+      if (result) {
+        return result;
+      }
+    }
+  }
+
+  // 3. Try cache (with optional version)
+  if (!options.skipCache) {
+    const cacheDir = getCacheDir();
+    const toolCacheBase = getToolPath(cacheDir, normalizedName);
+
+    if (options.version) {
+      // Look for specific version
+      const versionDir = join(toolCacheBase, `v${options.version.replace(/^v/, "")}`);
+      searchedLocations.push(versionDir);
+
+      const result = tryLoadFromDir(versionDir, "cache");
+      if (result) {
+        return result;
+      }
+    } else {
+      // Look for latest cached version
+      if (existsSync(toolCacheBase)) {
+        const latestVersion = findLatestCachedVersion(toolCacheBase);
+        if (latestVersion) {
+          const versionDir = join(toolCacheBase, latestVersion);
+          searchedLocations.push(versionDir);
+
+          const result = tryLoadFromDir(versionDir, "cache");
+          if (result) {
+            return result;
+          }
+        }
+      }
+    }
+  }
+
+  throw new ToolResolveError(
+    `Tool not found: ${toolName}. Searched locations:\n${searchedLocations.map((l) => `  - ${l}`).join("\n")}`,
+    toolName,
+    searchedLocations
+  );
+}
+
+/**
+ * Find the latest cached version directory
+ */
+function findLatestCachedVersion(toolCacheBase: string): string | null {
+  try {
+    const entries = readdirSync(toolCacheBase, { withFileTypes: true });
+    const versions = entries
+      .filter((e) => e.isDirectory() && e.name.startsWith("v"))
+      .map((e) => e.name)
+      .sort((a, b) => {
+        // Sort by semver (v1.0.0 format)
+        const aVer = a.slice(1).split(".").map(Number);
+        const bVer = b.slice(1).split(".").map(Number);
+        for (let i = 0; i < 3; i++) {
+          if ((aVer[i] ?? 0) !== (bVer[i] ?? 0)) {
+            return (bVer[i] ?? 0) - (aVer[i] ?? 0);
+          }
+        }
+        return 0;
+      });
+
+    return versions[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Try to resolve a tool, returning null instead of throwing
+ *
+ * @param toolNameOrPath - Tool name or path
+ * @param options - Resolution options
+ * @returns ToolResolution or null
+ */
+export function tryResolveTool(
+  toolNameOrPath: string,
+  options: ResolveOptions = {}
+): ToolResolution | null {
+  try {
+    // Check if it looks like a path
+    if (
+      toolNameOrPath.startsWith("/") ||
+      toolNameOrPath.startsWith("./") ||
+      toolNameOrPath.startsWith("../") ||
+      toolNameOrPath.includes("\\") ||
+      existsSync(toolNameOrPath)
+    ) {
+      return resolveToolFromPath(toolNameOrPath);
+    }
+
+    return resolveTool(toolNameOrPath, options);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a tool, automatically detecting if input is a path or name
+ *
+ * @param toolNameOrPath - Tool name or path to manifest/directory
+ * @param options - Resolution options
+ * @returns ToolResolution
+ * @throws ToolResolveError if not found
+ */
+export function resolveToolAuto(
+  toolNameOrPath: string,
+  options: ResolveOptions = {}
+): ToolResolution {
+  // Check if it looks like a path
+  if (
+    toolNameOrPath.startsWith("/") ||
+    toolNameOrPath.startsWith("./") ||
+    toolNameOrPath.startsWith("../") ||
+    toolNameOrPath.includes("\\")
+  ) {
+    return resolveToolFromPath(toolNameOrPath);
+  }
+
+  // Check if the path exists as-is (could be a relative directory without ./)
+  if (existsSync(toolNameOrPath)) {
+    const result = tryLoadFromDir(resolve(toolNameOrPath), "file");
+    if (result) {
+      return result;
+    }
+  }
+
+  // Treat as tool name
+  return resolveTool(toolNameOrPath, options);
+}
+
+/**
+ * Get all locations where a tool might be installed
+ *
+ * @param toolName - Tool name
+ * @param options - Resolution options
+ * @returns Array of potential paths
+ */
+export function getToolSearchPaths(toolName: string, options: ResolveOptions = {}): string[] {
+  const normalizedName = normalizeToolName(toolName);
+  const paths: string[] = [];
+
+  // Project tools
+  if (!options.skipProject) {
+    const projectDir = getProjectEnactDir(options.startDir);
+    if (projectDir) {
+      paths.push(join(projectDir, "tools", toolNameToPath(normalizedName)));
+    }
+  }
+
+  // Global tools (via tools.json → cache)
+  if (!options.skipUser) {
+    const globalVersion = getInstalledVersion(normalizedName, "global");
+    if (globalVersion) {
+      paths.push(getToolCachePath(normalizedName, globalVersion));
+    }
+  }
+
+  // Cache
+  if (!options.skipCache) {
+    const cacheDir = getCacheDir();
+    paths.push(join(cacheDir, toolNameToPath(normalizedName)));
+  }
+
+  return paths;
+}

package/src/types/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Type exports from @enactprotocol/shared
+ */
+
+export type {
+  // Manifest types
+  ToolManifest,
+  PackageManifest,
+  ParsedManifest,
+  // Sub-types
+  EnvVariable,
+  EnvVariables,
+  Author,
+  ToolAnnotations,
+  ResourceRequirements,
+  ToolExample,
+  // Validation types
+  ValidationResult,
+  ValidationError,
+  ValidationWarning,
+  // Resolution types
+  ToolLocation,
+  ToolResolution,
+  ManifestFileName,
+} from "./manifest";
+
+export {
+  MANIFEST_FILES,
+  PACKAGE_MANIFEST_FILE,
+} from "./manifest";

package/src/types/manifest.ts

@@ -0,0 +1,255 @@
+/**
+ * TypeScript types for Enact tool manifests
+ * These types define the structure of enact.yaml and enact.md frontmatter
+ */
+
+import type { JSONSchema7 } from "json-schema";
+
+/**
+ * Environment variable declaration in a tool manifest
+ */
+export interface EnvVariable {
+  /** Human-readable description of what this variable is for */
+  description: string;
+  /** If true, stored in OS keyring; if false, stored in .env files */
+  secret?: boolean;
+  /** Default value if not set (only for non-secrets) */
+  default?: string;
+}
+
+/**
+ * Environment variables map
+ */
+export type EnvVariables = Record<string, EnvVariable>;
+
+/**
+ * Author information
+ */
+export interface Author {
+  /** Author name */
+  name: string;
+  /** Author email (optional) */
+  email?: string;
+  /** Author website URL (optional) */
+  url?: string;
+}
+
+/**
+ * Behavior annotations for AI models
+ */
+export interface ToolAnnotations {
+  /** Human-readable display name */
+  title?: string;
+  /** Tool does not modify the environment */
+  readOnlyHint?: boolean;
+  /** Tool may make irreversible changes */
+  destructiveHint?: boolean;
+  /** Multiple executions produce the same result */
+  idempotentHint?: boolean;
+  /** Tool interacts with external systems (network, APIs) */
+  openWorldHint?: boolean;
+}
+
+/**
+ * Resource requirements for tool execution
+ */
+export interface ResourceRequirements {
+  /** System memory needed (e.g., "512Mi", "2Gi") */
+  memory?: string;
+  /** GPU memory needed (e.g., "24Gi") */
+  gpu?: string;
+  /** Disk space needed (e.g., "100Gi") */
+  disk?: string;
+}
+
+/**
+ * Example/test case for a tool
+ */
+export interface ToolExample {
+  /** Input parameters for this example */
+  input?: Record<string, unknown>;
+  /** Expected output (for validation) */
+  output?: unknown;
+  /** Description of this test case */
+  description?: string;
+}
+
+/**
+ * Complete tool manifest structure
+ * This represents the YAML frontmatter in enact.md or the full enact.yaml
+ */
+export interface ToolManifest {
+  // ==================== Required Fields ====================
+
+  /** Hierarchical tool identifier (e.g., "org/category/tool-name") */
+  name: string;
+
+  /** Human-readable description of what the tool does */
+  description: string;
+
+  // ==================== Recommended Fields ====================
+
+  /** Version of the Enact protocol specification (e.g., "2.0.0") */
+  enact?: string;
+
+  /** Tool version in semver format (e.g., "1.2.3") */
+  version?: string;
+
+  /** Container base image for tool execution (e.g., "node:18-alpine") */
+  from?: string;
+
+  /** Build command(s) to run before execution (cached by Dagger) */
+  build?: string | string[];
+
+  /** Shell command to execute with ${parameter} substitution */
+  command?: string;
+
+  /** Maximum execution time (e.g., "30s", "5m", "1h") */
+  timeout?: string;
+
+  /** SPDX license identifier (e.g., "MIT", "Apache-2.0") */
+  license?: string;
+
+  /** Keywords for tool discovery and categorization */
+  tags?: string[];
+
+  // ==================== Schema Fields ====================
+
+  /** JSON Schema defining input parameters */
+  inputSchema?: JSONSchema7;
+
+  /** JSON Schema defining output structure */
+  outputSchema?: JSONSchema7;
+
+  // ==================== Environment Variables ====================
+
+  /** Environment variables and secrets required by the tool */
+  env?: EnvVariables;
+
+  // ==================== Behavior & Resources ====================
+
+  /** Behavior hints for AI models */
+  annotations?: ToolAnnotations;
+
+  /** Resource limits and requirements */
+  resources?: ResourceRequirements;
+
+  // ==================== Documentation ====================
+
+  /** Extended documentation (Markdown) */
+  doc?: string;
+
+  /** Tool creators and maintainers */
+  authors?: Author[];
+
+  // ==================== Testing ====================
+
+  /** Test cases and expected outputs */
+  examples?: ToolExample[];
+
+  // ==================== Custom Extensions ====================
+
+  /** Custom fields starting with x- (not included in signature verification) */
+  [key: `x-${string}`]: unknown;
+}
+
+/**
+ * Package-level configuration (enact-package.yaml)
+ * Provides shared configuration for all tools in a directory
+ */
+export interface PackageManifest {
+  /** Version of the Enact protocol specification */
+  enact?: string;
+
+  /** Shared environment variables for all tools in this folder */
+  env?: EnvVariables;
+
+  /** Shared authors for all tools */
+  authors?: Author[];
+
+  /** Shared license for all tools */
+  license?: string;
+
+  /** Custom extension fields */
+  [key: `x-${string}`]: unknown;
+}
+
+/**
+ * Parsed manifest with optional markdown body
+ */
+export interface ParsedManifest {
+  /** The parsed YAML frontmatter */
+  manifest: ToolManifest;
+  /** The markdown body content (if from .md file) */
+  body?: string | undefined;
+  /** The file format the manifest was loaded from */
+  format: "yaml" | "md";
+}
+
+/**
+ * Result of manifest validation
+ */
+export interface ValidationResult {
+  /** Whether the manifest is valid */
+  valid: boolean;
+  /** Validation errors (if any) */
+  errors?: ValidationError[] | undefined;
+  /** Warnings (non-fatal issues) */
+  warnings?: ValidationWarning[] | undefined;
+}
+
+/**
+ * A validation error
+ */
+export interface ValidationError {
+  /** Path to the field with the error (e.g., "inputSchema.properties.name") */
+  path: string;
+  /** Error message */
+  message: string;
+  /** Error code for programmatic handling */
+  code: string;
+}
+
+/**
+ * A validation warning
+ */
+export interface ValidationWarning {
+  /** Path to the field with the warning */
+  path: string;
+  /** Warning message */
+  message: string;
+  /** Warning code */
+  code: string;
+}
+
+/**
+ * Tool location types for resolution
+ */
+export type ToolLocation = "file" | "project" | "user" | "cache" | "registry";
+
+/**
+ * Result of tool resolution
+ */
+export interface ToolResolution {
+  /** The loaded and validated manifest */
+  manifest: ToolManifest;
+  /** Directory containing the tool */
+  sourceDir: string;
+  /** Where the tool was found */
+  location: ToolLocation;
+  /** Path to the manifest file */
+  manifestPath: string;
+  /** Tool version (if available) */
+  version?: string | undefined;
+}
+
+/**
+ * Supported manifest file names
+ */
+export const MANIFEST_FILES = ["enact.md", "enact.yaml", "enact.yml"] as const;
+export type ManifestFileName = (typeof MANIFEST_FILES)[number];
+
+/**
+ * Package manifest file name
+ */
+export const PACKAGE_MANIFEST_FILE = "enact-package.yaml";