@enactprotocol/shared 2.1.23 → 2.1.28

package/src/manifest/validator.ts

@@ -83,68 +83,85 @@ 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
+ * Tool name regex - hierarchical path format (required for publishing)
  */
 const TOOL_NAME_REGEX = /^[a-z0-9_-]+(?:\/[a-z0-9_-]+)+$/;
 
+/**
+ * Tool name regex - simple format (allowed for local tools)
+ * Allows both hierarchical (org/tool) and simple (my-tool) names
+ */
+const TOOL_NAME_REGEX_LOCAL = /^[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
+ * Create a tool manifest schema with configurable name validation
  */
-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
+function createToolManifestSchema(allowSimpleNames: boolean) {
+  const nameRegex = allowSimpleNames ? TOOL_NAME_REGEX_LOCAL : TOOL_NAME_REGEX;
+  const nameMessage = allowSimpleNames
+    ? "Tool name must contain only lowercase letters, numbers, hyphens, and underscores"
+    : "Tool name must be hierarchical path format (e.g., 'org/tool' or 'org/category/tool')";
+
+  return z
+    .object({
+      // Required fields
+      name: z.string().min(1, "Tool name is required").regex(nameRegex, nameMessage),
+
+      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
+}
+
+/**
+ * Complete tool manifest schema (strict - requires hierarchical names)
+ */
+const ToolManifestSchema = createToolManifestSchema(false);
+
+/**
+ * Local tool manifest schema (relaxed - allows simple names)
+ */
+const ToolManifestSchemaLocal = createToolManifestSchema(true);
 
 // ==================== Validation Functions ====================
 
@@ -239,14 +256,31 @@ function generateWarnings(manifest: ToolManifest): ValidationWarning[] {
   return warnings;
 }
 
+/**
+ * Options for manifest validation
+ */
+export interface ValidateManifestOptions {
+  /**
+   * Allow simple tool names without hierarchy (e.g., "my-tool" instead of "org/my-tool").
+   * Use this for local tools that won't be published.
+   * @default false
+   */
+  allowSimpleNames?: boolean;
+}
+
 /**
  * Validate a tool manifest
  *
  * @param manifest - The manifest to validate (parsed but unvalidated)
+ * @param options - Validation options
  * @returns ValidationResult with valid flag, errors, and warnings
  */
-export function validateManifest(manifest: unknown): ValidationResult {
-  const result = ToolManifestSchema.safeParse(manifest);
+export function validateManifest(
+  manifest: unknown,
+  options: ValidateManifestOptions = {}
+): ValidationResult {
+  const schema = options.allowSimpleNames ? ToolManifestSchemaLocal : ToolManifestSchema;
+  const result = schema.safeParse(manifest);
 
   if (!result.success) {
     return {
@@ -270,11 +304,15 @@ export function validateManifest(manifest: unknown): ValidationResult {
  * Throws if validation fails
  *
  * @param manifest - The manifest to validate
+ * @param options - Validation options
  * @returns The validated ToolManifest
  * @throws Error if validation fails
  */
-export function validateManifestStrict(manifest: unknown): ToolManifest {
-  const result = validateManifest(manifest);
+export function validateManifestStrict(
+  manifest: unknown,
+  options: ValidateManifestOptions = {}
+): ToolManifest {
+  const result = validateManifest(manifest, options);
 
   if (!result.valid) {
     const errorMessages = result.errors?.map((e) => `${e.path}: ${e.message}`).join(", ");
@@ -285,12 +323,19 @@ export function validateManifestStrict(manifest: unknown): ToolManifest {
 }
 
 /**
- * Check if a string is a valid tool name
+ * Check if a string is a valid tool name (hierarchical format for publishing)
  */
 export function isValidToolName(name: string): boolean {
   return TOOL_NAME_REGEX.test(name);
 }
 
+/**
+ * Check if a string is a valid local tool name (allows simple names)
+ */
+export function isValidLocalToolName(name: string): boolean {
+  return TOOL_NAME_REGEX_LOCAL.test(name);
+}
+
 /**
  * Check if a string is a valid semver version
  */

package/src/mcp-registry.ts

@@ -0,0 +1,337 @@
+/**
+ * MCP tools registry management
+ *
+ * Manages mcp.json for tracking tools exposed to MCP clients:
+ * - Global only: ~/.enact/mcp.json
+ *
+ * Similar to tools.json but adds toolset management for organizing
+ * which tools are exposed to MCP clients.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getCacheDir, getEnactHome } from "./paths";
+
+/**
+ * Structure of mcp.json file
+ */
+export interface McpRegistry {
+  /** Map of tool name to installed version */
+  tools: Record<string, string>;
+  /** Named collections of tools */
+  toolsets: Record<string, string[]>;
+  /** Currently active toolset (null = expose all tools) */
+  activeToolset: string | null;
+}
+
+/**
+ * Information about an MCP-exposed tool
+ */
+export interface McpToolInfo {
+  name: string;
+  version: string;
+  cachePath: string;
+}
+
+/**
+ * Get the path to mcp.json
+ */
+export function getMcpJsonPath(): string {
+  return join(getEnactHome(), "mcp.json");
+}
+
+/**
+ * Load mcp.json
+ * Returns empty registry if file doesn't exist
+ */
+export function loadMcpRegistry(): McpRegistry {
+  const registryPath = getMcpJsonPath();
+
+  if (!existsSync(registryPath)) {
+    return { tools: {}, toolsets: {}, activeToolset: null };
+  }
+
+  try {
+    const content = readFileSync(registryPath, "utf-8");
+    const parsed = JSON.parse(content);
+    return {
+      tools: parsed.tools ?? {},
+      toolsets: parsed.toolsets ?? {},
+      activeToolset: parsed.activeToolset ?? null,
+    };
+  } catch {
+    // Return empty registry on parse error
+    return { tools: {}, toolsets: {}, activeToolset: null };
+  }
+}
+
+/**
+ * Save mcp.json
+ */
+export function saveMcpRegistry(registry: McpRegistry): void {
+  const registryPath = getMcpJsonPath();
+
+  // 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 MCP registry
+ */
+export function addMcpTool(toolName: string, version: string): void {
+  const registry = loadMcpRegistry();
+  registry.tools[toolName] = version;
+  saveMcpRegistry(registry);
+}
+
+/**
+ * Remove a tool from the MCP registry
+ */
+export function removeMcpTool(toolName: string): boolean {
+  const registry = loadMcpRegistry();
+
+  if (!(toolName in registry.tools)) {
+    return false;
+  }
+
+  delete registry.tools[toolName];
+
+  // Also remove from all toolsets
+  for (const toolsetName of Object.keys(registry.toolsets)) {
+    const toolset = registry.toolsets[toolsetName];
+    if (toolset) {
+      registry.toolsets[toolsetName] = toolset.filter((t) => t !== toolName);
+    }
+  }
+
+  saveMcpRegistry(registry);
+  return true;
+}
+
+/**
+ * Check if a tool is in the MCP registry
+ */
+export function isMcpToolInstalled(toolName: string): boolean {
+  const registry = loadMcpRegistry();
+  return toolName in registry.tools;
+}
+
+/**
+ * Get the installed version of an MCP tool
+ * Returns null if not installed
+ */
+export function getMcpToolVersion(toolName: string): string | null {
+  const registry = loadMcpRegistry();
+  return registry.tools[toolName] ?? null;
+}
+
+/**
+ * Get the cache path for an MCP tool
+ */
+function getMcpToolCachePath(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 tools that should be exposed to MCP clients
+ * If activeToolset is set, only returns tools in that toolset
+ * Otherwise returns all tools
+ */
+export function listMcpTools(): McpToolInfo[] {
+  const registry = loadMcpRegistry();
+  const tools: McpToolInfo[] = [];
+
+  // Determine which tools to expose
+  let toolsToExpose: string[];
+
+  const activeToolsetTools = registry.activeToolset
+    ? registry.toolsets[registry.activeToolset]
+    : undefined;
+
+  if (activeToolsetTools) {
+    // Filter to only tools in the active toolset that are also installed
+    toolsToExpose = activeToolsetTools.filter((name) => name in registry.tools);
+  } else {
+    // Expose all installed tools
+    toolsToExpose = Object.keys(registry.tools);
+  }
+
+  for (const name of toolsToExpose) {
+    const version = registry.tools[name];
+    if (version) {
+      tools.push({
+        name,
+        version,
+        cachePath: getMcpToolCachePath(name, version),
+      });
+    }
+  }
+
+  return tools;
+}
+
+/**
+ * Get info for a specific MCP tool if it's exposed
+ */
+export function getMcpToolInfo(toolName: string): McpToolInfo | null {
+  const registry = loadMcpRegistry();
+  const version = registry.tools[toolName];
+
+  if (!version) {
+    return null;
+  }
+
+  // Check if tool is in active toolset (if one is set)
+  if (registry.activeToolset) {
+    const activeToolsetTools = registry.toolsets[registry.activeToolset];
+    if (activeToolsetTools && !activeToolsetTools.includes(toolName)) {
+      return null; // Tool is installed but not in active toolset
+    }
+  }
+
+  const cachePath = getMcpToolCachePath(toolName, version);
+
+  // Verify cache exists
+  if (!existsSync(cachePath)) {
+    return null;
+  }
+
+  return { name: toolName, version, cachePath };
+}
+
+// Toolset management
+
+/**
+ * Create a new toolset
+ */
+export function createToolset(name: string, tools: string[] = []): void {
+  const registry = loadMcpRegistry();
+  registry.toolsets[name] = tools;
+  saveMcpRegistry(registry);
+}
+
+/**
+ * Delete a toolset
+ */
+export function deleteToolset(name: string): boolean {
+  const registry = loadMcpRegistry();
+
+  if (!(name in registry.toolsets)) {
+    return false;
+  }
+
+  delete registry.toolsets[name];
+
+  // Clear active toolset if it was the deleted one
+  if (registry.activeToolset === name) {
+    registry.activeToolset = null;
+  }
+
+  saveMcpRegistry(registry);
+  return true;
+}
+
+/**
+ * Add a tool to a toolset
+ */
+export function addToolToToolset(toolsetName: string, toolName: string): boolean {
+  const registry = loadMcpRegistry();
+
+  const toolset = registry.toolsets[toolsetName];
+  if (!toolset) {
+    return false;
+  }
+
+  if (!toolset.includes(toolName)) {
+    toolset.push(toolName);
+    saveMcpRegistry(registry);
+  }
+
+  return true;
+}
+
+/**
+ * Remove a tool from a toolset
+ */
+export function removeToolFromToolset(toolsetName: string, toolName: string): boolean {
+  const registry = loadMcpRegistry();
+
+  const toolset = registry.toolsets[toolsetName];
+  if (!toolset) {
+    return false;
+  }
+
+  const index = toolset.indexOf(toolName);
+  if (index === -1) {
+    return false;
+  }
+
+  toolset.splice(index, 1);
+  saveMcpRegistry(registry);
+  return true;
+}
+
+/**
+ * Set the active toolset
+ */
+export function setActiveToolset(name: string | null): boolean {
+  const registry = loadMcpRegistry();
+
+  if (name !== null && !(name in registry.toolsets)) {
+    return false;
+  }
+
+  registry.activeToolset = name;
+  saveMcpRegistry(registry);
+  return true;
+}
+
+/**
+ * Get the active toolset name
+ */
+export function getActiveToolset(): string | null {
+  const registry = loadMcpRegistry();
+  return registry.activeToolset;
+}
+
+/**
+ * List all toolsets
+ */
+export function listToolsets(): Array<{ name: string; tools: string[]; isActive: boolean }> {
+  const registry = loadMcpRegistry();
+
+  return Object.entries(registry.toolsets).map(([name, tools]) => ({
+    name,
+    tools,
+    isActive: registry.activeToolset === name,
+  }));
+}
+
+/**
+ * Sync MCP registry with global tools.json
+ * Adds any tools from tools.json that aren't in mcp.json
+ * Does NOT remove tools (allows mcp.json to have subset of tools.json)
+ */
+export function syncMcpWithGlobalTools(globalTools: Record<string, string>): void {
+  const registry = loadMcpRegistry();
+  let changed = false;
+
+  for (const [name, version] of Object.entries(globalTools)) {
+    if (!(name in registry.tools)) {
+      registry.tools[name] = version;
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    saveMcpRegistry(registry);
+  }
+}