@mcptoolshop/mcpt-publishing 0.2.0

package/src/commands/publish.mjs

@@ -0,0 +1,215 @@
+/**
+ * `mcpt-publishing publish` — publish packages to registries with receipts.
+ *
+ * Loads config → reads manifest → filters by --repo/--target → pre-flight
+ * credential check → executes publishes → writes receipts → updates index.
+ *
+ * Exit codes:
+ *   0 — all publishes succeeded (or no packages matched)
+ *   4 — missing credentials
+ *   5 — one or more publishes failed
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { loadConfig } from "../config/loader.mjs";
+import { updatePublishEntry } from "../receipts/index-writer.mjs";
+import { EXIT } from "../cli/exit-codes.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const helpText = `
+mcpt-publishing publish — Publish packages to registries and generate receipts.
+
+Usage:
+  mcpt-publishing publish [flags]
+
+Flags:
+  --repo <owner/name>   Filter to packages from this repo
+  --target <registry>   Filter to a specific registry (npm, nuget)
+  --cwd <path>          Working directory for the repo (default: cwd)
+  --dry-run             Do everything except the actual registry push
+  --json                Output results as JSON
+  --help                Show this help
+
+Exit codes:
+  0   All publishes succeeded
+  4   Missing credentials (NPM_TOKEN or NUGET_API_KEY)
+  5   One or more publishes failed
+
+Examples:
+  mcpt-publishing publish --target npm --dry-run
+  mcpt-publishing publish --repo mcp-tool-shop-org/mcpt --target npm
+  mcpt-publishing publish --repo mcp-tool-shop-org/soundboard-maui --target nuget --cwd /path/to/repo
+`.trim();
+
+/** Required env vars per provider. */
+const CRED_MAP = {
+  npm: "NPM_TOKEN",
+  nuget: "NUGET_API_KEY",
+  pypi: "PYPI_TOKEN",
+  ghcr: "GITHUB_TOKEN",
+};
+
+/**
+ * Execute the publish command.
+ * @param {object} flags - Parsed CLI flags
+ * @returns {number} Exit code
+ */
+export async function execute(flags) {
+  // 1. Load config
+  const config = flags.config
+    ? loadConfig(dirname(flags.config))
+    : loadConfig();
+
+  // 2. Read manifest
+  const manifestPath = join(config.profilesDir, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    process.stderr.write(`Error: Manifest not found at ${manifestPath}\n`);
+    process.stderr.write(`Run 'mcpt-publishing init' to scaffold the project.\n`);
+    return EXIT.CONFIG_ERROR;
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+  // 3. Load providers
+  const registryPath = join(__dirname, "..", "..", "scripts", "lib", "registry.mjs");
+  const registryUrl = pathToFileURL(registryPath).href;
+  const { loadProviders, matchProviders } = await import(registryUrl);
+  const providers = await loadProviders();
+
+  // 4. Build task list from manifest
+  const tasks = [];
+  for (const [ecosystem, packages] of Object.entries(manifest)) {
+    if (!Array.isArray(packages)) continue;
+    for (const pkg of packages) {
+      const entry = { ...pkg, ecosystem };
+
+      // Apply filters
+      if (flags.repo && entry.repo !== flags.repo) continue;
+      if (flags.target && ecosystem !== flags.target) continue;
+      if (entry.deprecated) continue;
+
+      // Find ecosystem providers (skip github context loader)
+      const matched = matchProviders(providers, entry).filter(p => p.name !== "github");
+      for (const provider of matched) {
+        tasks.push({ entry, provider });
+      }
+    }
+  }
+
+  if (tasks.length === 0) {
+    if (flags.json) {
+      process.stdout.write(JSON.stringify({ results: [], failures: 0, message: "No packages matched filters" }) + "\n");
+    } else {
+      process.stderr.write("No packages matched the given filters.\n");
+      if (flags.repo) process.stderr.write(`  --repo: ${flags.repo}\n`);
+      if (flags.target) process.stderr.write(`  --target: ${flags.target}\n`);
+    }
+    return EXIT.SUCCESS;
+  }
+
+  // 5. Pre-flight credential check
+  const neededCreds = new Set();
+  for (const { provider } of tasks) {
+    const envVar = CRED_MAP[provider.name];
+    if (envVar && !process.env[envVar]) {
+      neededCreds.add(envVar);
+    }
+  }
+
+  if (neededCreds.size > 0 && !flags["dry-run"]) {
+    for (const envVar of neededCreds) {
+      process.stderr.write(`Error: ${envVar} environment variable is not set.\n`);
+    }
+    return EXIT.MISSING_CREDENTIALS;
+  }
+
+  // 6. Execute publishes sequentially
+  const cwd = flags.cwd ? resolve(flags.cwd) : process.cwd();
+  const dryRun = !!flags["dry-run"];
+  const results = [];
+  let failures = 0;
+
+  // Import receipt writer and shell utils
+  const receiptWriterPath = join(__dirname, "..", "..", "scripts", "lib", "receipt-writer.mjs");
+  const shellPath = join(__dirname, "..", "..", "scripts", "lib", "shell.mjs");
+  const { write: writeReceipt } = await import(pathToFileURL(receiptWriterPath).href);
+  const { getCommitSha } = await import(pathToFileURL(shellPath).href);
+
+  for (const { entry, provider } of tasks) {
+    const label = `${entry.name} → ${provider.name}`;
+    process.stderr.write(`\nPublishing ${label}${dryRun ? " (dry-run)" : ""}...\n`);
+
+    try {
+      const result = await provider.publish(entry, { dryRun, cwd });
+
+      if (!result.success) {
+        process.stderr.write(`  FAIL: ${result.error}\n`);
+        failures++;
+        results.push({ name: entry.name, target: provider.name, success: false, error: result.error });
+        continue;
+      }
+
+      process.stderr.write(`  OK: ${entry.name}@${result.version}\n`);
+
+      // Write receipt (skip in dry-run)
+      if (!dryRun) {
+        try {
+          const commitSha = getCommitSha(cwd);
+          const receiptData = provider.receipt({
+            ...entry,
+            version: result.version,
+            commitSha,
+            artifacts: result.artifacts,
+          });
+
+          const receiptFile = writeReceipt(receiptData);
+          updatePublishEntry(config.receiptsDir, receiptData);
+          process.stderr.write(`  Receipt: ${receiptFile}\n`);
+
+          // GitHub glue: attach to release (opt-in)
+          if (config.github?.attachReceipts) {
+            try {
+              const gluePath = join(__dirname, "..", "..", "scripts", "lib", "github-glue.mjs");
+              const { attachReceiptToRelease } = await import(pathToFileURL(gluePath).href);
+              const tagName = `v${result.version}`;
+              attachReceiptToRelease(entry.repo, tagName, receiptFile);
+              process.stderr.write(`  Attached to release ${tagName}\n`);
+            } catch (e) {
+              // GitHub glue failures are non-fatal
+              process.stderr.write(`  Warning: GitHub glue failed: ${e.message}\n`);
+            }
+          }
+        } catch (e) {
+          process.stderr.write(`  Warning: Receipt write failed: ${e.message}\n`);
+          // Receipt failure doesn't fail the publish — the package IS published
+        }
+      }
+
+      results.push({
+        name: entry.name,
+        target: provider.name,
+        success: true,
+        version: result.version,
+        artifacts: result.artifacts,
+        dryRun,
+      });
+    } catch (e) {
+      process.stderr.write(`  ERROR: ${e.message}\n`);
+      failures++;
+      results.push({ name: entry.name, target: provider.name, success: false, error: e.message });
+    }
+  }
+
+  // 7. Summary
+  const succeeded = results.filter(r => r.success).length;
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ results, succeeded, failures, dryRun }, null, 2) + "\n");
+  } else {
+    process.stderr.write(`\nDone. ${succeeded} succeeded, ${failures} failed.${dryRun ? " (dry-run)" : ""}\n`);
+  }
+
+  return failures > 0 ? EXIT.PUBLISH_FAILURE : EXIT.SUCCESS;
+}

package/src/commands/verify-receipt.mjs

@@ -0,0 +1,175 @@
+/**
+ * `mcpt-publishing verify-receipt` — validate a receipt file.
+ *
+ * Checks:
+ *   1. File exists and is readable
+ *   2. Valid JSON
+ *   3. Schema validation (publish or audit receipt)
+ *   4. SHA-256 integrity hash (for reference/verification)
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { EXIT } from "../cli/exit-codes.mjs";
+
+export const helpText = `
+mcpt-publishing verify-receipt — Validate a receipt file.
+
+Usage:
+  mcpt-publishing verify-receipt <path> [flags]
+
+Arguments:
+  <path>        Path to the receipt JSON file
+
+Flags:
+  --json        Output result as JSON
+  --help        Show this help
+
+Checks:
+  1. File exists and is readable
+  2. Valid JSON parse
+  3. Schema validation (publish or audit receipt)
+  4. SHA-256 content integrity hash
+
+Exit codes:
+  0   Receipt is valid
+  3   Validation failed
+`.trim();
+
+/** Required fields for audit receipts. */
+const AUDIT_REQUIRED = ["schemaVersion", "type", "timestamp", "counts", "totalPackages"];
+
+/** Required fields for publish receipts. */
+const PUBLISH_REQUIRED = ["schemaVersion", "repo", "target", "version", "packageName", "commitSha", "timestamp", "artifacts"];
+
+const VALID_TARGETS = ["npm", "nuget", "pypi", "ghcr"];
+
+/**
+ * Execute the verify-receipt command.
+ * @param {object} flags - Parsed CLI flags
+ * @returns {number} Exit code
+ */
+export async function execute(flags) {
+  const receiptPath = flags._positionals[0];
+
+  if (!receiptPath) {
+    process.stderr.write("Error: receipt path is required.\n");
+    process.stderr.write("Usage: mcpt-publishing verify-receipt <path>\n");
+    return EXIT.CONFIG_ERROR;
+  }
+
+  const absPath = resolve(receiptPath);
+  const checks = [];
+
+  // Check 1: File exists
+  if (!existsSync(absPath)) {
+    checks.push({ check: "exists", pass: false, msg: `File not found: ${absPath}` });
+    return output(checks, flags);
+  }
+  checks.push({ check: "exists", pass: true });
+
+  // Check 2: Valid JSON
+  let receipt;
+  try {
+    receipt = JSON.parse(readFileSync(absPath, "utf8"));
+    checks.push({ check: "json", pass: true });
+  } catch (e) {
+    checks.push({ check: "json", pass: false, msg: `Invalid JSON: ${e.message}` });
+    return output(checks, flags);
+  }
+
+  // Check 3: Schema validation
+  // Detect receipt type: audit receipts have type="audit", publish receipts have "target"
+  if (receipt.type === "audit") {
+    const missing = AUDIT_REQUIRED.filter(f => !(f in receipt));
+    if (missing.length > 0) {
+      checks.push({ check: "schema", pass: false, type: "audit", msg: `Missing fields: ${missing.join(", ")}` });
+    } else {
+      checks.push({ check: "schema", pass: true, type: "audit" });
+    }
+  } else if (receipt.target || receipt.packageName) {
+    // Publish receipt — validate against full schema
+    const missing = PUBLISH_REQUIRED.filter(f => !(f in receipt));
+    if (missing.length > 0) {
+      checks.push({ check: "schema", pass: false, type: "publish", msg: `Missing fields: ${missing.join(", ")}` });
+    } else {
+      // Deep validation
+      const errors = validatePublishReceipt(receipt);
+      if (errors.length > 0) {
+        checks.push({ check: "schema", pass: false, type: "publish", msg: errors.join("; ") });
+      } else {
+        checks.push({ check: "schema", pass: true, type: "publish" });
+      }
+    }
+  } else {
+    checks.push({ check: "schema", pass: false, msg: "Unknown receipt type (no 'type' or 'target' field)" });
+  }
+
+  // Check 4: Compute SHA-256 integrity hash
+  const content = readFileSync(absPath);
+  const sha256 = createHash("sha256").update(content).digest("hex");
+  checks.push({ check: "integrity", pass: true, sha256 });
+
+  return output(checks, flags);
+}
+
+/**
+ * Validate publish receipt fields beyond presence checks.
+ * @param {object} r - Receipt object
+ * @returns {string[]} Error messages (empty = valid)
+ */
+function validatePublishReceipt(r) {
+  const errors = [];
+
+  if (r.schemaVersion !== "1.0.0") {
+    errors.push(`Unknown schemaVersion: ${r.schemaVersion}`);
+  }
+  if (typeof r.repo !== "object" || !r.repo.owner || !r.repo.name) {
+    errors.push("repo must have owner and name");
+  }
+  if (!VALID_TARGETS.includes(r.target)) {
+    errors.push(`Invalid target: ${r.target}`);
+  }
+  if (typeof r.commitSha !== "string" || !/^[0-9a-f]{40}$/.test(r.commitSha)) {
+    errors.push("commitSha must be 40 lowercase hex characters");
+  }
+  if (!Array.isArray(r.artifacts)) {
+    errors.push("artifacts must be an array");
+  } else {
+    for (const art of r.artifacts) {
+      if (!art.name) errors.push("artifact missing name");
+      if (typeof art.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(art.sha256)) {
+        errors.push(`artifact ${art.name ?? "?"} has invalid sha256`);
+      }
+      if (typeof art.size !== "number" || art.size < 0) {
+        errors.push(`artifact ${art.name ?? "?"} has invalid size`);
+      }
+      if (!art.url) errors.push(`artifact ${art.name ?? "?"} missing url`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Output check results and return exit code.
+ */
+function output(checks, flags) {
+  const allPass = checks.every(c => c.pass);
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ valid: allPass, checks }, null, 2) + "\n");
+  } else {
+    for (const c of checks) {
+      const icon = c.pass ? "PASS" : "FAIL";
+      const detail = c.msg ? ` — ${c.msg}` : "";
+      const extra = c.sha256 ? ` (sha256: ${c.sha256.slice(0, 16)}...)` : "";
+      const typeNote = c.type ? ` [${c.type}]` : "";
+      process.stderr.write(`  ${icon}  ${c.check}${typeNote}${detail}${extra}\n`);
+    }
+    process.stderr.write(`\n${allPass ? "Receipt is valid." : "Receipt validation FAILED."}\n`);
+  }
+
+  return allPass ? EXIT.SUCCESS : EXIT.CONFIG_ERROR;
+}

package/src/config/defaults.mjs

@@ -0,0 +1,14 @@
+/**
+ * Default config values used when no publishing.config.json is found
+ * or when fields are omitted from the config file.
+ */
+export const DEFAULTS = {
+  profilesDir: "profiles",
+  receiptsDir: "receipts",
+  reportsDir: "reports",
+  github: {
+    updateIssue: true,
+    attachReceipts: true,
+  },
+  enabledProviders: [], // empty = all providers enabled
+};

package/src/config/loader.mjs

@@ -0,0 +1,86 @@
+/**
+ * Config loader — discovers and parses publishing.config.json.
+ *
+ * Discovery order:
+ *   1. PUBLISHING_CONFIG env var (explicit path)
+ *   2. Walk up from startDir looking for publishing.config.json
+ *   3. Fall back to defaults rooted at startDir
+ *
+ * All directory paths (profilesDir, receiptsDir, reportsDir) resolve
+ * relative to the config file location, not process.cwd().
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve, isAbsolute } from "node:path";
+import { DEFAULTS } from "./defaults.mjs";
+import { validateConfig } from "./schema.mjs";
+
+const CONFIG_FILENAME = "publishing.config.json";
+
+/**
+ * Load config from the filesystem.
+ * @param {string} [startDir=process.cwd()] - Directory to start searching from
+ * @returns {object} Resolved config with absolute paths
+ */
+export function loadConfig(startDir = process.cwd()) {
+  // 1. Env override takes priority
+  const envPath = process.env.PUBLISHING_CONFIG;
+  if (envPath) {
+    const resolved = resolve(envPath);
+    if (!existsSync(resolved)) {
+      throw new Error(`PUBLISHING_CONFIG points to non-existent file: ${resolved}`);
+    }
+    return parseAndResolve(resolved);
+  }
+
+  // 2. Walk up from startDir
+  let dir = resolve(startDir);
+  while (true) {
+    const candidate = join(dir, CONFIG_FILENAME);
+    if (existsSync(candidate)) {
+      return parseAndResolve(candidate);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // filesystem root reached
+    dir = parent;
+  }
+
+  // 3. No config found — return defaults rooted at startDir
+  const resolvedStart = resolve(startDir);
+  return {
+    ...DEFAULTS,
+    github: { ...DEFAULTS.github },
+    profilesDir: join(resolvedStart, DEFAULTS.profilesDir),
+    receiptsDir: join(resolvedStart, DEFAULTS.receiptsDir),
+    reportsDir: join(resolvedStart, DEFAULTS.reportsDir),
+    _configDir: resolvedStart,
+    _configFile: null,
+  };
+}
+
+/**
+ * Parse a config file and resolve all paths relative to its location.
+ * @param {string} filePath - Absolute path to the config file
+ * @returns {object}
+ */
+function parseAndResolve(filePath) {
+  const raw = JSON.parse(readFileSync(filePath, "utf8"));
+  validateConfig(raw);
+
+  const configDir = dirname(filePath);
+
+  return {
+    ...DEFAULTS,
+    ...raw,
+    github: { ...DEFAULTS.github, ...raw.github },
+    profilesDir: resolvePath(configDir, raw.profilesDir ?? DEFAULTS.profilesDir),
+    receiptsDir: resolvePath(configDir, raw.receiptsDir ?? DEFAULTS.receiptsDir),
+    reportsDir: resolvePath(configDir, raw.reportsDir ?? DEFAULTS.reportsDir),
+    _configDir: configDir,
+    _configFile: filePath,
+  };
+}
+
+function resolvePath(base, p) {
+  return isAbsolute(p) ? p : resolve(base, p);
+}

package/src/config/schema.mjs

@@ -0,0 +1,70 @@
+/**
+ * Lightweight config validation (zero dependencies).
+ *
+ * Validates publishing.config.json structure and types.
+ * Throws on invalid input with a clear message.
+ */
+
+const KNOWN_KEYS = new Set([
+  "$schema", "profilesDir", "receiptsDir", "reportsDir",
+  "github", "enabledProviders",
+]);
+
+const KNOWN_GITHUB_KEYS = new Set([
+  "updateIssue", "attachReceipts",
+]);
+
+/**
+ * Validate a parsed config object.
+ * @param {object} config
+ * @throws {Error} on invalid config
+ */
+export function validateConfig(config) {
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error("Config must be a JSON object");
+  }
+
+  // Check for unknown top-level keys
+  for (const key of Object.keys(config)) {
+    if (!KNOWN_KEYS.has(key)) {
+      throw new Error(`Unknown config key: "${key}"`);
+    }
+  }
+
+  // String path fields
+  for (const field of ["profilesDir", "receiptsDir", "reportsDir"]) {
+    if (field in config && typeof config[field] !== "string") {
+      throw new Error(`Config "${field}" must be a string`);
+    }
+  }
+
+  // github section
+  if ("github" in config) {
+    if (typeof config.github !== "object" || Array.isArray(config.github)) {
+      throw new Error('Config "github" must be an object');
+    }
+    for (const key of Object.keys(config.github)) {
+      if (!KNOWN_GITHUB_KEYS.has(key)) {
+        throw new Error(`Unknown config github key: "${key}"`);
+      }
+    }
+    if ("updateIssue" in config.github && typeof config.github.updateIssue !== "boolean") {
+      throw new Error('Config "github.updateIssue" must be a boolean');
+    }
+    if ("attachReceipts" in config.github && typeof config.github.attachReceipts !== "boolean") {
+      throw new Error('Config "github.attachReceipts" must be a boolean');
+    }
+  }
+
+  // enabledProviders
+  if ("enabledProviders" in config) {
+    if (!Array.isArray(config.enabledProviders)) {
+      throw new Error('Config "enabledProviders" must be an array');
+    }
+    for (const p of config.enabledProviders) {
+      if (typeof p !== "string") {
+        throw new Error('Config "enabledProviders" entries must be strings');
+      }
+    }
+  }
+}

package/src/receipts/audit-receipt.mjs

@@ -0,0 +1,53 @@
+/**
+ * Audit receipt builder — emits a receipt after each audit run.
+ *
+ * Path: receipts/audit/<YYYY-MM-DD>.json
+ * Date-keyed: latest run of the day overwrites (not immutable like publish receipts).
+ */
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { updateReceiptsIndex } from "./index-writer.mjs";
+
+/**
+ * Build and write an audit receipt from audit results.
+ * @param {object} config  - Resolved config (needs config.receiptsDir)
+ * @param {object} results - Audit results { npm:[], nuget:[], counts:{}, generated }
+ * @returns {string} Path to the written receipt file
+ */
+export function emitAuditReceipt(config, results) {
+  const auditDir = join(config.receiptsDir, "audit");
+  mkdirSync(auditDir, { recursive: true });
+
+  // Count packages per ecosystem
+  const ecosystems = {};
+  let totalPackages = 0;
+  for (const [key, val] of Object.entries(results)) {
+    if (Array.isArray(val)) {
+      ecosystems[key] = val.length;
+      totalPackages += val.length;
+    }
+  }
+
+  const receipt = {
+    schemaVersion: "1.0.0",
+    type: "audit",
+    timestamp: new Date().toISOString(),
+    counts: results.counts,
+    ecosystems,
+    totalPackages,
+    reportFiles: {
+      json: "reports/latest.json",
+      markdown: "reports/latest.md",
+    },
+  };
+
+  const date = receipt.timestamp.slice(0, 10); // YYYY-MM-DD
+  const filePath = join(auditDir, `${date}.json`);
+  writeFileSync(filePath, JSON.stringify(receipt, null, 2) + "\n");
+
+  // Update the receipts index
+  updateReceiptsIndex(config.receiptsDir, receipt);
+
+  return filePath;
+}

package/src/receipts/index-writer.mjs

@@ -0,0 +1,65 @@
+/**
+ * Receipts index maintainer — keeps receipts/index.json current.
+ *
+ * The index provides a single-file view of:
+ *   - Latest audit run (date, counts, totalPackages)
+ *   - Latest publish per target/package (version, timestamp, commitSha)
+ *
+ * The Receipt Factory site can consume this file to render dashboards.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/**
+ * Update the index with the latest audit receipt data.
+ * @param {string} receiptsDir - Absolute path to receipts directory
+ * @param {object} auditReceipt - The audit receipt object
+ */
+export function updateReceiptsIndex(receiptsDir, auditReceipt) {
+  const index = loadIndex(receiptsDir);
+
+  index.latestAudit = {
+    date: auditReceipt.timestamp,
+    counts: auditReceipt.counts,
+    totalPackages: auditReceipt.totalPackages,
+  };
+
+  saveIndex(receiptsDir, index);
+}
+
+/**
+ * Update the index with a publish receipt entry.
+ * @param {string} receiptsDir - Absolute path to receipts directory
+ * @param {object} publishReceipt - A publish receipt object
+ */
+export function updatePublishEntry(receiptsDir, publishReceipt) {
+  const index = loadIndex(receiptsDir);
+
+  if (!index.publish) index.publish = {};
+
+  const key = `${publishReceipt.target}/${publishReceipt.packageName}`;
+  index.publish[key] = {
+    version: publishReceipt.version,
+    timestamp: publishReceipt.timestamp,
+    commitSha: publishReceipt.commitSha,
+  };
+
+  saveIndex(receiptsDir, index);
+}
+
+// ─── Internal ────────────────────────────────────────────────────────────────
+
+function loadIndex(receiptsDir) {
+  const indexPath = join(receiptsDir, "index.json");
+  if (existsSync(indexPath)) {
+    return JSON.parse(readFileSync(indexPath, "utf8"));
+  }
+  return { latestAudit: null, publish: {} };
+}
+
+function saveIndex(receiptsDir, index) {
+  mkdirSync(receiptsDir, { recursive: true });
+  const indexPath = join(receiptsDir, "index.json");
+  writeFileSync(indexPath, JSON.stringify(index, null, 2) + "\n");
+}