@gethmy/mcp 2.12.0 → 2.13.0

package/dist/cli.js

@@ -990,6 +990,7 @@ import { createRequire as createRequire2 } from "node:module";
 import { program } from "commander";
 
 // src/server.ts
+import { createHash as createHash4 } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 // ../memory/dist/sync.js
@@ -1496,6 +1497,9 @@ var TIMINGS = {
   QUERY_STALE_TIME: 1000 * 60 * 5,
   QUERY_GC_TIME: 1000 * 60 * 60 * 24
 };
+// ../harmony-shared/dist/stageHandoff.js
+var HANDOFF_MARKER = "harmony:stage-handoff";
+var HANDOFF_BLOCK_RE = new RegExp("```json\\s*\\n//\\s*" + HANDOFF_MARKER + "\\s*\\n([\\s\\S]*?)\\n```", "m");
 // src/api-client.ts
 init_config();
 var RETRY_CONFIG = {
@@ -1855,12 +1859,24 @@ class HarmonyApiClient {
   async uploadCardAttachment(cardId, data) {
     return this.request("POST", `/cards/${cardId}/attachments`, data);
   }
+  async requestCardAttachmentUploadUrl(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/attachment-upload-url`, data);
+  }
+  async finalizeCardAttachment(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/attachments/finalize`, data);
+  }
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
   async uploadArtifact(data) {
     return this.request("POST", "/artifacts", data);
   }
+  async requestArtifactUploadUrl(data) {
+    return this.request("POST", "/artifacts/upload-url", data);
+  }
+  async finalizeArtifact(data) {
+    return this.request("POST", "/artifacts/finalize", data);
+  }
   async createArtifactShareLink(artifactId, expiresAt) {
     return this.request("POST", `/artifacts/${artifactId}/share`, {
       expires_at: expiresAt
@@ -2338,6 +2354,12 @@ ${planContent.trim()}`;
   async getPlaybook(playbookId) {
     return this.request("GET", `/playbooks/${playbookId}`);
   }
+  async getPlaybookVersion(playbookId, version) {
+    return this.request("GET", `/playbooks/${encodeURIComponent(playbookId)}/versions/${version}`);
+  }
+  async recordStageGateEvidence(insert) {
+    return this.request("POST", `/cards/${encodeURIComponent(insert.card_id)}/stage-gate-evidence`, insert);
+  }
   async createPlaybook(data) {
     return this.request("POST", "/playbooks", data);
   }
@@ -3436,6 +3458,52 @@ async function refreshSkills(opts = {}) {
 }
 
 // src/server.ts
+var MAX_ARTIFACT_SIZE = 2 * 1024 * 1024;
+var MAX_ATTACHMENT_SIZE = 5 * 1024 * 1024;
+function base64ByteLength(base64) {
+  const stripped = base64.replace(/^data:[^,]*,/, "");
+  return Buffer.from(stripped, "base64").byteLength;
+}
+function sha256Hex(bytes) {
+  return createHash4("sha256").update(bytes).digest("hex");
+}
+async function readFileForUpload(filePath, maxSize, kind) {
+  const bytes = await readFile(filePath);
+  if (bytes.byteLength === 0) {
+    throw new Error(`File is empty: ${filePath}`);
+  }
+  if (bytes.byteLength > maxSize) {
+    const mb = Math.round(maxSize / (1024 * 1024));
+    throw new Error(`File is ${bytes.byteLength} bytes, over the ${maxSize}-byte (${mb}MB) ${kind} limit.`);
+  }
+  return bytes;
+}
+function requireExactlyOneScope(scope) {
+  if ([scope.cardId, scope.planId, scope.workspaceId].filter(Boolean).length !== 1) {
+    throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
+  }
+}
+var SIGNED_UPLOAD_TIMEOUT_MS = 30000;
+async function putToSignedUrl(uploadUrl, bytes, contentType) {
+  let res;
+  try {
+    res = await fetch(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": contentType },
+      body: bytes,
+      signal: AbortSignal.timeout(SIGNED_UPLOAD_TIMEOUT_MS)
+    });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "TimeoutError") {
+      throw new Error(`Direct storage upload timed out after ${SIGNED_UPLOAD_TIMEOUT_MS}ms.`);
+    }
+    throw err;
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`Direct storage upload failed: ${res.status}${detail ? ` — ${detail}` : ""}`);
+  }
+}
 var memorySessions = new Map;
 function parseLabelList(raw) {
   if (raw === undefined || raw === null)
@@ -3896,7 +3964,7 @@ var TOOLS = {
     }
   },
   harmony_upload_card_attachment: {
-    description: "Upload a file attachment to a card (e.g. a pasted screenshot or a document). Provide the file either as `filePath` (a local path the MCP server can read — works in local/stdio mode) or as `base64Data` (raw base64 bytes — works everywhere, including remote mode). Max 5MB. Allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV. Returns the stored attachment with a short-lived signed URL.",
+    description: "Upload a file attachment to a card (e.g. a pasted screenshot or a document). Provide the file either as `filePath` (a local path the MCP server can read — works in local/stdio mode) or as `base64Data` (raw base64 bytes — works everywhere, including remote mode). With `filePath` the server uploads direct-to-storage (no base64 through the model context); `base64Data` is the small-file fallback. Max 5MB. Allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV. Returns the stored attachment with a short-lived signed URL. For large files on the hosted MCP server (where only base64Data works), prefer the two-step harmony_request_card_attachment_upload_url + harmony_finalize_card_attachment handshake, which keeps bytes out of the model context.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3921,6 +3989,58 @@ var TOOLS = {
       required: ["cardId"]
     }
   },
+  harmony_request_card_attachment_upload_url: {
+    description: "Step 1 of the agent-driven card-attachment upload — use this for large files or when running against the hosted MCP server (which cannot read your local disk). Mints a one-shot signed Supabase Storage upload URL for a server-chosen path under the card. Provide cardId, fileName (with extension), the byte size, and optionally fileType. Returns { uploadUrl, token, storagePath, fileType }. Next: PUT the raw bytes straight to uploadUrl (e.g. `curl -X PUT --data-binary @file.png '<uploadUrl>'`) — no bytes pass through the model context — then call harmony_finalize_card_attachment with the returned storagePath. Max 5MB; allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" },
+        fileName: {
+          type: "string",
+          description: "File name including extension (e.g. 'screenshot.png')."
+        },
+        fileType: {
+          type: "string",
+          description: "Optional MIME type (e.g. 'image/png'). Inferred from the file extension when omitted."
+        },
+        size: {
+          type: "number",
+          description: "File size in bytes (rejected early if over 5MB)."
+        }
+      },
+      required: ["cardId", "fileName", "size"]
+    }
+  },
+  harmony_finalize_card_attachment: {
+    description: "Step 2 of the agent-driven card-attachment upload. After PUTting the bytes to the signed uploadUrl from harmony_request_card_attachment_upload_url, call this with the returned storagePath to validate and register the attachment. The server re-downloads the object and enforces size, an allowlisted content-type (magic-byte sniff, never the declared type), and — when you pass sha256 — an integrity check, deleting the object and failing on any mismatch. Returns the stored attachment with a short-lived signed URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" },
+        storagePath: {
+          type: "string",
+          description: "The storagePath returned by harmony_request_card_attachment_upload_url."
+        },
+        fileName: {
+          type: "string",
+          description: "File name including extension (e.g. 'screenshot.png')."
+        },
+        fileType: {
+          type: "string",
+          description: "Optional MIME type; inferred from the extension when omitted."
+        },
+        sha256: {
+          type: "string",
+          description: "Optional hex SHA-256 of the uploaded bytes; verified against the stored object."
+        },
+        size: {
+          type: "number",
+          description: "Optional byte size (advisory; re-validated server-side)."
+        }
+      },
+      required: ["cardId", "storagePath", "fileName"]
+    }
+  },
   harmony_classify_card: {
     description: "Classify a card with the LLM classifier: sets `intent` (plan/think/implement/review), `complexity_score` (0-10), and `model_tier` (simple/advanced/research), stamps `classified_at`, and applies the canonical type label (feature/bug/idea). Use this right after creating a card (e.g. in the `hmy-new` flow) so it's classified in-flow instead of waiting for it to surface on the web board. Idempotent — safe to re-run. Never touches the user-owned `model_override`.",
     inputSchema: {
@@ -3932,7 +4052,7 @@ var TOOLS = {
     }
   },
   harmony_upload_artifact: {
-    description: "Host a self-contained HTML document (e.g. a visual design draft or diagram) in Harmony and link it to a card, a plan, or a workspace. The file is stored privately and rendered in-app inside a sandboxed cross-origin iframe. Provide exactly one of cardId, planId, or workspaceId. Supply the HTML as `filePath` (a local path the MCP server can read) or `base64Data`. Only text/html, max 2MB. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link.",
+    description: "Host a self-contained HTML document (e.g. a visual design draft or diagram) in Harmony and link it to a card, a plan, or a workspace. The file is stored privately and rendered in-app inside a sandboxed cross-origin iframe. Provide exactly one of cardId, planId, or workspaceId. Supply the HTML as `filePath` (a local path the MCP server can read — uploaded direct-to-storage, no base64 through the model context) or `base64Data` (the small-file fallback). Only text/html, max 2MB. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link. For large files on the hosted MCP server (where only base64Data works), prefer the two-step harmony_request_artifact_upload_url + harmony_finalize_artifact handshake, which keeps bytes out of the model context.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3958,6 +4078,61 @@ var TOOLS = {
       required: []
     }
   },
+  harmony_request_artifact_upload_url: {
+    description: "Step 1 of the agent-driven artifact upload — use this for large files or when running against the hosted MCP server (which cannot read your local disk), instead of streaming base64 through the model context. Mints a one-shot signed Supabase Storage upload URL for a server-chosen path. Provide exactly one of cardId/planId/workspaceId, optionally a title and the byte size. Returns { uploadUrl, token, storagePath }. Next: PUT the raw HTML bytes straight to uploadUrl (e.g. `curl -X PUT --data-binary @doc.html '<uploadUrl>'`), then call harmony_finalize_artifact with the returned storagePath. Only text/html, max 2MB.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Display title (defaults to the file basename at finalize)."
+        },
+        cardId: { type: "string", description: "Link to this card (UUID)." },
+        planId: { type: "string", description: "Link to this plan (UUID)." },
+        workspaceId: {
+          type: "string",
+          description: "Attach to this workspace as a standalone artifact (UUID)."
+        },
+        contentType: {
+          type: "string",
+          description: "MIME type; only 'text/html' is accepted (the default)."
+        },
+        size: {
+          type: "number",
+          description: "File size in bytes (rejected early if over 2MB)."
+        }
+      },
+      required: []
+    }
+  },
+  harmony_finalize_artifact: {
+    description: "Step 2 of the agent-driven artifact upload. After PUTting the HTML bytes to the signed uploadUrl from harmony_request_artifact_upload_url, call this with the returned storagePath to validate and register the artifact. The server re-downloads the object and enforces size, the text/html content-type (magic-byte sniff), and — when you pass sha256 — an integrity check, deleting the object and failing on any mismatch. Provide the same one of cardId/planId/workspaceId used for the upload URL. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        storagePath: {
+          type: "string",
+          description: "The storagePath returned by harmony_request_artifact_upload_url."
+        },
+        title: { type: "string", description: "Display title." },
+        cardId: { type: "string", description: "Link to this card (UUID)." },
+        planId: { type: "string", description: "Link to this plan (UUID)." },
+        workspaceId: {
+          type: "string",
+          description: "Attach to this workspace as a standalone artifact (UUID)."
+        },
+        sha256: {
+          type: "string",
+          description: "Optional hex SHA-256 of the uploaded bytes; verified against the stored object."
+        },
+        size: {
+          type: "number",
+          description: "Optional byte size (advisory; re-validated server-side)."
+        }
+      },
+      required: ["storagePath"]
+    }
+  },
   harmony_share_artifact: {
     description: "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL.",
     inputSchema: {
@@ -5555,70 +5730,157 @@ async function handleToolCall(name, args, deps) {
       const cardId = z.string().uuid().parse(args.cardId);
       const filePath = args.filePath != null ? z.string().parse(args.filePath) : undefined;
       const base64Data = args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
-      let fileName = args.fileName != null ? z.string().parse(args.fileName) : undefined;
+      const fileName = args.fileName != null ? z.string().parse(args.fileName) : undefined;
       const contentType = args.contentType != null ? z.string().parse(args.contentType) : undefined;
       if (filePath && base64Data) {
         throw new Error("Provide either filePath or base64Data, not both.");
       }
-      let data;
       if (filePath) {
-        const bytes = await readFile(filePath);
-        if (bytes.byteLength === 0) {
-          throw new Error(`File is empty: ${filePath}`);
-        }
-        data = bytes.toString("base64");
-        fileName = fileName || basename(filePath);
-      } else if (base64Data) {
+        const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
+        const resolvedName = fileName || basename(filePath);
+        const signed = await client3.requestCardAttachmentUploadUrl(cardId, {
+          fileName: resolvedName,
+          fileType: contentType,
+          size: bytes.byteLength
+        });
+        await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
+        return await client3.finalizeCardAttachment(cardId, {
+          storagePath: signed.storagePath,
+          fileName: resolvedName,
+          fileType: contentType || signed.fileType,
+          sha256: sha256Hex(bytes),
+          size: bytes.byteLength
+        });
+      }
+      if (base64Data) {
         if (!fileName) {
           throw new Error("fileName is required when using base64Data.");
         }
-        data = base64Data;
-      } else {
-        throw new Error("Provide either filePath or base64Data.");
+        if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
+          throw new Error(`File is over the 5MB attachment limit. Use the harmony_request_card_attachment_upload_url + harmony_finalize_card_attachment handshake for large files.`);
+        }
+        return await client3.uploadCardAttachment(cardId, {
+          fileName,
+          data: base64Data,
+          fileType: contentType
+        });
       }
-      const result = await client3.uploadCardAttachment(cardId, {
-        fileName,
-        data,
-        fileType: contentType
-      });
-      return result;
+      throw new Error("Provide either filePath or base64Data.");
     }
     case "harmony_upload_artifact": {
       const title = args.title != null ? z.string().parse(args.title) : undefined;
       const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
       const planId = args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
       const workspaceId = args.workspaceId != null ? z.string().uuid().parse(args.workspaceId) : undefined;
-      const anchors = [cardId, planId, workspaceId].filter(Boolean);
-      if (anchors.length !== 1) {
-        throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
-      }
+      requireExactlyOneScope({ cardId, planId, workspaceId });
       const filePath = args.filePath != null ? z.string().parse(args.filePath) : undefined;
       const base64Data = args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
       if (filePath && base64Data) {
         throw new Error("Provide either filePath or base64Data, not both.");
       }
-      let data;
-      let inferredTitle = title;
       if (filePath) {
-        const bytes = await readFile(filePath);
-        if (bytes.byteLength === 0) {
-          throw new Error(`File is empty: ${filePath}`);
+        const bytes = await readFileForUpload(filePath, MAX_ARTIFACT_SIZE, "artifact");
+        const resolvedTitle = title || basename(filePath);
+        const signed = await client3.requestArtifactUploadUrl({
+          title: resolvedTitle,
+          cardId,
+          planId,
+          workspaceId,
+          contentType: "text/html",
+          size: bytes.byteLength
+        });
+        await putToSignedUrl(signed.uploadUrl, bytes, "text/html");
+        return await client3.finalizeArtifact({
+          storagePath: signed.storagePath,
+          sha256: sha256Hex(bytes),
+          size: bytes.byteLength,
+          title: resolvedTitle,
+          cardId,
+          planId,
+          workspaceId
+        });
+      }
+      if (base64Data) {
+        if (base64ByteLength(base64Data) > MAX_ARTIFACT_SIZE) {
+          throw new Error(`Artifact is over the 2MB limit. Use the harmony_request_artifact_upload_url + harmony_finalize_artifact handshake for large files.`);
         }
-        data = bytes.toString("base64");
-        inferredTitle = inferredTitle || basename(filePath);
-      } else if (base64Data) {
-        data = base64Data;
-      } else {
-        throw new Error("Provide either filePath or base64Data.");
+        return await client3.uploadArtifact({
+          title,
+          cardId,
+          planId,
+          workspaceId,
+          data: base64Data
+        });
       }
-      const result = await client3.uploadArtifact({
-        title: inferredTitle,
+      throw new Error("Provide either filePath or base64Data.");
+    }
+    case "harmony_request_artifact_upload_url": {
+      const title = args.title != null ? z.string().parse(args.title) : undefined;
+      const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
+      const planId = args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
+      const workspaceId = args.workspaceId != null ? z.string().uuid().parse(args.workspaceId) : undefined;
+      requireExactlyOneScope({ cardId, planId, workspaceId });
+      const contentType = args.contentType != null ? z.string().parse(args.contentType) : undefined;
+      const size = args.size != null ? z.number().positive().parse(args.size) : undefined;
+      if (size != null && size > MAX_ARTIFACT_SIZE) {
+        throw new Error(`Declared size ${size} bytes is over the ${MAX_ARTIFACT_SIZE}-byte (2MB) artifact limit.`);
+      }
+      return await client3.requestArtifactUploadUrl({
+        title,
         cardId,
         planId,
         workspaceId,
-        data
+        contentType,
+        size
+      });
+    }
+    case "harmony_finalize_artifact": {
+      const storagePath = z.string().parse(args.storagePath);
+      const title = args.title != null ? z.string().parse(args.title) : undefined;
+      const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
+      const planId = args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
+      const workspaceId = args.workspaceId != null ? z.string().uuid().parse(args.workspaceId) : undefined;
+      requireExactlyOneScope({ cardId, planId, workspaceId });
+      const sha256 = args.sha256 != null ? z.string().parse(args.sha256) : undefined;
+      const size = args.size != null ? z.number().positive().parse(args.size) : undefined;
+      return await client3.finalizeArtifact({
+        storagePath,
+        sha256,
+        size,
+        title,
+        cardId,
+        planId,
+        workspaceId
+      });
+    }
+    case "harmony_request_card_attachment_upload_url": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const fileName = z.string().parse(args.fileName);
+      const fileType = args.fileType != null ? z.string().parse(args.fileType) : undefined;
+      const size = z.number().positive().parse(args.size);
+      if (size > MAX_ATTACHMENT_SIZE) {
+        throw new Error(`Declared size ${size} bytes is over the ${MAX_ATTACHMENT_SIZE}-byte (5MB) attachment limit.`);
+      }
+      return await client3.requestCardAttachmentUploadUrl(cardId, {
+        fileName,
+        fileType,
+        size
+      });
+    }
+    case "harmony_finalize_card_attachment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const storagePath = z.string().parse(args.storagePath);
+      const fileName = z.string().parse(args.fileName);
+      const fileType = args.fileType != null ? z.string().parse(args.fileType) : undefined;
+      const sha256 = args.sha256 != null ? z.string().parse(args.sha256) : undefined;
+      const size = args.size != null ? z.number().positive().parse(args.size) : undefined;
+      return await client3.finalizeCardAttachment(cardId, {
+        storagePath,
+        fileName,
+        fileType,
+        sha256,
+        size
       });
-      return result;
     }
     case "harmony_share_artifact": {
       const artifactId = z.string().uuid().parse(args.artifactId);
@@ -6745,7 +7007,7 @@ class HarmonyMCPServer {
 }
 
 // src/tui/setup.ts
-import { createHash as createHash4 } from "node:crypto";
+import { createHash as createHash5 } from "node:crypto";
 import {
   existsSync as existsSync8,
   lstatSync,
@@ -7940,7 +8202,7 @@ ${summary}`);
       }
       try {
         const updateCheckFetched = await client3.fetchSkill("hmy-update-check");
-        const actualHash = createHash4("sha256").update(updateCheckFetched.content).digest("hex");
+        const actualHash = createHash5("sha256").update(updateCheckFetched.content).digest("hex");
         if (actualHash !== updateCheckFetched.sha256) {
           throw new Error(`hmy-update-check integrity check failed: expected ${updateCheckFetched.sha256}, got ${actualHash}`);
         }