@gethmy/mcp 3.8.0 → 3.9.0

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})`)}`,
       );