@mcptoolshop/mcpt-publishing 0.2.0

package/scripts/lib/providers/nuget.mjs

@@ -0,0 +1,198 @@
+/**
+ * NuGet provider — audit + publish.
+ *
+ * Audit: fetches metadata via NuGet search API + flat-container,
+ *        detects indexing lag, and classifies drift against git state.
+ * Publish: packs .nupkg, computes SHA-256, pushes to nuget.org.
+ */
+
+import { execSync } from "node:child_process";
+import { readdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { Provider } from "../provider.mjs";
+import { exec, hashFile } from "../shell.mjs";
+
+export default class NuGetProvider extends Provider {
+  get name() { return "nuget"; }
+
+  detect(entry) {
+    return entry.ecosystem === "nuget";
+  }
+
+  async audit(entry, ctx) {
+    const meta = this.#fetchMeta(entry.name);
+    const flatVersions = this.#fetchVersions(entry.name);
+    const tags = ctx.tags.get(entry.repo) ?? [];
+    const releases = ctx.releases.get(entry.repo) ?? [];
+
+    const version = flatVersions.length > 0
+      ? flatVersions[flatVersions.length - 1]
+      : (meta?.version ?? "?");
+
+    const findings = this.#classify(entry, meta, tags, releases, flatVersions);
+    return { version, findings };
+  }
+
+  /**
+   * Publish a NuGet package.
+   *
+   * @param {object} entry - { name, repo, audience, ecosystem }
+   * @param {object} opts  - { dryRun: boolean, cwd: string }
+   * @returns {Promise<{ success: boolean, version: string, artifacts: Array, error?: string }>}
+   */
+  async publish(entry, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+
+    // Check credentials (skip in dry-run — dotnet pack doesn't need auth)
+    if (!process.env.NUGET_API_KEY && !opts.dryRun) {
+      return { success: false, version: "", artifacts: [], error: "NUGET_API_KEY environment variable is not set" };
+    }
+
+    const outputDir = join(cwd, "nupkg-output");
+
+    // dotnet pack
+    const packResult = exec("dotnet pack -c Release -o nupkg-output", { cwd });
+    if (packResult.exitCode !== 0) {
+      return { success: false, version: "", artifacts: [], error: `dotnet pack failed: ${packResult.stderr}` };
+    }
+
+    // Find the .nupkg matching the package name
+    if (!existsSync(outputDir)) {
+      return { success: false, version: "", artifacts: [], error: "nupkg-output directory not created by dotnet pack" };
+    }
+
+    const nupkgFiles = readdirSync(outputDir).filter(f => f.endsWith(".nupkg") && !f.endsWith(".symbols.nupkg"));
+    const targetNupkg = nupkgFiles.find(f => f.toLowerCase().startsWith(entry.name.toLowerCase() + "."));
+
+    if (!targetNupkg) {
+      // Clean up
+      try { rmSync(outputDir, { recursive: true }); } catch { /* ignore */ }
+      return {
+        success: false, version: "", artifacts: [],
+        error: `No .nupkg found matching "${entry.name}" in nupkg-output/ (found: ${nupkgFiles.join(", ") || "none"})`,
+      };
+    }
+
+    // Extract version from filename: PackageName.1.2.3.nupkg
+    const nupkgBasename = targetNupkg.replace(/\.nupkg$/, "");
+    const version = nupkgBasename.slice(entry.name.length + 1); // +1 for the dot
+
+    if (!version) {
+      try { rmSync(outputDir, { recursive: true }); } catch { /* ignore */ }
+      return { success: false, version: "", artifacts: [], error: `Could not parse version from ${targetNupkg}` };
+    }
+
+    // Compute SHA-256
+    const nupkgPath = join(outputDir, targetNupkg);
+    const { sha256, size } = hashFile(nupkgPath);
+
+    // Push (or dry-run)
+    if (!opts.dryRun) {
+      const pushResult = exec(
+        `dotnet nuget push "${nupkgPath}" --api-key "${process.env.NUGET_API_KEY}" --source https://api.nuget.org/v3/index.json --skip-duplicate`,
+        { cwd }
+      );
+      if (pushResult.exitCode !== 0) {
+        try { rmSync(outputDir, { recursive: true }); } catch { /* ignore */ }
+        return { success: false, version, artifacts: [], error: `dotnet nuget push failed: ${pushResult.stderr}` };
+      }
+    }
+
+    // Clean up
+    try { rmSync(outputDir, { recursive: true }); } catch { /* ignore */ }
+
+    // Build artifact metadata
+    const artifact = {
+      name: targetNupkg,
+      sha256,
+      size,
+      url: `https://www.nuget.org/packages/${entry.name}/${version}`,
+    };
+
+    return { success: true, version, artifacts: [artifact] };
+  }
+
+  // ─── Private ───────────────────────────────────────────────────────────────
+
+  #fetchMeta(id) {
+    try {
+      const url = `https://azuresearch-usnc.nuget.org/query?q=packageid:${id}&take=1`;
+      const raw = execSync(`curl -sf "${url}"`, { encoding: "utf8", timeout: 15_000 });
+      const data = JSON.parse(raw);
+      return data.data?.[0] ?? null;
+    } catch { return null; }
+  }
+
+  /** Flat container returns actual published versions (updates faster than search). */
+  #fetchVersions(id) {
+    try {
+      const url = `https://api.nuget.org/v3-flatcontainer/${id.toLowerCase()}/index.json`;
+      const raw = execSync(`curl -sf "${url}"`, { encoding: "utf8", timeout: 15_000 });
+      return JSON.parse(raw).versions ?? [];
+    } catch { return []; }
+  }
+
+  #classify(pkg, meta, tags, releases, flatVersions) {
+    const findings = [];
+
+    if (!meta) {
+      findings.push({ severity: "RED", code: "nuget-unreachable", msg: `Cannot reach ${pkg.name} on NuGet` });
+      return findings;
+    }
+
+    const searchVer = meta.version;
+    const latestFlat = flatVersions.length > 0 ? flatVersions[flatVersions.length - 1] : null;
+
+    // Detect indexing lag: flat container knows about a newer version than the search API
+    const indexingLag = latestFlat && latestFlat !== searchVer;
+    const ver = latestFlat ?? searchVer;
+    const tagName = `v${ver}`;
+
+    // Published-but-not-tagged
+    if (!tags.includes(tagName)) {
+      findings.push({ severity: "RED", code: "published-not-tagged", msg: `${pkg.name}@${ver} — no git tag ${tagName}` });
+    }
+
+    // ProjectUrl — suppress during indexing lag (metadata not propagated yet)
+    if (!meta.projectUrl && !indexingLag) {
+      if (pkg.audience === "front-door") {
+        findings.push({ severity: "YELLOW", code: "missing-project-url", msg: `${pkg.name} has no projectUrl on NuGet` });
+      }
+    }
+
+    // Icon — suppress during indexing lag
+    if (!meta.iconUrl && pkg.audience === "front-door" && !indexingLag) {
+      findings.push({ severity: "YELLOW", code: "missing-icon", msg: `${pkg.name} (front-door) has no icon` });
+    }
+
+    // Indexing lag notice (non-failing)
+    if (indexingLag) {
+      findings.push({
+        severity: "INFO",
+        code: "pending-index",
+        msg: `${pkg.name} v${latestFlat} published but search API still shows v${searchVer} — retry in 60-120 min`
+      });
+    }
+
+    // Description
+    if (!meta.description) {
+      findings.push({ severity: "GRAY", code: "missing-description", msg: `${pkg.name} has no description` });
+    }
+
+    return findings;
+  }
+
+  receipt(result) {
+    const [owner, name] = result.repo.split("/");
+    return {
+      schemaVersion: "1.0.0",
+      repo: { owner, name },
+      target: "nuget",
+      version: result.version,
+      packageName: result.name,
+      commitSha: result.commitSha,
+      timestamp: new Date().toISOString(),
+      artifacts: result.artifacts ?? [],
+    };
+  }
+}

package/scripts/lib/providers/pypi.mjs

@@ -0,0 +1,102 @@
+/**
+ * PyPI provider — audits Python packages on pypi.org.
+ *
+ * Uses the PyPI JSON API: https://pypi.org/pypi/<pkg>/json
+ */
+
+import { execSync } from "node:child_process";
+import { Provider } from "../provider.mjs";
+
+export default class PyPIProvider extends Provider {
+  get name() { return "pypi"; }
+
+  detect(entry) {
+    return entry.ecosystem === "pypi";
+  }
+
+  async audit(entry, ctx) {
+    const meta = this.#fetchMeta(entry.name);
+    const tags = ctx.tags.get(entry.repo) ?? [];
+    const releases = ctx.releases.get(entry.repo) ?? [];
+
+    if (!meta) {
+      return {
+        version: "?",
+        findings: [{ severity: "RED", code: "pypi-unreachable", msg: `Cannot reach ${entry.name} on PyPI` }],
+      };
+    }
+
+    const version = meta.info?.version ?? "?";
+    const findings = this.#classify(entry, meta, version, tags, releases);
+    return { version, findings };
+  }
+
+  // ─── Private ───────────────────────────────────────────────────────────────
+
+  #fetchMeta(pkg) {
+    try {
+      const url = `https://pypi.org/pypi/${pkg}/json`;
+      const raw = execSync(`curl -sf "${url}"`, { encoding: "utf8", timeout: 15_000 });
+      return JSON.parse(raw);
+    } catch { return null; }
+  }
+
+  #classify(entry, meta, version, tags, releases) {
+    const findings = [];
+    const tagName = `v${version}`;
+
+    // Published-but-not-tagged (RED)
+    if (!tags.includes(tagName)) {
+      findings.push({
+        severity: "RED",
+        code: "published-not-tagged",
+        msg: `${entry.name}@${version} — no git tag ${tagName}`,
+      });
+    }
+
+    // Tagged-but-not-released (YELLOW for front-door)
+    if (tags.includes(tagName) && !releases.includes(tagName) && entry.audience === "front-door") {
+      findings.push({
+        severity: "YELLOW",
+        code: "tagged-not-released",
+        msg: `${entry.name} tag ${tagName} has no GitHub Release`,
+      });
+    }
+
+    // Description / summary
+    const summary = meta.info?.summary ?? "";
+    if (!summary) {
+      findings.push({
+        severity: entry.audience === "front-door" ? "YELLOW" : "GRAY",
+        code: "missing-description",
+        msg: `${entry.name} has no summary on PyPI`,
+      });
+    }
+
+    // Homepage / project URL
+    const projectUrl = meta.info?.home_page || meta.info?.project_urls?.Homepage || "";
+    if (!projectUrl) {
+      findings.push({
+        severity: "GRAY",
+        code: "missing-homepage",
+        msg: `${entry.name} has no homepage on PyPI`,
+      });
+    }
+
+    return findings;
+  }
+
+  receipt(result) {
+    const [owner, name] = result.repo.split("/");
+    return {
+      schemaVersion: "1.0.0",
+      repo: { owner, name },
+      target: "pypi",
+      version: result.version,
+      packageName: result.name,
+      commitSha: result.commitSha,
+      timestamp: new Date().toISOString(),
+      artifacts: result.artifacts ?? [],
+    };
+  }
+}

package/scripts/lib/receipt-writer.mjs

@@ -0,0 +1,123 @@
+/**
+ * Receipt writer — validates and persists publish receipts.
+ *
+ * Receipts are immutable once written (append-only directory).
+ * Path: receipts/publish/<owner>--<name>/<target>/<version>.json
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..", "..");
+
+const VALID_TARGETS = ["npm", "nuget", "pypi", "ghcr"];
+
+/**
+ * Validate receipt data against the receipt schema (lightweight, no Ajv).
+ * @param {object} receipt
+ * @throws {Error} on validation failure
+ */
+export function validate(receipt) {
+  if (!receipt || typeof receipt !== "object") throw new Error("Receipt must be an object");
+
+  // Required top-level fields
+  const required = ["schemaVersion", "repo", "target", "version", "packageName", "commitSha", "timestamp", "artifacts"];
+  for (const field of required) {
+    if (!(field in receipt)) throw new Error(`Receipt missing required field: ${field}`);
+  }
+
+  // schemaVersion
+  if (receipt.schemaVersion !== "1.0.0") {
+    throw new Error(`Unknown schemaVersion: ${receipt.schemaVersion}`);
+  }
+
+  // repo
+  if (typeof receipt.repo !== "object" || !receipt.repo.owner || !receipt.repo.name) {
+    throw new Error("repo must have owner and name");
+  }
+
+  // target
+  if (!VALID_TARGETS.includes(receipt.target)) {
+    throw new Error(`Invalid target: ${receipt.target} (expected one of ${VALID_TARGETS.join(", ")})`);
+  }
+
+  // version
+  if (typeof receipt.version !== "string" || !receipt.version) {
+    throw new Error("version must be a non-empty string");
+  }
+
+  // packageName
+  if (typeof receipt.packageName !== "string" || !receipt.packageName) {
+    throw new Error("packageName must be a non-empty string");
+  }
+
+  // commitSha — 40 hex chars
+  if (typeof receipt.commitSha !== "string" || !/^[0-9a-f]{40}$/.test(receipt.commitSha)) {
+    throw new Error("commitSha must be a 40-character lowercase hex string");
+  }
+
+  // timestamp — ISO 8601
+  if (typeof receipt.timestamp !== "string" || !receipt.timestamp) {
+    throw new Error("timestamp must be a non-empty string");
+  }
+
+  // artifacts
+  if (!Array.isArray(receipt.artifacts)) {
+    throw new Error("artifacts must be an array");
+  }
+  for (const art of receipt.artifacts) {
+    if (!art.name || typeof art.name !== "string") throw new Error("artifact.name required");
+    if (typeof art.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(art.sha256)) {
+      throw new Error(`Invalid artifact sha256: ${art.sha256}`);
+    }
+    if (typeof art.size !== "number" || art.size < 0 || !Number.isInteger(art.size)) {
+      throw new Error(`Invalid artifact size: ${art.size}`);
+    }
+    if (!art.url || typeof art.url !== "string") throw new Error("artifact.url required");
+  }
+}
+
+/**
+ * Build the filesystem path for a receipt.
+ * @param {object} receipt
+ * @returns {string} Absolute path
+ */
+function receiptPath(receipt) {
+  const slug = `${receipt.repo.owner}--${receipt.repo.name}`;
+  return join(ROOT, "receipts", "publish", slug, receipt.target, `${receipt.version}.json`);
+}
+
+/**
+ * Write a receipt to the immutable store.
+ * @param {object} receipt - Validated receipt data
+ * @returns {string} Absolute path of written receipt
+ * @throws {Error} if receipt already exists (immutability) or validation fails
+ */
+export function write(receipt) {
+  validate(receipt);
+
+  const filePath = receiptPath(receipt);
+
+  if (existsSync(filePath)) {
+    throw new Error(`Receipt already exists (immutable): ${filePath}`);
+  }
+
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(receipt, null, 2) + "\n");
+  return filePath;
+}
+
+/**
+ * Read an existing receipt.
+ * @param {string} repoSlug - "owner--name"
+ * @param {string} target   - "npm" | "nuget" | "pypi" | "ghcr"
+ * @param {string} version
+ * @returns {object|null}
+ */
+export function read(repoSlug, target, version) {
+  const filePath = join(ROOT, "receipts", "publish", repoSlug, target, `${version}.json`);
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}

package/scripts/lib/registry.mjs

@@ -0,0 +1,65 @@
+/**
+ * Provider registry — auto-discovers and validates providers.
+ *
+ * Scans scripts/lib/providers/*.mjs, imports each default export,
+ * and validates it extends Provider with required method overrides.
+ */
+
+import { readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Provider } from "./provider.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROVIDERS_DIR = join(__dirname, "providers");
+
+const REQUIRED_METHODS = ["detect", "audit"];
+
+/**
+ * Dynamically import all .mjs files from providers/ directory.
+ * Each must export default a class extending Provider.
+ * @returns {Promise<Provider[]>}
+ */
+export async function loadProviders() {
+  const files = readdirSync(PROVIDERS_DIR).filter(f => f.endsWith(".mjs"));
+  const providers = [];
+
+  for (const file of files) {
+    const filePath = join(PROVIDERS_DIR, file);
+    const fileUrl = pathToFileURL(filePath).href;
+    const mod = await import(fileUrl);
+    const Ctor = mod.default;
+
+    if (!Ctor || typeof Ctor !== "function") {
+      throw new Error(`${file}: default export must be a class`);
+    }
+
+    // Verify it extends Provider
+    if (!(Ctor.prototype instanceof Provider)) {
+      throw new Error(`${file}: default export must extend Provider`);
+    }
+
+    const instance = new Ctor();
+
+    // Validate required methods are overridden (not the base class stubs)
+    for (const method of REQUIRED_METHODS) {
+      if (instance[method] === Provider.prototype[method]) {
+        throw new Error(`${file}: must override ${method}()`);
+      }
+    }
+
+    providers.push(instance);
+  }
+
+  return providers;
+}
+
+/**
+ * Given an entry, return the providers that claim it via detect().
+ * @param {Provider[]} providers
+ * @param {object} entry
+ * @returns {Provider[]}
+ */
+export function matchProviders(providers, entry) {
+  return providers.filter(p => p.detect(entry));
+}

package/scripts/lib/shell.mjs

@@ -0,0 +1,64 @@
+/**
+ * Shell utilities for publish providers.
+ * Zero dependencies — uses node:child_process, node:crypto, node:fs.
+ */
+
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+
+/**
+ * Execute a command and capture output.
+ * Does NOT throw on non-zero exit — caller decides what to do.
+ *
+ * @param {string} cmd - Shell command to run
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] - Working directory
+ * @param {number} [opts.timeout] - Timeout in ms (default 120s)
+ * @param {object} [opts.env] - Extra environment variables (merged with process.env)
+ * @returns {{ stdout: string, stderr: string, exitCode: number }}
+ */
+export function exec(cmd, opts = {}) {
+  try {
+    const stdout = execSync(cmd, {
+      encoding: "utf8",
+      timeout: opts.timeout ?? 120_000,
+      cwd: opts.cwd,
+      env: opts.env ? { ...process.env, ...opts.env } : process.env,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { stdout, stderr: "", exitCode: 0 };
+  } catch (e) {
+    return {
+      stdout: e.stdout ?? "",
+      stderr: e.stderr ?? e.message,
+      exitCode: e.status ?? 1,
+    };
+  }
+}
+
+/**
+ * Compute SHA-256 hash and size of a file.
+ *
+ * @param {string} filePath - Absolute path to file
+ * @returns {{ sha256: string, size: number }}
+ */
+export function hashFile(filePath) {
+  const data = readFileSync(filePath);
+  const sha256 = createHash("sha256").update(data).digest("hex");
+  const { size } = statSync(filePath);
+  return { sha256, size };
+}
+
+/**
+ * Get the current HEAD commit SHA (40 lowercase hex chars).
+ *
+ * @param {string} [cwd] - Working directory (defaults to process.cwd())
+ * @returns {string}
+ * @throws {Error} if not in a git repo
+ */
+export function getCommitSha(cwd) {
+  const { stdout, exitCode } = exec("git rev-parse HEAD", { cwd });
+  if (exitCode !== 0) throw new Error("Not in a git repo or git not available");
+  return stdout.trim();
+}

package/src/cli/exit-codes.mjs

@@ -0,0 +1,17 @@
+/**
+ * Named exit codes for CI-friendly CLI behavior.
+ *
+ *   0 — success
+ *   1 — reserved for uncaught exceptions (Node default)
+ *   2 — drift found (audit found RED-severity issues)
+ *   3 — config or schema error
+ *   4 — missing credentials for a requested operation
+ *   5 — one or more publishes failed
+ */
+export const EXIT = {
+  SUCCESS: 0,
+  DRIFT_FOUND: 2,
+  CONFIG_ERROR: 3,
+  MISSING_CREDENTIALS: 4,
+  PUBLISH_FAILURE: 5,
+};

package/src/cli/help.mjs

@@ -0,0 +1,38 @@
+/**
+ * Help text for the mcpt-publishing CLI.
+ */
+
+export const GLOBAL_HELP = `
+mcpt-publishing — A human-first publishing house for your repos.
+
+Usage:
+  mcpt-publishing <command> [flags]
+
+Commands:
+  audit           Run publishing health audit across all registries
+  init            Scaffold publishing.config.json and starter manifest
+  publish         Publish packages to registries with receipts
+  providers       List registered providers and their status
+  verify-receipt  Validate a receipt file (schema + integrity)
+  plan            Dry-run publish plan [coming soon]
+
+Global flags:
+  --help      Show help for a command
+  --version   Show version
+  --json      Machine-readable output (supported by all commands)
+
+Examples:
+  mcpt-publishing audit                          # audit all packages
+  mcpt-publishing audit --json                   # JSON output to stdout
+  mcpt-publishing publish --target npm --dry-run # dry-run npm publish
+  mcpt-publishing verify-receipt receipts/audit/2026-02-17.json
+  mcpt-publishing providers                      # list providers + env vars
+
+Environment:
+  PUBLISHING_CONFIG   Path to publishing.config.json (overrides walk-up discovery)
+  GH_TOKEN            GitHub token for API access (tags, releases, issues)
+  NPM_TOKEN           npm publish token (granular, publish rights)
+  NUGET_API_KEY       NuGet API key
+
+Docs: https://github.com/mcp-tool-shop/mcpt-publishing
+`.trim();