@enactprotocol/shared 2.3.4 → 2.3.7

package/src/manifest/loader.ts

@@ -52,7 +52,7 @@ export interface LoadManifestOptions extends ValidateManifestOptions {
 /**
  * Load a manifest from a file path
  *
- * @param filePath - Path to the manifest file (SKILL.md, skill.yaml, skill.yml, enact.md, enact.yaml, or enact.yml)
+ * @param filePath - Path to the manifest file (SKILL.md, skill.package.yml, skill.yml, 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
@@ -120,7 +120,7 @@ export function loadManifest(filePath: string, options: LoadManifestOptions = {}
 /**
  * Load SKILL.md for its body content and frontmatter fields.
  * Does NOT validate as a full ToolManifest — used only to extract
- * agent-facing documentation in two-file mode (skill.yaml + SKILL.md).
+ * agent-facing documentation in two-file mode (skill.package.yml + SKILL.md).
  */
 function loadSkillDoc(
   filePath: string
@@ -142,10 +142,10 @@ function loadSkillDoc(
  * Find and load a manifest from a directory
  *
  * Supports two modes:
- * 1. **Two-file model**: If both `skill.yaml` and `SKILL.md` exist, `skill.yaml` is
- *    the package manifest and `SKILL.md` provides agent-facing documentation (body → `doc`).
- *    Also supports legacy `enact.yaml` in place of `skill.yaml`.
- * 2. **Single-file fallback**: Searches for SKILL.md, skill.yaml, skill.yml, enact.md, enact.yaml, or enact.yml
+ * 1. **Two-file model**: If both a package manifest (`skill.package.yaml`, `skill.package.yml`, etc.) and `SKILL.md` exist,
+ *    the package manifest provides execution metadata and `SKILL.md` provides agent-facing documentation (body → `doc`).
+ *    Also supports legacy `enact.yaml` in place of `skill.package.yml`.
+ * 2. **Single-file fallback**: Searches for SKILL.md, skill.package.yaml, skill.package.yml, skill.yml, enact.md, enact.yaml, or enact.yml
  *    and uses the first match as the complete manifest.
  *
  * @param dir - Directory to search for manifest
@@ -160,9 +160,15 @@ export function loadManifestFromDir(
   const skillMdPath = join(dir, "SKILL.md");
   const hasSkillMd = existsSync(skillMdPath);
 
-  // Find config file (skill.yaml, skill.yml, or legacy enact.yaml/enact.yml)
+  // Find config file (skill.package.yaml, skill.package.yml, skill.yml, or legacy enact.yaml/enact.yml)
   let enactConfigPath: string | null = null;
-  for (const f of ["skill.yaml", "skill.yml", "enact.yaml", "enact.yml"]) {
+  for (const f of [
+    "skill.package.yaml",
+    "skill.package.yml",
+    "skill.yml",
+    "enact.yaml",
+    "enact.yml",
+  ]) {
     const p = join(dir, f);
     if (existsSync(p)) {
       enactConfigPath = p;
@@ -170,7 +176,7 @@ export function loadManifestFromDir(
     }
   }
 
-  // Two-file model: skill.yaml + SKILL.md
+  // Two-file model: skill.package.yaml/skill.package.yml + SKILL.md
   if (enactConfigPath && hasSkillMd) {
     const loaded = loadManifest(enactConfigPath, options);
     const skillDoc = loadSkillDoc(skillMdPath);

package/src/manifest/parser.ts

@@ -3,7 +3,7 @@
  *
  * Handles parsing of:
  * - SKILL.md files (YAML frontmatter + Markdown body) - primary format
- * - skill.yaml/yml files (pure YAML) - package manifest
+ * - skill.package.yml/yml files (pure YAML) - package manifest
  * - enact.yaml/yml files (pure YAML) - legacy format
  * - enact.md files (YAML frontmatter + Markdown body) - legacy format
  */

package/src/manifest/validator.ts

@@ -359,5 +359,12 @@ export function isValidTimeout(timeout: string): boolean {
   return GO_DURATION_REGEX.test(timeout);
 }
 
+/**
+ * Check if a tool name is org-scoped (starts with @)
+ */
+export function isOrgScoped(name: string): boolean {
+  return name.startsWith("@");
+}
+
 // Export the schema for external use
 export { ToolManifestSchema };

package/src/resolver.ts

@@ -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

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

@@ -25,7 +25,7 @@ describe("tool resolver", () => {
 
     // Create a project-level tool
     writeFileSync(
-      join(PROJECT_ENACT_DIR, "tools", "test", "project-tool", "skill.yaml"),
+      join(PROJECT_ENACT_DIR, "tools", "test", "project-tool", "skill.package.yml"),
       `
 name: test/project-tool
 description: A project-level test tool
@@ -37,7 +37,7 @@ version: "1.0.0"
     // Create a direct tool directory for path-based resolution
     mkdirSync(join(TEST_DIR, "direct-tool"), { recursive: true });
     writeFileSync(
-      join(TEST_DIR, "direct-tool", "skill.yaml"),
+      join(TEST_DIR, "direct-tool", "skill.package.yml"),
       `
 name: test/direct-tool
 description: A directly referenced tool
@@ -91,8 +91,8 @@ Documentation here.
         expect(toolNameToPath("acme/greeter")).toBe("acme/greeter");
       });
 
-      test("strips @ prefix for disk paths", () => {
-        expect(toolNameToPath("@acme/greeter")).toBe("acme/greeter");
+      test("preserves @ prefix for npm-style disk layout", () => {
+        expect(toolNameToPath("@acme/greeter")).toBe("@acme/greeter");
       });
 
       test("normalizes backslashes", () => {
@@ -146,7 +146,7 @@ Documentation here.
     });
 
     test("resolves tool from manifest file directly", () => {
-      const manifestPath = join(TEST_DIR, "direct-tool", "skill.yaml");
+      const manifestPath = join(TEST_DIR, "direct-tool", "skill.package.yml");
       const result = resolveToolFromPath(manifestPath);
 
       expect(result.manifest.name).toBe("test/direct-tool");