@enactprotocol/shared 2.1.23 → 2.1.24

package/src/manifest/loader.ts

@@ -9,7 +9,7 @@ import { basename, join } from "node:path";
 import type { ParsedManifest, ToolManifest, ValidationResult } from "../types/manifest";
 import { MANIFEST_FILES } from "../types/manifest";
 import { ManifestParseError, parseManifestAuto } from "./parser";
-import { validateManifest } from "./validator";
+import { type ValidateManifestOptions, validateManifest } from "./validator";
 
 /**
  * Error thrown when loading a manifest fails
@@ -41,14 +41,22 @@ export interface LoadedManifest {
   warnings?: ValidationResult["warnings"];
 }
 
+/**
+ * Options for loading a manifest
+ */
+export interface LoadManifestOptions extends ValidateManifestOptions {
+  // Inherits allowSimpleNames from ValidateManifestOptions
+}
+
 /**
  * Load a manifest from a file path
  *
  * @param filePath - Path to the manifest file (SKILL.md, enact.md, enact.yaml, or enact.yml)
+ * @param options - Options for loading and validation
  * @returns LoadedManifest with validated manifest and metadata
  * @throws ManifestLoadError if file doesn't exist, parse fails, or validation fails
  */
-export function loadManifest(filePath: string): LoadedManifest {
+export function loadManifest(filePath: string, options: LoadManifestOptions = {}): LoadedManifest {
   // Check file exists
   if (!existsSync(filePath)) {
     throw new ManifestLoadError(`Manifest file not found: ${filePath}`, filePath);
@@ -82,7 +90,7 @@ export function loadManifest(filePath: string): LoadedManifest {
   }
 
   // Validate the manifest
-  const validation = validateManifest(parsed.manifest);
+  const validation = validateManifest(parsed.manifest, options);
 
   if (!validation.valid) {
     const errorMessages =
@@ -114,15 +122,19 @@ export function loadManifest(filePath: string): LoadedManifest {
  * Searches for SKILL.md, enact.md, enact.yaml, or enact.yml in the given directory
  *
  * @param dir - Directory to search for manifest
+ * @param options - Options for loading and validation
  * @returns LoadedManifest if found
  * @throws ManifestLoadError if no manifest found or loading fails
  */
-export function loadManifestFromDir(dir: string): LoadedManifest {
+export function loadManifestFromDir(
+  dir: string,
+  options: LoadManifestOptions = {}
+): LoadedManifest {
   // Try each manifest filename in order of preference
   for (const filename of MANIFEST_FILES) {
     const filePath = join(dir, filename);
     if (existsSync(filePath)) {
-      return loadManifest(filePath);
+      return loadManifest(filePath, options);
     }
   }
 
@@ -162,11 +174,15 @@ export function hasManifest(dir: string): boolean {
  * Try to load a manifest, returning null instead of throwing
  *
  * @param filePath - Path to the manifest file
+ * @param options - Options for loading and validation
  * @returns LoadedManifest or null if loading fails
  */
-export function tryLoadManifest(filePath: string): LoadedManifest | null {
+export function tryLoadManifest(
+  filePath: string,
+  options: LoadManifestOptions = {}
+): LoadedManifest | null {
   try {
-    return loadManifest(filePath);
+    return loadManifest(filePath, options);
   } catch {
     return null;
   }
@@ -176,11 +192,15 @@ export function tryLoadManifest(filePath: string): LoadedManifest | null {
  * Try to load a manifest from a directory, returning null instead of throwing
  *
  * @param dir - Directory to search
+ * @param options - Options for loading and validation
  * @returns LoadedManifest or null if no manifest found or loading fails
  */
-export function tryLoadManifestFromDir(dir: string): LoadedManifest | null {
+export function tryLoadManifestFromDir(
+  dir: string,
+  options: LoadManifestOptions = {}
+): LoadedManifest | null {
   try {
-    return loadManifestFromDir(dir);
+    return loadManifestFromDir(dir, options);
   } catch {
     return null;
   }

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/resolver.ts

@@ -10,7 +10,7 @@
 
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { findManifestFile, loadManifest } from "./manifest/loader";
+import { type LoadManifestOptions, findManifestFile, loadManifest } from "./manifest/loader";
 import { getCacheDir, getProjectEnactDir } from "./paths";
 import { getInstalledVersion, getToolCachePath } from "./registry";
 import type { ToolLocation, ToolResolution } from "./types/manifest";
@@ -73,9 +73,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 +91,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 +108,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 +118,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 +131,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 +142,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;
   }
@@ -298,7 +309,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);