@gethmy/mcp 3.7.0 → 3.9.0

package/src/tui/setup.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
   existsSync,
@@ -23,7 +24,11 @@ import {
 } from "../config.js";
 import { loginWithBrowser, type OAuthTokens } from "../oauth-login.js";
 import { onboardNewUser } from "../onboard.js";
-import { buildSkillFile, HARMONY_WORKFLOW_PROMPT } from "../skills.js";
+import { buildSkillFile } from "../skills.js";
+import {
+  HARMONY_AGENTS_SECTION,
+  renderWorkflowPrompt,
+} from "./agent-instructions.js";
 import { type AgentId, detectAgents } from "./agents.js";
 import { confirmOrDefault, shouldAssumeYes } from "./confirm.js";
 import { runDocsStep } from "./docs.js";
@@ -61,11 +66,17 @@ export interface SetupOptions {
  * keep, especially under autonomous agent runs. New tools default to prompting
  * until someone classifies them here (safe failure mode). `--allow-all-tools`
  * overrides this with a blanket grant.
+ *
+ * Every name here must exist in the advertised `TOOLS` object in `server.ts`.
+ * `harmony_get_card_by_short_id` sat in this list for four minor versions after
+ * 2.14.0 dropped it, writing a permission rule for a tool that can never be
+ * offered — and the same dead name was being installed into AGENTS.md, where an
+ * agent read it and had to correct us. `setup-agent-files.test.ts` now fails on
+ * a name that is not advertised, in this list and in every generated file (#1124).
  */
-const SAFE_HARMONY_TOOLS = [
+export const SAFE_HARMONY_TOOLS = [
   // Reads
   "harmony_get_card",
-  "harmony_get_card_by_short_id",
   "harmony_search_cards",
   "harmony_get_board",
   "harmony_get_context",
@@ -77,12 +88,19 @@ const SAFE_HARMONY_TOOLS = [
   "harmony_get_comments",
   "harmony_get_plan",
   "harmony_list_plans",
+  "harmony_get_playbook",
+  "harmony_list_playbook",
   "harmony_get_agent_session",
+  // The checkpoint steering poll. Absent until #1124, so every checkpoint of
+  // every run raised a prompt for a read the workflow itself prescribes.
+  "harmony_get_pending_messages",
   "harmony_get_workspace_members",
   "harmony_list_agents",
   "harmony_resolve_links",
+  "harmony_suggest_relations",
   "harmony_recall",
   "harmony_memory_search",
+  "harmony_vault_index",
   "harmony_generate_prompt",
   // Routine writes
   "harmony_create_card",
@@ -91,6 +109,7 @@ const SAFE_HARMONY_TOOLS = [
   "harmony_assign_card",
   "harmony_create_subtask",
   "harmony_toggle_subtask",
+  "harmony_update_subtask",
   "harmony_add_label_to_card",
   "harmony_remove_label_from_card",
   "harmony_create_label",
@@ -98,6 +117,10 @@ const SAFE_HARMONY_TOOLS = [
   "harmony_update_comment",
   "harmony_add_link_to_card",
   "harmony_remove_link_from_card",
+  // The durable carrier for a PR link — the completion path calls it on every
+  // card that changed code, and it mirrors the card-link pair above.
+  "harmony_add_external_link",
+  "harmony_remove_external_link",
   "harmony_start_agent_session",
   "harmony_update_agent_progress",
   "harmony_end_agent_session",
@@ -112,6 +135,9 @@ const SAFE_HARMONY_TOOLS = [
   "harmony_remember",
   "harmony_relate",
   "harmony_update_memory",
+  // A ranking counter on a recalled memory. A write, not a read — it never
+  // deletes, hides or supersedes anything.
+  "harmony_recall_feedback",
   "harmony_process_command",
   "harmony_sync",
 ];
@@ -401,7 +427,8 @@ export async function resolveProjectSlug(
 export interface FileToWrite {
   path: string;
   content: string;
-  type: "text" | "json" | "toml";
+  /** `markdown` merges a Harmony-owned section into a file the project owns. */
+  type: "text" | "json" | "toml" | "markdown";
   tomlSection?: string;
   mode?: number;
 }
@@ -512,64 +539,15 @@ async function getAgentFiles(
     }
 
     case "codex": {
-      // AGENTS.md in project root (always local - project context)
-      const agentsContent = `# Harmony Integration
-
-This project uses Harmony for task management. When working on tasks:
-
-## Agent identity — always identify as yourself
-
-Every \`harmony_start_agent_session\` call passes \`agentIdentifier\` + \`agentName\`. **Use your own
-identity, never a hardcoded one from this file.** AGENTS.md is a cross-runtime convention file, so
-more than one kind of agent will read it; the board shows agents as teammates, and a session
-attributed to the wrong runtime misattributes the work in front of the whole team.
-
-- \`agentIdentifier\` — a stable kebab-case id for the runtime you actually are
-- \`agentName\` — its human-readable name
-
-Known values: \`claude-code\` / "Claude Code", \`codex\` / "OpenAI Codex", \`cursor\` / "Cursor",
-\`claude-desktop\` / "Claude Desktop". If you are a runtime not listed here, use your own name rather
-than borrowing the closest entry.
-
-## Starting Work on a Card
-
-When given a card reference (e.g., #42 or a card name), follow this workflow:
-
-1. Use \`harmony_get_card\` or \`harmony_search_cards\` to find the card
-2. Move the card to "In Progress" using \`harmony_move_card\`
-3. Add the "agent" label using \`harmony_add_label_to_card\`
-4. Start a session with \`harmony_start_agent_session\`, passing **your own** \`agentIdentifier\` +
-   \`agentName\` (see "Agent identity" above)
-5. Show the card details to the user
-6. Use \`harmony_generate_prompt\` to get guidance, then implement the solution
-7. Update progress periodically with \`harmony_update_agent_progress\`
-8. When done, call \`harmony_end_agent_session\` and move to "Review"
-
-## Auto-Detect Card for Implementation Tasks
-
-Before implementing a plan or feature, check if it maps to an existing Harmony card:
-
-1. Use \`harmony_search_cards\` with keywords from the task description
-2. If a match is found, call \`harmony_start_agent_session\` with **your own** \`agentIdentifier\` +
-   \`agentName\` (see "Agent identity" above), plus \`moveToColumn: "In Progress"\`, \`addLabels: ["agent"]\`
-3. Update progress with \`harmony_update_agent_progress\` at milestones
-4. When done, call \`harmony_end_agent_session\` with status: "completed", moveToColumn: "Review"
-
-Skip if: work was already started with a card reference, or no matching card exists.
-
-## Available Harmony Tools
-
-- \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\` - Find cards
-- \`harmony_move_card\` - Move cards between columns
-- \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\` - Manage labels
-- \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\` - Track work
-- \`harmony_get_board\` - Get board state
-- \`harmony_generate_prompt\` - Get role-based guidance and focus areas for the card
-`;
+      // The Harmony section of AGENTS.md, written as type "markdown" so it is
+      // MERGED into whatever the project already has: the docs-step scaffold
+      // written earlier in this same run, or a file the user maintains by hand.
+      // A plain text write destroyed both — setup forces writes on a fresh
+      // install, and this push lands after the scaffold's (#1124).
       files.push({
         path: join(cwd, "AGENTS.md"),
-        content: agentsContent,
-        type: "text",
+        content: HARMONY_AGENTS_SECTION,
+        type: "markdown",
       });
 
       // Codex prompt file
@@ -582,7 +560,7 @@ arguments:
     required: true
 ---
 
-${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "{{card}}").replace("Your agent identifier", "codex").replace("Your agent name", "OpenAI Codex")}
+${renderWorkflowPrompt({ cardArgument: "{{card}}", agentIdentifier: "codex", agentName: "OpenAI Codex" })}
 `;
 
       if (installMode === "global") {
@@ -652,7 +630,7 @@ alwaysApply: false
 
 When the user asks you to work on a Harmony card (references like #42, card names, or UUIDs):
 
-${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "cursor").replace("Your agent name", "Cursor AI")}
+${renderWorkflowPrompt({ cardArgument: "the card reference", agentIdentifier: "cursor", agentName: "Cursor" })}
 `;
 
       if (installMode === "global") {
@@ -708,7 +686,7 @@ description: Activate when user asks to work on a Harmony card (references like
 
 When working on a Harmony card:
 
-${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "windsurf").replace("Your agent name", "Windsurf AI")}
+${renderWorkflowPrompt({ cardArgument: "the card reference", agentIdentifier: "windsurf", agentName: "Windsurf" })}
 `;
 
       if (installMode === "global") {
@@ -1576,6 +1554,11 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
       `  ${colors.success("\u2713")} ${colors.dim(formatPath(writtenLocalConfigPath, home))} ${colors.dim("(created)")}`,
     );
 
+    // The scan runs AFTER the global mirror below, deliberately: it spawns a
+    // child with inherited stdio for as long as this repo's test suite takes,
+    // and a Ctrl-C there must not cost the operator the global default that
+    // every server started outside this directory reads (#893).
+    //
     // Mirror the choice into the GLOBAL default, explicitly (#893). The local
     // file above already pins this directory; this second write is what gives a
     // server started elsewhere — Claude Desktop, another repo — a context at
@@ -1592,6 +1575,8 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
         { global: true },
       );
     }
+
+    await offerCommandScan(dirname(writtenLocalConfigPath), assumeYes);
   }
 
   // Step 10: Show completion message
@@ -1686,3 +1671,99 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   }
   console.log("");
 }
+
+/**
+ * The command that proposes a repo's `commands` block by running it.
+ *
+ * `@latest` is this repo's own convention for an `npx` spec (`@gethmy/mcp@latest`
+ * in every documented invocation) and it is load-bearing here: `scan-commands`
+ * arrives in a release later than several already published, and a warm npx
+ * cache of an older `@gethmy/agent` would otherwise hand the operator the
+ * "may predate it" fallback forever with no way to see why.
+ */
+const SCAN_ARGV = ["--yes", "@gethmy/agent@latest", "scan-commands"] as const;
+
+function scanTip(): void {
+  console.log(
+    `  ${colors.dim("Tip: run")} ${colors.highlight(`npx ${SCAN_ARGV.slice(1).join(" ")}`)} ${colors.dim("to have the daemon prove which build, test and dev commands this repo has, and write them into the pin.")}`,
+  );
+}
+
+/**
+ * Offer to scan this repo's commands, and run the scanner when asked (#1116).
+ *
+ * Card 1116's first acceptance criterion is that the scanner RUNS when a
+ * project is set up — this is that moment, and a printed tip is not a run.
+ * What this package must not do is scan by itself: the scan executes the
+ * repo's own build, test and dev commands, and `@gethmy/mcp` neither depends
+ * on `@gethmy/harness` (which owns both the execution and the schema) nor
+ * spawns a toolchain anywhere else. So it does what the tip asked a person to
+ * do — spawn the agent CLI — which keeps the dependency direction intact
+ * (agent → harness → shared, mcp beside them) and re-types no schema.
+ *
+ * Three properties, each deliberate.
+ *
+ * **Asked, never assumed.** The scan starts this repo's build, test and dev
+ * commands, which is minutes of work and arbitrary code from the checkout. A
+ * person is present at setup and is the right one to say yes.
+ *
+ * **Non-interactive setups are not scanned at all** — `--yes`, a pipe, a
+ * coding agent — even though `--yes` means yes to everything else. Those two
+ * are not the same question: the other confirmations write files this command
+ * already owns, and this one hands control to another package's process for
+ * an unbounded time. They get the tip, i.e. exactly the behaviour that
+ * shipped before this.
+ *
+ * **A failure is not an error.** The published `@gethmy/agent` gains this
+ * subcommand only on its next release, and `npx` needs a network. Either way
+ * the fallback is the tip, so an older agent degrades to the previous
+ * behaviour rather than turning setup red over an optional convenience.
+ *
+ * It deliberately does NOT pass `--write`: the proposal is printed for a
+ * person to read, which is card 1116's fourth criterion (never applied
+ * silently), and `scan-commands --write` is the separate, explicit act.
+ */
+export async function offerCommandScan(
+  repoDir: string,
+  assumeYes: boolean,
+): Promise<void> {
+  if (assumeYes) {
+    scanTip();
+    return;
+  }
+
+  const scan = await confirmOrDefault(assumeYes, {
+    message:
+      "Scan this repo's commands now? It runs your build, test and dev scripts once to prove which ones exist. Nothing is written.",
+    initialValue: true,
+  });
+  // Ctrl-C ends setup, as it does at every other prompt in this file. A
+  // cancel folded into "no" would carry on through the remaining steps as if
+  // the person had answered, which is the one reading they did not give.
+  if (p.isCancel(scan)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  if (!scan) {
+    scanTip();
+    return;
+  }
+
+  console.log(
+    `  ${colors.dim("Running")} ${colors.highlight(`npx ${SCAN_ARGV.slice(1).join(" ")}`)}${colors.dim(" …")}`,
+  );
+  const result = spawnSync("npx", [...SCAN_ARGV], {
+    cwd: repoDir,
+    stdio: "inherit",
+  });
+  if (result.error || result.status !== 0) {
+    console.log(
+      `  ${colors.dim("The scan did not run — your installed @gethmy/agent may predate it.")}`,
+    );
+    scanTip();
+    return;
+  }
+  console.log(
+    `  ${colors.dim("Re-run it with")} ${colors.highlight("--write")} ${colors.dim("to merge that block into the pin.")}`,
+  );
+}

package/src/tui/writer.ts

@@ -204,6 +204,112 @@ export function appendToToml(
   }
 }
 
+/**
+ * Markers delimiting the Harmony-owned section of a shared markdown file.
+ * Everything between them is package-generated and refreshed on reinstall;
+ * everything outside them belongs to the project and is never rewritten.
+ */
+export const MARKDOWN_SECTION_START = "<!-- harmony:start -->";
+export const MARKDOWN_SECTION_END = "<!-- harmony:end -->";
+
+/**
+ * Locate the Harmony-owned section: the first WELL-FORMED marker pair — a
+ * START, the first END after it, and no second START in between.
+ *
+ * **This choice is the whole safety argument of `mergeMarkdownSection`,** and
+ * the two obvious rules are each unsafe in one direction. First-START-first-END
+ * swallows everything between a stray START above our section and our real END.
+ * Last-START-first-END-after does the mirror: a project quoting both markers
+ * BELOW our section loses whatever sits between those two mentions. A file that
+ * merely shows the markers inside a code fence hits one or the other.
+ *
+ * Requiring the span to hold no START defeats both, because a stray marker
+ * disqualifies the candidate it sits inside and the scan moves past it. What
+ * this does NOT do is notice a file holding two complete sections: it updates
+ * the first and leaves the second stale. That is a duplicate to spot by eye,
+ * not content destroyed, which is the trade this function exists to make.
+ */
+function findSection(text: string): { start: number; end: number } | null {
+  let from = 0;
+  while (true) {
+    const start = text.indexOf(MARKDOWN_SECTION_START, from);
+    if (start === -1) return null;
+    const bodyFrom = start + MARKDOWN_SECTION_START.length;
+    const end = text.indexOf(MARKDOWN_SECTION_END, bodyFrom);
+    if (end === -1) return null;
+    const nextStart = text.indexOf(MARKDOWN_SECTION_START, bodyFrom);
+    if (nextStart === -1 || nextStart > end) return { start, end };
+    // `start` is unpaired. `nextStart > from` always, so the scan terminates.
+    from = nextStart;
+  }
+}
+
+/**
+ * Merge a Harmony-owned section into a shared markdown file (AGENTS.md).
+ *
+ * `AGENTS.md` is the project's file, not ours. It may already carry the
+ * docs-step scaffold written earlier in the same run, or a file the user has
+ * maintained by hand for months. A plain `writeFile` destroyed both: setup runs
+ * with `force: true` on every fresh install (`needsSkills`), which bypasses the
+ * exists-skip, and the agent files are pushed onto `allFiles` AFTER the docs
+ * scaffold — so the last write of `AGENTS.md` won and the scaffold vanished in
+ * the same breath as the line announcing it. Hence markers and a merge (#1124).
+ *
+ * - File absent → create it holding just the section.
+ * - A section is present (see `findSection`) → replace what lies between its
+ *   markers, and only under `force` (matching `appendToToml`) — the section is
+ *   package-generated, so a reinstall is when it should be refreshed.
+ * - No section → append. The file's existing content is never rewritten.
+ */
+export function mergeMarkdownSection(
+  filePath: string,
+  content: string,
+  options: WriteOptions = {},
+): FileResult {
+  const section = `${MARKDOWN_SECTION_START}\n${content.trim()}\n${MARKDOWN_SECTION_END}\n`;
+
+  if (!existsSync(filePath)) {
+    try {
+      ensureDir(dirname(filePath));
+      writeFileSync(filePath, section, { mode: 0o644 });
+      return { path: filePath, action: "create" };
+    } catch (error) {
+      return {
+        path: filePath,
+        action: "skip",
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  try {
+    const existing = readFileSync(filePath, "utf-8");
+    const found = findSection(existing);
+
+    if (found) {
+      if (!options.force) return { path: filePath, action: "skip" };
+      const updated =
+        existing.slice(0, found.start) +
+        section.trimEnd() +
+        existing.slice(found.end + MARKDOWN_SECTION_END.length);
+      writeFileSync(filePath, updated, { mode: 0o644 });
+      return { path: filePath, action: "update" };
+    }
+
+    // No section we can identify — every byte of this file is the project's.
+    // Append, never overwrite, however forceful the caller is.
+    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+    writeFileSync(filePath, existing + separator + section, { mode: 0o644 });
+    return { path: filePath, action: "merge" };
+  } catch (error) {
+    return {
+      path: filePath,
+      action: "skip",
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 /**
  * Write multiple files with progress display
  */
@@ -211,7 +317,7 @@ export async function writeFilesWithProgress(
   files: Array<{
     path: string;
     content: string;
-    type: "text" | "json" | "toml";
+    type: "text" | "json" | "toml" | "markdown";
     jsonKey?: string;
     tomlSection?: string;
     mode?: number;
@@ -232,6 +338,8 @@ export async function writeFilesWithProgress(
       result = mergeJsonFile(file.path, jsonContent, options);
     } else if (file.type === "toml" && file.tomlSection) {
       result = appendToToml(file.path, file.tomlSection, file.content, options);
+    } else if (file.type === "markdown") {
+      result = mergeMarkdownSection(file.path, file.content, options);
     } else {
       result = writeFile(file.path, file.content, {
         ...options,
@@ -256,7 +364,15 @@ export async function writeFilesWithProgress(
     } else if (result.action === "skip") {
       console.log(messages.fileSkipped(displayPath));
     } else {
-      const actionLabel = result.action === "merge" ? "updated" : "created";
+      // `update` used to fall through to "created" — harmless while it was rare,
+      // and a lie the moment AGENTS.md started taking the merge path on every
+      // reinstall, telling the user a months-old file was just created (#1124).
+      const actionLabel =
+        result.action === "create"
+          ? "created"
+          : result.action === "merge"
+            ? "merged"
+            : "updated";
       console.log(
         `  ${colors.success("\u2713")} ${colors.dim(displayPath)} ${colors.dim(`(${actionLabel})`)}`,
       );