@gethmy/mcp 3.2.0 → 3.4.0

package/src/hook-install.ts

@@ -0,0 +1,388 @@
+/**
+ * Installing the `PostToolUse` hook — and why only into the USER layer (#874).
+ *
+ * ## The project layer is not a preference, it is refused
+ *
+ * `assertNoProjectSandboxOverride` (`packages/harmony-harness/src/run-containment.ts`)
+ * reads a worktree's `.claude/settings.json` and `.claude/settings.local.json`
+ * before every contained spawn and refuses ANY key outside an eight-key inert
+ * allow-list (`$schema`, `cleanupPeriodDays`, `includeCoAuthoredBy`,
+ * `language`, `outputStyle`, `spinnerTipsEnabled`, `theme`, `verbose`).
+ *
+ * `hooks` is not merely missing from that list — it is the key that BROKE the
+ * previous denylist and forced the inversion. A hook block in a run's own
+ * worktree executed as the daemon user, outside the sandbox, and read
+ * `~/.ssh/config` and `~/.harmony-mcp/config.json`. So writing this hook into a
+ * project settings file would throw `ProjectSandboxOverrideError` on every
+ * contained implement run in that repo — it would not degrade, it would stop
+ * the daemon.
+ *
+ * ## The user layer is also what makes it CORRECT
+ *
+ * `implementRunContainment` sets `settingSources: readOnly ? [] : ["project"]`.
+ * `"user"` appears in neither branch. A daemon run therefore never loads
+ * `~/.claude/settings.json` and never fires this hook, while an operator's own
+ * `/hmy` terminal session — which runs under their own settings — does.
+ *
+ * That is the whole of the card's "a daemon run is untouched: still exactly one
+ * stream, no doubled events" criterion, satisfied by construction rather than
+ * by a runtime toggle that could be set wrong. There is no flag to get right,
+ * because the two layers are already disjoint.
+ *
+ * ## Merging, not overwriting
+ *
+ * `~/.claude/settings.json` is the operator's file and usually already has
+ * hooks in it. Every function here merges into a parsed object and leaves
+ * unrelated entries untouched, and the install is idempotent — running it twice
+ * yields one entry, not two. The pure functions are separated from the file I/O
+ * so the merge is table-tested rather than verified by writing to a real home
+ * directory.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * A marker argument the hook binary ignores.
+ *
+ * Identifying our entry by its PATH would be fragile — it differs between a
+ * global npm install, a bunx cache and a dev checkout — so the command carries
+ * a stable sentinel instead. It doubles as a note to whoever reads the settings
+ * file and wonders what the entry is.
+ */
+export const HOOK_MARKER = "--harmony-post-tool-use";
+
+/** Seconds. Generous: the hook does no network I/O, so it should never hit it. */
+const HOOK_TIMEOUT_SECONDS = 10;
+
+/** Matches every tool. The redaction rules, not the matcher, decide what is sent. */
+const HOOK_MATCHER = "*";
+
+interface HookCommandEntry {
+  type?: string;
+  command?: string;
+  timeout?: number;
+}
+
+interface HookMatcherEntry {
+  matcher?: string;
+  hooks?: HookCommandEntry[];
+}
+
+/** `~/.claude/settings.json` — the user layer, never the project layer. */
+export function userSettingsPath(home: string = homedir()): string {
+  return join(home, ".claude", "settings.json");
+}
+
+/**
+ * Absolute path to the hook binary.
+ *
+ * Resolved from this module's own location rather than looked up on `PATH`, for
+ * the reason `harmonyMcpServer` resolves the MCP CLI the same way: a `PATH`
+ * lookup or an `npx` resolution step can find a different install than the one
+ * that wrote the settings entry. The `.ts` fallback is for a dev checkout run
+ * straight from source.
+ */
+export function hookBinaryPath(moduleUrl: string = import.meta.url): string {
+  const here = dirname(fileURLToPath(moduleUrl));
+  const candidates = [
+    // Built package: `bun build src/run-hook-cli.ts --outdir dist`.
+    join(here, "run-hook-cli.js"),
+    join(here, "..", "dist", "run-hook-cli.js"),
+    // Dev checkout running straight from source.
+    join(here, "run-hook-cli.ts"),
+  ];
+  return (
+    candidates.find((path) => existsSync(path)) ?? (candidates[0] as string)
+  );
+}
+
+/**
+ * The exact command string written into the settings file.
+ *
+ * Both absolute paths are pinned deliberately (see `hookBinaryPath`), and both
+ * can go away under the user's feet: an `npx`/`bunx` cache is hash- or
+ * version-scoped, so upgrading `@gethmy/mcp` or clearing the cache moves the
+ * binary, and a Node upgrade through a version manager moves `execPath`. The
+ * entry lives in the USER layer with a `*` matcher, so a bare command would
+ * then fail on every tool call of every session on the machine — `exit 1` with
+ * `Cannot find module`, or `exit 127` with no such file. That is the exact
+ * inverse of this card's "the hook is a no-op — never an error" criterion, and
+ * `hook status` reported `installed` throughout, because it only looked for the
+ * marker.
+ *
+ * So the command guards its own preconditions and exits 0 when either path is
+ * gone. The trailing `|| exit 0` also swallows a non-zero exit from the hook
+ * itself, which is the same promise stated once more at the shell level: this
+ * hook never breaks the tool call it observes. `hook status` reports the stale
+ * path so the user knows to re-run `hook install`.
+ *
+ * This is POSIX shell (`sh -c`), which is what the harness runs a hook command
+ * with on macOS and Linux — the only platforms `~/.claude/settings.json`
+ * installs are supported on.
+ */
+export function hookCommand(
+  binary: string,
+  execPath = process.execPath,
+): string {
+  return `[ -x "${execPath}" ] && [ -f "${binary}" ] && "${execPath}" "${binary}" ${HOOK_MARKER} || exit 0`;
+}
+
+/**
+ * The hook binary an installed command points at, or null.
+ *
+ * Parsed back out of the `[ -f "…" ]` guard `hookCommand` writes. Reading it
+ * from the command string keeps the settings entry to the three keys the
+ * harness's hook schema defines, rather than smuggling a path into a fourth.
+ */
+export function hookCommandBinary(command: string): string | null {
+  const match = /\[ -f "([^"]+)" \]/.exec(command);
+  return match?.[1] ?? null;
+}
+
+/** Is this settings entry ours? */
+function isHarmonyHook(entry: HookCommandEntry | undefined): boolean {
+  return (
+    typeof entry?.command === "string" && entry.command.includes(HOOK_MARKER)
+  );
+}
+
+type Settings = Record<string, unknown>;
+
+/**
+ * Add (or update) the Harmony `PostToolUse` entry in a parsed settings object.
+ *
+ * Idempotent: an existing Harmony entry has its command REPLACED, so upgrading
+ * to a new install path fixes the entry rather than adding a second one that
+ * would double every tool row. Other people's hooks are never touched.
+ */
+export function addHarmonyHook(
+  settings: Settings,
+  command: string,
+): { settings: Settings; changed: boolean } {
+  const next: Settings = { ...settings };
+  const hooks: Record<string, unknown> = {
+    ...((next.hooks as Record<string, unknown>) ?? {}),
+  };
+  const postToolUse: HookMatcherEntry[] = Array.isArray(hooks.PostToolUse)
+    ? [...(hooks.PostToolUse as HookMatcherEntry[])]
+    : [];
+
+  const ours: HookCommandEntry = {
+    type: "command",
+    command,
+    timeout: HOOK_TIMEOUT_SECONDS,
+  };
+
+  let changed = false;
+  let placed = false;
+
+  for (let i = 0; i < postToolUse.length; i++) {
+    const group = postToolUse[i] as HookMatcherEntry;
+    const inner = Array.isArray(group?.hooks) ? group.hooks : [];
+    const index = inner.findIndex(isHarmonyHook);
+    if (index === -1) continue;
+    placed = true;
+    if (inner[index]?.command !== command) {
+      const updated = [...inner];
+      updated[index] = ours;
+      postToolUse[i] = { ...group, hooks: updated };
+      changed = true;
+    }
+  }
+
+  if (!placed) {
+    postToolUse.push({ matcher: HOOK_MATCHER, hooks: [ours] });
+    changed = true;
+  }
+
+  hooks.PostToolUse = postToolUse;
+  next.hooks = hooks;
+  return { settings: next, changed };
+}
+
+/**
+ * Remove the Harmony entry, leaving every other hook alone.
+ *
+ * A matcher group left with no hooks is dropped, and a `PostToolUse` array left
+ * empty is dropped with it, so uninstalling returns the file to the shape it
+ * had before — an empty `"PostToolUse": []` is litter that outlives the reason
+ * for it.
+ */
+export function removeHarmonyHook(settings: Settings): {
+  settings: Settings;
+  changed: boolean;
+} {
+  const hooksValue = settings.hooks;
+  if (hooksValue === null || typeof hooksValue !== "object") {
+    return { settings, changed: false };
+  }
+  const hooks: Record<string, unknown> = {
+    ...(hooksValue as Record<string, unknown>),
+  };
+  if (!Array.isArray(hooks.PostToolUse)) {
+    return { settings, changed: false };
+  }
+
+  let changed = false;
+  const groups: HookMatcherEntry[] = [];
+  for (const group of hooks.PostToolUse as HookMatcherEntry[]) {
+    const inner = Array.isArray(group?.hooks) ? group.hooks : [];
+    const kept = inner.filter((entry) => !isHarmonyHook(entry));
+    if (kept.length !== inner.length) changed = true;
+    if (kept.length === 0 && inner.length > 0) continue;
+    groups.push(
+      kept.length === inner.length ? group : { ...group, hooks: kept },
+    );
+  }
+
+  if (!changed) return { settings, changed: false };
+
+  if (groups.length > 0) {
+    hooks.PostToolUse = groups;
+  } else {
+    delete hooks.PostToolUse;
+  }
+
+  const next: Settings = { ...settings };
+  if (Object.keys(hooks).length > 0) {
+    next.hooks = hooks;
+  } else {
+    delete next.hooks;
+  }
+  return { settings: next, changed: true };
+}
+
+/** Is the Harmony hook present in a parsed settings object? */
+export function hasHarmonyHook(settings: Settings): boolean {
+  return harmonyHookCommand(settings) !== null;
+}
+
+/** The Harmony hook's command string as installed, or null when absent. */
+export function harmonyHookCommand(settings: Settings): string | null {
+  const hooks = settings?.hooks as Record<string, unknown> | undefined;
+  const groups = hooks?.PostToolUse;
+  if (!Array.isArray(groups)) return null;
+  for (const group of groups as HookMatcherEntry[]) {
+    for (const entry of Array.isArray(group?.hooks) ? group.hooks : []) {
+      if (isHarmonyHook(entry)) return entry.command as string;
+    }
+  }
+  return null;
+}
+
+/**
+ * What `hook status` needs to say something true.
+ *
+ * `installed` on its own was misleading: the entry can name a binary that an
+ * upgrade or a cache purge has moved, in which case the hook is inert and only
+ * re-running `hook install` fixes it. The guard in `hookCommand` keeps that
+ * inert rather than broken; this is how the user finds out.
+ */
+export function hookInstallStatus(settings: Settings): {
+  installed: boolean;
+  binary: string | null;
+  binaryExists: boolean;
+} {
+  const command = harmonyHookCommand(settings);
+  if (command === null) {
+    return { installed: false, binary: null, binaryExists: false };
+  }
+  const binary = hookCommandBinary(command);
+  return {
+    installed: true,
+    binary,
+    binaryExists: binary !== null && existsSync(binary),
+  };
+}
+
+function readSettings(path: string): Settings {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return parsed !== null &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed)
+      ? (parsed as Settings)
+      : {};
+  } catch {
+    // A missing file is the common case. A CORRUPT one is not ours to silently
+    // replace, so the callers below check `existsSync` and refuse instead.
+    return {};
+  }
+}
+
+function writeSettings(path: string, settings: Settings): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+}
+
+export type HookInstallResult =
+  | { ok: true; path: string; changed: boolean; command: string }
+  | { ok: false; path: string; error: string };
+
+/** Write the hook into the user settings layer. */
+export function installUserHook(options?: {
+  settingsPath?: string;
+  binary?: string;
+}): HookInstallResult {
+  const path = options?.settingsPath ?? userSettingsPath();
+  const command = hookCommand(options?.binary ?? hookBinaryPath());
+  if (existsSync(path)) {
+    try {
+      JSON.parse(readFileSync(path, "utf-8"));
+    } catch (err) {
+      return {
+        ok: false,
+        path,
+        error: `${path} is not valid JSON, so it was left untouched: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      };
+    }
+  }
+  try {
+    const { settings, changed } = addHarmonyHook(readSettings(path), command);
+    if (changed) writeSettings(path, settings);
+    return { ok: true, path, changed, command };
+  } catch (err) {
+    return {
+      ok: false,
+      path,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/** Remove the hook from the user settings layer. */
+export function uninstallUserHook(options?: {
+  settingsPath?: string;
+}): HookInstallResult {
+  const path = options?.settingsPath ?? userSettingsPath();
+  if (!existsSync(path)) {
+    return { ok: true, path, changed: false, command: "" };
+  }
+  try {
+    JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    return {
+      ok: false,
+      path,
+      error: `${path} is not valid JSON, so it was left untouched: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+  try {
+    const { settings, changed } = removeHarmonyHook(readSettings(path));
+    if (changed) writeSettings(path, settings);
+    return { ok: true, path, changed, command: "" };
+  } catch (err) {
+    return {
+      ok: false,
+      path,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/plan-task-link.ts

@@ -0,0 +1,130 @@
+/**
+ * Plan criterion ↔ card linking (card #1038, plan "Harmony SDLC — ein Rückgrat").
+ *
+ * A `plan_task` row is a plan's **success criterion**, not a work item. `cards.plan_id`
+ * has always carried the plan → card direction; `plan_tasks.card_id` is the return leg
+ * ("Linked card ID if task has been converted to a card", 20260127100000). It shipped
+ * with the table and no client ever wrote it, so a card outcome had nowhere to land and
+ * plan progress fell back to matching board-column NAMES. The number now counts these
+ * criteria instead (`computePlanProgress`, `src/lib/planProgress.ts`, card #1042), so a
+ * criterion left unlinked here is a criterion the plan reports as unmet.
+ *
+ * Everything here is pure and total, because the interesting cases are the ones a live
+ * call cannot cheaply produce: a criterion that belongs to a different plan, a malformed
+ * task list off the wire, and the half-written state where the card exists but the return
+ * leg did not get written.
+ *
+ * WHY NOTHING HERE RESOLVES A PLAN FROM A TASK ID ALONE: there is no
+ * `GET /plan-tasks/:id` route, and adding one to save the caller a field would be a new
+ * server surface for a lookup the caller already has. `planId` is therefore required
+ * alongside `planTaskId`, which also makes the two impossible to contradict — the plan is
+ * named once and used for both the card's `plan_id` and the criterion's scope.
+ */
+
+/** A `plan_tasks` row as it comes back from `GET /plans/:id`. */
+export interface PlanTaskRow {
+  id: string;
+  plan_id?: string | null;
+  card_id?: string | null;
+  content?: string | null;
+  status?: string | null;
+}
+
+export type PlanTaskLookup =
+  | { ok: true; task: PlanTaskRow }
+  | { ok: false; reason: string };
+
+/**
+ * Find `taskId` among a plan's criteria.
+ *
+ * Fails CLOSED on every shape it does not recognise. The caller uses this to decide
+ * whether to create a card at all, so "I could not read the list" must never be reported
+ * as "the criterion is fine" — a card created against a criterion that does not exist is
+ * a card created on a false premise.
+ */
+export function findPlanTask(tasks: unknown, taskId: string): PlanTaskLookup {
+  if (!taskId) {
+    return { ok: false, reason: "No plan task id was given." };
+  }
+  if (!Array.isArray(tasks)) {
+    return {
+      ok: false,
+      reason: "The plan returned no readable criteria list.",
+    };
+  }
+
+  for (const row of tasks) {
+    if (!row || typeof row !== "object") continue;
+    const candidate = row as PlanTaskRow;
+    if (candidate.id === taskId) {
+      return { ok: true, task: candidate };
+    }
+  }
+
+  return {
+    ok: false,
+    reason:
+      `Plan task ${taskId} is not one of this plan's criteria. ` +
+      `Read the plan with harmony_get_plan and use an id from its \`tasks\`.`,
+  };
+}
+
+/** What happened to the return leg after a card was created. */
+export interface PlanTaskLinkReport {
+  planId: string;
+  taskId: string;
+  /** True once `plan_tasks.card_id` points at the new card. */
+  linked: boolean;
+  /** The criterion text, echoed so the caller sees what the card now answers for. */
+  criterion?: string | null;
+  /** Present only when `linked` is false. */
+  error?: string;
+  /** Set when the criterion already pointed at a different card. */
+  replacedCardId?: string | null;
+}
+
+/**
+ * Build the report for a criterion whose return leg was written.
+ *
+ * `replacedCardId` is reported rather than refused: re-pointing a criterion at a new card
+ * is legitimate (the first card was abandoned, or the criterion moved), and a silent
+ * overwrite is the part that would be wrong.
+ */
+export function linkedReport(
+  planId: string,
+  task: PlanTaskRow,
+  newCardId: string,
+): PlanTaskLinkReport {
+  const previous = task.card_id ?? null;
+  return {
+    planId,
+    taskId: task.id,
+    linked: true,
+    criterion: task.content ?? null,
+    ...(previous && previous !== newCardId ? { replacedCardId: previous } : {}),
+  };
+}
+
+/**
+ * Build the report for a return leg that did NOT get written.
+ *
+ * The card is deliberately kept. A card without its return leg is repairable with
+ * `harmony_link_plan_task`; a card thrown away because a second write failed is not.
+ * The message says exactly that, so the caller does not retry the create.
+ */
+export function unlinkedReport(
+  planId: string,
+  task: PlanTaskRow,
+  error: unknown,
+): PlanTaskLinkReport {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    planId,
+    taskId: task.id,
+    linked: false,
+    criterion: task.content ?? null,
+    error:
+      `The card was created, but the plan criterion still does not point at it: ${message}. ` +
+      `Repair it with harmony_link_plan_task — do not create the card again.`,
+  };
+}