@gethmy/mcp 2.5.2 → 2.5.4

package/dist/cli.js

@@ -4786,7 +4786,6 @@ class HarmonyMCPServer {
 // src/skills.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname } from "node:path";
-var VERSION_MARKER_PREFIX = "<!-- skills-version:";
 var HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
 
 Start work on a Harmony card. Card reference: $ARGUMENTS
@@ -4863,17 +4862,34 @@ If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
 **AI:** \`harmony_generate_prompt\`, \`harmony_process_command\`
 `;
 function buildSkillFile(skill) {
-  const major = Number.parseInt(skill.version.split(".")[0] ?? "", 10);
-  if (!Number.isFinite(major) || major < 1) {
-    throw new Error(`Invalid skill version: ${skill.version}`);
+  if (skill.skillVersion !== undefined && !hasMetadataVersion(skill.content)) {
+    return injectMetadataVersion(skill.content, skill.skillVersion);
   }
-  const trimmed = skill.content.replace(/\n+$/, "");
-  return `${trimmed}
-${VERSION_MARKER_PREFIX}${major} -->`;
+  return skill.content;
+}
+function hasMetadataVersion(content) {
+  return parseSkillVersion(content) !== null;
+}
+function injectMetadataVersion(content, version) {
+  const fmMatch = content.match(/^(---\n[\s\S]*?\n)(---\n)([\s\S]*)$/);
+  if (!fmMatch)
+    return content;
+  const [, head, close, body] = fmMatch;
+  const block = `metadata:
+  version: "${version}"
+`;
+  return `${head}${block}${close}${body}`;
 }
 function parseSkillVersion(content) {
-  const match = content.match(/<!-- skills-version:(\d+) -->/);
-  return match ? match[1] : null;
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const fm = fmMatch[1];
+    const verMatch = fm.match(/^metadata:[\s\S]*?\n[ \t]+version:[ \t]*["']?(\d+)["']?\s*$/m);
+    if (verMatch)
+      return verMatch[1];
+  }
+  const legacy = content.match(/<!-- skills-version:(\d+) -->/);
+  return legacy ? legacy[1] : null;
 }
 function findSkillFiles(paths, knownNames) {
   const results = [];
@@ -4919,18 +4935,16 @@ async function refreshSkills() {
     }
     if (skillFiles.length === 0)
       return;
-    const remoteMajor = Number.parseInt(versionInfo.version.split(".")[0] ?? "", 10);
-    if (!Number.isFinite(remoteMajor))
-      return;
     let updated = false;
     for (const { name, filePath } of skillFiles) {
       try {
         const currentContent = readFileSync3(filePath, "utf-8");
         const localVersion = parseSkillVersion(currentContent);
-        if (localVersion !== null && Number(localVersion) >= remoteMajor) {
+        const fetched = await client3.fetchSkill(name);
+        const remoteVersion = fetched.skillVersion;
+        if (remoteVersion !== undefined && localVersion !== null && Number(localVersion) >= remoteVersion) {
           continue;
         }
-        const fetched = await client3.fetchSkill(name);
         const newContent = buildSkillFile(fetched);
         const dir = dirname(filePath);
         if (!existsSync3(dir))
@@ -4943,7 +4957,7 @@ async function refreshSkills() {
       }
     }
     if (updated) {
-      console.error(`Harmony: Updated skills to v${versionInfo.version}`);
+      console.error("Harmony: Refreshed skills from server");
     }
   } catch {}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.5.2",
+  "version": "2.5.4",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -342,10 +342,15 @@ export class HarmonyApiClient {
   /**
    * GET /v1/skills/{name} — authenticated content fetch.
    * Returns rendered SKILL.md (frontmatter + body) ready to install.
+   *
+   * Phase 3b: `skillVersion` (per-skill integer) is returned alongside the
+   * legacy aggregate `version` string so refreshSkills can compare per-skill
+   * instead of treating any global bump as "everything stale."
    */
   async fetchSkill(name: string): Promise<{
     name: string;
     version: string;
+    skillVersion?: number;
     content: string;
     sha256: string;
     signature: string;

package/src/skills.ts

@@ -3,8 +3,6 @@ import { dirname } from "node:path";
 import { HarmonyApiClient } from "./api-client.js";
 import { areSkillsInstalled, isConfigured } from "./config.js";
 
-const VERSION_MARKER_PREFIX = "<!-- skills-version:";
-
 /**
  * Legacy workflow prompt used by Codex / Cursor agents. Kept inline because
  * those agents install via AGENTS.md and not via /v1/skills. Claude Code
@@ -88,35 +86,76 @@ If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
 
 /**
  * Shape of a /v1/skills/{name} response. Used by buildSkillFile + tests.
+ *
+ * Phase 3b: `skillVersion` is the per-skill integer from `skill_resource.version`.
+ * `version` remains the aggregate "<major>.0.0" string used by the bash bootstrap
+ * for cache freshness — kept for compatibility, not load-bearing for refresh.
  */
 export interface FetchedSkill {
   name: string;
-  version: string; // "X.Y.Z" aggregate from /v1/skills/{name}
-  content: string; // rendered SKILL.md (frontmatter + body), already complete
+  version: string;
+  /** Per-skill row.version (Phase 3b). Optional during rollout — older harmony-api
+   *  deployments may omit it; treat absence as "trust the rendered frontmatter". */
+  skillVersion?: number;
+  content: string;
 }
 
 /**
- * Append the version marker so refreshSkills() can detect stale files later.
- * The harmony-api distribution shape omits the marker; mcp-server adds it on
- * install so parseSkillVersion() can read it back. The marker integer is the
- * major component of the aggregate version (e.g., "5.0.0" → 5).
+ * Pass the API-rendered SKILL.md through to disk. As of Phase 3b the
+ * frontmatter already carries `metadata.version: "<N>"` (rendered server-side
+ * by harmony-api), which is the source of truth `parseSkillVersion` reads on
+ * the next refresh. No EOF marker is appended.
+ *
+ * If `skillVersion` is provided AND the rendered content lacks the metadata.version
+ * block (older harmony-api deployment), we splice it in so install state always
+ * carries a parseable version. This preserves Phase-3b semantics across rolling
+ * deploys where the API hasn't been upgraded yet.
  */
 export function buildSkillFile(skill: FetchedSkill): string {
-  const major = Number.parseInt(skill.version.split(".")[0] ?? "", 10);
-  if (!Number.isFinite(major) || major < 1) {
-    throw new Error(`Invalid skill version: ${skill.version}`);
+  if (skill.skillVersion !== undefined && !hasMetadataVersion(skill.content)) {
+    return injectMetadataVersion(skill.content, skill.skillVersion);
   }
-  const trimmed = skill.content.replace(/\n+$/, "");
-  return `${trimmed}\n${VERSION_MARKER_PREFIX}${major} -->`;
+  return skill.content;
+}
+
+function hasMetadataVersion(content: string): boolean {
+  return parseSkillVersion(content) !== null;
+}
+
+/**
+ * Splice `metadata.version: "<N>"` into the frontmatter of a rendered
+ * SKILL.md. Only used when harmony-api hasn't been upgraded to Phase-3b
+ * yet but mcp-server has — the fallback keeps install state consistent.
+ */
+function injectMetadataVersion(content: string, version: number): string {
+  const fmMatch = content.match(/^(---\n[\s\S]*?\n)(---\n)([\s\S]*)$/);
+  if (!fmMatch) return content;
+  const [, head, close, body] = fmMatch;
+  const block = `metadata:\n  version: "${version}"\n`;
+  return `${head}${block}${close}${body}`;
 }
 
 /**
- * Parse the embedded version marker out of an installed skill file.
- * Returns null if no marker is found — caller treats that as "stale".
+ * Parse `metadata.version` out of an installed skill's frontmatter.
+ * Falls back to the legacy `<!-- skills-version:N -->` EOF marker so files
+ * installed by pre-Phase-3b mcp-server builds keep refreshing correctly
+ * until they're rewritten. Returns null when neither is present — the
+ * caller treats null as "stale, rewrite from API".
  */
 function parseSkillVersion(content: string): string | null {
-  const match = content.match(/<!-- skills-version:(\d+) -->/);
-  return match ? match[1] : null;
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const fm = fmMatch[1];
+    // Match a `version:` line under a `metadata:` block. Tolerates either
+    // 2-space or 4-space child indentation and "..." or '...' quoting.
+    const verMatch = fm.match(
+      /^metadata:[\s\S]*?\n[ \t]+version:[ \t]*["']?(\d+)["']?\s*$/m,
+    );
+    if (verMatch) return verMatch[1];
+  }
+  // Legacy fallback — installed by pre-Phase-3b mcp-server builds.
+  const legacy = content.match(/<!-- skills-version:(\d+) -->/);
+  return legacy ? legacy[1] : null;
 }
 
 /**
@@ -146,6 +185,12 @@ function findSkillFiles(
  * Silently refresh installed skill files if remote versions are newer.
  * Called at MCP server startup. Non-blocking — any error (offline, 401,
  * partial install) is caught and the existing files are left in place.
+ *
+ * Phase 3b: per-skill compare. Each skill_resource row carries its own
+ * monotonic `version`. The mcp-server fetches each skill's `/v1/skills/<name>`
+ * once, reads the per-skill `skillVersion` from the response, and rewrites
+ * only the local files that are behind. An admin bumping `hmy` no longer
+ * triggers a re-fetch of `hmy-plan`, `hmy-cleanup`, etc.
  */
 export async function refreshSkills(): Promise<void> {
   try {
@@ -179,21 +224,25 @@ export async function refreshSkills(): Promise<void> {
     }
     if (skillFiles.length === 0) return;
 
-    const remoteMajor = Number.parseInt(
-      versionInfo.version.split(".")[0] ?? "",
-      10,
-    );
-    if (!Number.isFinite(remoteMajor)) return;
-
     let updated = false;
     for (const { name, filePath } of skillFiles) {
       try {
         const currentContent = readFileSync(filePath, "utf-8");
         const localVersion = parseSkillVersion(currentContent);
-        if (localVersion !== null && Number(localVersion) >= remoteMajor) {
+
+        // Fetch first so we can read the authoritative per-skill version
+        // from the response. Cheaper than a separate version probe per skill.
+        const fetched = await client.fetchSkill(name);
+        const remoteVersion = fetched.skillVersion;
+
+        if (
+          remoteVersion !== undefined &&
+          localVersion !== null &&
+          Number(localVersion) >= remoteVersion
+        ) {
           continue;
         }
-        const fetched = await client.fetchSkill(name);
+
         const newContent = buildSkillFile(fetched);
         const dir = dirname(filePath);
         if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -205,7 +254,7 @@ export async function refreshSkills(): Promise<void> {
       }
     }
     if (updated) {
-      console.error(`Harmony: Updated skills to v${versionInfo.version}`);
+      console.error("Harmony: Refreshed skills from server");
     }
   } catch {
     // Non-blocking — offline / 401 / partial install all fall through here.