@gethmy/mcp 2.4.7 → 2.5.0

package/src/__tests__/prompt-builder.test.ts

@@ -1,12 +1,17 @@
 import { describe, expect, test } from "bun:test";
+import { HarmonyApiClient } from "../api-client.js";
 import {
   type CardData,
+  computeContentHash,
   generatePrompt,
   getAvailableCategories,
   getAvailableVariants,
   getRoleFraming,
   inferCategoryFromLabels,
   type MemoryData,
+  PROMPT_TEMPLATE_VERSION,
+  type PromptCohortRow,
+  proposePromptVariant,
 } from "../prompt-builder.js";
 
 function makeCard(overrides: Partial<CardData> = {}): CardData {
@@ -503,3 +508,232 @@ describe("utility exports", () => {
     }
   });
 });
+
+// ─── AGP P2: snapshot identity (promptId, contentHash, version) ──────
+
+describe("generatePrompt — AGP P2 snapshot fields", () => {
+  test("returns promptId, contentHash, version", () => {
+    const result = generatePrompt({
+      card: makeCard(),
+      variant: "execute",
+    });
+
+    expect(typeof result.promptId).toBe("string");
+    expect(result.promptId.length).toBeGreaterThan(0);
+    expect(typeof result.contentHash).toBe("string");
+    // sha256 hex = 64 chars
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(result.version).toBe(PROMPT_TEMPLATE_VERSION);
+  });
+
+  test("identical inputs produce identical contentHash", () => {
+    const a = generatePrompt({ card: makeCard(), variant: "analysis" });
+    const b = generatePrompt({ card: makeCard(), variant: "analysis" });
+    expect(a.contentHash).toBe(b.contentHash);
+  });
+
+  test("different inputs produce different contentHash", () => {
+    const a = generatePrompt({ card: makeCard(), variant: "analysis" });
+    const b = generatePrompt({
+      card: makeCard({ title: "Different title" }),
+      variant: "analysis",
+    });
+    expect(a.contentHash).not.toBe(b.contentHash);
+  });
+
+  test("each call produces a fresh promptId", () => {
+    const a = generatePrompt({ card: makeCard(), variant: "execute" });
+    const b = generatePrompt({ card: makeCard(), variant: "execute" });
+    expect(a.promptId).not.toBe(b.promptId);
+  });
+
+  test("computeContentHash matches generated prompt hash", () => {
+    const result = generatePrompt({ card: makeCard(), variant: "execute" });
+    expect(computeContentHash(result.prompt)).toBe(result.contentHash);
+  });
+});
+
+// ─── AGP P2: persistence wiring via api-client ────────────────────────
+//
+// The api-client wraps generatePrompt() with a best-effort POST to
+// /prompt-history. We unit-test by stubbing `request` so we don't need
+// a live API.
+
+describe("api-client.generateCardPrompt — prompt_history persistence", () => {
+  test("POSTs a prompt-history row with matching contentHash", async () => {
+    const recorded: Array<{ method: string; path: string; body?: unknown }> =
+      [];
+    const client = new HarmonyApiClient({
+      apiUrl: "http://test",
+      apiKey: "test-key",
+    });
+    (client as any).request = async (
+      method: string,
+      path: string,
+      body?: unknown,
+    ) => {
+      recorded.push({ method, path, body });
+      // Minimal stubs for the subset of routes generateCardPrompt hits.
+      if (path.startsWith("/cards/") && method === "GET") {
+        return {
+          card: {
+            id: "card-1",
+            short_id: 7,
+            title: "Test card",
+            description: "desc",
+            priority: "medium",
+            done: false,
+            labels: [],
+            subtasks: [],
+            links: [],
+            project_id: "proj-1",
+            column_id: "col-1",
+          },
+        };
+      }
+      if (path.startsWith("/board/")) {
+        return { columns: [] };
+      }
+      if (path.startsWith("/memory/")) {
+        return { entities: [] };
+      }
+      if (path === "/prompt-history") {
+        return { entry: { id: "ph-1" } };
+      }
+      return {};
+    };
+
+    const result = await client.generateCardPrompt({
+      cardId: "card-1",
+      workspaceId: "ws-1",
+      projectId: "proj-1",
+      variant: "execute",
+    });
+
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+
+    const phCall = recorded.find(
+      (c) => c.method === "POST" && c.path === "/prompt-history",
+    );
+    expect(phCall).toBeDefined();
+    const body = phCall!.body as Record<string, unknown>;
+    expect(body.cardId).toBe("card-1");
+    expect(body.contentHash).toBe(result.contentHash);
+    expect(body.templateVersion).toBe(PROMPT_TEMPLATE_VERSION);
+    expect(body.confidence).toBe(0.5);
+    expect(body.variant).toBe("execute");
+  });
+
+  test("returns successfully when persistence fails (best-effort)", async () => {
+    const client = new HarmonyApiClient({
+      apiUrl: "http://test",
+      apiKey: "test-key",
+    });
+    (client as any).request = async (method: string, path: string) => {
+      if (path.startsWith("/cards/") && method === "GET") {
+        return {
+          card: {
+            id: "card-1",
+            short_id: 7,
+            title: "Test card",
+            description: null,
+            priority: "medium",
+            done: false,
+            labels: [],
+            subtasks: [],
+            links: [],
+            project_id: "proj-1",
+            column_id: "col-1",
+          },
+        };
+      }
+      if (path.startsWith("/board/")) return { columns: [] };
+      if (path.startsWith("/memory/")) return { entities: [] };
+      if (path === "/prompt-history") {
+        throw new Error("network down");
+      }
+      return {};
+    };
+
+    const result = await client.generateCardPrompt({
+      cardId: "card-1",
+      workspaceId: "ws-1",
+      variant: "analysis",
+    });
+    // Generation still succeeds even when logging fails.
+    expect(result.prompt.length).toBeGreaterThan(0);
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+// ─── AGP P2: variant proposal helper (logged-only) ────────────────────
+
+describe("proposePromptVariant", () => {
+  function row(overrides: Partial<PromptCohortRow> = {}): PromptCohortRow {
+    return {
+      status: "completed",
+      progressPercent: 100,
+      hadBlockers: false,
+      ...overrides,
+    };
+  }
+
+  test("returns null when cohort is smaller than 10", async () => {
+    const cohort = Array.from({ length: 5 }, () =>
+      row({ status: "paused", progressPercent: 30 }),
+    );
+    const suggestion = await proposePromptVariant("hash-1", async () => cohort);
+    expect(suggestion).toBeNull();
+  });
+
+  test("returns null when completion rate is acceptable (>=0.4)", async () => {
+    const cohort = [
+      ...Array.from({ length: 5 }, () => row()),
+      ...Array.from({ length: 5 }, () =>
+        row({ status: "paused", progressPercent: 50 }),
+      ),
+    ];
+    const suggestion = await proposePromptVariant("hash-2", async () => cohort);
+    expect(suggestion).toBeNull();
+  });
+
+  test("returns suggestion when cohort is >=10 and completion rate <0.4", async () => {
+    // 2 successes / 10 sessions = 0.2 completion rate, below 0.4 threshold.
+    const cohort = [
+      ...Array.from({ length: 2 }, () => row()),
+      ...Array.from({ length: 8 }, () =>
+        row({ status: "paused", progressPercent: 30, hadBlockers: false }),
+      ),
+    ];
+    const suggestion = await proposePromptVariant("hash-3", async () => cohort);
+    expect(suggestion).not.toBeNull();
+    expect(suggestion!.contentHash).toBe("hash-3");
+    expect(suggestion!.cohortSize).toBe(10);
+    expect(suggestion!.completionRate).toBeCloseTo(0.2, 5);
+    expect(suggestion!.framingHint).toContain("action-forcing");
+  });
+
+  test("returns blocker-flavoured framing hint when blockers dominate", async () => {
+    // 1 success, 9 blocked sessions → completionRate=0.1, blockerRate=0.9
+    const cohort = [
+      row(),
+      ...Array.from({ length: 9 }, () =>
+        row({ status: "paused", progressPercent: 25, hadBlockers: true }),
+      ),
+    ];
+    const suggestion = await proposePromptVariant("hash-4", async () => cohort);
+    expect(suggestion).not.toBeNull();
+    expect(suggestion!.framingHint).toContain("diagnostic");
+  });
+
+  test("blockers count against completion rate", async () => {
+    // Even at 100% status="completed"+100%, blockers should disqualify them
+    // from being counted as success.
+    const cohort = Array.from({ length: 10 }, () =>
+      row({ status: "completed", progressPercent: 100, hadBlockers: true }),
+    );
+    const suggestion = await proposePromptVariant("hash-5", async () => cohort);
+    expect(suggestion).not.toBeNull();
+    expect(suggestion!.completionRate).toBe(0);
+  });
+});

package/src/__tests__/skills.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Verification harness for skill rendering. Card #182.
+ *
+ * Pins the contract that backs `~/.claude/skills/` delivery: frontmatter shape,
+ * version-marker injection, agent-id substitution. If any of these drift the
+ * MCP bridge installs broken skills silently, so this file is the floor.
+ *
+ * Run with: bun test packages/mcp-server/src/__tests__/skills.test.ts
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  buildSkillFile,
+  SKILL_DEFINITIONS,
+  SKILLS_VERSION,
+} from "../skills.js";
+
+const SKILL_IDS = Object.keys(SKILL_DEFINITIONS);
+const VERSION_MARKER_RE = /<!-- skills-version:(\d+) -->\s*$/;
+
+describe("SKILL_DEFINITIONS", () => {
+  test("registry is non-empty", () => {
+    expect(SKILL_IDS.length).toBeGreaterThan(0);
+  });
+
+  test("SKILLS_VERSION is a numeric string", () => {
+    expect(SKILLS_VERSION).toMatch(/^\d+$/);
+  });
+
+  test.each(SKILL_IDS)("definition %s has required fields", (skillId) => {
+    const skill = SKILL_DEFINITIONS[skillId];
+    expect(skill.name).toBe(skillId);
+    expect(skill.description.length).toBeGreaterThan(0);
+    expect(skill.argumentHint.length).toBeGreaterThan(0);
+    expect(skill.content.length).toBeGreaterThan(0);
+  });
+
+  test("all skill names are unique", () => {
+    const names = SKILL_IDS.map((id) => SKILL_DEFINITIONS[id].name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});
+
+describe("buildSkillFile()", () => {
+  test.each(SKILL_IDS)("renders %s with valid frontmatter", (skillId) => {
+    const out = buildSkillFile(skillId);
+    const skill = SKILL_DEFINITIONS[skillId];
+
+    expect(out.startsWith("---\n")).toBe(true);
+    expect(out).toContain(`\nname: ${skill.name}\n`);
+    expect(out).toContain(`\ndescription: ${skill.description}\n`);
+    expect(out).toContain(`\nargument-hint: ${skill.argumentHint}\n`);
+    expect(out).toContain("---\n\n");
+  });
+
+  test.each(SKILL_IDS)("appends version marker for %s", (skillId) => {
+    const out = buildSkillFile(skillId);
+    const match = out.match(VERSION_MARKER_RE);
+
+    expect(match).not.toBeNull();
+    expect(match?.[1]).toBe(SKILLS_VERSION);
+  });
+
+  test.each(SKILL_IDS)("embeds skill content for %s", (skillId) => {
+    const out = buildSkillFile(skillId);
+    const content = SKILL_DEFINITIONS[skillId].content;
+
+    expect(out).toContain(content.split("\n")[0]);
+    const lastLine = content.trim().split("\n").at(-1) ?? "";
+    expect(out).toContain(lastLine);
+  });
+
+  test("is deterministic — same input yields same output", () => {
+    const a = buildSkillFile("hmy");
+    const b = buildSkillFile("hmy");
+    expect(a).toBe(b);
+  });
+
+  test("throws on unknown skill id", () => {
+    expect(() => buildSkillFile("does-not-exist")).toThrow(/Unknown skill/);
+  });
+
+  describe("agent-id substitution", () => {
+    test("agentId='claude' replaces placeholder phrases in hmy", () => {
+      const withAgent = buildSkillFile("hmy", "claude");
+      expect(withAgent).not.toContain("Your agent identifier");
+      expect(withAgent).not.toContain("Your agent name");
+      expect(withAgent).toContain("claude-code");
+      expect(withAgent).toContain("Claude Code");
+    });
+
+    test("agentId omitted leaves placeholders untouched", () => {
+      const raw = buildSkillFile("hmy");
+      const hasPlaceholder =
+        raw.includes("Your agent identifier") ||
+        raw.includes("Your agent name");
+      const skillContent = SKILL_DEFINITIONS.hmy.content;
+      const sourceHasPlaceholder =
+        skillContent.includes("Your agent identifier") ||
+        skillContent.includes("Your agent name");
+
+      expect(hasPlaceholder).toBe(sourceHasPlaceholder);
+    });
+
+    test("unknown agentId is treated as no-op", () => {
+      const raw = buildSkillFile("hmy");
+      const unknownAgent = buildSkillFile("hmy", "some-other-agent");
+      expect(unknownAgent).toBe(raw);
+    });
+  });
+});

package/src/__tests__/tool-dispatch.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Verification harness for MCP tool dispatch. Card #182.
+ *
+ * Pins the contract between Harmony's MCP server and any MCP client (Claude
+ * Code, Codex, Cursor, etc.). If the dispatch shape drifts, agents lose tools
+ * silently, so this is the floor:
+ *
+ *   1. TOOLS registry is well-formed (shape, names, schemas).
+ *   2. ListTools handler emits the same set TOOLS declares.
+ *   3. CallTool handler routes valid names and isErrors unknown ones.
+ *   4. ListResources / ReadResource cover the published URIs.
+ *   5. Tool ↔ skill name spaces are disjoint.
+ *
+ * Run with: bun test packages/mcp-server/src/__tests__/tool-dispatch.test.ts
+ */
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  RESOURCES,
+  registerHandlers,
+  TOOLS,
+  type ToolDeps,
+} from "../server.js";
+import { SKILL_DEFINITIONS } from "../skills.js";
+
+const TOOL_NAMES = Object.keys(TOOLS);
+
+// ── Fake transport ────────────────────────────────────────────────────────
+
+type Schema = unknown;
+type Handler = (req: unknown) => Promise<unknown>;
+
+class FakeServer {
+  handlers = new Map<Schema, Handler>();
+  setRequestHandler(schema: Schema, handler: Handler): void {
+    this.handlers.set(schema, handler);
+  }
+  call<T = unknown>(schema: Schema, request: unknown): Promise<T> {
+    const handler = this.handlers.get(schema);
+    if (!handler) throw new Error("Handler not registered");
+    return handler(request) as Promise<T>;
+  }
+}
+
+function makeDeps(overrides: Partial<ToolDeps> = {}): ToolDeps {
+  return {
+    getClient: () => ({}) as never,
+    isConfigured: () => true,
+    getActiveProjectId: () => "11111111-1111-1111-1111-111111111111",
+    getActiveWorkspaceId: () => "22222222-2222-2222-2222-222222222222",
+    setActiveProject: () => {},
+    setActiveWorkspace: () => {},
+    getApiUrl: () => "http://localhost",
+    getMemoryDir: () => null,
+    getUserEmail: () => null,
+    saveConfig: () => {},
+    resetClient: () => {},
+    ...overrides,
+  };
+}
+
+// ── Static registry shape ────────────────────────────────────────────────
+
+describe("TOOLS registry", () => {
+  test("is non-empty", () => {
+    expect(TOOL_NAMES.length).toBeGreaterThan(0);
+  });
+
+  test("every name is unique", () => {
+    expect(new Set(TOOL_NAMES).size).toBe(TOOL_NAMES.length);
+  });
+
+  test.each(TOOL_NAMES)("%s is namespaced under harmony_", (name) => {
+    expect(name).toMatch(/^harmony_[a-z0-9_]+$/);
+  });
+
+  test.each(TOOL_NAMES)("%s has description and inputSchema", (name) => {
+    const tool = (
+      TOOLS as Record<string, { description?: unknown; inputSchema?: unknown }>
+    )[name];
+    expect(typeof tool.description).toBe("string");
+    expect((tool.description as string).length).toBeGreaterThan(0);
+    expect(typeof tool.inputSchema).toBe("object");
+    expect(tool.inputSchema).not.toBeNull();
+  });
+
+  test.each(TOOL_NAMES)("%s inputSchema is a JSON Schema object", (name) => {
+    const schema = (
+      TOOLS as Record<
+        string,
+        { inputSchema: { type?: string; properties?: unknown } }
+      >
+    )[name].inputSchema;
+    expect(schema.type).toBe("object");
+    if ("properties" in schema && schema.properties !== undefined) {
+      expect(typeof schema.properties).toBe("object");
+    }
+  });
+});
+
+// ── Skill ↔ tool boundary ────────────────────────────────────────────────
+
+describe("skill ↔ tool namespace boundary", () => {
+  test("skill names and tool names are disjoint", () => {
+    const skillNames = new Set(Object.keys(SKILL_DEFINITIONS));
+    const collisions = TOOL_NAMES.filter((name) => skillNames.has(name));
+    expect(collisions).toEqual([]);
+  });
+});
+
+// ── Dispatch round-trip ──────────────────────────────────────────────────
+
+describe("registerHandlers — ListTools", () => {
+  let server: FakeServer;
+
+  beforeAll(() => {
+    server = new FakeServer();
+    registerHandlers(server as never, makeDeps());
+  });
+
+  test("registers all four request handlers", () => {
+    expect(server.handlers.has(ListToolsRequestSchema)).toBe(true);
+    expect(server.handlers.has(CallToolRequestSchema)).toBe(true);
+    expect(server.handlers.has(ListResourcesRequestSchema)).toBe(true);
+    expect(server.handlers.has(ReadResourceRequestSchema)).toBe(true);
+  });
+
+  test("emits one entry per TOOLS row, with name+description+inputSchema", async () => {
+    const result = await server.call<{
+      tools: Array<{ name: string; description: string; inputSchema: unknown }>;
+    }>(ListToolsRequestSchema, { method: "tools/list" });
+
+    expect(result.tools.length).toBe(TOOL_NAMES.length);
+
+    const emittedNames = result.tools.map((t) => t.name).sort();
+    expect(emittedNames).toEqual([...TOOL_NAMES].sort());
+
+    for (const tool of result.tools) {
+      expect(typeof tool.name).toBe("string");
+      expect(typeof tool.description).toBe("string");
+      expect(typeof tool.inputSchema).toBe("object");
+    }
+  });
+});
+
+describe("registerHandlers — CallTool", () => {
+  let server: FakeServer;
+  let workspaceId: string | null;
+  let projectId: string | null;
+
+  beforeAll(() => {
+    server = new FakeServer();
+    workspaceId = "22222222-2222-2222-2222-222222222222";
+    projectId = "11111111-1111-1111-1111-111111111111";
+    const deps = makeDeps({
+      getActiveWorkspaceId: () => workspaceId,
+      getActiveProjectId: () => projectId,
+    });
+    registerHandlers(server as never, deps);
+  });
+
+  test("routes harmony_get_context and returns active ids", async () => {
+    const result = await server.call<{
+      content: Array<{ type: string; text: string }>;
+      isError?: boolean;
+    }>(CallToolRequestSchema, {
+      method: "tools/call",
+      params: { name: "harmony_get_context", arguments: {} },
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].type).toBe("text");
+    const payload = JSON.parse(result.content[0].text);
+    expect(payload.success).toBe(true);
+    expect(payload.context.activeWorkspaceId).toBe(workspaceId);
+    expect(payload.context.activeProjectId).toBe(projectId);
+  });
+
+  test("unknown tool name returns isError without throwing", async () => {
+    const result = await server.call<{
+      content: Array<{ type: string; text: string }>;
+      isError?: boolean;
+    }>(CallToolRequestSchema, {
+      method: "tools/call",
+      params: { name: "harmony_does_not_exist", arguments: {} },
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text.toLowerCase()).toContain("error");
+  });
+
+  test("not-configured rejects authenticated tools", async () => {
+    const unconfigured = new FakeServer();
+    registerHandlers(
+      unconfigured as never,
+      makeDeps({ isConfigured: () => false }),
+    );
+
+    const result = await unconfigured.call<{
+      content: Array<{ type: string; text: string }>;
+      isError?: boolean;
+    }>(CallToolRequestSchema, {
+      method: "tools/call",
+      params: { name: "harmony_get_context", arguments: {} },
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("Not configured");
+  });
+});
+
+// ── Resources ────────────────────────────────────────────────────────────
+
+describe("registerHandlers — Resources", () => {
+  let server: FakeServer;
+
+  beforeAll(() => {
+    server = new FakeServer();
+    registerHandlers(server as never, makeDeps());
+  });
+
+  test("ListResources mirrors the static RESOURCES array", async () => {
+    const result = await server.call<{ resources: typeof RESOURCES }>(
+      ListResourcesRequestSchema,
+      { method: "resources/list" },
+    );
+    expect(result.resources).toEqual(RESOURCES);
+  });
+
+  test("ReadResource serves harmony://context as JSON", async () => {
+    const result = await server.call<{
+      contents: Array<{ uri: string; mimeType: string; text: string }>;
+    }>(ReadResourceRequestSchema, {
+      method: "resources/read",
+      params: { uri: "harmony://context" },
+    });
+
+    expect(result.contents[0].uri).toBe("harmony://context");
+    expect(result.contents[0].mimeType).toBe("application/json");
+    const parsed = JSON.parse(result.contents[0].text);
+    expect(parsed).toHaveProperty("configured");
+    expect(parsed).toHaveProperty("activeWorkspaceId");
+    expect(parsed).toHaveProperty("activeProjectId");
+  });
+
+  test("ReadResource on unknown URI throws", async () => {
+    await expect(
+      server.call(ReadResourceRequestSchema, {
+        method: "resources/read",
+        params: { uri: "harmony://nope" },
+      }),
+    ).rejects.toThrow(/Unknown resource/);
+  });
+});