@enactprotocol/shared 2.2.4 → 2.3.1

package/src/types/manifest.ts

@@ -1,6 +1,6 @@
 /**
  * TypeScript types for Enact tool manifests
- * These types define the structure of SKILL.md (and legacy enact.yaml/enact.md) frontmatter
+ * These types define the structure of SKILL.md (and skill.yaml/legacy enact.yaml/enact.md) frontmatter
  */
 
 import type { JSONSchema7 } from "json-schema";
@@ -13,6 +13,8 @@ export interface EnvVariable {
   description: string;
   /** If true, stored in OS keyring; if false, stored in .env files */
   secret?: boolean;
+  /** If true, must be set before execution (no default fallback) */
+  required?: boolean;
   /** Default value if not set (only for non-secrets) */
   default?: string;
 }
@@ -50,6 +52,32 @@ export interface ToolAnnotations {
   openWorldHint?: boolean;
 }
 
+/**
+ * Lifecycle hooks for tool installation and management
+ */
+export interface ToolHooks {
+  /** Command(s) to run after the tool is installed/extracted (e.g., "npm install", "pip install -r requirements.txt") */
+  postinstall?: string | string[];
+  /** Build command(s) to run before execution (e.g., "pip install -r requirements.txt") */
+  build?: string | string[];
+}
+
+/**
+ * Script definition — either a simple command string or an expanded object
+ *
+ * Simple form: "python main.py {{url}}"
+ * Expanded form: { command: "python main.py {{url}}", description: "Scrape a URL" }
+ */
+export type ScriptDefinition =
+  | string
+  | {
+      command: string;
+      description?: string;
+      inputSchema?: JSONSchema7;
+      outputSchema?: JSONSchema7;
+      annotations?: ToolAnnotations;
+    };
+
 /**
  * Resource requirements for tool execution
  */
@@ -76,7 +104,7 @@ export interface ToolExample {
 
 /**
  * Complete tool manifest structure
- * This represents the YAML frontmatter in SKILL.md (or legacy enact.md/enact.yaml)
+ * This represents the YAML frontmatter in SKILL.md (or skill.yaml/legacy enact.md/enact.yaml)
  */
 export interface ToolManifest {
   // ==================== Required Fields ====================
@@ -115,9 +143,6 @@ export interface ToolManifest {
 
   // ==================== Schema Fields ====================
 
-  /** JSON Schema defining input parameters */
-  inputSchema?: JSONSchema7;
-
   /** JSON Schema defining output structure */
   outputSchema?: JSONSchema7;
 
@@ -134,6 +159,28 @@ export interface ToolManifest {
   /** Resource limits and requirements */
   resources?: ResourceRequirements;
 
+  // ==================== Lifecycle Hooks ====================
+
+  /** Lifecycle hooks (e.g., postinstall build step) */
+  hooks?: ToolHooks;
+
+  // ==================== Scripts ====================
+
+  /**
+   * Inline executable scripts (each becomes an MCP tool via colon syntax)
+   *
+   * Scripts replace the need for a separate ACTIONS.yaml file.
+   * Each script maps a name to a command with {{param}} template syntax.
+   *
+   * @example
+   * scripts:
+   *   scrape: python scripts/scrape.py {{url}}
+   *   crawl:
+   *     command: python scripts/crawl.py {{url}} {{depth}}
+   *     description: Crawl a website to specified depth
+   */
+  scripts?: Record<string, ScriptDefinition>;
+
   // ==================== Agent Skills Spec Fields ====================
 
   /** Environment requirements (intended product, system packages, network access, etc.) */
@@ -252,14 +299,28 @@ export interface ToolResolution {
   manifestPath: string;
   /** Tool version (if available) */
   version?: string | undefined;
+  /** The resolved script (if a script was specified via colon syntax) */
+  action?: import("./actions").Action | undefined;
+  /** The requested script name (if specified via colon syntax) */
+  actionName?: string | undefined;
+  /** The scripts manifest (converted from inline scripts) */
+  actionsManifest?: import("./actions").ActionsManifest | undefined;
 }
 
 /**
  * Supported manifest file names
  * SKILL.md is the primary format (aligned with Anthropic Agent Skills)
+ * skill.yaml/yml is the package manifest
  * enact.md/yaml/yml are supported for backwards compatibility
  */
-export const MANIFEST_FILES = ["SKILL.md", "enact.md", "enact.yaml", "enact.yml"] as const;
+export const MANIFEST_FILES = [
+  "SKILL.md",
+  "skill.yaml",
+  "skill.yml",
+  "enact.md",
+  "enact.yaml",
+  "enact.yml",
+] as const;
 export type ManifestFileName = (typeof MANIFEST_FILES)[number];
 
 /**

package/tests/action-command.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Tests for the action command interpolation module.
+ *
+ * Covers {{param}} template parsing, interpolation, omission of optionals,
+ * and the prepareActionCommand entry point.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  getActionCommandParams,
+  getMissingRequiredParams,
+  hasActionTemplates,
+  interpolateActionCommand,
+  parseActionArgument,
+  parseActionCommand,
+  prepareActionCommand,
+} from "../src/execution/action-command";
+
+describe("hasActionTemplates", () => {
+  test("returns true for string with {{param}}", () => {
+    expect(hasActionTemplates("hello {{name}}")).toBe(true);
+  });
+
+  test("returns false for plain string", () => {
+    expect(hasActionTemplates("echo hello")).toBe(false);
+  });
+
+  test("returns false for ${param} syntax", () => {
+    expect(hasActionTemplates("echo ${name}")).toBe(false);
+  });
+
+  test("returns true for standalone {{param}}", () => {
+    expect(hasActionTemplates("{{url}}")).toBe(true);
+  });
+});
+
+describe("parseActionArgument", () => {
+  test("parses a literal argument", () => {
+    const result = parseActionArgument("echo");
+    expect(result.tokens).toHaveLength(1);
+    expect(result.tokens[0]?.type).toBe("literal");
+    expect(result.tokens[0]?.type === "literal" && result.tokens[0].value).toBe("echo");
+    expect(result.parameters).toHaveLength(0);
+  });
+
+  test("parses a standalone parameter", () => {
+    const result = parseActionArgument("{{url}}");
+    expect(result.tokens).toHaveLength(1);
+    expect(result.tokens[0]?.type).toBe("parameter");
+    expect(result.tokens[0]?.type === "parameter" && result.tokens[0].name).toBe("url");
+    expect(result.parameters).toEqual(["url"]);
+  });
+
+  test("parses mixed literal and parameter", () => {
+    const result = parseActionArgument("--name={{name}}");
+    expect(result.tokens).toHaveLength(2);
+    expect(result.tokens[0]?.type).toBe("literal");
+    expect(result.tokens[1]?.type).toBe("parameter");
+    expect(result.parameters).toEqual(["name"]);
+  });
+
+  test("parses multiple parameters in one argument", () => {
+    const result = parseActionArgument("{{host}}:{{port}}");
+    expect(result.tokens).toHaveLength(3);
+    expect(result.parameters).toEqual(["host", "port"]);
+  });
+
+  test("trims whitespace in parameter names", () => {
+    const result = parseActionArgument("{{ name }}");
+    expect(result.parameters).toEqual(["name"]);
+  });
+});
+
+describe("parseActionCommand", () => {
+  test("parses command with no templates", () => {
+    const result = parseActionCommand(["echo", "hello", "world"]);
+    expect(result.allParameters).toHaveLength(0);
+    expect(result.arguments).toHaveLength(3);
+  });
+
+  test("parses command with templates", () => {
+    const result = parseActionCommand(["python", "main.py", "{{url}}"]);
+    expect(result.allParameters).toEqual(["url"]);
+  });
+
+  test("deduplicates parameter names", () => {
+    const result = parseActionCommand(["echo", "{{name}}", "{{name}}"]);
+    expect(result.allParameters).toEqual(["name"]);
+  });
+
+  test("collects all unique parameters", () => {
+    const result = parseActionCommand(["cmd", "{{a}}", "{{b}}", "{{c}}"]);
+    expect(result.allParameters).toEqual(["a", "b", "c"]);
+  });
+});
+
+describe("interpolateActionCommand", () => {
+  test("replaces parameter with value", () => {
+    const result = interpolateActionCommand(["echo", "{{name}}"], { name: "Alice" });
+    expect(result).toEqual(["echo", "Alice"]);
+  });
+
+  test("preserves literal arguments", () => {
+    const result = interpolateActionCommand(["python", "main.py", "--verbose"], {});
+    expect(result).toEqual(["python", "main.py", "--verbose"]);
+  });
+
+  test("handles mixed literal and parameter", () => {
+    const result = interpolateActionCommand(["--output={{format}}"], { format: "json" });
+    expect(result).toEqual(["--output=json"]);
+  });
+
+  test("converts number to string", () => {
+    const result = interpolateActionCommand(["echo", "{{count}}"], { count: 42 });
+    expect(result).toEqual(["echo", "42"]);
+  });
+
+  test("converts boolean to string", () => {
+    const result = interpolateActionCommand(["echo", "{{flag}}"], { flag: true });
+    expect(result).toEqual(["echo", "true"]);
+  });
+
+  test("converts object to JSON string", () => {
+    const result = interpolateActionCommand(["echo", "{{data}}"], { data: { key: "value" } });
+    expect(result).toEqual(["echo", '{"key":"value"}']);
+  });
+
+  test("omits argument for optional param with no value", () => {
+    const schema = {
+      type: "object" as const,
+      properties: {
+        name: { type: "string" as const },
+        verbose: { type: "boolean" as const },
+      },
+      required: ["name"],
+    };
+
+    const result = interpolateActionCommand(
+      ["echo", "{{name}}", "{{verbose}}"],
+      { name: "Alice" },
+      { inputSchema: schema }
+    );
+    // "verbose" is optional with no value → omitted
+    expect(result).toEqual(["echo", "Alice"]);
+  });
+
+  test("uses default value for optional param", () => {
+    const schema = {
+      type: "object" as const,
+      properties: {
+        format: { type: "string" as const, default: "text" },
+      },
+    };
+
+    const result = interpolateActionCommand(["echo", "{{format}}"], {}, { inputSchema: schema });
+    expect(result).toEqual(["echo", "text"]);
+  });
+
+  test("does not split values with spaces into multiple args", () => {
+    const result = interpolateActionCommand(["echo", "{{msg}}"], {
+      msg: "hello world with spaces",
+    });
+    // Must remain a single argument — security property
+    expect(result).toEqual(["echo", "hello world with spaces"]);
+  });
+});
+
+describe("getMissingRequiredParams", () => {
+  test("returns empty when all required params provided", () => {
+    const schema = {
+      type: "object" as const,
+      required: ["name"],
+      properties: { name: { type: "string" as const } },
+    };
+    const missing = getMissingRequiredParams(["echo", "{{name}}"], { name: "hi" }, schema);
+    expect(missing).toHaveLength(0);
+  });
+
+  test("returns missing required param names", () => {
+    const schema = {
+      type: "object" as const,
+      required: ["name", "age"],
+      properties: {
+        name: { type: "string" as const },
+        age: { type: "number" as const },
+      },
+    };
+    const missing = getMissingRequiredParams(
+      ["echo", "{{name}}", "{{age}}"],
+      { name: "Alice" },
+      schema
+    );
+    expect(missing).toEqual(["age"]);
+  });
+
+  test("does not report optional params as missing", () => {
+    const schema = {
+      type: "object" as const,
+      required: [],
+      properties: { verbose: { type: "boolean" as const } },
+    };
+    const missing = getMissingRequiredParams(["echo", "{{verbose}}"], {}, schema);
+    expect(missing).toHaveLength(0);
+  });
+});
+
+describe("getActionCommandParams", () => {
+  test("returns all parameter names from command", () => {
+    expect(getActionCommandParams(["cmd", "{{a}}", "{{b}}"])).toEqual(["a", "b"]);
+  });
+
+  test("returns empty for command without templates", () => {
+    expect(getActionCommandParams(["echo", "hello"])).toEqual([]);
+  });
+});
+
+describe("prepareActionCommand", () => {
+  test("interpolates and returns command array", () => {
+    const schema = {
+      type: "object" as const,
+      required: ["url"],
+      properties: { url: { type: "string" as const } },
+    };
+    const result = prepareActionCommand(
+      ["python", "main.py", "{{url}}"],
+      { url: "https://example.com" },
+      schema
+    );
+    expect(result).toEqual(["python", "main.py", "https://example.com"]);
+  });
+
+  test("throws when required parameters are missing", () => {
+    const schema = {
+      type: "object" as const,
+      required: ["url"],
+      properties: { url: { type: "string" as const } },
+    };
+    expect(() => prepareActionCommand(["python", "main.py", "{{url}}"], {}, schema)).toThrow(
+      "Missing required parameters: url"
+    );
+  });
+
+  test("works without schema (all params treated conservatively)", () => {
+    // Without schema, all params are treated as required
+    expect(() => prepareActionCommand(["echo", "{{name}}"], {})).toThrow(
+      "Missing required parameters: name"
+    );
+  });
+});

package/tests/config-normalization.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Tests for config normalization — alias fields added in the README update.
+ *
+ * TrustConfig aliases: require_signatures → policy, trusted_publishers → auditors
+ * ExecutionConfig routing: default, fallback, trusted_scopes
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import {
+  DEFAULT_CONFIG,
+  getTrustPolicy,
+  getTrustedIdentities,
+  loadConfig,
+  saveConfig,
+} from "../src/config";
+
+describe("config normalization", () => {
+  describe("TrustConfig aliases", () => {
+    test("require_signatures: true sets policy to require_attestation", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      mkdirSync(join(homedir(), ".enact"), { recursive: true });
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          trust: {
+            require_signatures: true,
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      expect(config.trust?.policy).toBe("require_attestation");
+    });
+
+    test("require_signatures: false sets policy to allow", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          trust: {
+            require_signatures: false,
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      expect(config.trust?.policy).toBe("allow");
+    });
+
+    test("explicit policy takes precedence over require_signatures", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          trust: {
+            policy: "prompt",
+            require_signatures: true,
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      // When policy is explicitly set, require_signatures should not override it
+      expect(config.trust?.policy).toBe("prompt");
+    });
+
+    test("trusted_publishers merges into auditors", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          trust: {
+            auditors: ["github:existing-user"],
+            trusted_publishers: ["@my-org"],
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      expect(config.trust?.auditors).toContain("github:existing-user");
+      expect(config.trust?.auditors).toContain("@my-org");
+    });
+
+    test("trusted_publishers does not create duplicates", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          trust: {
+            auditors: ["@my-org", "github:alice"],
+            trusted_publishers: ["@my-org"],
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      const orgCount = config.trust?.auditors?.filter((a) => a === "@my-org").length;
+      expect(orgCount).toBe(1);
+    });
+
+    test("trusted_publishers works without existing auditors", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          trust: {
+            trusted_publishers: ["@my-org", "@other-org"],
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      // Should merge with default auditors
+      expect(config.trust?.auditors).toContain("@my-org");
+      expect(config.trust?.auditors).toContain("@other-org");
+    });
+
+    test("getTrustPolicy respects require_signatures alias", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          trust: {
+            require_signatures: true,
+          },
+        }),
+        "utf-8"
+      );
+
+      expect(getTrustPolicy()).toBe("require_attestation");
+    });
+
+    test("getTrustedIdentities includes trusted_publishers", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          trust: {
+            auditors: ["github:alice"],
+            trusted_publishers: ["@acme"],
+          },
+        }),
+        "utf-8"
+      );
+
+      const identities = getTrustedIdentities();
+      expect(identities).toContain("github:alice");
+      expect(identities).toContain("@acme");
+    });
+  });
+
+  describe("ExecutionConfig routing fields", () => {
+    test("default execution backend is preserved", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          execution: {
+            default: "docker",
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      expect(config.execution?.default).toBe("docker");
+    });
+
+    test("fallback execution backend is preserved", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          execution: {
+            default: "container",
+            fallback: "remote",
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      expect(config.execution?.default).toBe("container");
+      expect(config.execution?.fallback).toBe("remote");
+    });
+
+    test("trusted_scopes is preserved as array", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          execution: {
+            default: "container",
+            fallback: "remote",
+            trusted_scopes: ["@my-org/*", "@internal/*"],
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      expect(config.execution?.trusted_scopes).toEqual(["@my-org/*", "@internal/*"]);
+    });
+
+    test("routing fields coexist with existing fields", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          execution: {
+            defaultTimeout: "1m",
+            verbose: true,
+            default: "docker",
+            fallback: "local",
+            trusted_scopes: ["@my-org/*"],
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+      expect(config.execution?.defaultTimeout).toBe("1m");
+      expect(config.execution?.verbose).toBe(true);
+      expect(config.execution?.default).toBe("docker");
+      expect(config.execution?.fallback).toBe("local");
+      expect(config.execution?.trusted_scopes).toEqual(["@my-org/*"]);
+    });
+
+    test("missing routing fields default to undefined", () => {
+      saveConfig({ ...DEFAULT_CONFIG });
+      const config = loadConfig();
+      expect(config.execution?.default).toBeUndefined();
+      expect(config.execution?.fallback).toBeUndefined();
+      expect(config.execution?.trusted_scopes).toBeUndefined();
+    });
+  });
+
+  describe("full README-style config", () => {
+    test("parses complete README example correctly", () => {
+      const configPath = join(homedir(), ".enact", "config.yaml");
+      writeFileSync(
+        configPath,
+        yaml.dump({
+          trust: {
+            require_signatures: true,
+            trusted_publishers: ["@my-org"],
+          },
+          execution: {
+            default: "container",
+            fallback: "remote",
+            trusted_scopes: ["@my-org/*"],
+          },
+        }),
+        "utf-8"
+      );
+
+      const config = loadConfig();
+
+      // Trust
+      expect(config.trust?.policy).toBe("require_attestation");
+      expect(config.trust?.auditors).toContain("@my-org");
+
+      // Execution
+      expect(config.execution?.default).toBe("container");
+      expect(config.execution?.fallback).toBe("remote");
+      expect(config.execution?.trusted_scopes).toEqual(["@my-org/*"]);
+    });
+  });
+});

package/tests/config.test.ts

@@ -534,7 +534,7 @@ describe("configuration manager", () => {
       expect(existsSync(enactHome)).toBe(true);
     });
 
-    test("creates ~/.enact/cache/ directory", () => {
+    test("creates ~/.agent/skills/ directory", () => {
       const enactHome = getEnactHome();
       const cacheDir = getCacheDir();
 
@@ -542,6 +542,9 @@ describe("configuration manager", () => {
       if (existsSync(enactHome)) {
         rmSync(enactHome, { recursive: true, force: true });
       }
+      if (existsSync(cacheDir)) {
+        rmSync(cacheDir, { recursive: true, force: true });
+      }
 
       ensureGlobalSetup();