@mcptoolshop/mcpt-publishing 0.2.0 → 0.3.0

package/src/fixers/fixers/npm-keywords.mjs

@@ -0,0 +1,77 @@
+/**
+ * Fixer: npm-keywords — adds starter `keywords` to package.json.
+ * Matches audit finding code: "missing-keywords"
+ */
+
+import { Fixer } from "../fixer.mjs";
+import { readPkgJson, writePkgJson, readRemoteFile, writeRemoteFile } from "./_npm-helpers.mjs";
+
+export default class NpmKeywordsFixer extends Fixer {
+  get code() { return "npm-keywords"; }
+  get target() { return "npm"; }
+
+  canFix(finding) {
+    return finding.code === "missing-keywords";
+  }
+
+  describe() {
+    return "Add starter keywords to package.json";
+  }
+
+  #buildKeywords(entry) {
+    const base = ["mcp", "mcp-tool-shop"];
+    // Extract a usable keyword from package name (strip scope)
+    const shortName = entry.name.replace(/^@[^/]+\//, "");
+    if (shortName && !base.includes(shortName)) {
+      base.push(shortName);
+    }
+    return base;
+  }
+
+  async diagnose(entry, ctx, opts = {}) {
+    const expected = this.#buildKeywords(entry);
+
+    if (opts.remote) {
+      const remote = readRemoteFile(entry.repo, "package.json");
+      if (!remote) return { needed: false };
+      const data = JSON.parse(remote.content);
+      if (data.keywords?.length > 0) return { needed: false };
+      return { needed: true, before: null, after: expected, file: "package.json" };
+    }
+
+    const pkg = readPkgJson(opts.cwd ?? process.cwd());
+    if (!pkg) return { needed: false };
+    if (pkg.data.keywords?.length > 0) return { needed: false };
+    return { needed: true, before: null, after: expected, file: "package.json" };
+  }
+
+  async applyLocal(entry, ctx, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const pkg = readPkgJson(cwd);
+    if (!pkg) return { changed: false };
+
+    const before = pkg.data.keywords ?? null;
+    pkg.data.keywords = this.#buildKeywords(entry);
+    writePkgJson(pkg.path, pkg.data);
+
+    return { changed: true, before, after: pkg.data.keywords, file: "package.json" };
+  }
+
+  async applyRemote(entry, ctx, opts = {}) {
+    const remote = readRemoteFile(entry.repo, "package.json");
+    if (!remote) return { changed: false };
+
+    const data = JSON.parse(remote.content);
+    const before = data.keywords ?? null;
+    data.keywords = this.#buildKeywords(entry);
+
+    const ok = writeRemoteFile(
+      entry.repo, "package.json",
+      JSON.stringify(data, null, 2) + "\n",
+      remote.sha,
+      `chore: add keywords to package.json`
+    );
+
+    return { changed: ok, before, after: data.keywords, file: "package.json" };
+  }
+}

package/src/fixers/fixers/npm-repository.mjs

@@ -0,0 +1,80 @@
+/**
+ * Fixer: npm-repository — corrects the `repository` field in package.json.
+ * Matches audit finding code: "wrong-repo-url"
+ */
+
+import { Fixer } from "../fixer.mjs";
+import { readPkgJson, writePkgJson, readRemoteFile, writeRemoteFile } from "./_npm-helpers.mjs";
+
+export default class NpmRepositoryFixer extends Fixer {
+  get code() { return "npm-repository"; }
+  get target() { return "npm"; }
+
+  canFix(finding) {
+    return finding.code === "wrong-repo-url";
+  }
+
+  describe() {
+    return "Fix npm package repository URL";
+  }
+
+  async diagnose(entry, ctx, opts = {}) {
+    const expected = {
+      type: "git",
+      url: `git+https://github.com/${entry.repo}.git`,
+    };
+
+    if (opts.remote) {
+      const remote = readRemoteFile(entry.repo, "package.json");
+      if (!remote) return { needed: false };
+      const data = JSON.parse(remote.content);
+      const current = data.repository;
+      const currentUrl = typeof current === "string" ? current : current?.url;
+      if (currentUrl === expected.url) return { needed: false };
+      return { needed: true, before: current ?? null, after: expected, file: "package.json" };
+    }
+
+    const pkg = readPkgJson(opts.cwd ?? process.cwd());
+    if (!pkg) return { needed: false };
+    const current = pkg.data.repository;
+    const currentUrl = typeof current === "string" ? current : current?.url;
+    if (currentUrl === expected.url) return { needed: false };
+    return { needed: true, before: current ?? null, after: expected, file: "package.json" };
+  }
+
+  async applyLocal(entry, ctx, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const pkg = readPkgJson(cwd);
+    if (!pkg) return { changed: false };
+
+    const before = pkg.data.repository ?? null;
+    pkg.data.repository = {
+      type: "git",
+      url: `git+https://github.com/${entry.repo}.git`,
+    };
+    writePkgJson(pkg.path, pkg.data);
+
+    return { changed: true, before, after: pkg.data.repository, file: "package.json" };
+  }
+
+  async applyRemote(entry, ctx, opts = {}) {
+    const remote = readRemoteFile(entry.repo, "package.json");
+    if (!remote) return { changed: false };
+
+    const data = JSON.parse(remote.content);
+    const before = data.repository ?? null;
+    data.repository = {
+      type: "git",
+      url: `git+https://github.com/${entry.repo}.git`,
+    };
+
+    const ok = writeRemoteFile(
+      entry.repo, "package.json",
+      JSON.stringify(data, null, 2) + "\n",
+      remote.sha,
+      `chore: fix repository URL in package.json`
+    );
+
+    return { changed: ok, before, after: data.repository, file: "package.json" };
+  }
+}

package/src/fixers/fixers/nuget-csproj.mjs

@@ -0,0 +1,200 @@
+/**
+ * Fixer: nuget-csproj — adds/fixes metadata fields in .csproj.
+ * Matches audit finding code: "missing-project-url"
+ *
+ * Handles: PackageProjectUrl, RepositoryUrl, PackageIcon, PackageReadmeFile
+ * Uses string manipulation (no XML parser, zero deps).
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { Fixer } from "../fixer.mjs";
+import { readRemoteFile, writeRemoteFile } from "./_npm-helpers.mjs";
+
+export default class NuGetCsprojFixer extends Fixer {
+  get code() { return "nuget-csproj"; }
+  get target() { return "nuget"; }
+
+  canFix(finding) {
+    return finding.code === "missing-project-url";
+  }
+
+  describe() {
+    return "Add PackageProjectUrl and RepositoryUrl to .csproj";
+  }
+
+  async diagnose(entry, ctx, opts = {}) {
+    const repoUrl = `https://github.com/${entry.repo}`;
+    const projectUrl = `${repoUrl}#readme`;
+
+    if (opts.remote) {
+      // Find csproj remotely — check common paths
+      const csprojPath = await this.#findCsprojRemote(entry);
+      if (!csprojPath) return { needed: false };
+
+      const remote = readRemoteFile(entry.repo, csprojPath);
+      if (!remote) return { needed: false };
+
+      const needs = this.#analyzeCsproj(remote.content, repoUrl, projectUrl);
+      if (needs.length === 0) return { needed: false };
+
+      return {
+        needed: true,
+        before: needs.map(n => `${n}: (missing)`).join(", "),
+        after: needs.map(n => `${n}: (set)`).join(", "),
+        file: csprojPath,
+      };
+    }
+
+    const cwd = opts.cwd ?? process.cwd();
+    const csprojPath = this.#findCsprojLocal(cwd, entry.name);
+    if (!csprojPath) return { needed: false };
+
+    const content = readFileSync(csprojPath, "utf8");
+    const needs = this.#analyzeCsproj(content, repoUrl, projectUrl);
+    if (needs.length === 0) return { needed: false };
+
+    return {
+      needed: true,
+      before: needs.map(n => `${n}: (missing)`).join(", "),
+      after: needs.map(n => `${n}: (set)`).join(", "),
+      file: csprojPath,
+    };
+  }
+
+  async applyLocal(entry, ctx, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const csprojPath = this.#findCsprojLocal(cwd, entry.name);
+    if (!csprojPath) return { changed: false };
+
+    const content = readFileSync(csprojPath, "utf8");
+    const repoUrl = `https://github.com/${entry.repo}`;
+    const projectUrl = `${repoUrl}#readme`;
+    const newContent = this.#fixCsproj(content, repoUrl, projectUrl);
+
+    if (newContent === content) return { changed: false };
+
+    writeFileSync(csprojPath, newContent);
+    return { changed: true, before: "(missing metadata)", after: "(metadata added)", file: csprojPath };
+  }
+
+  async applyRemote(entry, ctx, opts = {}) {
+    const csprojPath = await this.#findCsprojRemote(entry);
+    if (!csprojPath) return { changed: false };
+
+    const remote = readRemoteFile(entry.repo, csprojPath);
+    if (!remote) return { changed: false };
+
+    const repoUrl = `https://github.com/${entry.repo}`;
+    const projectUrl = `${repoUrl}#readme`;
+    const newContent = this.#fixCsproj(remote.content, repoUrl, projectUrl);
+
+    if (newContent === remote.content) return { changed: false };
+
+    const ok = writeRemoteFile(
+      entry.repo, csprojPath, newContent, remote.sha,
+      `chore: add NuGet metadata to ${csprojPath}`
+    );
+
+    return { changed: ok, before: "(missing metadata)", after: "(metadata added)", file: csprojPath };
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  /** Find a .csproj file locally that matches the NuGet package name. */
+  #findCsprojLocal(cwd, packageName) {
+    // Look for <PackageName>.csproj or any .csproj in cwd and one level down
+    const candidates = [];
+
+    // Direct match
+    const directPath = join(cwd, `${packageName}.csproj`);
+    if (existsSync(directPath)) return directPath;
+
+    // Search cwd for any .csproj
+    try {
+      const files = readdirSync(cwd).filter(f => f.endsWith(".csproj"));
+      for (const f of files) candidates.push(join(cwd, f));
+    } catch { /* ignore */ }
+
+    // Search src/ directory
+    const srcDir = join(cwd, "src");
+    if (existsSync(srcDir)) {
+      try {
+        for (const dir of readdirSync(srcDir, { withFileTypes: true })) {
+          if (dir.isDirectory()) {
+            const subPath = join(srcDir, dir.name);
+            const subFiles = readdirSync(subPath).filter(f => f.endsWith(".csproj"));
+            for (const f of subFiles) candidates.push(join(subPath, f));
+          }
+        }
+      } catch { /* ignore */ }
+    }
+
+    // Prefer a csproj whose name matches the package name
+    const match = candidates.find(p => {
+      const name = p.split(/[\\/]/).pop().replace(".csproj", "");
+      return name.toLowerCase() === packageName.toLowerCase() ||
+             name.toLowerCase() === packageName.split(".").pop().toLowerCase();
+    });
+
+    return match ?? candidates[0] ?? null;
+  }
+
+  /** Find csproj remotely by checking common paths. */
+  async #findCsprojRemote(entry) {
+    const { execSync } = await import("node:child_process");
+    try {
+      // List repo root for .csproj files
+      const raw = execSync(
+        `gh api "repos/${entry.repo}/git/trees/HEAD?recursive=1" --jq "[.tree[].path | select(test(\"\\\\.csproj$\"))]"`,
+        { encoding: "utf8", timeout: 15_000, stdio: ["pipe", "pipe", "pipe"] }
+      );
+      const paths = JSON.parse(raw);
+      if (paths.length === 0) return null;
+
+      // Prefer one matching the package name
+      const match = paths.find(p => {
+        const name = p.split("/").pop().replace(".csproj", "");
+        return name.toLowerCase() === entry.name.toLowerCase() ||
+               name.toLowerCase() === entry.name.split(".").pop().toLowerCase();
+      });
+      return match ?? paths[0];
+    } catch {
+      return null;
+    }
+  }
+
+  /** Check which metadata elements are missing. */
+  #analyzeCsproj(content, repoUrl, projectUrl) {
+    const missing = [];
+    if (!content.includes("<PackageProjectUrl>")) missing.push("PackageProjectUrl");
+    if (!content.includes("<RepositoryUrl>")) missing.push("RepositoryUrl");
+    return missing;
+  }
+
+  /** Insert missing metadata into the first <PropertyGroup>. */
+  #fixCsproj(content, repoUrl, projectUrl) {
+    let result = content;
+
+    // Find the first <PropertyGroup> closing or a line before </PropertyGroup>
+    const pgMatch = result.match(/<PropertyGroup[^>]*>/);
+    if (!pgMatch) return result; // Can't safely edit without PropertyGroup
+
+    const insertIdx = result.indexOf(pgMatch[0]) + pgMatch[0].length;
+
+    const additions = [];
+    if (!result.includes("<PackageProjectUrl>")) {
+      additions.push(`    <PackageProjectUrl>${projectUrl}</PackageProjectUrl>`);
+    }
+    if (!result.includes("<RepositoryUrl>")) {
+      additions.push(`    <RepositoryUrl>${repoUrl}.git</RepositoryUrl>`);
+    }
+
+    if (additions.length === 0) return result;
+
+    const insertBlock = "\n" + additions.join("\n");
+    result = result.slice(0, insertIdx) + insertBlock + result.slice(insertIdx);
+
+    return result;
+  }
+}

package/src/fixers/fixers/readme-header.mjs

@@ -0,0 +1,136 @@
+/**
+ * Fixer: readme-header — ensures README.md has a logo and site link.
+ * Matches audit finding code: "missing-readme"
+ *
+ * Ported from scripts/storefront-fix.mjs (GitHub API version) to
+ * support both local and remote modes.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { Fixer } from "../fixer.mjs";
+import { readRemoteFile, writeRemoteFile } from "./_npm-helpers.mjs";
+
+const SITE_URL = "https://mcptoolshop.com";
+const LOGO_PATHS = ["logo.png", "logo.svg", "assets/logo.png", "assets/logo.svg"];
+
+export default class ReadmeHeaderFixer extends Fixer {
+  get code() { return "readme-header"; }
+  get target() { return "readme"; }
+
+  canFix(finding) {
+    return finding.code === "missing-readme";
+  }
+
+  describe() {
+    return "Add logo and site link to README.md header";
+  }
+
+  async diagnose(entry, ctx, opts = {}) {
+    if (opts.remote) {
+      const remote = readRemoteFile(entry.repo, "README.md");
+      if (!remote) return { needed: true, before: null, after: "README.md with header", file: "README.md" };
+      return this.#analyzeContent(remote.content, entry);
+    }
+
+    const cwd = opts.cwd ?? process.cwd();
+    const readmePath = join(cwd, "README.md");
+    if (!existsSync(readmePath)) {
+      return { needed: true, before: null, after: "README.md with header", file: "README.md" };
+    }
+    const content = readFileSync(readmePath, "utf8");
+    return this.#analyzeContent(content, entry);
+  }
+
+  async applyLocal(entry, ctx, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const readmePath = join(cwd, "README.md");
+    if (!existsSync(readmePath)) return { changed: false };
+
+    const content = readFileSync(readmePath, "utf8");
+    const newContent = this.#fixContent(content, entry, cwd);
+
+    if (newContent === content) return { changed: false };
+
+    writeFileSync(readmePath, newContent);
+    return { changed: true, before: "(header missing)", after: "(header added)", file: "README.md" };
+  }
+
+  async applyRemote(entry, ctx, opts = {}) {
+    const remote = readRemoteFile(entry.repo, "README.md");
+    if (!remote) return { changed: false };
+
+    const newContent = this.#fixContent(remote.content, entry);
+    if (newContent === remote.content) return { changed: false };
+
+    const ok = writeRemoteFile(
+      entry.repo, "README.md",
+      newContent, remote.sha,
+      `chore: add logo and MCP Tool Shop link to README`
+    );
+
+    return { changed: ok, before: "(header missing)", after: "(header added)", file: "README.md" };
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  #analyzeContent(content, entry) {
+    const firstLines = content.split("\n").slice(0, 10).join("\n");
+    const hasLogo = firstLines.includes("![") || firstLines.includes("<img");
+    const hasSiteLink = content.includes(SITE_URL) || content.includes("mcptoolshop.com") || content.includes("MCP Tool Shop");
+
+    if (hasLogo && hasSiteLink) return { needed: false };
+
+    const changes = [];
+    if (!hasLogo) changes.push("logo");
+    if (!hasSiteLink) changes.push("site link");
+
+    return {
+      needed: true,
+      before: `Missing: ${changes.join(", ")}`,
+      after: "Logo + site link in header",
+      file: "README.md",
+    };
+  }
+
+  #fixContent(content, entry, cwd = null) {
+    let result = content;
+    const repoName = entry.repo.split("/")[1];
+
+    // Detect existing logo path
+    let logoPath = "logo.png";
+    if (cwd) {
+      for (const p of LOGO_PATHS) {
+        if (existsSync(join(cwd, p))) {
+          logoPath = p;
+          break;
+        }
+      }
+    }
+
+    // Check if logo is in the first 10 lines
+    const firstLines = result.split("\n").slice(0, 10).join("\n");
+    const hasLogo = firstLines.includes("![") || firstLines.includes("<img");
+
+    if (!hasLogo) {
+      const logoHeader = `<p align="center">\n  <img src="${logoPath}" width="200" alt="${repoName}">\n</p>\n\n`;
+      result = logoHeader + result;
+    }
+
+    // Check for site link
+    const hasSiteLink = result.includes(SITE_URL) || result.includes("mcptoolshop.com") || result.includes("MCP Tool Shop");
+
+    if (!hasSiteLink) {
+      const headingMatch = result.match(/^#\s+.+$/m);
+      if (headingMatch) {
+        const idx = result.indexOf(headingMatch[0]) + headingMatch[0].length;
+        const catalogLine = `\n\n> Part of [MCP Tool Shop](${SITE_URL})`;
+        result = result.slice(0, idx) + catalogLine + result.slice(idx);
+      } else {
+        result = result + `\n\n> Part of [MCP Tool Shop](${SITE_URL})\n`;
+      }
+    }
+
+    return result;
+  }
+}

package/src/fixers/registry.mjs

@@ -0,0 +1,71 @@
+/**
+ * Fixer registry — auto-discovers and validates fixer modules.
+ *
+ * Mirrors the pattern from scripts/lib/registry.mjs (provider auto-discovery).
+ * Scans src/fixers/fixers/*.mjs, validates each extends Fixer, returns instances.
+ */
+
+import { readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Fixer } from "./fixer.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXERS_DIR = join(__dirname, "fixers");
+
+/**
+ * Load all fixer modules from the fixers/ directory.
+ * Skips files prefixed with `_` (helpers).
+ *
+ * @returns {Promise<Fixer[]>} Array of fixer instances
+ */
+export async function loadFixers() {
+  const files = readdirSync(FIXERS_DIR)
+    .filter(f => f.endsWith(".mjs") && !f.startsWith("_"))
+    .sort();
+
+  const fixers = [];
+
+  for (const file of files) {
+    const url = pathToFileURL(join(FIXERS_DIR, file)).href;
+    const mod = await import(url);
+    const FixerClass = mod.default;
+
+    if (!FixerClass) {
+      throw new Error(`Fixer module ${file} has no default export`);
+    }
+
+    const instance = new FixerClass();
+
+    if (!(instance instanceof Fixer)) {
+      throw new Error(`Fixer module ${file} does not extend Fixer`);
+    }
+
+    // Validate required overrides
+    try {
+      instance.code;
+    } catch {
+      throw new Error(`Fixer ${file} does not override 'code'`);
+    }
+    try {
+      instance.target;
+    } catch {
+      throw new Error(`Fixer ${file} does not override 'target'`);
+    }
+
+    fixers.push(instance);
+  }
+
+  return fixers;
+}
+
+/**
+ * Find fixers that can handle a given audit finding.
+ *
+ * @param {Fixer[]} fixers  - All loaded fixers
+ * @param {object}  finding - { severity, code, msg }
+ * @returns {Fixer[]} Matching fixers
+ */
+export function matchFixers(fixers, finding) {
+  return fixers.filter(f => f.canFix(finding));
+}

package/src/plugins/loader.mjs

@@ -0,0 +1,48 @@
+/**
+ * Plugin loader — discovers and loads optional plugin packages.
+ *
+ * Pattern: known plugin names → npm package names.
+ * If the package is installed, import and return it.
+ * If not, return null (caller shows install hint).
+ */
+
+const KNOWN_PLUGINS = {
+  assets: "@mcptoolshop/mcpt-publishing-assets",
+};
+
+/**
+ * Attempt to load a known plugin.
+ * @param {string} name — "assets"
+ * @returns {Promise<object|null>} The plugin module, or null if not installed.
+ */
+export async function loadPlugin(name) {
+  const pkgName = KNOWN_PLUGINS[name];
+  if (!pkgName) return null;
+
+  try {
+    return await import(pkgName);
+  } catch (e) {
+    if (e.code === "ERR_MODULE_NOT_FOUND" || e.code === "MODULE_NOT_FOUND") {
+      return null;
+    }
+    throw e; // Re-throw unexpected errors
+  }
+}
+
+/**
+ * Get the install command hint for a plugin.
+ * @param {string} name — "assets"
+ * @returns {string}
+ */
+export function installHint(name) {
+  const pkgName = KNOWN_PLUGINS[name];
+  return pkgName ? `npm i -D ${pkgName}` : `Unknown plugin: ${name}`;
+}
+
+/**
+ * List all known plugins.
+ * @returns {Array<{ name: string, package: string }>}
+ */
+export function listPlugins() {
+  return Object.entries(KNOWN_PLUGINS).map(([name, pkg]) => ({ name, package: pkg }));
+}

package/src/receipts/fix-receipt.mjs

@@ -0,0 +1,49 @@
+/**
+ * Fix receipt builder — emits a receipt after each fix run.
+ *
+ * Path: receipts/fix/<YYYY-MM-DD>-<slug>.json
+ * Date-keyed with repo slug: overwrites within the same day for same repo.
+ */
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { updateFixEntry } from "./index-writer.mjs";
+
+/**
+ * Build and write a fix receipt.
+ *
+ * @param {object} config     - Resolved config (needs config.receiptsDir)
+ * @param {object} fixResult  - Fix results:
+ *   { repo, mode, dryRun, changes[], auditBefore, auditAfter, commitSha?, prUrl?, branchName?, fileHashes? }
+ * @returns {string} Path to the written receipt file
+ */
+export function emitFixReceipt(config, fixResult) {
+  const fixDir = join(config.receiptsDir, "fix");
+  mkdirSync(fixDir, { recursive: true });
+
+  const receipt = {
+    schemaVersion: "1.0.0",
+    type: "fix",
+    timestamp: new Date().toISOString(),
+    repo: fixResult.repo ?? "*",
+    mode: fixResult.mode,
+    dryRun: fixResult.dryRun ?? false,
+    prUrl: fixResult.prUrl ?? null,
+    branchName: fixResult.branchName ?? null,
+    changes: fixResult.changes ?? [],
+    auditBefore: fixResult.auditBefore ?? null,
+    auditAfter: fixResult.auditAfter ?? null,
+    commitSha: fixResult.commitSha ?? null,
+    fileHashes: fixResult.fileHashes ?? {},
+  };
+
+  const date = receipt.timestamp.slice(0, 10); // YYYY-MM-DD
+  const slug = (fixResult.repo ?? "fleet").replace(/\//g, "--");
+  const filePath = join(fixDir, `${date}-${slug}.json`);
+  writeFileSync(filePath, JSON.stringify(receipt, null, 2) + "\n");
+
+  // Update the receipts index
+  updateFixEntry(config.receiptsDir, receipt);
+
+  return filePath;
+}

package/src/receipts/index-writer.mjs

@@ -48,6 +48,27 @@ export function updatePublishEntry(receiptsDir, publishReceipt) {
   saveIndex(receiptsDir, index);
 }
 
+/**
+ * Update the index with a fix receipt entry.
+ * @param {string} receiptsDir - Absolute path to receipts directory
+ * @param {object} fixReceipt  - A fix receipt object
+ */
+export function updateFixEntry(receiptsDir, fixReceipt) {
+  const index = loadIndex(receiptsDir);
+
+  if (!index.fix) index.fix = {};
+
+  const key = fixReceipt.repo ?? "fleet";
+  index.fix[key] = {
+    timestamp: fixReceipt.timestamp,
+    mode: fixReceipt.mode,
+    changesCount: fixReceipt.changes?.length ?? 0,
+    dryRun: fixReceipt.dryRun ?? false,
+  };
+
+  saveIndex(receiptsDir, index);
+}
+
 // ─── Internal ────────────────────────────────────────────────────────────────
 
 function loadIndex(receiptsDir) {