@enactprotocol/shared 1.2.13 → 2.0.1

package/src/manifest/validator.ts

@@ -0,0 +1,309 @@
+/**
+ * Manifest validator using Zod
+ *
+ * Validates that parsed manifests conform to the Enact specification
+ */
+
+import { z } from "zod/v4";
+import type {
+  ToolManifest,
+  ValidationError,
+  ValidationResult,
+  ValidationWarning,
+} from "../types/manifest";
+
+// ==================== Zod Schemas ====================
+
+/**
+ * Environment variable schema
+ */
+const EnvVariableSchema = z.object({
+  description: z.string().min(1, "Description is required"),
+  secret: z.boolean().optional(),
+  default: z.string().optional(),
+});
+
+/**
+ * Author schema
+ */
+const AuthorSchema = z.object({
+  name: z.string().min(1, "Author name is required"),
+  email: z.string().email().optional(),
+  url: z.string().url().optional(),
+});
+
+/**
+ * Tool annotations schema
+ */
+const ToolAnnotationsSchema = z.object({
+  title: z.string().optional(),
+  readOnlyHint: z.boolean().optional(),
+  destructiveHint: z.boolean().optional(),
+  idempotentHint: z.boolean().optional(),
+  openWorldHint: z.boolean().optional(),
+});
+
+/**
+ * Resource requirements schema
+ */
+const ResourceRequirementsSchema = z.object({
+  memory: z.string().optional(),
+  gpu: z.string().optional(),
+  disk: z.string().optional(),
+});
+
+/**
+ * Tool example schema
+ */
+const ToolExampleSchema = z.object({
+  input: z.record(z.string(), z.unknown()).optional(),
+  output: z.unknown().optional(),
+  description: z.string().optional(),
+});
+
+/**
+ * JSON Schema validation (basic structure check)
+ * We don't fully validate JSON Schema here, just ensure it's an object
+ */
+const JsonSchemaSchema = z
+  .object({
+    type: z.string().optional(),
+    properties: z.record(z.string(), z.unknown()).optional(),
+    required: z.array(z.string()).optional(),
+    items: z.unknown().optional(),
+    enum: z.array(z.unknown()).optional(),
+    description: z.string().optional(),
+  })
+  .passthrough(); // Allow additional JSON Schema fields
+
+/**
+ * Semantic version regex
+ */
+const SEMVER_REGEX =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+/**
+ * Tool name regex - hierarchical path format
+ */
+const TOOL_NAME_REGEX = /^[a-z0-9_-]+(?:\/[a-z0-9_-]+)+$/;
+
+/**
+ * Go duration regex (used for timeout)
+ */
+const GO_DURATION_REGEX = /^(\d+)(ns|us|µs|ms|s|m|h)$/;
+
+/**
+ * Complete tool manifest schema
+ */
+const ToolManifestSchema = z
+  .object({
+    // Required fields
+    name: z
+      .string()
+      .min(1, "Tool name is required")
+      .regex(
+        TOOL_NAME_REGEX,
+        "Tool name must be hierarchical path format (e.g., 'org/tool' or 'org/category/tool')"
+      ),
+
+    description: z
+      .string()
+      .min(1, "Description is required")
+      .max(500, "Description should be 500 characters or less"),
+
+    // Recommended fields
+    enact: z.string().optional(),
+    version: z
+      .string()
+      .regex(SEMVER_REGEX, "Version must be valid semver (e.g., '1.0.0')")
+      .optional(),
+    from: z.string().optional(),
+    command: z.string().optional(),
+    timeout: z
+      .string()
+      .regex(GO_DURATION_REGEX, "Timeout must be Go duration format (e.g., '30s', '5m', '1h')")
+      .optional(),
+    license: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+
+    // Schema fields
+    inputSchema: JsonSchemaSchema.optional(),
+    outputSchema: JsonSchemaSchema.optional(),
+
+    // Environment variables
+    env: z.record(z.string(), EnvVariableSchema).optional(),
+
+    // Behavior & Resources
+    annotations: ToolAnnotationsSchema.optional(),
+    resources: ResourceRequirementsSchema.optional(),
+
+    // Documentation
+    doc: z.string().optional(),
+    authors: z.array(AuthorSchema).optional(),
+
+    // Testing
+    examples: z.array(ToolExampleSchema).optional(),
+  })
+  .passthrough(); // Allow x-* custom fields
+
+// ==================== Validation Functions ====================
+
+/**
+ * Convert Zod error to our ValidationError format
+ */
+function zodErrorToValidationErrors(zodError: z.ZodError): ValidationError[] {
+  return zodError.issues.map((issue) => ({
+    path: issue.path.join("."),
+    message: issue.message,
+    code: issue.code,
+  }));
+}
+
+/**
+ * Generate warnings for recommended but missing fields
+ */
+function generateWarnings(manifest: ToolManifest): ValidationWarning[] {
+  const warnings: ValidationWarning[] = [];
+
+  // Check for recommended fields
+  if (!manifest.enact) {
+    warnings.push({
+      path: "enact",
+      message: "Protocol version (enact) is recommended for compatibility",
+      code: "MISSING_RECOMMENDED",
+    });
+  }
+
+  if (!manifest.version) {
+    warnings.push({
+      path: "version",
+      message: "Tool version is recommended for versioning and updates",
+      code: "MISSING_RECOMMENDED",
+    });
+  }
+
+  if (!manifest.from && manifest.command) {
+    warnings.push({
+      path: "from",
+      message: "Container image (from) is recommended for reproducibility",
+      code: "MISSING_RECOMMENDED",
+    });
+  }
+
+  if (!manifest.license) {
+    warnings.push({
+      path: "license",
+      message: "License is recommended for published tools",
+      code: "MISSING_RECOMMENDED",
+    });
+  }
+
+  if (!manifest.inputSchema && manifest.command) {
+    warnings.push({
+      path: "inputSchema",
+      message: "Input schema is recommended for tools with parameters",
+      code: "MISSING_RECOMMENDED",
+    });
+  }
+
+  if (!manifest.outputSchema) {
+    warnings.push({
+      path: "outputSchema",
+      message: "Output schema is recommended for structured output validation",
+      code: "MISSING_RECOMMENDED",
+    });
+  }
+
+  // Check for potential issues
+  if (manifest.env) {
+    for (const [key, value] of Object.entries(manifest.env)) {
+      if (value.secret && value.default) {
+        warnings.push({
+          path: `env.${key}`,
+          message: "Secret variables should not have default values",
+          code: "SECRET_WITH_DEFAULT",
+        });
+      }
+    }
+  }
+
+  // Check for timeout on command tools
+  if (manifest.command && !manifest.timeout) {
+    warnings.push({
+      path: "timeout",
+      message: "Timeout is recommended for command-based tools",
+      code: "MISSING_RECOMMENDED",
+    });
+  }
+
+  return warnings;
+}
+
+/**
+ * Validate a tool manifest
+ *
+ * @param manifest - The manifest to validate (parsed but unvalidated)
+ * @returns ValidationResult with valid flag, errors, and warnings
+ */
+export function validateManifest(manifest: unknown): ValidationResult {
+  const result = ToolManifestSchema.safeParse(manifest);
+
+  if (!result.success) {
+    return {
+      valid: false,
+      errors: zodErrorToValidationErrors(result.error),
+      warnings: [],
+    };
+  }
+
+  // Generate warnings for missing recommended fields
+  const warnings = generateWarnings(result.data as ToolManifest);
+
+  return {
+    valid: true,
+    warnings: warnings.length > 0 ? warnings : undefined,
+  };
+}
+
+/**
+ * Validate and return the typed manifest
+ * Throws if validation fails
+ *
+ * @param manifest - The manifest to validate
+ * @returns The validated ToolManifest
+ * @throws Error if validation fails
+ */
+export function validateManifestStrict(manifest: unknown): ToolManifest {
+  const result = validateManifest(manifest);
+
+  if (!result.valid) {
+    const errorMessages = result.errors?.map((e) => `${e.path}: ${e.message}`).join(", ");
+    throw new Error(`Manifest validation failed: ${errorMessages}`);
+  }
+
+  return manifest as ToolManifest;
+}
+
+/**
+ * Check if a string is a valid tool name
+ */
+export function isValidToolName(name: string): boolean {
+  return TOOL_NAME_REGEX.test(name);
+}
+
+/**
+ * Check if a string is a valid semver version
+ */
+export function isValidVersion(version: string): boolean {
+  return SEMVER_REGEX.test(version);
+}
+
+/**
+ * Check if a string is a valid Go duration
+ */
+export function isValidTimeout(timeout: string): boolean {
+  return GO_DURATION_REGEX.test(timeout);
+}
+
+// Export the schema for external use
+export { ToolManifestSchema };

package/src/paths.ts

@@ -0,0 +1,108 @@
+/**
+ * Path resolution utilities for Enact directories and tool locations
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/**
+ * Scope for tool directories
+ */
+export type ToolScope = "user" | "project";
+
+/**
+ * Get the Enact home directory (~/.enact/)
+ * @returns Absolute path to ~/.enact/
+ */
+export function getEnactHome(): string {
+  return join(homedir(), ".enact");
+}
+
+/**
+ * Get the project-level .enact directory
+ * Searches up from current working directory to find .enact/
+ * NOTE: Does NOT return ~/.enact/ - that's the global home, not a project dir
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Absolute path to .enact/ or null if not found
+ */
+export function getProjectEnactDir(startDir?: string): string | null {
+  let currentDir = resolve(startDir ?? process.cwd());
+  const root = resolve("/");
+  const enactHome = getEnactHome();
+
+  // Walk up directory tree looking for .enact/
+  while (currentDir !== root) {
+    const enactDir = join(currentDir, ".enact");
+    // Skip ~/.enact/ - that's the global home, not a project directory
+    if (existsSync(enactDir) && enactDir !== enactHome) {
+      return enactDir;
+    }
+    const parentDir = resolve(currentDir, "..");
+    if (parentDir === currentDir) {
+      break; // Reached root
+    }
+    currentDir = parentDir;
+  }
+
+  return null;
+}
+
+/**
+ * Get the tools directory for specified scope
+ *
+ * NOTE: For global scope ("user"), this is DEPRECATED.
+ * Global tools are now tracked in ~/.enact/tools.json and stored in cache.
+ * Use getToolsJsonPath("global") and getToolCachePath() from ./registry instead.
+ *
+ * For project scope, this returns .enact/tools/ where project tools are copied.
+ *
+ * @param scope - 'user' for ~/.enact/tools/ (deprecated) or 'project' for .enact/tools/
+ * @param startDir - For project scope, directory to start searching from
+ * @returns Absolute path to tools directory or null if project scope and not found
+ * @deprecated Use registry.ts functions for global tools
+ */
+export function getToolsDir(scope: ToolScope, startDir?: string): string | null {
+  if (scope === "user") {
+    // DEPRECATED: Global tools now use tools.json + cache
+    // This path is kept for backward compatibility during migration
+    return join(getEnactHome(), "tools");
+  }
+
+  const projectDir = getProjectEnactDir(startDir);
+  return projectDir ? join(projectDir, "tools") : null;
+}
+
+/**
+ * Get the cache directory (~/.enact/cache/)
+ * @returns Absolute path to ~/.enact/cache/
+ */
+export function getCacheDir(): string {
+  return join(getEnactHome(), "cache");
+}
+
+/**
+ * Get the configuration file path (~/.enact/config.yaml)
+ * @returns Absolute path to ~/.enact/config.yaml
+ */
+export function getConfigPath(): string {
+  return join(getEnactHome(), "config.yaml");
+}
+
+/**
+ * Get the global .env file path (~/.enact/.env)
+ * @returns Absolute path to ~/.enact/.env
+ */
+export function getGlobalEnvPath(): string {
+  return join(getEnactHome(), ".env");
+}
+
+/**
+ * Get the project .env file path (.enact/.env)
+ * @param startDir - Directory to start searching from
+ * @returns Absolute path to .enact/.env or null if not found
+ */
+export function getProjectEnvPath(startDir?: string): string | null {
+  const projectDir = getProjectEnactDir(startDir);
+  return projectDir ? join(projectDir, ".env") : null;
+}

package/src/registry.ts

@@ -0,0 +1,219 @@
+/**
+ * Local tool registry management
+ *
+ * Manages tools.json files for tracking installed tools:
+ * - Global: ~/.enact/tools.json (installed with -g)
+ * - Project: .enact/tools.json (project dependencies)
+ *
+ * Tools are stored in cache and referenced by version in tools.json.
+ * This eliminates the need for a separate ~/.enact/tools/ directory.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getCacheDir, getEnactHome, getProjectEnactDir } from "./paths";
+
+/**
+ * Structure of tools.json file
+ */
+export interface ToolsRegistry {
+  /** Map of tool name to installed version */
+  tools: Record<string, string>;
+}
+
+/**
+ * Scope for tool registry
+ */
+export type RegistryScope = "global" | "project";
+
+/**
+ * Information about an installed tool
+ */
+export interface InstalledToolInfo {
+  name: string;
+  version: string;
+  scope: RegistryScope;
+  cachePath: string;
+}
+
+/**
+ * Get the path to tools.json for the specified scope
+ */
+export function getToolsJsonPath(scope: RegistryScope, startDir?: string): string | null {
+  if (scope === "global") {
+    return join(getEnactHome(), "tools.json");
+  }
+
+  const projectDir = getProjectEnactDir(startDir);
+  return projectDir ? join(projectDir, "tools.json") : null;
+}
+
+/**
+ * Load tools.json from the specified scope
+ * Returns empty registry if file doesn't exist
+ */
+export function loadToolsRegistry(scope: RegistryScope, startDir?: string): ToolsRegistry {
+  const registryPath = getToolsJsonPath(scope, startDir);
+
+  if (!registryPath || !existsSync(registryPath)) {
+    return { tools: {} };
+  }
+
+  try {
+    const content = readFileSync(registryPath, "utf-8");
+    const parsed = JSON.parse(content);
+    return {
+      tools: parsed.tools ?? {},
+    };
+  } catch {
+    // Return empty registry on parse error
+    return { tools: {} };
+  }
+}
+
+/**
+ * Save tools.json to the specified scope
+ */
+export function saveToolsRegistry(
+  registry: ToolsRegistry,
+  scope: RegistryScope,
+  startDir?: string
+): void {
+  let registryPath = getToolsJsonPath(scope, startDir);
+
+  // For project scope, create .enact/ directory if it doesn't exist
+  if (!registryPath && scope === "project") {
+    const projectRoot = startDir ?? process.cwd();
+    const enactDir = join(projectRoot, ".enact");
+    mkdirSync(enactDir, { recursive: true });
+    registryPath = join(enactDir, "tools.json");
+  }
+
+  if (!registryPath) {
+    throw new Error("Cannot save project registry: unable to determine registry path");
+  }
+
+  // Ensure directory exists
+  const dir = dirname(registryPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const content = JSON.stringify(registry, null, 2);
+  writeFileSync(registryPath, content, "utf-8");
+}
+
+/**
+ * Add a tool to the registry
+ */
+export function addToolToRegistry(
+  toolName: string,
+  version: string,
+  scope: RegistryScope,
+  startDir?: string
+): void {
+  const registry = loadToolsRegistry(scope, startDir);
+  registry.tools[toolName] = version;
+  saveToolsRegistry(registry, scope, startDir);
+}
+
+/**
+ * Remove a tool from the registry
+ */
+export function removeToolFromRegistry(
+  toolName: string,
+  scope: RegistryScope,
+  startDir?: string
+): boolean {
+  const registry = loadToolsRegistry(scope, startDir);
+
+  if (!(toolName in registry.tools)) {
+    return false;
+  }
+
+  delete registry.tools[toolName];
+  saveToolsRegistry(registry, scope, startDir);
+  return true;
+}
+
+/**
+ * Check if a tool is installed in the registry
+ */
+export function isToolInstalled(
+  toolName: string,
+  scope: RegistryScope,
+  startDir?: string
+): boolean {
+  const registry = loadToolsRegistry(scope, startDir);
+  return toolName in registry.tools;
+}
+
+/**
+ * Get the installed version of a tool
+ * Returns null if not installed
+ */
+export function getInstalledVersion(
+  toolName: string,
+  scope: RegistryScope,
+  startDir?: string
+): string | null {
+  const registry = loadToolsRegistry(scope, startDir);
+  return registry.tools[toolName] ?? null;
+}
+
+/**
+ * Get the cache path for an installed tool
+ */
+export function getToolCachePath(toolName: string, version: string): string {
+  const cacheDir = getCacheDir();
+  const normalizedVersion = version.startsWith("v") ? version.slice(1) : version;
+  return join(cacheDir, toolName, `v${normalizedVersion}`);
+}
+
+/**
+ * List all installed tools in a registry
+ */
+export function listInstalledTools(scope: RegistryScope, startDir?: string): InstalledToolInfo[] {
+  const registry = loadToolsRegistry(scope, startDir);
+  const tools: InstalledToolInfo[] = [];
+
+  for (const [name, version] of Object.entries(registry.tools)) {
+    tools.push({
+      name,
+      version,
+      scope,
+      cachePath: getToolCachePath(name, version),
+    });
+  }
+
+  return tools;
+}
+
+/**
+ * Get tool info if installed (checks cache path exists)
+ */
+export function getInstalledToolInfo(
+  toolName: string,
+  scope: RegistryScope,
+  startDir?: string
+): InstalledToolInfo | null {
+  const version = getInstalledVersion(toolName, scope, startDir);
+
+  if (!version) {
+    return null;
+  }
+
+  const cachePath = getToolCachePath(toolName, version);
+
+  // Verify cache exists
+  if (!existsSync(cachePath)) {
+    return null;
+  }
+
+  return {
+    name: toolName,
+    version,
+    scope,
+    cachePath,
+  };
+}