@elizaos/autonomous 2.0.0-alpha.10

package/src/hooks/discovery.test.ts

@@ -0,0 +1,357 @@
+/**
+ * Hook Discovery — Unit Tests
+ *
+ * Tests for:
+ * - Frontmatter parsing (valid, metadata JSON, missing delimiters, empty name, invalid JSON)
+ * - Handler resolution (handler.ts, fallback chain, no handler)
+ * - Discovery precedence (workspace > managed > bundled > extra)
+ */
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { discoverHooks } from "./discovery";
+
+// ---------------------------------------------------------------------------
+// mocks
+// ---------------------------------------------------------------------------
+
+vi.mock("@elizaos/core", () => ({
+  logger: { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() },
+}));
+
+// Stub the managed dir (~/.milady/hooks) to avoid picking up real hooks
+vi.mock("node:os", async (importOriginal) => {
+  const actual = (await importOriginal()) as typeof import("node:os");
+  return {
+    ...actual,
+    // Point homedir to a temp location so ~/.milady/hooks doesn't exist
+    homedir: () => join(tmpdir(), "__discovery_test_fake_home__"),
+  };
+});
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+let tempRoot: string;
+
+async function createHookDir(
+  base: string,
+  name: string,
+  opts: {
+    hookMd?: string;
+    handlerFile?: string; // which handler filename to create
+    handlerContent?: string;
+  } = {},
+): Promise<string> {
+  const dir = join(base, name);
+  await mkdir(dir, { recursive: true });
+
+  if (opts.hookMd !== undefined) {
+    await writeFile(join(dir, "HOOK.md"), opts.hookMd, "utf-8");
+  }
+
+  const handlerFile = opts.handlerFile ?? "handler.ts";
+  const handlerContent = opts.handlerContent ?? "export default () => {};";
+  await writeFile(join(dir, handlerFile), handlerContent, "utf-8");
+
+  return dir;
+}
+
+// ---------------------------------------------------------------------------
+// lifecycle
+// ---------------------------------------------------------------------------
+
+beforeEach(async () => {
+  tempRoot = join(
+    tmpdir(),
+    `hooks-discovery-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  await mkdir(tempRoot, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tempRoot, { recursive: true, force: true });
+});
+
+// ============================================================================
+//  1. Frontmatter parsing (tested via discoverHooks)
+// ============================================================================
+
+describe("frontmatter parsing", () => {
+  it("parses valid frontmatter with name and description", async () => {
+    const bundled = join(tempRoot, "bundled");
+    await createHookDir(bundled, "my-hook", {
+      hookMd: [
+        "---",
+        "name: my-hook",
+        "description: A test hook",
+        "---",
+        "",
+        "# My Hook",
+      ].join("\n"),
+    });
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].hook.name).toBe("my-hook");
+    expect(entries[0].frontmatter.description).toBe("A test hook");
+    expect(entries[0].hook.source).toBe("milady-bundled");
+  });
+
+  it("extracts milady metadata from frontmatter JSON", async () => {
+    const bundled = join(tempRoot, "bundled");
+    await createHookDir(bundled, "meta-hook", {
+      hookMd: [
+        "---",
+        "name: meta-hook",
+        "description: Hook with metadata",
+        'metadata: { "milady": { "emoji": "🔥", "events": ["command:new"], "hookKey": "custom-key" } }',
+        "---",
+      ].join("\n"),
+    });
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].metadata).toBeDefined();
+    expect(entries[0].metadata?.emoji).toBe("🔥");
+    expect(entries[0].metadata?.events).toEqual(["command:new"]);
+    expect(entries[0].metadata?.hookKey).toBe("custom-key");
+  });
+
+  it("skips hook when frontmatter delimiters are missing", async () => {
+    const bundled = join(tempRoot, "bundled");
+    await createHookDir(bundled, "bad-fm", {
+      hookMd: "name: no-delimiters\ndescription: missing ---\n",
+    });
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(0);
+  });
+
+  it("skips hook when name is empty", async () => {
+    const bundled = join(tempRoot, "bundled");
+    await createHookDir(bundled, "empty-name", {
+      hookMd: [
+        "---",
+        "name: ",
+        "description: Has description but no name",
+        "---",
+      ].join("\n"),
+    });
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(0);
+  });
+
+  it("warns but still parses name/description when metadata JSON is invalid", async () => {
+    const { logger } = await import("@elizaos/core");
+    const bundled = join(tempRoot, "bundled");
+    await createHookDir(bundled, "bad-meta", {
+      hookMd: [
+        "---",
+        "name: bad-meta",
+        "description: Invalid metadata JSON",
+        "metadata: {not valid json!!!}",
+        "---",
+      ].join("\n"),
+    });
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].hook.name).toBe("bad-meta");
+    expect(entries[0].frontmatter.description).toBe("Invalid metadata JSON");
+    expect(entries[0].metadata).toBeUndefined();
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("Failed to parse metadata"),
+    );
+  });
+
+  it("parses homepage from frontmatter", async () => {
+    const bundled = join(tempRoot, "bundled");
+    await createHookDir(bundled, "hp-hook", {
+      hookMd: [
+        "---",
+        "name: hp-hook",
+        "description: Hook with homepage",
+        "homepage: https://example.com",
+        "---",
+      ].join("\n"),
+    });
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].frontmatter.homepage).toBe("https://example.com");
+  });
+});
+
+// ============================================================================
+//  2. Handler resolution
+// ============================================================================
+
+describe("handler resolution", () => {
+  it("uses handler.ts when found", async () => {
+    const bundled = join(tempRoot, "bundled");
+    await createHookDir(bundled, "ts-handler", {
+      hookMd: "---\nname: ts-handler\ndescription: uses handler.ts\n---",
+      handlerFile: "handler.ts",
+    });
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].hook.handlerPath).toContain("handler.ts");
+  });
+
+  it("falls back to index.ts when handler.ts is missing", async () => {
+    const bundled = join(tempRoot, "bundled");
+    const dir = join(bundled, "idx-hook");
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, "HOOK.md"),
+      "---\nname: idx-hook\ndescription: uses index.ts\n---",
+      "utf-8",
+    );
+    // Only create index.ts, no handler.ts or handler
+    await writeFile(join(dir, "index.ts"), "export default () => {};", "utf-8");
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].hook.handlerPath).toContain("index.ts");
+  });
+
+  it("falls back to handler (no ext) when handler.ts is missing", async () => {
+    const bundled = join(tempRoot, "bundled");
+    const dir = join(bundled, "noext-hook");
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, "HOOK.md"),
+      "---\nname: noext-hook\ndescription: uses handler (no ext)\n---",
+      "utf-8",
+    );
+    await writeFile(join(dir, "handler"), "export default () => {};", "utf-8");
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(1);
+    expect(basename(entries[0].hook.handlerPath)).toBe("handler");
+  });
+
+  it("skips hook when no handler file exists", async () => {
+    const { logger } = await import("@elizaos/core");
+    const bundled = join(tempRoot, "bundled");
+    const dir = join(bundled, "no-handler");
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, "HOOK.md"),
+      "---\nname: no-handler\ndescription: missing handler\n---",
+      "utf-8",
+    );
+    // No handler file at all
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(0);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("no handler"),
+    );
+  });
+});
+
+// ============================================================================
+//  3. Discovery precedence
+// ============================================================================
+
+describe("discovery precedence", () => {
+  it("workspace hook overrides bundled hook with the same name", async () => {
+    const bundled = join(tempRoot, "bundled");
+    const workspace = join(tempRoot, "workspace");
+
+    await createHookDir(bundled, "shared-hook", {
+      hookMd: "---\nname: shared-hook\ndescription: bundled version\n---",
+    });
+    // workspace hooks live under <workspacePath>/hooks/
+    const wsHooks = join(workspace, "hooks");
+    await createHookDir(wsHooks, "shared-hook", {
+      hookMd: "---\nname: shared-hook\ndescription: workspace version\n---",
+    });
+
+    const entries = await discoverHooks({
+      bundledDir: bundled,
+      workspacePath: workspace,
+    });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].frontmatter.description).toBe("workspace version");
+    expect(entries[0].hook.source).toBe("milady-workspace");
+  });
+
+  it("collects hooks from all sources when names are unique", async () => {
+    const bundled = join(tempRoot, "bundled");
+    const extra = join(tempRoot, "extra");
+
+    await createHookDir(bundled, "hook-a", {
+      hookMd: "---\nname: hook-a\ndescription: bundled\n---",
+    });
+    await createHookDir(extra, "hook-b", {
+      hookMd: "---\nname: hook-b\ndescription: extra\n---",
+    });
+
+    const entries = await discoverHooks({
+      bundledDir: bundled,
+      extraDirs: [extra],
+    });
+
+    const names = entries.map((e) => e.hook.name).sort();
+    expect(names).toEqual(["hook-a", "hook-b"]);
+  });
+
+  it("returns empty array for nonexistent directory", async () => {
+    const entries = await discoverHooks({
+      bundledDir: join(tempRoot, "does-not-exist"),
+    });
+
+    expect(entries).toEqual([]);
+  });
+
+  it("skips non-directory entries inside hooks dir", async () => {
+    const bundled = join(tempRoot, "bundled");
+    await mkdir(bundled, { recursive: true });
+    // Create a file (not directory) inside the hooks dir
+    await writeFile(join(bundled, "not-a-dir.txt"), "just a file", "utf-8");
+
+    await createHookDir(bundled, "real-hook", {
+      hookMd: "---\nname: real-hook\ndescription: a real hook\n---",
+    });
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].hook.name).toBe("real-hook");
+  });
+
+  it("skips directories without HOOK.md", async () => {
+    const bundled = join(tempRoot, "bundled");
+    const dir = join(bundled, "no-hookmd");
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, "handler.ts"),
+      "export default () => {};",
+      "utf-8",
+    );
+    // No HOOK.md
+
+    const entries = await discoverHooks({ bundledDir: bundled });
+
+    expect(entries).toEqual([]);
+  });
+});

package/src/hooks/discovery.ts

@@ -0,0 +1,231 @@
+/**
+ * Discover hooks from workspace, managed (~/.milady/hooks/), and bundled dirs.
+ * Later sources win on name conflicts.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { logger } from "@elizaos/core";
+import type {
+  Hook,
+  HookEntry,
+  HookSource,
+  MiladyHookMetadata,
+  ParsedHookFrontmatter,
+} from "./types";
+
+const HOOK_MD = "HOOK.md";
+const HANDLER_NAMES = ["handler.ts", "handler", "index.ts", "index"];
+
+function parseFrontmatter(content: string): ParsedHookFrontmatter | null {
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!fmMatch) return null;
+
+  const fmBlock = fmMatch[1];
+  const result: ParsedHookFrontmatter = { name: "", description: "" };
+
+  for (const line of fmBlock.split("\n")) {
+    const kvMatch = line.match(/^(\w+):\s*(.+)/);
+    if (!kvMatch) continue;
+    const [, key, rawValue] = kvMatch;
+    const value = rawValue.replace(/^["']|["']$/g, "").trim();
+
+    switch (key) {
+      case "name":
+        result.name = value;
+        break;
+      case "description":
+        result.description = value;
+        break;
+      case "homepage":
+        result.homepage = value;
+        break;
+      case "metadata":
+        try {
+          const metaStart = fmBlock.indexOf("metadata:");
+          if (metaStart !== -1) {
+            const metaRest = fmBlock
+              .slice(metaStart + "metadata:".length)
+              .trim();
+            const jsonMatch = metaRest.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+              result.metadata = JSON.parse(jsonMatch[0]);
+            }
+          }
+        } catch {
+          try {
+            result.metadata = JSON.parse(value);
+          } catch {
+            logger.warn(`[hooks] Failed to parse metadata in HOOK.md`);
+          }
+        }
+        break;
+    }
+  }
+
+  return result.name ? result : null;
+}
+
+function extractMetadata(
+  frontmatter: ParsedHookFrontmatter,
+): MiladyHookMetadata | undefined {
+  const milady = frontmatter.metadata?.milady;
+  if (!milady) return undefined;
+
+  return {
+    always: milady.always,
+    hookKey: milady.hookKey,
+    emoji: milady.emoji,
+    homepage: milady.homepage ?? frontmatter.homepage,
+    events: Array.isArray(milady.events) ? milady.events : [],
+    export: milady.export,
+    os: milady.os,
+    requires: milady.requires,
+    install: milady.install,
+  };
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function findHandlerPath(dir: string): Promise<string | null> {
+  for (const name of HANDLER_NAMES) {
+    const p = join(dir, name);
+    if (await fileExists(p)) return p;
+  }
+  return null;
+}
+
+async function loadHookFromDir(
+  dir: string,
+  source: HookSource,
+  pluginId?: string,
+): Promise<HookEntry | null> {
+  const hookMdPath = join(dir, HOOK_MD);
+
+  if (!(await fileExists(hookMdPath))) return null;
+
+  const handlerPath = await findHandlerPath(dir);
+  if (!handlerPath) {
+    logger.warn(`[hooks] Hook at ${dir} has HOOK.md but no handler`);
+    return null;
+  }
+
+  try {
+    const content = await readFile(hookMdPath, "utf-8");
+    const frontmatter = parseFrontmatter(content);
+    if (!frontmatter) {
+      logger.warn(`[hooks] Invalid frontmatter in ${hookMdPath}`);
+      return null;
+    }
+
+    const metadata = extractMetadata(frontmatter);
+
+    const hook: Hook = {
+      name: frontmatter.name,
+      description: frontmatter.description,
+      source,
+      pluginId,
+      filePath: hookMdPath,
+      baseDir: dir,
+      handlerPath,
+    };
+
+    return { hook, frontmatter, metadata };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn(`[hooks] Error loading hook from ${dir}: ${msg}`);
+    return null;
+  }
+}
+
+async function scanHooksDir(
+  dir: string,
+  source: HookSource,
+): Promise<HookEntry[]> {
+  if (!(await isDirectory(dir))) return [];
+
+  const entries: HookEntry[] = [];
+
+  try {
+    const items = await readdir(dir);
+    for (const item of items) {
+      const itemPath = join(dir, item);
+      if (!(await isDirectory(itemPath))) continue;
+
+      const entry = await loadHookFromDir(itemPath, source);
+      if (entry) {
+        entries.push(entry);
+      }
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn(`[hooks] Error scanning ${dir}: ${msg}`);
+  }
+
+  return entries;
+}
+
+export interface DiscoveryOptions {
+  workspacePath?: string;
+  bundledDir?: string;
+  extraDirs?: string[];
+}
+
+/** Precedence: extra (lowest) -> bundled -> managed -> workspace (highest). */
+export async function discoverHooks(
+  options: DiscoveryOptions = {},
+): Promise<HookEntry[]> {
+  const seen = new Map<string, HookEntry>();
+
+  if (options.extraDirs) {
+    for (const dir of options.extraDirs) {
+      const resolved = resolve(dir.replace(/^~/, homedir()));
+      for (const entry of await scanHooksDir(resolved, "milady-managed")) {
+        seen.set(entry.hook.name, entry);
+      }
+    }
+  }
+
+  if (options.bundledDir) {
+    for (const entry of await scanHooksDir(
+      options.bundledDir,
+      "milady-bundled",
+    )) {
+      seen.set(entry.hook.name, entry);
+    }
+  }
+
+  const managedDir = join(homedir(), ".milady", "hooks");
+  for (const entry of await scanHooksDir(managedDir, "milady-managed")) {
+    seen.set(entry.hook.name, entry);
+  }
+
+  if (options.workspacePath) {
+    const wsHooksDir = join(
+      options.workspacePath.replace(/^~/, homedir()),
+      "hooks",
+    );
+    for (const entry of await scanHooksDir(wsHooksDir, "milady-workspace")) {
+      seen.set(entry.hook.name, entry);
+    }
+  }
+
+  const all = Array.from(seen.values());
+  logger.info(`[hooks] Discovered ${all.length} hooks`);
+  return all;
+}