@enactprotocol/shared 2.1.22 → 2.1.24

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/execution/command.test.ts

@@ -431,6 +431,237 @@ describe("Command Interpolation", () => {
     });
   });
 
+  describe("knownParameters filtering", () => {
+    describe("parseCommand with knownParameters", () => {
+      test("only treats known parameters as parameters", () => {
+        const result = parseCommand("echo ${name} and ${unknown}", {
+          knownParameters: new Set(["name"]),
+        });
+
+        expect(result.parameters).toEqual(["name"]);
+        expect(result.tokens).toHaveLength(3);
+        expect(result.tokens[0]).toEqual({ type: "literal", value: "echo " });
+        expect(result.tokens[1]).toEqual({ type: "parameter", name: "name" });
+        expect(result.tokens[2]).toEqual({ type: "literal", value: " and ${unknown}" });
+      });
+
+      test("preserves bash array syntax ${#array[@]}", () => {
+        const result = parseCommand("echo ${#compliments[@]}", {
+          knownParameters: new Set(["name"]),
+        });
+
+        // The entire string should be a literal since #compliments[@] is not a known param
+        expect(result.parameters).toEqual([]);
+        expect(result.tokens).toHaveLength(1);
+        expect(result.tokens[0]).toEqual({
+          type: "literal",
+          value: "echo ${#compliments[@]}",
+        });
+      });
+
+      test("preserves bash array indexing ${array[$i]}", () => {
+        const result = parseCommand('echo "${compliments[$random_index]}"', {
+          knownParameters: new Set(["name"]),
+        });
+
+        expect(result.parameters).toEqual([]);
+        expect(result.tokens).toHaveLength(1);
+        expect(result.tokens[0]).toEqual({
+          type: "literal",
+          value: 'echo "${compliments[$random_index]}"',
+        });
+      });
+
+      test("handles mix of known params and bash syntax", () => {
+        const cmd = 'echo "${name}" and ${#arr[@]} and ${arr[$i]} and ${OTHER_VAR}';
+        const result = parseCommand(cmd, {
+          knownParameters: new Set(["name"]),
+        });
+
+        expect(result.parameters).toEqual(["name"]);
+        // Should have: literal, param, literal (containing all the bash stuff)
+        expect(result.tokens).toHaveLength(3);
+        expect(result.tokens[0]).toEqual({ type: "literal", value: "echo " });
+        expect(result.tokens[1]).toMatchObject({ type: "parameter", name: "name" });
+        expect(result.tokens[2]).toEqual({
+          type: "literal",
+          value: " and ${#arr[@]} and ${arr[$i]} and ${OTHER_VAR}",
+        });
+      });
+
+      test("legacy behavior when knownParameters not provided", () => {
+        const result = parseCommand("echo ${name} ${unknown}");
+
+        // Without knownParameters, all ${...} are treated as params
+        expect(result.parameters).toEqual(["name", "unknown"]);
+      });
+
+      test("empty knownParameters set treats nothing as parameter", () => {
+        const result = parseCommand("echo ${name} ${other}", {
+          knownParameters: new Set(),
+        });
+
+        expect(result.parameters).toEqual([]);
+        expect(result.tokens).toHaveLength(1);
+        expect(result.tokens[0]).toEqual({
+          type: "literal",
+          value: "echo ${name} ${other}",
+        });
+      });
+    });
+
+    describe("interpolateCommand with knownParameters", () => {
+      test("only substitutes known parameters", () => {
+        const result = interpolateCommand(
+          "echo ${name} and ${MY_VAR}",
+          { name: "Keith" },
+          { knownParameters: new Set(["name"]) }
+        );
+
+        expect(result).toBe("echo Keith and ${MY_VAR}");
+      });
+
+      test("preserves bash array operations", () => {
+        const cmd = 'arr=("a" "b"); echo ${#arr[@]} items: ${arr[0]}';
+        const result = interpolateCommand(
+          cmd,
+          {},
+          {
+            knownParameters: new Set(["name"]),
+          }
+        );
+
+        // Nothing should be substituted
+        expect(result).toBe(cmd);
+      });
+
+      test("substitutes only schema-defined params in complex command", () => {
+        const cmd = `
+          NAME="\${name}"
+          compliments=("Hello, $NAME!")
+          echo "\${compliments[0]}"
+        `;
+        const result = interpolateCommand(
+          cmd,
+          { name: "Alice" },
+          { knownParameters: new Set(["name"]) }
+        );
+
+        expect(result).toContain("Alice");
+        expect(result).toContain("${compliments[0]}");
+      });
+    });
+
+    describe("prepareCommand with knownParameters", () => {
+      test("passes through bash syntax while substituting known params", () => {
+        const result = prepareCommand(
+          "echo ${name} ${RANDOM}",
+          { name: "test" },
+          { knownParameters: new Set(["name"]) }
+        );
+
+        // Contains ${RANDOM} which has $, so needs shell wrap
+        expect(result).toEqual(["sh", "-c", "echo test ${RANDOM}"]);
+      });
+
+      test("handles full bash script with arrays", () => {
+        const cmd = `
+arr=("\${name}" "b" "c")
+echo \${#arr[@]}
+echo \${arr[0]}
+`;
+        const result = prepareCommand(
+          cmd,
+          { name: "Keith" },
+          {
+            knownParameters: new Set(["name"]),
+          }
+        );
+
+        // Should be shell wrapped due to special chars
+        expect(result[0]).toBe("sh");
+        expect(result[1]).toBe("-c");
+        // The name should be substituted but array syntax preserved
+        expect(result[2]).toContain("Keith");
+        expect(result[2]).toContain("${#arr[@]}");
+        expect(result[2]).toContain("${arr[0]}");
+      });
+    });
+
+    describe("getMissingParams with knownParameters", () => {
+      test("only checks known parameters", () => {
+        const result = getMissingParams(
+          "echo ${name} ${unknown}",
+          {},
+          { knownParameters: new Set(["name"]) }
+        );
+
+        // Only "name" is a known param, and it's missing
+        expect(result).toEqual(["name"]);
+      });
+
+      test("ignores unknown ${...} patterns", () => {
+        const result = getMissingParams(
+          "echo ${name} ${#arr[@]} ${arr[$i]}",
+          { name: "Keith" },
+          { knownParameters: new Set(["name"]) }
+        );
+
+        // name is provided, others are not params
+        expect(result).toEqual([]);
+      });
+    });
+
+    describe("real-world bash examples", () => {
+      test("compliment generator with bash arrays", () => {
+        const cmd = `
+compliments=(
+  "You're great, \${name}!"
+  "Keep it up, \${name}!"
+)
+random_index=$((RANDOM % \${#compliments[@]}))
+echo "\${compliments[$random_index]}"
+`;
+        const result = interpolateCommand(
+          cmd,
+          { name: "Keith" },
+          { knownParameters: new Set(["name"]) }
+        );
+
+        // ${name} should be substituted
+        expect(result).toContain("You're great, Keith!");
+        expect(result).toContain("Keep it up, Keith!");
+        // Bash syntax should be preserved
+        expect(result).toContain("${#compliments[@]}");
+        expect(result).toContain("${compliments[$random_index]}");
+      });
+
+      test("script with environment variables", () => {
+        const cmd = 'echo "Hello ${name}, your home is ${HOME}"';
+        const result = interpolateCommand(
+          cmd,
+          { name: "Alice" },
+          { knownParameters: new Set(["name"]) }
+        );
+
+        expect(result).toBe('echo "Hello Alice, your home is ${HOME}"');
+      });
+
+      test("for loop with index variable", () => {
+        const cmd = 'for i in 1 2 3; do echo "${prefix}$i"; done';
+        const result = interpolateCommand(
+          cmd,
+          { prefix: "item-" },
+          { knownParameters: new Set(["prefix"]) }
+        );
+
+        // prefix substituted, $i preserved (though not in ${} form)
+        expect(result).toContain("item-");
+        expect(result).toContain("$i");
+      });
+    });
+  });
+
   describe("getMissingParams", () => {
     test("returns empty array when all params present", () => {
       const result = getMissingParams("echo ${a} ${b}", { a: "1", b: "2" });

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);