@enactprotocol/shared 2.1.23 → 2.1.28

package/src/resolver.ts

@@ -10,7 +10,12 @@
 
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { findManifestFile, loadManifest } from "./manifest/loader";
+import {
+  type LoadManifestOptions,
+  ManifestLoadError,
+  findManifestFile,
+  loadManifest,
+} from "./manifest/loader";
 import { getCacheDir, getProjectEnactDir } from "./paths";
 import { getInstalledVersion, getToolCachePath } from "./registry";
 import type { ToolLocation, ToolResolution } from "./types/manifest";
@@ -29,6 +34,22 @@ export class ToolResolveError extends Error {
   }
 }
 
+/**
+ * Result of trying to resolve a tool with error details
+ */
+export interface TryResolveResult {
+  /** The resolved tool, or null if not found/invalid */
+  resolution: ToolResolution | null;
+  /** Error that occurred during resolution, if any */
+  error?: Error;
+  /** Locations that were searched */
+  searchedLocations: string[];
+  /** Whether a manifest was found but had errors */
+  manifestFound: boolean;
+  /** Path where manifest was found (if any) */
+  manifestPath?: string;
+}
+
 /**
  * Options for tool resolution
  */
@@ -73,9 +94,14 @@ export function getToolPath(toolsDir: string, toolName: string): string {
  *
  * @param dir - Directory to check
  * @param location - The location type for metadata
+ * @param options - Options for loading the manifest
  * @returns ToolResolution or null if not found/invalid
  */
-function tryLoadFromDir(dir: string, location: ToolLocation): ToolResolution | null {
+function tryLoadFromDir(
+  dir: string,
+  location: ToolLocation,
+  options: LoadManifestOptions = {}
+): ToolResolution | null {
   if (!existsSync(dir)) {
     return null;
   }
@@ -86,7 +112,7 @@ function tryLoadFromDir(dir: string, location: ToolLocation): ToolResolution | n
   }
 
   try {
-    const loaded = loadManifest(manifestPath);
+    const loaded = loadManifest(manifestPath, options);
     return {
       manifest: loaded.manifest,
       sourceDir: dir,
@@ -103,6 +129,9 @@ function tryLoadFromDir(dir: string, location: ToolLocation): ToolResolution | n
 /**
  * Resolve a tool from a file path
  *
+ * Local/file tools are allowed to have simple names (without hierarchy)
+ * since they don't need to be published.
+ *
  * @param filePath - Path to manifest file or directory containing manifest
  * @returns ToolResolution
  * @throws ToolResolveError if not found
@@ -110,6 +139,9 @@ function tryLoadFromDir(dir: string, location: ToolLocation): ToolResolution | n
 export function resolveToolFromPath(filePath: string): ToolResolution {
   const absolutePath = isAbsolute(filePath) ? filePath : resolve(filePath);
 
+  // Local tools can have simple names (no hierarchy required)
+  const localOptions: LoadManifestOptions = { allowSimpleNames: true };
+
   // Check if it's a manifest file directly
   if (
     absolutePath.endsWith(".yaml") ||
@@ -120,7 +152,7 @@ export function resolveToolFromPath(filePath: string): ToolResolution {
       throw new ToolResolveError(`Manifest file not found: ${absolutePath}`, filePath);
     }
 
-    const loaded = loadManifest(absolutePath);
+    const loaded = loadManifest(absolutePath, localOptions);
     return {
       manifest: loaded.manifest,
       sourceDir: dirname(absolutePath),
@@ -131,7 +163,7 @@ export function resolveToolFromPath(filePath: string): ToolResolution {
   }
 
   // Treat as directory
-  const result = tryLoadFromDir(absolutePath, "file");
+  const result = tryLoadFromDir(absolutePath, "file", localOptions);
   if (result) {
     return result;
   }
@@ -256,21 +288,123 @@ export function tryResolveTool(
   toolNameOrPath: string,
   options: ResolveOptions = {}
 ): ToolResolution | null {
+  const result = tryResolveToolDetailed(toolNameOrPath, options);
+  return result.resolution;
+}
+
+/**
+ * Try to resolve a tool with detailed error information
+ *
+ * Unlike tryResolveTool, this function returns information about why
+ * resolution failed, allowing callers to provide better error messages.
+ *
+ * @param toolNameOrPath - Tool name or path
+ * @param options - Resolution options
+ * @returns TryResolveResult with resolution or error details
+ */
+export function tryResolveToolDetailed(
+  toolNameOrPath: string,
+  options: ResolveOptions = {}
+): TryResolveResult {
+  const searchedLocations: string[] = [];
+
+  // Check if it looks like a path
+  const isPath =
+    toolNameOrPath.startsWith("/") ||
+    toolNameOrPath.startsWith("./") ||
+    toolNameOrPath.startsWith("../") ||
+    toolNameOrPath.includes("\\") ||
+    existsSync(toolNameOrPath);
+
+  if (isPath) {
+    // Resolve from path
+    const absolutePath = isAbsolute(toolNameOrPath) ? toolNameOrPath : resolve(toolNameOrPath);
+    searchedLocations.push(absolutePath);
+
+    // Check if path exists
+    if (!existsSync(absolutePath)) {
+      return {
+        resolution: null,
+        searchedLocations,
+        manifestFound: false,
+      };
+    }
+
+    // Find manifest file
+    const manifestPath =
+      absolutePath.endsWith(".yaml") ||
+      absolutePath.endsWith(".yml") ||
+      absolutePath.endsWith(".md")
+        ? absolutePath
+        : findManifestFile(absolutePath);
+
+    if (!manifestPath) {
+      return {
+        resolution: null,
+        searchedLocations,
+        manifestFound: false,
+      };
+    }
+
+    // Try to load the manifest
+    try {
+      const resolution = resolveToolFromPath(toolNameOrPath);
+      return {
+        resolution,
+        searchedLocations,
+        manifestFound: true,
+        manifestPath,
+      };
+    } catch (error) {
+      // Manifest found but invalid
+      return {
+        resolution: null,
+        error: error instanceof Error ? error : new Error(String(error)),
+        searchedLocations,
+        manifestFound: true,
+        manifestPath,
+      };
+    }
+  }
+
+  // Resolve by name
   try {
-    // Check if it looks like a path
-    if (
-      toolNameOrPath.startsWith("/") ||
-      toolNameOrPath.startsWith("./") ||
-      toolNameOrPath.startsWith("../") ||
-      toolNameOrPath.includes("\\") ||
-      existsSync(toolNameOrPath)
-    ) {
-      return resolveToolFromPath(toolNameOrPath);
+    const resolution = resolveTool(toolNameOrPath, options);
+    return {
+      resolution,
+      searchedLocations: getToolSearchPaths(toolNameOrPath, options),
+      manifestFound: true,
+      manifestPath: resolution.manifestPath,
+    };
+  } catch (error) {
+    // Check if error is due to manifest validation vs not found
+    if (error instanceof ToolResolveError) {
+      return {
+        resolution: null,
+        error,
+        searchedLocations: error.searchedLocations ?? [],
+        manifestFound: false,
+      };
     }
 
-    return resolveTool(toolNameOrPath, options);
-  } catch {
-    return null;
+    // ManifestLoadError means manifest was found but invalid
+    if (error instanceof ManifestLoadError) {
+      return {
+        resolution: null,
+        error,
+        searchedLocations: getToolSearchPaths(toolNameOrPath, options),
+        manifestFound: true,
+        manifestPath: error.filePath,
+      };
+    }
+
+    // Other error
+    return {
+      resolution: null,
+      error: error instanceof Error ? error : new Error(String(error)),
+      searchedLocations: getToolSearchPaths(toolNameOrPath, options),
+      manifestFound: false,
+    };
   }
 }
 
@@ -298,7 +432,8 @@ export function resolveToolAuto(
 
   // Check if the path exists as-is (could be a relative directory without ./)
   if (existsSync(toolNameOrPath)) {
-    const result = tryLoadFromDir(resolve(toolNameOrPath), "file");
+    // Local tools can have simple names (no hierarchy required)
+    const result = tryLoadFromDir(resolve(toolNameOrPath), "file", { allowSimpleNames: true });
     if (result) {
       return result;
     }

package/tests/manifest/validator.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import {
+  isValidLocalToolName,
   isValidTimeout,
   isValidToolName,
   isValidVersion,
@@ -237,6 +238,63 @@ describe("manifest validator", () => {
     });
   });
 
+  describe("allowSimpleNames option", () => {
+    test("rejects simple names by default", () => {
+      const manifest = {
+        name: "my-tool", // No slash
+        description: "A local tool",
+      };
+
+      const result = validateManifest(manifest);
+      expect(result.valid).toBe(false);
+      expect(result.errors?.some((e) => e.path === "name")).toBe(true);
+    });
+
+    test("accepts simple names with allowSimpleNames option", () => {
+      const manifest = {
+        name: "my-tool",
+        description: "A local tool",
+      };
+
+      const result = validateManifest(manifest, { allowSimpleNames: true });
+      expect(result.valid).toBe(true);
+    });
+
+    test("accepts hierarchical names with allowSimpleNames option", () => {
+      const manifest = {
+        name: "org/tool",
+        description: "A published tool",
+      };
+
+      const result = validateManifest(manifest, { allowSimpleNames: true });
+      expect(result.valid).toBe(true);
+    });
+
+    test("still rejects invalid characters with allowSimpleNames", () => {
+      const manifest = {
+        name: "My-Tool", // Uppercase not allowed
+        description: "Invalid tool name",
+      };
+
+      const result = validateManifest(manifest, { allowSimpleNames: true });
+      expect(result.valid).toBe(false);
+    });
+
+    test("validateManifestStrict respects allowSimpleNames option", () => {
+      const manifest = {
+        name: "local-tool",
+        description: "A local tool",
+      };
+
+      // Should throw without option
+      expect(() => validateManifestStrict(manifest)).toThrow();
+
+      // Should succeed with option
+      const result = validateManifestStrict(manifest, { allowSimpleNames: true });
+      expect(result.name).toBe("local-tool");
+    });
+  });
+
   describe("warnings", () => {
     test("warns about missing recommended fields", () => {
       const manifest = {
@@ -360,6 +418,25 @@ describe("manifest validator", () => {
       });
     });
 
+    describe("isValidLocalToolName", () => {
+      test("returns true for simple names (no hierarchy)", () => {
+        expect(isValidLocalToolName("my-tool")).toBe(true);
+        expect(isValidLocalToolName("tool_name")).toBe(true);
+        expect(isValidLocalToolName("simple")).toBe(true);
+      });
+
+      test("returns true for hierarchical names", () => {
+        expect(isValidLocalToolName("org/tool")).toBe(true);
+        expect(isValidLocalToolName("acme/utils/greeter")).toBe(true);
+      });
+
+      test("returns false for invalid names", () => {
+        expect(isValidLocalToolName("My-Tool")).toBe(false); // Uppercase
+        expect(isValidLocalToolName("tool name")).toBe(false); // Space
+        expect(isValidLocalToolName("")).toBe(false);
+      });
+    });
+
     describe("isValidVersion", () => {
       test("returns true for valid semver", () => {
         expect(isValidVersion("1.0.0")).toBe(true);