@mcptoolshop/mcpt-publishing 1.0.0

package/schemas/receipt.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mcp-tool-shop/mcpt-publishing/schemas/receipt.schema.json",
+  "title": "Publish Receipt",
+  "description": "Immutable record of a publish event.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "repo",
+    "target",
+    "version",
+    "packageName",
+    "commitSha",
+    "timestamp",
+    "artifacts"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0.0",
+      "description": "Receipt schema version"
+    },
+    "repo": {
+      "type": "object",
+      "required": ["owner", "name"],
+      "additionalProperties": false,
+      "properties": {
+        "owner": { "type": "string" },
+        "name": { "type": "string" }
+      }
+    },
+    "target": {
+      "type": "string",
+      "enum": ["npm", "nuget", "pypi", "ghcr"],
+      "description": "Registry this was published to"
+    },
+    "version": {
+      "type": "string",
+      "description": "Published version string (e.g. 1.0.0)"
+    },
+    "packageName": {
+      "type": "string",
+      "description": "Package name as it appears on the registry"
+    },
+    "commitSha": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$",
+      "description": "Full 40-char commit SHA at time of publish"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of publish event"
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "sha256", "size", "url"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Artifact filename (e.g. mcpt-1.0.1.tgz)"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$",
+            "description": "SHA-256 hash of the artifact"
+          },
+          "size": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Size in bytes"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Direct URL to the artifact on the registry"
+          }
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional provider-specific metadata",
+      "additionalProperties": true
+    }
+  }
+}

package/scripts/lib/github-glue.mjs

@@ -0,0 +1,101 @@
+/**
+ * GitHub Glue — connects receipts to GitHub Releases and the health issue.
+ *
+ * - attachReceiptToRelease() uploads receipt JSON as a release asset
+ * - updateHealthIssueWithReceipts() appends "Recent Receipts" to the pinned issue
+ */
+
+import { execSync } from "node:child_process";
+import { writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+/**
+ * Upload a receipt JSON file as a GitHub Release asset.
+ * @param {string} repo        - "owner/name"
+ * @param {string} tagName     - e.g. "v1.0.0"
+ * @param {string} receiptPath - absolute path to the receipt JSON file
+ * @returns {{ success: boolean, url?: string, error?: string }}
+ */
+export function attachReceiptToRelease(repo, tagName, receiptPath) {
+  try {
+    // Verify the release exists
+    execSync(
+      `gh api repos/${repo}/releases/tags/${tagName} --jq ".id"`,
+      { encoding: "utf8", timeout: 15_000, stdio: ["pipe", "pipe", "pipe"] }
+    );
+
+    // Upload receipt as asset (--clobber overwrites if already attached)
+    execSync(
+      `gh release upload ${tagName} "${receiptPath}" --repo ${repo} --clobber`,
+      { encoding: "utf8", timeout: 30_000, stdio: ["pipe", "pipe", "pipe"] }
+    );
+
+    return { success: true, url: `https://github.com/${repo}/releases/tag/${tagName}` };
+  } catch (e) {
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Update the pinned "Publishing Health" issue to include receipt links.
+ * Appends or replaces a "Recent Receipts" section in the issue body.
+ * @param {string} repo     - The mcpt-publishing repo
+ * @param {Array<{target: string, version: string, packageName: string, releaseUrl: string}>} receipts
+ */
+export function updateHealthIssueWithReceipts(repo, receipts) {
+  try {
+    // Find the pinned health issue
+    const issueNum = execSync(
+      `gh issue list --repo "${repo}" --search "in:title Publishing Health" --state open --json number --jq ".[0].number"`,
+      { encoding: "utf8", timeout: 15_000, stdio: ["pipe", "pipe", "pipe"] }
+    ).trim();
+
+    if (!issueNum) {
+      process.stderr.write("Warning: no 'Publishing Health' issue found\n");
+      return;
+    }
+
+    // Get current body
+    const body = execSync(
+      `gh issue view ${issueNum} --repo "${repo}" --json body --jq ".body"`,
+      { encoding: "utf8", timeout: 15_000, stdio: ["pipe", "pipe", "pipe"] }
+    );
+
+    // Build receipt links section
+    const receiptLines = receipts.map(r =>
+      `- **${r.target}** ${r.packageName}@${r.version} — [release](${r.releaseUrl})`
+    );
+
+    const receiptSection = [
+      "",
+      "### Recent Receipts",
+      ...receiptLines,
+      "",
+    ].join("\n");
+
+    // Replace existing receipt section or append
+    let newBody;
+    if (body.includes("### Recent Receipts")) {
+      newBody = body.replace(
+        /### Recent Receipts[\s\S]*?(?=\n###|\n---|\n## |$)/,
+        receiptSection.trim() + "\n"
+      );
+    } else {
+      newBody = body.trimEnd() + "\n" + receiptSection;
+    }
+
+    // Write to temp file to avoid shell escaping issues
+    const tmpFile = join(tmpdir(), `health-issue-${Date.now()}.md`);
+    writeFileSync(tmpFile, newBody);
+
+    execSync(
+      `gh issue edit ${issueNum} --repo "${repo}" --body-file "${tmpFile}"`,
+      { encoding: "utf8", timeout: 15_000, stdio: ["pipe", "pipe", "pipe"] }
+    );
+
+    unlinkSync(tmpFile);
+  } catch (e) {
+    process.stderr.write(`Warning: failed to update health issue: ${e.message}\n`);
+  }
+}

package/scripts/lib/provider.mjs

@@ -0,0 +1,63 @@
+/**
+ * Base class for registry providers.
+ *
+ * Every provider must extend this and override at least:
+ *   - get name()
+ *   - detect(entry)
+ *   - audit(entry, ctx)
+ *
+ * publish() and receipt() are optional stubs for future use.
+ */
+export class Provider {
+  /** Machine-readable name (e.g. "npm", "nuget", "pypi", "ghcr", "github") */
+  get name() {
+    throw new Error("Provider must define get name()");
+  }
+
+  /**
+   * Does this provider apply to the given manifest entry?
+   * @param {object} entry - { name, repo, audience, ecosystem }
+   * @returns {boolean}
+   */
+  detect(entry) {
+    throw new Error("not implemented");
+  }
+
+  /**
+   * Audit a single package. Returns version + findings.
+   * @param {object} entry - Manifest entry
+   * @param {object} ctx   - Shared context { tags: Map, releases: Map }
+   * @returns {Promise<{ version: string|null, findings: Array<{severity, code, msg}> }>}
+   */
+  async audit(entry, ctx) {
+    throw new Error("not implemented");
+  }
+
+  /**
+   * Plan a publish (dry-run). Override when publish support is added.
+   * @param {object} entry
+   * @returns {Promise<{ actions: string[] }>}
+   */
+  async plan(entry) {
+    return { actions: [] };
+  }
+
+  /**
+   * Execute a publish. Override when publish support is added.
+   * @param {object} entry
+   * @param {object} opts - { dryRun: boolean, version: string }
+   * @returns {Promise<{ success: boolean, version: string, artifacts: object[] }>}
+   */
+  async publish(entry, opts) {
+    throw new Error("not implemented");
+  }
+
+  /**
+   * Transform a publish result into a receipt object.
+   * @param {object} result - Output from publish()
+   * @returns {object} Receipt data conforming to receipt.schema.json
+   */
+  receipt(result) {
+    throw new Error("not implemented");
+  }
+}

package/scripts/lib/providers/ghcr.mjs

@@ -0,0 +1,112 @@
+/**
+ * GHCR provider — audits container images on GitHub Container Registry.
+ *
+ * Uses `gh api` to query package versions via the GitHub Packages API.
+ */
+
+import { execSync } from "node:child_process";
+import { Provider } from "../provider.mjs";
+
+export default class GhcrProvider extends Provider {
+  get name() { return "ghcr"; }
+
+  detect(entry) {
+    return entry.ecosystem === "ghcr";
+  }
+
+  async audit(entry, ctx) {
+    const tags = ctx.tags.get(entry.repo) ?? [];
+    const releases = ctx.releases.get(entry.repo) ?? [];
+    const versions = this.#fetchVersions(entry.repo, entry.name);
+
+    if (!versions) {
+      return {
+        version: "?",
+        findings: [{ severity: "RED", code: "ghcr-unreachable", msg: `Cannot reach ${entry.name} on ghcr.io` }],
+      };
+    }
+
+    if (versions.length === 0) {
+      return {
+        version: "?",
+        findings: [{ severity: "RED", code: "ghcr-no-versions", msg: `${entry.name} has no versions on ghcr.io` }],
+      };
+    }
+
+    // API returns newest first — extract the latest tagged version
+    const latest = versions[0];
+    const containerTags = latest?.metadata?.container?.tags ?? [];
+    const version = containerTags.find(t => /^\d/.test(t)) ?? containerTags[0] ?? "?";
+    const findings = this.#classify(entry, version, tags, releases);
+
+    return { version, findings };
+  }
+
+  // ─── Private ───────────────────────────────────────────────────────────────
+
+  #fetchVersions(repo, pkg) {
+    const owner = repo.split("/")[0];
+
+    // Try org-level endpoint first
+    try {
+      const endpoint = `/orgs/${owner}/packages/container/${encodeURIComponent(pkg)}/versions`;
+      const raw = execSync(
+        `gh api "${endpoint}" --jq "." 2>&1`,
+        { encoding: "utf8", timeout: 15_000 }
+      );
+      return JSON.parse(raw);
+    } catch {
+      // Fall back to user-level endpoint
+      try {
+        const endpoint = `/users/${owner}/packages/container/${encodeURIComponent(pkg)}/versions`;
+        const raw = execSync(
+          `gh api "${endpoint}" --jq "." 2>&1`,
+          { encoding: "utf8", timeout: 15_000 }
+        );
+        return JSON.parse(raw);
+      } catch { return null; }
+    }
+  }
+
+  #classify(entry, version, tags, releases) {
+    const findings = [];
+
+    if (version === "?") return findings;
+
+    const tagName = `v${version}`;
+
+    // Image exists but no matching git tag (RED)
+    if (!tags.includes(tagName)) {
+      findings.push({
+        severity: "RED",
+        code: "published-not-tagged",
+        msg: `${entry.name} image tagged ${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`,
+      });
+    }
+
+    return findings;
+  }
+
+  receipt(result) {
+    const [owner, name] = result.repo.split("/");
+    return {
+      schemaVersion: "1.0.0",
+      repo: { owner, name },
+      target: "ghcr",
+      version: result.version,
+      packageName: result.name,
+      commitSha: result.commitSha,
+      timestamp: new Date().toISOString(),
+      artifacts: result.artifacts ?? [],
+    };
+  }
+}

package/scripts/lib/providers/github.mjs

@@ -0,0 +1,52 @@
+/**
+ * GitHub provider — context loader for tags and releases.
+ *
+ * This provider doesn't produce its own findings. Its job is to populate
+ * ctx.tags and ctx.releases so that ecosystem providers (npm, nuget, etc.)
+ * can check for drift between registry and git state.
+ */
+
+import { execSync } from "node:child_process";
+import { Provider } from "../provider.mjs";
+
+export default class GitHubProvider extends Provider {
+  get name() { return "github"; }
+
+  detect(entry) {
+    return !!entry.repo;
+  }
+
+  async audit(entry, ctx) {
+    const repo = entry.repo;
+
+    if (!ctx.tags.has(repo)) {
+      ctx.tags.set(repo, this.#fetchTags(repo));
+    }
+    if (!ctx.releases.has(repo)) {
+      ctx.releases.set(repo, this.#fetchReleases(repo));
+    }
+
+    // No findings — this is a context loader
+    return { version: null, findings: [] };
+  }
+
+  #fetchTags(repo) {
+    try {
+      const raw = execSync(
+        `gh api repos/${repo}/tags --jq ".[].name" 2>&1`,
+        { encoding: "utf8", timeout: 15_000 }
+      );
+      return raw.trim().split("\n").filter(Boolean);
+    } catch { return []; }
+  }
+
+  #fetchReleases(repo) {
+    try {
+      const raw = execSync(
+        `gh api repos/${repo}/releases --jq ".[].tag_name" 2>&1`,
+        { encoding: "utf8", timeout: 15_000 }
+      );
+      return raw.trim().split("\n").filter(Boolean);
+    } catch { return []; }
+  }
+}

package/scripts/lib/providers/npm.mjs

@@ -0,0 +1,100 @@
+/**
+ * npm provider — extracted from audit.mjs.
+ *
+ * Fetches metadata via `npm view` and classifies drift against git state.
+ */
+
+import { execSync } from "node:child_process";
+import { Provider } from "../provider.mjs";
+
+export default class NpmProvider extends Provider {
+  get name() { return "npm"; }
+
+  detect(entry) {
+    return entry.ecosystem === "npm";
+  }
+
+  async audit(entry, ctx) {
+    const meta = this.#fetchMeta(entry.name);
+    const tags = ctx.tags.get(entry.repo) ?? [];
+    const releases = ctx.releases.get(entry.repo) ?? [];
+
+    const version = meta?.["dist-tags"]?.latest ?? meta?.version ?? "?";
+    const findings = this.#classify(entry, meta, tags, releases);
+
+    return { version, findings };
+  }
+
+  // ─── Private ───────────────────────────────────────────────────────────────
+
+  #fetchMeta(pkg) {
+    try {
+      const raw = execSync(`npm view ${pkg} --json 2>&1`, { encoding: "utf8", timeout: 15_000 });
+      return JSON.parse(raw);
+    } catch { return null; }
+  }
+
+  #classify(pkg, meta, tags, releases) {
+    const findings = [];
+
+    if (!meta) {
+      findings.push({ severity: "RED", code: "npm-unreachable", msg: `Cannot reach ${pkg.name} on npm` });
+      return findings;
+    }
+
+    const ver = meta["dist-tags"]?.latest ?? meta.version;
+    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}` });
+    }
+
+    // Tagged-but-not-released
+    if (tags.includes(tagName) && !releases.includes(tagName) && pkg.audience === "front-door") {
+      findings.push({ severity: "YELLOW", code: "tagged-not-released", msg: `${pkg.name} tag ${tagName} has no GitHub Release` });
+    }
+
+    // Repo URL check
+    const repoUrl = meta.repository?.url ?? "";
+    if (!repoUrl.includes(pkg.repo.split("/")[0])) {
+      findings.push({ severity: "RED", code: "wrong-repo-url", msg: `${pkg.name} repo URL "${repoUrl}" doesn't match expected ${pkg.repo}` });
+    }
+
+    // Description
+    const desc = meta.description ?? "";
+    if (!desc || desc.startsWith("<") || desc.includes("<img")) {
+      findings.push({ severity: "RED", code: "bad-description", msg: `${pkg.name} has missing/HTML description` });
+    }
+
+    // README
+    if (meta.readme === "ERROR: No README data found!" || meta.readme === "") {
+      if (pkg.audience === "front-door") {
+        findings.push({ severity: "YELLOW", code: "missing-readme", msg: `${pkg.name} has no README on npm` });
+      } else {
+        findings.push({ severity: "GRAY", code: "missing-readme", msg: `${pkg.name} (internal) has no README on npm` });
+      }
+    }
+
+    // Homepage
+    if (!meta.homepage) {
+      findings.push({ severity: "GRAY", code: "missing-homepage", msg: `${pkg.name} has no homepage` });
+    }
+
+    return findings;
+  }
+
+  receipt(result) {
+    const [owner, name] = result.repo.split("/");
+    return {
+      schemaVersion: "1.0.0",
+      repo: { owner, name },
+      target: "npm",
+      version: result.version,
+      packageName: result.name,
+      commitSha: result.commitSha,
+      timestamp: new Date().toISOString(),
+      artifacts: result.artifacts ?? [],
+    };
+  }
+}

package/scripts/lib/providers/nuget.mjs

@@ -0,0 +1,115 @@
+/**
+ * NuGet provider — extracted from audit.mjs.
+ *
+ * Fetches metadata via NuGet search API + flat-container,
+ * detects indexing lag, and classifies drift against git state.
+ */
+
+import { execSync } from "node:child_process";
+import { Provider } from "../provider.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 };
+  }
+
+  // ─── 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 ?? [],
+    };
+  }
+}