@mcptoolshop/mcpt-publishing 1.0.0

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;
+}

package/src/commands/publish.mjs

@@ -0,0 +1,37 @@
+/**
+ * `mcpt-publishing publish` — execute publish and generate receipts (stub).
+ *
+ * Future: reads a publish plan, executes it against registries,
+ * generates immutable publish receipts, and updates the receipts index.
+ */
+
+import { EXIT } from "../cli/exit-codes.mjs";
+
+export const helpText = `
+mcpt-publishing publish — Execute a publish plan and generate receipts.
+
+Usage:
+  mcpt-publishing publish [flags]
+
+Flags:
+  --json        Output as JSON
+  --dry-run     Show what would be published without executing
+  --help        Show this help
+
+Status: Not yet implemented. Coming in a future release.
+`.trim();
+
+/**
+ * Execute the publish 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: "Publish command is not yet implemented." }) + "\n");
+  } else {
+    process.stderr.write("Publish command is not yet implemented.\n");
+    process.stderr.write("This will execute publishes and generate receipts in a future release.\n");
+  }
+  return EXIT.SUCCESS;
+}

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");
+}