@enactprotocol/shared 2.2.1 → 2.2.4

package/src/registry.ts

@@ -19,6 +19,8 @@ import { getCacheDir, getEnactHome, getProjectEnactDir } from "./paths";
 export interface ToolsRegistry {
   /** Map of tool name to installed version */
   tools: Record<string, string>;
+  /** Map of alias to full tool name */
+  aliases?: Record<string, string>;
 }
 
 /**
@@ -56,7 +58,7 @@ export function loadToolsRegistry(scope: RegistryScope, startDir?: string): Tool
   const registryPath = getToolsJsonPath(scope, startDir);
 
   if (!registryPath || !existsSync(registryPath)) {
-    return { tools: {} };
+    return { tools: {}, aliases: {} };
   }
 
   try {
@@ -64,10 +66,11 @@ export function loadToolsRegistry(scope: RegistryScope, startDir?: string): Tool
     const parsed = JSON.parse(content);
     return {
       tools: parsed.tools ?? {},
+      aliases: parsed.aliases ?? {},
     };
   } catch {
     // Return empty registry on parse error
-    return { tools: {} };
+    return { tools: {}, aliases: {} };
   }
 }
 
@@ -217,3 +220,129 @@ export function getInstalledToolInfo(
     cachePath,
   };
 }
+
+/**
+ * Add an alias for a tool
+ * @param alias - Short name for the tool (e.g., "firebase")
+ * @param toolName - Full tool name (e.g., "user/api/firebase")
+ * @param scope - Registry scope (global or project)
+ * @param startDir - Starting directory for project scope
+ * @throws Error if alias already exists for a different tool
+ */
+export function addAlias(
+  alias: string,
+  toolName: string,
+  scope: RegistryScope,
+  startDir?: string
+): void {
+  const registry = loadToolsRegistry(scope, startDir);
+
+  // Initialize aliases if not present
+  if (!registry.aliases) {
+    registry.aliases = {};
+  }
+
+  // Check if alias already exists for a different tool
+  const existingTarget = registry.aliases[alias];
+  if (existingTarget && existingTarget !== toolName) {
+    throw new Error(
+      `Alias "${alias}" already exists for tool "${existingTarget}". Remove it first with 'enact alias --remove ${alias}'.`
+    );
+  }
+
+  registry.aliases[alias] = toolName;
+  saveToolsRegistry(registry, scope, startDir);
+}
+
+/**
+ * Remove an alias
+ * @param alias - Alias to remove
+ * @param scope - Registry scope
+ * @param startDir - Starting directory for project scope
+ * @returns true if alias was removed, false if it didn't exist
+ */
+export function removeAlias(alias: string, scope: RegistryScope, startDir?: string): boolean {
+  const registry = loadToolsRegistry(scope, startDir);
+
+  if (!registry.aliases || !(alias in registry.aliases)) {
+    return false;
+  }
+
+  delete registry.aliases[alias];
+  saveToolsRegistry(registry, scope, startDir);
+  return true;
+}
+
+/**
+ * Resolve an alias to its full tool name
+ * @param alias - Alias to resolve
+ * @param scope - Registry scope
+ * @param startDir - Starting directory for project scope
+ * @returns Full tool name or null if alias doesn't exist
+ */
+export function resolveAlias(
+  alias: string,
+  scope: RegistryScope,
+  startDir?: string
+): string | null {
+  const registry = loadToolsRegistry(scope, startDir);
+  return registry.aliases?.[alias] ?? null;
+}
+
+/**
+ * Get all aliases for a specific tool
+ * @param toolName - Full tool name
+ * @param scope - Registry scope
+ * @param startDir - Starting directory for project scope
+ * @returns Array of aliases for the tool
+ */
+export function getAliasesForTool(
+  toolName: string,
+  scope: RegistryScope,
+  startDir?: string
+): string[] {
+  const registry = loadToolsRegistry(scope, startDir);
+  const aliases: string[] = [];
+
+  if (registry.aliases) {
+    for (const [alias, target] of Object.entries(registry.aliases)) {
+      if (target === toolName) {
+        aliases.push(alias);
+      }
+    }
+  }
+
+  return aliases;
+}
+
+/**
+ * Remove all aliases for a specific tool
+ * Useful when uninstalling a tool
+ * @param toolName - Full tool name
+ * @param scope - Registry scope
+ * @param startDir - Starting directory for project scope
+ * @returns Number of aliases removed
+ */
+export function removeAliasesForTool(
+  toolName: string,
+  scope: RegistryScope,
+  startDir?: string
+): number {
+  const registry = loadToolsRegistry(scope, startDir);
+  let removed = 0;
+
+  if (registry.aliases) {
+    for (const [alias, target] of Object.entries(registry.aliases)) {
+      if (target === toolName) {
+        delete registry.aliases[alias];
+        removed++;
+      }
+    }
+
+    if (removed > 0) {
+      saveToolsRegistry(registry, scope, startDir);
+    }
+  }
+
+  return removed;
+}

package/src/resolver.ts

@@ -17,7 +17,7 @@ import {
   loadManifest,
 } from "./manifest/loader";
 import { getCacheDir, getProjectEnactDir } from "./paths";
-import { getInstalledVersion, getToolCachePath } from "./registry";
+import { getInstalledVersion, getToolCachePath, resolveAlias } from "./registry";
 import type { ToolLocation, ToolResolution } from "./types/manifest";
 
 /**
@@ -174,15 +174,26 @@ export function resolveToolFromPath(filePath: string): ToolResolution {
 /**
  * Resolve a tool by name, searching through standard locations
  *
- * @param toolName - Tool name (e.g., "acme/utils/greeter")
+ * @param toolName - Tool name (e.g., "acme/utils/greeter") or alias (e.g., "firebase")
  * @param options - Resolution options
  * @returns ToolResolution
  * @throws ToolResolveError if not found
  */
 export function resolveTool(toolName: string, options: ResolveOptions = {}): ToolResolution {
-  const normalizedName = normalizeToolName(toolName);
+  let normalizedName = normalizeToolName(toolName);
   const searchedLocations: string[] = [];
 
+  // Check if this might be an alias (no slashes = not a full tool name)
+  if (!normalizedName.includes("/")) {
+    // Try project-level alias first, then global
+    const aliasedName =
+      resolveAlias(normalizedName, "project", options.startDir) ??
+      resolveAlias(normalizedName, "global");
+    if (aliasedName) {
+      normalizedName = normalizeToolName(aliasedName);
+    }
+  }
+
   // 1. Try project tools (.enact/tools/{name}/)
   if (!options.skipProject) {
     const projectDir = getProjectEnactDir(options.startDir);

package/src/types/manifest.ts

@@ -134,6 +134,17 @@ export interface ToolManifest {
   /** Resource limits and requirements */
   resources?: ResourceRequirements;
 
+  // ==================== Agent Skills Spec Fields ====================
+
+  /** Environment requirements (intended product, system packages, network access, etc.) */
+  compatibility?: string;
+
+  /** Arbitrary key-value metadata for additional properties */
+  metadata?: Record<string, string>;
+
+  /** Space-delimited list of pre-approved tools the skill may use (experimental) */
+  allowedTools?: string;
+
   // ==================== Documentation ====================
 
   /** Extended documentation (Markdown) */

package/tests/manifest/validator.test.ts

@@ -182,10 +182,10 @@ describe("manifest validator", () => {
       }
     });
 
-    test("fails for description over 500 characters", () => {
+    test("fails for description over 1024 characters", () => {
       const manifest = {
         name: "org/tool",
-        description: "a".repeat(501),
+        description: "a".repeat(1025),
       };
 
       const result = validateManifest(manifest);

package/tests/registry.test.ts

@@ -6,14 +6,19 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
+  addAlias,
   addToolToRegistry,
+  getAliasesForTool,
   getInstalledVersion,
   getToolCachePath,
   getToolsJsonPath,
   isToolInstalled,
   listInstalledTools,
   loadToolsRegistry,
+  removeAlias,
+  removeAliasesForTool,
   removeToolFromRegistry,
+  resolveAlias,
   saveToolsRegistry,
 } from "../src/registry";
 
@@ -228,4 +233,194 @@ describe("registry", () => {
       expect(tools.length).toBe(0);
     });
   });
+
+  describe("addAlias", () => {
+    test("adds alias to registry", () => {
+      addToolToRegistry("test/aliased-tool", "1.0.0", "project", PROJECT_DIR);
+      addAlias("mytool", "test/aliased-tool", "project", PROJECT_DIR);
+
+      const registry = loadToolsRegistry("project", PROJECT_DIR);
+      expect(registry.aliases?.mytool).toBe("test/aliased-tool");
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+
+    test("throws error when alias already exists for different tool", () => {
+      addToolToRegistry("test/tool1", "1.0.0", "project", PROJECT_DIR);
+      addToolToRegistry("test/tool2", "1.0.0", "project", PROJECT_DIR);
+      addAlias("shared", "test/tool1", "project", PROJECT_DIR);
+
+      expect(() => {
+        addAlias("shared", "test/tool2", "project", PROJECT_DIR);
+      }).toThrow('Alias "shared" already exists for tool "test/tool1"');
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+
+    test("allows adding same alias for same tool (idempotent)", () => {
+      addToolToRegistry("test/same-tool", "1.0.0", "project", PROJECT_DIR);
+      addAlias("same", "test/same-tool", "project", PROJECT_DIR);
+
+      // Should not throw
+      expect(() => {
+        addAlias("same", "test/same-tool", "project", PROJECT_DIR);
+      }).not.toThrow();
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+  });
+
+  describe("removeAlias", () => {
+    test("removes existing alias", () => {
+      addToolToRegistry("test/removable", "1.0.0", "project", PROJECT_DIR);
+      addAlias("removeme", "test/removable", "project", PROJECT_DIR);
+
+      const removed = removeAlias("removeme", "project", PROJECT_DIR);
+      expect(removed).toBe(true);
+
+      const registry = loadToolsRegistry("project", PROJECT_DIR);
+      expect(registry.aliases?.removeme).toBeUndefined();
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+
+    test("returns false for non-existent alias", () => {
+      const removed = removeAlias("nonexistent", "project", PROJECT_DIR);
+      expect(removed).toBe(false);
+    });
+  });
+
+  describe("resolveAlias", () => {
+    test("resolves existing alias to tool name", () => {
+      addToolToRegistry("org/category/full-name", "1.0.0", "project", PROJECT_DIR);
+      addAlias("short", "org/category/full-name", "project", PROJECT_DIR);
+
+      const resolved = resolveAlias("short", "project", PROJECT_DIR);
+      expect(resolved).toBe("org/category/full-name");
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+
+    test("returns null for non-existent alias", () => {
+      const resolved = resolveAlias("unknown", "project", PROJECT_DIR);
+      expect(resolved).toBeNull();
+    });
+  });
+
+  describe("getAliasesForTool", () => {
+    test("returns all aliases for a tool", () => {
+      addToolToRegistry("test/multi-alias", "1.0.0", "project", PROJECT_DIR);
+      addAlias("alias1", "test/multi-alias", "project", PROJECT_DIR);
+      addAlias("alias2", "test/multi-alias", "project", PROJECT_DIR);
+
+      const aliases = getAliasesForTool("test/multi-alias", "project", PROJECT_DIR);
+      expect(aliases).toContain("alias1");
+      expect(aliases).toContain("alias2");
+      expect(aliases.length).toBe(2);
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+
+    test("returns empty array for tool without aliases", () => {
+      addToolToRegistry("test/no-alias", "1.0.0", "project", PROJECT_DIR);
+
+      const aliases = getAliasesForTool("test/no-alias", "project", PROJECT_DIR);
+      expect(aliases).toEqual([]);
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+  });
+
+  describe("removeAliasesForTool", () => {
+    test("removes all aliases for a tool", () => {
+      addToolToRegistry("test/cleanup", "1.0.0", "project", PROJECT_DIR);
+      addAlias("cleanup1", "test/cleanup", "project", PROJECT_DIR);
+      addAlias("cleanup2", "test/cleanup", "project", PROJECT_DIR);
+
+      const removed = removeAliasesForTool("test/cleanup", "project", PROJECT_DIR);
+      expect(removed).toBe(2);
+
+      const registry = loadToolsRegistry("project", PROJECT_DIR);
+      expect(registry.aliases?.cleanup1).toBeUndefined();
+      expect(registry.aliases?.cleanup2).toBeUndefined();
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+
+    test("returns 0 for tool without aliases", () => {
+      addToolToRegistry("test/no-aliases-to-remove", "1.0.0", "project", PROJECT_DIR);
+
+      const removed = removeAliasesForTool("test/no-aliases-to-remove", "project", PROJECT_DIR);
+      expect(removed).toBe(0);
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+
+    test("does not remove aliases for other tools", () => {
+      addToolToRegistry("test/keep", "1.0.0", "project", PROJECT_DIR);
+      addToolToRegistry("test/remove", "1.0.0", "project", PROJECT_DIR);
+      addAlias("keepme", "test/keep", "project", PROJECT_DIR);
+      addAlias("removeme", "test/remove", "project", PROJECT_DIR);
+
+      removeAliasesForTool("test/remove", "project", PROJECT_DIR);
+
+      const registry = loadToolsRegistry("project", PROJECT_DIR);
+      expect(registry.aliases?.keepme).toBe("test/keep");
+      expect(registry.aliases?.removeme).toBeUndefined();
+
+      // Clean up
+      rmSync(join(PROJECT_ENACT_DIR, "tools.json"));
+    });
+  });
+
+  describe("loadToolsRegistry with aliases", () => {
+    test("loads existing registry with aliases", () => {
+      const registryPath = join(PROJECT_ENACT_DIR, "tools.json");
+      writeFileSync(
+        registryPath,
+        JSON.stringify({
+          tools: {
+            "test/tool": "1.0.0",
+          },
+          aliases: {
+            t: "test/tool",
+          },
+        })
+      );
+
+      const registry = loadToolsRegistry("project", PROJECT_DIR);
+      expect(registry.tools["test/tool"]).toBe("1.0.0");
+      expect(registry.aliases?.t).toBe("test/tool");
+
+      // Clean up
+      rmSync(registryPath);
+    });
+
+    test("returns empty aliases when not present in file", () => {
+      const registryPath = join(PROJECT_ENACT_DIR, "tools.json");
+      writeFileSync(
+        registryPath,
+        JSON.stringify({
+          tools: {
+            "test/tool": "1.0.0",
+          },
+        })
+      );
+
+      const registry = loadToolsRegistry("project", PROJECT_DIR);
+      expect(registry.aliases).toEqual({});
+
+      // Clean up
+      rmSync(registryPath);
+    });
+  });
 });

package/tests/resolver.test.ts

@@ -1,6 +1,7 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { addAlias, addToolToRegistry, removeAlias } from "../src/registry";
 import {
   ToolResolveError,
   getToolPath,
@@ -269,4 +270,83 @@ Documentation here.
       expect(error.searchedLocations).toEqual(["/path/1", "/path/2"]);
     });
   });
+
+  describe("alias resolution", () => {
+    test("resolves tool via alias", () => {
+      // Set up an alias for the project tool
+      addToolToRegistry("test/project-tool", "1.0.0", "project", PROJECT_DIR);
+      addAlias("pt", "test/project-tool", "project", PROJECT_DIR);
+
+      try {
+        // Resolve using the alias (no slashes = potential alias)
+        const result = resolveTool("pt", { startDir: PROJECT_DIR });
+        expect(result.manifest.name).toBe("test/project-tool");
+        expect(result.location).toBe("project");
+      } finally {
+        // Clean up
+        removeAlias("pt", "project", PROJECT_DIR);
+        rmSync(join(PROJECT_ENACT_DIR, "tools.json"), { force: true });
+      }
+    });
+
+    test("alias resolution is case-insensitive (normalized to lowercase)", () => {
+      addToolToRegistry("test/project-tool", "1.0.0", "project", PROJECT_DIR);
+      addAlias("mytool", "test/project-tool", "project", PROJECT_DIR);
+
+      try {
+        // Lowercase alias should work
+        const result = resolveTool("mytool", { startDir: PROJECT_DIR });
+        expect(result.manifest.name).toBe("test/project-tool");
+
+        // Uppercase alias should also work (normalized to lowercase)
+        const upperResult = resolveTool("MYTOOL", { startDir: PROJECT_DIR });
+        expect(upperResult.manifest.name).toBe("test/project-tool");
+
+        // Mixed case should also work
+        const mixedResult = resolveTool("MyTool", { startDir: PROJECT_DIR });
+        expect(mixedResult.manifest.name).toBe("test/project-tool");
+      } finally {
+        removeAlias("mytool", "project", PROJECT_DIR);
+        rmSync(join(PROJECT_ENACT_DIR, "tools.json"), { force: true });
+      }
+    });
+
+    test("full tool names bypass alias resolution", () => {
+      addToolToRegistry("test/project-tool", "1.0.0", "project", PROJECT_DIR);
+      // Create an alias that would conflict if checked
+      addAlias("test/project-tool", "some/other/tool", "project", PROJECT_DIR);
+
+      try {
+        // Full name with slashes should resolve directly, not via alias
+        const result = resolveTool("test/project-tool", { startDir: PROJECT_DIR });
+        expect(result.manifest.name).toBe("test/project-tool");
+      } finally {
+        removeAlias("test/project-tool", "project", PROJECT_DIR);
+        rmSync(join(PROJECT_ENACT_DIR, "tools.json"), { force: true });
+      }
+    });
+
+    test("tryResolveTool works with aliases", () => {
+      addToolToRegistry("test/project-tool", "1.0.0", "project", PROJECT_DIR);
+      addAlias("try-alias", "test/project-tool", "project", PROJECT_DIR);
+
+      try {
+        const result = tryResolveTool("try-alias", { startDir: PROJECT_DIR });
+        expect(result).not.toBeNull();
+        expect(result?.manifest.name).toBe("test/project-tool");
+      } finally {
+        removeAlias("try-alias", "project", PROJECT_DIR);
+        rmSync(join(PROJECT_ENACT_DIR, "tools.json"), { force: true });
+      }
+    });
+
+    test("non-existent alias returns null from tryResolveTool", () => {
+      const result = tryResolveTool("nonexistent-alias", {
+        startDir: PROJECT_DIR,
+        skipUser: true,
+        skipCache: true,
+      });
+      expect(result).toBeNull();
+    });
+  });
 });