@enactprotocol/shared 2.3.5 → 2.3.8

package/src/paths.ts

@@ -4,7 +4,7 @@
 
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 /**
  * Scope for tool directories
@@ -48,44 +48,81 @@ export function getProjectEnactDir(startDir?: string): string | null {
   return null;
 }
 
+/**
+ * Get the project-level agents directory
+ * Searches up from current working directory to find agents/
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Absolute path to agents/ or null if not found
+ */
+export function getProjectAgentsDir(startDir?: string): string | null {
+  let currentDir = resolve(startDir ?? process.cwd());
+  const root = resolve("/");
+
+  while (currentDir !== root) {
+    const agentsDir = join(currentDir, "agents");
+    if (existsSync(agentsDir)) {
+      return agentsDir;
+    }
+    const parentDir = resolve(currentDir, "..");
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  return null;
+}
+
+/**
+ * Get the project root directory by searching for agents/ directory
+ * @param startDir - Directory to start searching from (defaults to cwd)
+ * @returns Absolute path to the project root or the startDir/cwd as fallback
+ */
+export function getProjectRoot(startDir?: string): string {
+  const agentsDir = getProjectAgentsDir(startDir);
+  if (agentsDir) {
+    return dirname(agentsDir);
+  }
+  return resolve(startDir ?? process.cwd());
+}
+
 /**
  * Get the tools directory for specified scope
  *
  * NOTE: For global scope ("user"), this is DEPRECATED.
- * Global tools are now tracked in ~/.enact/tools.json and stored in cache.
+ * Global tools are now tracked in ~/.enact/tools.json and stored in cache (~/.agents/skills/).
  * Use getToolsJsonPath("global") and getToolCachePath() from ./registry instead.
  *
- * For project scope, this returns .enact/tools/ where project tools are copied.
+ * For project scope, this returns agents/skills/ where project tools are installed.
  *
- * @param scope - 'user' for ~/.enact/tools/ (deprecated) or 'project' for .enact/tools/
+ * @param scope - 'user' for ~/.agents/skills/ or 'project' for agents/skills/
  * @param startDir - For project scope, directory to start searching from
  * @returns Absolute path to tools directory or null if project scope and not found
  * @deprecated Use registry.ts functions for global tools
  */
 export function getToolsDir(scope: ToolScope, startDir?: string): string | null {
   if (scope === "user") {
-    // DEPRECATED: Global tools now use tools.json + cache
-    // This path is kept for backward compatibility during migration
-    return join(getEnactHome(), "tools");
+    // Global tools use ~/.agents/skills/
+    return getSkillsDir();
   }
 
-  const projectDir = getProjectEnactDir(startDir);
-  return projectDir ? join(projectDir, "tools") : null;
+  const agentsDir = getProjectAgentsDir(startDir);
+  return agentsDir ? join(agentsDir, "skills") : null;
 }
 
 /**
- * Get the skills directory (~/.agent/skills/)
+ * Get the skills directory (~/.agents/skills/)
  * This is the standard Agent Skills location for installed skills.
- * @returns Absolute path to ~/.agent/skills/
+ * @returns Absolute path to ~/.agents/skills/
  */
 export function getSkillsDir(): string {
-  return join(homedir(), ".agent", "skills");
+  return join(homedir(), ".agents", "skills");
 }
 
 /**
- * Get the cache directory (~/.agent/skills/)
+ * Get the cache directory (~/.agents/skills/)
  * @deprecated Use getSkillsDir() instead
- * @returns Absolute path to ~/.agent/skills/
+ * @returns Absolute path to ~/.agents/skills/
  */
 export function getCacheDir(): string {
   return getSkillsDir();

package/src/registry.ts

@@ -1,17 +1,16 @@
 /**
  * Local tool registry management
  *
- * Manages tools.json files for tracking installed tools:
+ * Manages skills.json files for tracking installed tools:
  * - Global: ~/.enact/tools.json (installed with -g)
- * - Project: .enact/tools.json (project dependencies)
+ * - Project: agents/skills.json (project dependencies)
  *
- * Tools are stored in cache and referenced by version in tools.json.
- * This eliminates the need for a separate ~/.enact/tools/ directory.
+ * Tools are stored in cache and referenced by version in the registry.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { getCacheDir, getEnactHome, getProjectEnactDir } from "./paths";
+import { dirname, join, resolve } from "node:path";
+import { getCacheDir, getEnactHome, getProjectAgentsDir } from "./paths";
 
 /**
  * Structure of tools.json file
@@ -39,15 +38,17 @@ export interface InstalledToolInfo {
 }
 
 /**
- * Get the path to tools.json for the specified scope
+ * Get the path to the registry file for the specified scope
+ * - Global: ~/.enact/tools.json
+ * - Project: agents/skills.json
  */
 export function getToolsJsonPath(scope: RegistryScope, startDir?: string): string | null {
   if (scope === "global") {
     return join(getEnactHome(), "tools.json");
   }
 
-  const projectDir = getProjectEnactDir(startDir);
-  return projectDir ? join(projectDir, "tools.json") : null;
+  const agentsDir = getProjectAgentsDir(startDir);
+  return agentsDir ? join(agentsDir, "skills.json") : null;
 }
 
 /**
@@ -84,12 +85,12 @@ export function saveToolsRegistry(
 ): void {
   let registryPath = getToolsJsonPath(scope, startDir);
 
-  // For project scope, create .enact/ directory if it doesn't exist
+  // For project scope, create agents/ directory if it doesn't exist
   if (!registryPath && scope === "project") {
-    const projectRoot = startDir ?? process.cwd();
-    const enactDir = join(projectRoot, ".enact");
-    mkdirSync(enactDir, { recursive: true });
-    registryPath = join(enactDir, "tools.json");
+    const projectRoot = resolve(startDir ?? process.cwd());
+    const agentsDir = join(projectRoot, "agents");
+    mkdirSync(agentsDir, { recursive: true });
+    registryPath = join(agentsDir, "skills.json");
   }
 
   if (!registryPath) {
@@ -166,7 +167,7 @@ export function getInstalledVersion(
 
 /**
  * Get the install path for a skill
- * Skills are stored at ~/.agent/skills/{name}/ (flat, no version subdirectory)
+ * Skills are stored at ~/.agents/skills/{name}/ (flat, no version subdirectory)
  */
 export function getToolCachePath(toolName: string, _version: string): string {
   const skillsDir = getCacheDir();

package/src/resolver.ts

@@ -3,9 +3,9 @@
  *
  * Resolution order:
  * 1. Direct file path (if provided path exists)
- * 2. Project tools (.enact/tools/{name}/)
- * 3. Global tools (via ~/.enact/tools.json → ~/.agent/skills/)
- * 4. Skills directory (~/.agent/skills/{name}/)
+ * 2. Project skills (agents/skills/{name}/)
+ * 3. Global tools (via ~/.enact/tools.json → ~/.agents/skills/)
+ * 4. Skills directory (~/.agents/skills/{name}/)
  */
 
 import { existsSync } from "node:fs";
@@ -18,7 +18,7 @@ import {
   loadManifestFromDir,
 } from "./manifest/loader";
 import { manifestScriptsToActionsManifest } from "./manifest/scripts";
-import { getProjectEnactDir, getSkillsDir } from "./paths";
+import { getProjectAgentsDir, getSkillsDir } from "./paths";
 import { getInstalledVersion, getToolCachePath, resolveAlias } from "./registry";
 import type { ToolLocation, ToolResolution } from "./types/manifest";
 
@@ -127,11 +127,12 @@ export function parseActionSpecifier(specifier: string): ParsedActionSpecifier {
 }
 
 /**
- * Convert tool name to directory path
- * Strips the @ prefix for disk paths: "@org/my-skill" -> "org/my-skill"
+ * Convert tool name to directory path.
+ * Preserves @ prefix for npm-style layout: "@org/my-skill" -> "@org/my-skill"
+ * User tools unchanged: "user/my-skill" -> "user/my-skill"
  */
 export function toolNameToPath(name: string): string {
-  return name.replace(/^@/, "").replace(/\\/g, "/");
+  return name.replace(/\\/g, "/");
 }
 
 /**
@@ -151,7 +152,7 @@ export function getToolPath(toolsDir: string, toolName: string): string {
 /**
  * Try to load a tool from a specific directory
  *
- * Supports two-file model (skill.yaml + SKILL.md) via loadManifestFromDir().
+ * Supports two-file model (skill.package.yml + SKILL.md) via loadManifestFromDir().
  *
  * @param dir - Directory to check
  * @param location - The location type for metadata
@@ -335,12 +336,12 @@ export function resolveTool(toolName: string, options: ResolveOptions = {}): Too
     }
   }
 
-  // 1. Try project tools (.enact/tools/{name}/)
+  // 1. Try project skills (agents/skills/{name}/)
   if (!options.skipProject) {
-    const projectDir = getProjectEnactDir(options.startDir);
-    if (projectDir) {
-      const projectToolsDir = join(projectDir, "tools");
-      const toolDir = getToolPath(projectToolsDir, normalizedName);
+    const agentsDir = getProjectAgentsDir(options.startDir);
+    if (agentsDir) {
+      const projectSkillsDir = join(agentsDir, "skills");
+      const toolDir = getToolPath(projectSkillsDir, normalizedName);
       searchedLocations.push(toolDir);
 
       const result = tryLoadFromDir(toolDir, "project");
@@ -350,7 +351,7 @@ export function resolveTool(toolName: string, options: ResolveOptions = {}): Too
     }
   }
 
-  // 2. Try global tools (via ~/.enact/tools.json → ~/.agent/skills/)
+  // 2. Try global tools (via ~/.enact/tools.json → ~/.agents/skills/)
   if (!options.skipUser) {
     const globalVersion = getInstalledVersion(normalizedName, "global");
     if (globalVersion) {
@@ -364,7 +365,7 @@ export function resolveTool(toolName: string, options: ResolveOptions = {}): Too
     }
   }
 
-  // 3. Try skills directory (~/.agent/skills/{name}/)
+  // 3. Try skills directory (~/.agents/skills/{name}/)
   if (!options.skipCache) {
     const skillsDir = getSkillsDir();
     const skillDir = getToolPath(skillsDir, normalizedName);
@@ -560,11 +561,11 @@ export function getToolSearchPaths(toolName: string, options: ResolveOptions = {
   const normalizedName = normalizeToolName(toolName);
   const paths: string[] = [];
 
-  // Project tools
+  // Project skills
   if (!options.skipProject) {
-    const projectDir = getProjectEnactDir(options.startDir);
-    if (projectDir) {
-      paths.push(join(projectDir, "tools", toolNameToPath(normalizedName)));
+    const agentsDir = getProjectAgentsDir(options.startDir);
+    if (agentsDir) {
+      paths.push(join(agentsDir, "skills", toolNameToPath(normalizedName)));
     }
   }
 

package/src/types/manifest.ts

@@ -1,6 +1,6 @@
 /**
  * TypeScript types for Enact tool manifests
- * These types define the structure of SKILL.md (and skill.yaml/legacy enact.yaml/enact.md) frontmatter
+ * These types define the structure of SKILL.md (and skill.package.yml/legacy enact.yaml/enact.md) frontmatter
  */
 
 import type { JSONSchema7 } from "json-schema";
@@ -104,7 +104,7 @@ export interface ToolExample {
 
 /**
  * Complete tool manifest structure
- * This represents the YAML frontmatter in SKILL.md (or skill.yaml/legacy enact.md/enact.yaml)
+ * This represents the YAML frontmatter in SKILL.md (or skill.package.yml/legacy enact.md/enact.yaml)
  */
 export interface ToolManifest {
   // ==================== Required Fields ====================
@@ -310,12 +310,13 @@ export interface ToolResolution {
 /**
  * Supported manifest file names
  * SKILL.md is the primary format (aligned with Anthropic Agent Skills)
- * skill.yaml/yml is the package manifest
+ * skill.package.yml/yml is the package manifest
  * enact.md/yaml/yml are supported for backwards compatibility
  */
 export const MANIFEST_FILES = [
   "SKILL.md",
-  "skill.yaml",
+  "skill.package.yaml",
+  "skill.package.yml",
   "skill.yml",
   "enact.md",
   "enact.yaml",

package/src/types/organization.ts

@@ -0,0 +1,55 @@
+/**
+ * Organization types for org-scoped tool namespaces.
+ *
+ * Organizations allow businesses to reserve @org scopes (e.g., @anthropic/tool-name)
+ * and manage team publishing permissions.
+ */
+
+/**
+ * Organization membership roles.
+ * - owner: Full control (manage org, members, tools, delete org)
+ * - admin: Publish tools + manage members
+ * - member: Publish tools only
+ */
+export type OrgRole = "owner" | "admin" | "member";
+
+/**
+ * Organization entity
+ */
+export interface Organization {
+  id: string;
+  /** Org name without @ prefix (e.g., "anthropic") */
+  name: string;
+  display_name: string | null;
+  description: string | null;
+  avatar_url: string | null;
+  created_by: string;
+  created_at: string;
+}
+
+/**
+ * Organization member
+ */
+export interface OrgMember {
+  org_id: string;
+  user_id: string;
+  username: string;
+  role: OrgRole;
+  added_at: string;
+  added_by: string | null;
+}
+
+/**
+ * Full org info with counts (for API responses)
+ */
+export interface OrgInfo extends Organization {
+  member_count: number;
+  tool_count: number;
+}
+
+/**
+ * Check if a tool name is org-scoped (starts with @)
+ */
+export function isOrgScoped(name: string): boolean {
+  return name.startsWith("@");
+}

package/tests/config.test.ts

@@ -534,7 +534,7 @@ describe("configuration manager", () => {
       expect(existsSync(enactHome)).toBe(true);
     });
 
-    test("creates ~/.agent/skills/ directory", () => {
+    test("creates ~/.agents/skills/ directory", () => {
       const enactHome = getEnactHome();
       const cacheDir = getCacheDir();
 

package/tests/manifest/loader.test.ts

@@ -104,11 +104,11 @@ description: A minimal tool
   });
 
   describe("loadManifestFromDir", () => {
-    test("loads manifest from directory with skill.yaml", () => {
+    test("loads manifest from directory with skill.package.yml", () => {
       const testDir = join(TEST_DIR, "yaml-dir");
       mkdirSync(testDir, { recursive: true });
       writeFileSync(
-        join(testDir, "skill.yaml"),
+        join(testDir, "skill.package.yml"),
         `
 name: test/yaml
 description: Test YAML manifest
@@ -156,12 +156,53 @@ description: Test Markdown manifest
       expect(result.format).toBe("md");
     });
 
-    test("prefers skill.yaml over legacy enact.yaml", () => {
+    test("loads manifest from directory with skill.package.yaml", () => {
+      const testDir = join(TEST_DIR, "package-yaml-dir");
+      mkdirSync(testDir, { recursive: true });
+      writeFileSync(
+        join(testDir, "skill.package.yaml"),
+        `
+name: test/package-yaml
+description: Test package YAML manifest
+`,
+        "utf-8"
+      );
+
+      const result = loadManifestFromDir(testDir);
+      expect(result.manifest.name).toBe("test/package-yaml");
+    });
+
+    test("prefers skill.package.yaml over skill.package.yml", () => {
+      const testDir = join(TEST_DIR, "package-vs-skill-dir");
+      mkdirSync(testDir, { recursive: true });
+
+      writeFileSync(
+        join(testDir, "skill.package.yaml"),
+        `
+name: test/package-preferred
+description: Package version
+`,
+        "utf-8"
+      );
+      writeFileSync(
+        join(testDir, "skill.package.yml"),
+        `
+name: test/skill-version
+description: Skill version
+`,
+        "utf-8"
+      );
+
+      const result = loadManifestFromDir(testDir);
+      expect(result.manifest.name).toBe("test/package-preferred");
+    });
+
+    test("prefers skill.package.yml over legacy enact.yaml", () => {
       const testDir = join(TEST_DIR, "both-dir");
       mkdirSync(testDir, { recursive: true });
 
       writeFileSync(
-        join(testDir, "skill.yaml"),
+        join(testDir, "skill.package.yml"),
         `
 name: test/skill-preferred
 description: Skill version
@@ -191,13 +232,13 @@ description: Legacy version
   });
 
   describe("findManifestFile", () => {
-    test("finds skill.yaml", () => {
+    test("finds skill.package.yml", () => {
       const testDir = join(TEST_DIR, "find-yaml");
       mkdirSync(testDir, { recursive: true });
-      writeFileSync(join(testDir, "skill.yaml"), "name: test/find", "utf-8");
+      writeFileSync(join(testDir, "skill.package.yml"), "name: test/find", "utf-8");
 
       const result = findManifestFile(testDir);
-      expect(result).toBe(join(testDir, "skill.yaml"));
+      expect(result).toBe(join(testDir, "skill.package.yml"));
     });
 
     test("finds enact.md", () => {
@@ -222,7 +263,7 @@ description: Legacy version
     test("returns true when manifest exists", () => {
       const testDir = join(TEST_DIR, "has-manifest");
       mkdirSync(testDir, { recursive: true });
-      writeFileSync(join(testDir, "skill.yaml"), "name: test/has", "utf-8");
+      writeFileSync(join(testDir, "skill.package.yml"), "name: test/has", "utf-8");
 
       expect(hasManifest(testDir)).toBe(true);
     });
@@ -264,7 +305,7 @@ description: Legacy version
       const testDir = join(TEST_DIR, "try-success");
       mkdirSync(testDir, { recursive: true });
       writeFileSync(
-        join(testDir, "skill.yaml"),
+        join(testDir, "skill.package.yml"),
         `
 name: test/try
 description: Test try loading

package/tests/manifest/parser.test.ts

@@ -260,10 +260,11 @@ Body here.
 
   describe("detectFormat", () => {
     test("detects .yaml extension", () => {
-      expect(detectFormat("skill.yaml")).toBe("yaml");
+      expect(detectFormat("skill.package.yaml")).toBe("yaml");
+      expect(detectFormat("skill.package.yml")).toBe("yaml");
       expect(detectFormat("enact.yaml")).toBe("yaml");
       expect(detectFormat("tool.yaml")).toBe("yaml");
-      expect(detectFormat("/path/to/skill.yaml")).toBe("yaml");
+      expect(detectFormat("/path/to/skill.package.yml")).toBe("yaml");
     });
 
     test("detects .yml extension", () => {
@@ -298,7 +299,7 @@ Body here.
 name: org/tool
 description: Test
 `;
-      const result = parseManifestAuto(yaml, "skill.yaml");
+      const result = parseManifestAuto(yaml, "skill.package.yml");
       expect(result.manifest.name).toBe("org/tool");
       expect(result.format).toBe("yaml");
     });

package/tests/manifest-types.test.ts

@@ -310,7 +310,7 @@ describe("manifest types", () => {
         },
         sourceDir: "/home/user/.enact/tools/org/tool",
         location: "user",
-        manifestPath: "/home/user/.enact/tools/org/tool/skill.yaml",
+        manifestPath: "/home/user/.enact/tools/org/tool/skill.package.yml",
         version: "1.0.0",
       };
 
@@ -332,7 +332,7 @@ describe("manifest types", () => {
           manifest: { name: "test", description: "test" },
           sourceDir: "/test",
           location: loc,
-          manifestPath: "/test/skill.yaml",
+          manifestPath: "/test/skill.package.yml",
         };
         expect(resolution.location).toBe(loc);
       }
@@ -342,12 +342,13 @@ describe("manifest types", () => {
   describe("constants", () => {
     test("MANIFEST_FILES contains expected files", () => {
       expect(MANIFEST_FILES).toContain("SKILL.md");
-      expect(MANIFEST_FILES).toContain("skill.yaml");
+      expect(MANIFEST_FILES).toContain("skill.package.yaml");
+      expect(MANIFEST_FILES).toContain("skill.package.yml");
       expect(MANIFEST_FILES).toContain("skill.yml");
       expect(MANIFEST_FILES).toContain("enact.md");
       expect(MANIFEST_FILES).toContain("enact.yaml");
       expect(MANIFEST_FILES).toContain("enact.yml");
-      expect(MANIFEST_FILES.length).toBe(6);
+      expect(MANIFEST_FILES.length).toBe(7);
     });
 
     test("PACKAGE_MANIFEST_FILE is correct", () => {

package/tests/paths.test.ts

@@ -21,6 +21,7 @@ describe("path utilities", () => {
     // Create test directory structure
     mkdirSync(NESTED_DIR, { recursive: true });
     mkdirSync(join(TEST_DIR, ".enact"), { recursive: true });
+    mkdirSync(join(TEST_DIR, "agents"), { recursive: true });
   });
 
   afterAll(() => {
@@ -81,36 +82,35 @@ describe("path utilities", () => {
   });
 
   describe("getToolsDir", () => {
-    test("returns ~/.enact/tools/ for user scope", () => {
+    test("returns ~/.agents/skills/ for user scope", () => {
       const result = getToolsDir("user");
-      const expected = join(homedir(), ".enact", "tools");
+      const expected = join(homedir(), ".agents", "skills");
       expect(result).toBe(expected);
     });
 
-    test("returns .enact/tools/ for project scope", () => {
+    test("returns agents/skills/ for project scope", () => {
       const result = getToolsDir("project", TEST_DIR);
-      expect(result).toBe(join(TEST_DIR, ".enact", "tools"));
+      expect(result).toBe(join(TEST_DIR, "agents", "skills"));
     });
 
     test("finds project tools in parent directory", () => {
       const result = getToolsDir("project", NESTED_DIR);
-      expect(result).toBe(join(TEST_DIR, ".enact", "tools"));
+      expect(result).toBe(join(TEST_DIR, "agents", "skills"));
     });
 
-    test("returns null for project scope when .enact not found", () => {
-      // Similar to above - may find ~/.enact/ if it exists
-      const result = getToolsDir("project", "/tmp/no-enact-unlikely-path");
-      // Result will be null or a valid tools directory
+    test("returns null for project scope when agents/ not found", () => {
+      const result = getToolsDir("project", "/tmp/no-agents-unlikely-path");
+      // Result will be null or a valid skills directory
       if (result !== null) {
-        expect(result.endsWith("tools")).toBe(true);
+        expect(result.endsWith("skills")).toBe(true);
       }
     });
   });
 
   describe("getSkillsDir", () => {
-    test("returns ~/.agent/skills/ path", () => {
+    test("returns ~/.agents/skills/ path", () => {
       const result = getSkillsDir();
-      const expected = join(homedir(), ".agent", "skills");
+      const expected = join(homedir(), ".agents", "skills");
       expect(result).toBe(expected);
     });
   });