@mcptoolshop/mcpt-publishing 0.2.0

package/src/cli/router.mjs

@@ -0,0 +1,121 @@
+/**
+ * CLI router — zero-dependency subcommand parser and dispatcher.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { GLOBAL_HELP } from "./help.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Lazy-loaded command map. Keys are subcommand names. */
+const COMMANDS = {
+  audit:            () => import("../commands/audit.mjs"),
+  init:             () => import("../commands/init.mjs"),
+  plan:             () => import("../commands/plan.mjs"),
+  publish:          () => import("../commands/publish.mjs"),
+  providers:        () => import("../commands/providers.mjs"),
+  "verify-receipt": () => import("../commands/verify-receipt.mjs"),
+};
+
+/**
+ * Parse CLI flags from an argv slice (after the subcommand).
+ *
+ *   --flag        → { flag: true }
+ *   --key value   → { key: "value" }
+ *   bare          → pushed to _positionals
+ *
+ * @param {string[]} args
+ * @returns {object}
+ */
+export function parseFlags(args) {
+  const flags = { _positionals: [] };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--") {
+      flags._positionals.push(...args.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (!next || next.startsWith("--")) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      // Short flag aliases
+      const SHORT = { h: "help", v: "version", j: "json" };
+      const expanded = SHORT[arg[1]];
+      if (expanded) flags[expanded] = true;
+      else flags._positionals.push(arg);
+    } else {
+      flags._positionals.push(arg);
+    }
+  }
+  return flags;
+}
+
+/**
+ * Main entry point — parse argv and dispatch to the matching command.
+ * @param {string[]} argv - process.argv
+ */
+export async function run(argv) {
+  const args = argv.slice(2);
+  const subcommand = args[0];
+
+  // --help / -h at global level (before subcommand lookup)
+  if (args.includes("--help") || args.includes("-h")) {
+    // If a valid subcommand precedes --help, show per-command help
+    if (subcommand && COMMANDS[subcommand]) {
+      // handled below after flag parsing
+    } else {
+      process.stdout.write(GLOBAL_HELP + "\n");
+      process.exit(0);
+    }
+  }
+
+  // --version at global level
+  if (args.includes("--version") || args.includes("-v")) {
+    const pkgPath = join(__dirname, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    process.stdout.write(pkg.version + "\n");
+    process.exit(0);
+  }
+
+  // No subcommand or unknown → global help
+  if (!subcommand || !COMMANDS[subcommand]) {
+    if (subcommand && !subcommand.startsWith("-") && !COMMANDS[subcommand]) {
+      process.stderr.write(`Unknown command: ${subcommand}\n\n`);
+    }
+    process.stdout.write(GLOBAL_HELP + "\n");
+    process.exit(!subcommand || subcommand.startsWith("-") ? 0 : 3);
+  }
+
+  // Parse flags after the subcommand
+  const flags = parseFlags(args.slice(1));
+
+  // Per-command help
+  if (flags.help) {
+    const mod = await COMMANDS[subcommand]();
+    if (mod.helpText) {
+      process.stdout.write(mod.helpText + "\n");
+    } else {
+      process.stdout.write(GLOBAL_HELP + "\n");
+    }
+    process.exit(0);
+  }
+
+  // Dispatch
+  try {
+    const mod = await COMMANDS[subcommand]();
+    const exitCode = await mod.execute(flags);
+    process.exit(exitCode ?? 0);
+  } catch (e) {
+    process.stderr.write(`Error: ${e.message}\n`);
+    process.exit(3);
+  }
+}

package/src/commands/audit.mjs

@@ -0,0 +1,238 @@
+/**
+ * `mcpt-publishing audit` — run publishing health audit across all registries.
+ *
+ * Loads config → reads manifest → imports providers from scripts/lib/registry.mjs
+ * → runs orchestration loop → writes reports → emits audit receipt.
+ *
+ * Exit codes:
+ *   0 — all clean
+ *   2 — RED-severity drift found
+ *   3 — config or file error
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { loadConfig } from "../config/loader.mjs";
+import { emitAuditReceipt } from "../receipts/audit-receipt.mjs";
+import { EXIT } from "../cli/exit-codes.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Ecosystem labels for markdown headings
+const ECOSYSTEM_LABELS = {
+  npm: "npm",
+  nuget: "NuGet",
+  pypi: "PyPI",
+  ghcr: "GHCR",
+};
+
+export const helpText = `
+mcpt-publishing audit — Run publishing health audit.
+
+Usage:
+  mcpt-publishing audit [flags]
+
+Flags:
+  --json        Output JSON to stdout (skip markdown reports)
+  --config      Explicit path to publishing.config.json
+  --help        Show this help
+
+Exit codes:
+  0   All packages clean
+  2   RED-severity drift detected (CI-friendly non-zero)
+
+Examples:
+  mcpt-publishing audit              # writes reports/latest.md + .json
+  mcpt-publishing audit --json       # JSON to stdout only
+`.trim();
+
+/**
+ * Execute the audit command.
+ * @param {object} flags - Parsed CLI flags
+ * @returns {number} Exit code
+ */
+export async function execute(flags) {
+  // Load config
+  const config = flags.config
+    ? loadConfig(dirname(flags.config))
+    : loadConfig();
+
+  // 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"));
+
+  // Import provider registry from scripts/lib (reuse existing working code)
+  const registryPath = join(__dirname, "..", "..", "scripts", "lib", "registry.mjs");
+  const registryUrl = pathToFileURL(registryPath).href;
+  const { loadProviders, matchProviders } = await import(registryUrl);
+
+  const providers = await loadProviders();
+
+  // Optional: filter by enabledProviders config
+  const enabled = config.enabledProviders ?? [];
+  const activeProviders = enabled.length > 0
+    ? providers.filter(p => enabled.includes(p.name))
+    : providers;
+
+  // Shared context for tag/release caching
+  const ctx = {
+    tags: new Map(),
+    releases: new Map(),
+  };
+
+  // Find the GitHub provider (context loader) — must run before ecosystem providers
+  const ghProvider = activeProviders.find(p => p.name === "github");
+
+  // Build results object with an array per ecosystem key present in the manifest
+  const results = {};
+  for (const key of Object.keys(manifest)) {
+    if (Array.isArray(manifest[key])) results[key] = [];
+  }
+  results.generated = new Date().toISOString();
+
+  const allFindings = [];
+
+  // Process each ecosystem section from the manifest
+  for (const [ecosystem, packages] of Object.entries(manifest)) {
+    if (!Array.isArray(packages)) continue;
+    process.stderr.write(`Auditing ${packages.length} ${ECOSYSTEM_LABELS[ecosystem] ?? ecosystem} packages...\n`);
+
+    for (const pkg of packages) {
+      const entry = { ...pkg, ecosystem };
+
+      // Ensure GitHub context (tags + releases) is loaded for this repo
+      if (ghProvider && ghProvider.detect(entry)) {
+        await ghProvider.audit(entry, ctx);
+      }
+
+      // Find the ecosystem-specific provider(s)
+      const ecosystemProviders = matchProviders(activeProviders, entry).filter(p => p.name !== "github");
+
+      let version = "?";
+      const findings = [];
+
+      for (const provider of ecosystemProviders) {
+        const result = await provider.audit(entry, ctx);
+        if (result.version && result.version !== "?") version = result.version;
+        findings.push(...result.findings);
+      }
+
+      const resultEntry = {
+        name: pkg.name,
+        version,
+        repo: pkg.repo,
+        audience: pkg.audience,
+        findings,
+      };
+
+      if (results[ecosystem]) {
+        results[ecosystem].push(resultEntry);
+      }
+      allFindings.push(...findings.map(f => ({ ...f, pkg: pkg.name, ecosystem })));
+    }
+  }
+
+  // Counts
+  const red = allFindings.filter(f => f.severity === "RED");
+  const yellow = allFindings.filter(f => f.severity === "YELLOW");
+  const gray = allFindings.filter(f => f.severity === "GRAY");
+  const info = allFindings.filter(f => f.severity === "INFO");
+  results.counts = { RED: red.length, YELLOW: yellow.length, GRAY: gray.length, INFO: info.length };
+
+  // Count total packages
+  let totalPackages = 0;
+  for (const [, val] of Object.entries(results)) {
+    if (Array.isArray(val)) totalPackages += val.length;
+  }
+  results.totalPackages = totalPackages;
+
+  // JSON-only mode
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(results, null, 2) + "\n");
+    emitAuditReceipt(config, results);
+    return red.length > 0 ? EXIT.DRIFT_FOUND : EXIT.SUCCESS;
+  }
+
+  // Generate markdown report
+  const md = buildMarkdownReport(results, manifest, allFindings, red, yellow, gray, info);
+
+  // Write reports
+  mkdirSync(config.reportsDir, { recursive: true });
+  writeFileSync(join(config.reportsDir, "latest.md"), md);
+  writeFileSync(join(config.reportsDir, "latest.json"), JSON.stringify(results, null, 2));
+
+  const infoSuffix = info.length > 0 ? ` INFO=${info.length} (indexing — retry later)` : "";
+  process.stderr.write(`\nDone. RED=${red.length} YELLOW=${yellow.length} GRAY=${gray.length}${infoSuffix}\n`);
+  process.stderr.write(`Reports written to ${config.reportsDir}/latest.md and latest.json\n`);
+
+  // Emit audit receipt
+  emitAuditReceipt(config, results);
+
+  return red.length > 0 ? EXIT.DRIFT_FOUND : EXIT.SUCCESS;
+}
+
+// ─── Internal ────────────────────────────────────────────────────────────────
+
+function buildMarkdownReport(results, manifest, allFindings, red, yellow, gray, info) {
+  const lines = [];
+  lines.push("# Publishing Health Report");
+  lines.push("");
+  lines.push(`> Generated: ${results.generated}`);
+  lines.push("");
+  const infoLabel = info.length > 0 ? ` | **INFO: ${info.length}** (indexing)` : "";
+  lines.push(`**RED: ${red.length}** | **YELLOW: ${yellow.length}** | **GRAY: ${gray.length}**${infoLabel}`);
+  lines.push("");
+
+  if (red.length + yellow.length + info.length > 0) {
+    lines.push("## Top Actions");
+    lines.push("");
+    for (const f of [...red, ...yellow, ...info].slice(0, 10)) {
+      lines.push(`- **${f.severity}** ${f.msg}`);
+    }
+    lines.push("");
+  }
+
+  // Group by package
+  const byRepo = {};
+  for (const f of allFindings) {
+    const key = f.pkg;
+    if (!byRepo[key]) byRepo[key] = [];
+    byRepo[key].push(f);
+  }
+
+  if (Object.keys(byRepo).length > 0) {
+    lines.push("## Findings by Package");
+    lines.push("");
+    for (const [pkg, findings] of Object.entries(byRepo)) {
+      lines.push(`### ${pkg}`);
+      for (const f of findings) {
+        lines.push(`- **${f.severity}** [${f.code}] ${f.msg}`);
+      }
+      lines.push("");
+    }
+  }
+
+  // Summary tables per ecosystem
+  for (const [ecosystem, packages] of Object.entries(manifest)) {
+    if (!Array.isArray(packages) || packages.length === 0) continue;
+    const label = ECOSYSTEM_LABELS[ecosystem] ?? ecosystem;
+
+    lines.push(`## ${label} Packages`);
+    lines.push("");
+    lines.push("| Package | Version | Audience | Issues |");
+    lines.push("|---------|---------|----------|--------|");
+    for (const e of results[ecosystem] ?? []) {
+      const issues = e.findings.length === 0 ? "clean" : e.findings.map(f => f.severity).join(", ");
+      lines.push(`| ${e.name} | ${e.version} | ${e.audience} | ${issues} |`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/commands/init.mjs

@@ -0,0 +1,107 @@
+/**
+ * `mcpt-publishing init` — scaffold publishing config and starter directories.
+ *
+ * Creates:
+ *   - publishing.config.json  (with $schema pointer)
+ *   - profiles/manifest.json  (empty skeleton)
+ *   - receipts/               (empty dir)
+ *   - reports/                (empty dir)
+ */
+
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { EXIT } from "../cli/exit-codes.mjs";
+
+export const helpText = `
+mcpt-publishing init — Scaffold publishing config in current directory.
+
+Usage:
+  mcpt-publishing init [flags]
+
+Flags:
+  --force       Overwrite existing publishing.config.json
+  --json        Output result as JSON
+  --help        Show this help
+
+Creates:
+  publishing.config.json   Configuration file with schema pointer
+  profiles/manifest.json   Empty package inventory
+  receipts/                Receipt output directory
+  reports/                 Report output directory
+`.trim();
+
+const STARTER_CONFIG = {
+  $schema: "https://github.com/mcp-tool-shop/mcpt-publishing/schemas/publishing-config.schema.json",
+  profilesDir: "profiles",
+  receiptsDir: "receipts",
+  reportsDir: "reports",
+  github: {
+    updateIssue: true,
+    attachReceipts: true,
+  },
+  enabledProviders: [],
+};
+
+const STARTER_MANIFEST = {
+  $comment: "Machine-readable inventory of all published packages. Source of truth for audit.",
+  npm: [],
+  nuget: [],
+  pypi: [],
+  ghcr: [],
+};
+
+/**
+ * Execute the init command.
+ * @param {object} flags - Parsed CLI flags
+ * @returns {number} Exit code
+ */
+export async function execute(flags) {
+  const cwd = process.cwd();
+  const configPath = join(cwd, "publishing.config.json");
+  const created = [];
+
+  // Config file
+  if (existsSync(configPath) && !flags.force) {
+    if (flags.json) {
+      process.stdout.write(JSON.stringify({ error: "publishing.config.json already exists. Use --force to overwrite." }) + "\n");
+    } else {
+      process.stderr.write(`publishing.config.json already exists. Use --force to overwrite.\n`);
+    }
+    return EXIT.CONFIG_ERROR;
+  }
+
+  writeFileSync(configPath, JSON.stringify(STARTER_CONFIG, null, 2) + "\n");
+  created.push("publishing.config.json");
+
+  // Profiles directory + manifest
+  const profilesDir = join(cwd, "profiles");
+  mkdirSync(profilesDir, { recursive: true });
+  const manifestPath = join(profilesDir, "manifest.json");
+  if (!existsSync(manifestPath) || flags.force) {
+    writeFileSync(manifestPath, JSON.stringify(STARTER_MANIFEST, null, 2) + "\n");
+    created.push("profiles/manifest.json");
+  }
+
+  // Receipts directory
+  const receiptsDir = join(cwd, "receipts");
+  mkdirSync(receiptsDir, { recursive: true });
+  created.push("receipts/");
+
+  // Reports directory
+  const reportsDir = join(cwd, "reports");
+  mkdirSync(reportsDir, { recursive: true });
+  created.push("reports/");
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ created, path: cwd }) + "\n");
+  } else {
+    process.stderr.write(`Initialized mcpt-publishing in ${cwd}\n`);
+    for (const f of created) {
+      process.stderr.write(`  + ${f}\n`);
+    }
+    process.stderr.write(`\nNext: edit profiles/manifest.json to add your packages, then run:\n`);
+    process.stderr.write(`  mcpt-publishing audit\n`);
+  }
+
+  return EXIT.SUCCESS;
+}

package/src/commands/plan.mjs

@@ -0,0 +1,36 @@
+/**
+ * `mcpt-publishing plan` — dry-run publish plan (stub).
+ *
+ * Future: compares manifest → registries → generates a publish plan
+ * showing what would be published, skipped, or blocked.
+ */
+
+import { EXIT } from "../cli/exit-codes.mjs";
+
+export const helpText = `
+mcpt-publishing plan — Generate a dry-run publish plan.
+
+Usage:
+  mcpt-publishing plan [flags]
+
+Flags:
+  --json        Output as JSON
+  --help        Show this help
+
+Status: Not yet implemented. Coming in a future release.
+`.trim();
+
+/**
+ * Execute the plan command (stub).
+ * @param {object} flags - Parsed CLI flags
+ * @returns {number} Exit code
+ */
+export async function execute(flags) {
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ status: "not_implemented", message: "Plan command is not yet implemented." }) + "\n");
+  } else {
+    process.stderr.write("Plan command is not yet implemented.\n");
+    process.stderr.write("This will generate a dry-run publish plan in a future release.\n");
+  }
+  return EXIT.SUCCESS;
+}

package/src/commands/providers.mjs

@@ -0,0 +1,81 @@
+/**
+ * `mcpt-publishing providers` — list registered providers and their status.
+ *
+ * Loads providers from scripts/lib/registry.mjs, optionally filters by
+ * enabledProviders config, and prints a summary table.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { loadConfig } from "../config/loader.mjs";
+import { EXIT } from "../cli/exit-codes.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const helpText = `
+mcpt-publishing providers — List registered providers.
+
+Usage:
+  mcpt-publishing providers [flags]
+
+Flags:
+  --json        Output as JSON array
+  --config      Explicit path to publishing.config.json
+  --help        Show this help
+
+Output:
+  Shows each provider name, supported ecosystems, and enabled/disabled status.
+`.trim();
+
+/**
+ * Execute the providers command.
+ * @param {object} flags - Parsed CLI flags
+ * @returns {number} Exit code
+ */
+export async function execute(flags) {
+  const config = flags.config
+    ? loadConfig(dirname(flags.config))
+    : loadConfig();
+
+  // Import provider registry from scripts/lib
+  const registryPath = join(__dirname, "..", "..", "scripts", "lib", "registry.mjs");
+  const registryUrl = pathToFileURL(registryPath).href;
+  const { loadProviders } = await import(registryUrl);
+
+  const providers = await loadProviders();
+  const enabled = config.enabledProviders ?? [];
+  const allEnabled = enabled.length === 0; // empty = all enabled
+
+  const rows = providers.map(p => {
+    const isEnabled = allEnabled || enabled.includes(p.name);
+    return {
+      name: p.name,
+      ecosystem: p.ecosystem ?? p.name,
+      enabled: isEnabled,
+      status: isEnabled ? "active" : "disabled",
+    };
+  });
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
+    return EXIT.SUCCESS;
+  }
+
+  // Human-readable table
+  process.stdout.write("\n");
+  process.stdout.write("  Provider     Ecosystem    Status\n");
+  process.stdout.write("  ─────────    ─────────    ──────\n");
+  for (const row of rows) {
+    const name = row.name.padEnd(12);
+    const eco = row.ecosystem.padEnd(12);
+    const status = row.enabled ? "active" : "disabled";
+    process.stdout.write(`  ${name} ${eco} ${status}\n`);
+  }
+  process.stdout.write("\n");
+
+  if (!allEnabled) {
+    process.stdout.write(`  Filter: enabledProviders = [${enabled.join(", ")}]\n\n`);
+  }
+
+  return EXIT.SUCCESS;
+}