@mcptoolshop/mcpt-publishing 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2026-02-17
+
+### Added
+- **fix command**: `mcpt-publishing fix` — allowlisted metadata fixes with local, `--remote`, and `--pr` modes
+- **7 fixers**: npm-repository, npm-homepage, npm-bugs, npm-keywords, readme-header, github-about, nuget-csproj
+- **Fixer plugin system**: Base `Fixer` class with auto-discovery registry, matching `canFix()` to audit findings
+- **weekly command**: `mcpt-publishing weekly` — orchestrates audit → fix → optionally publish in one shot
+- **assets command**: `mcpt-publishing assets` — bridges to optional `@mcptoolshop/mcpt-publishing-assets` plugin
+- **Assets plugin**: `@mcptoolshop/mcpt-publishing-assets` — logo/icon generation via `sharp` (doctor, logo, wire)
+- **Fix receipts**: Immutable JSON receipts for fix operations with schema validation
+- **Assets receipts**: Receipt type for asset generation operations
+- **CI prepublish gate**: Tarball verification, install smoke test, CLI smoke tests in GitHub Actions
+- **Plugin loader**: Auto-discovers optional plugins with install hints
+- **Shared audit loop**: Extracted `runAudit()` for reuse by both audit and fix commands
+- Exit code 6 (`FIX_FAILURE`) for failed fixes
+- `init --dry-run` support
+- npm workspace support (`packages/` directory)
+- 2 new npm audit findings: `missing-bugs-url`, `missing-keywords`
+
+### Changed
+- Version bumped from 0.2.0 to 0.3.0
+- Global help rewritten with Golden Path workflow
+- README rewritten with fix command, weekly, assets plugin documentation
+- CI workflow renamed from `audit-weekly.yml` to `ci.yml` with prepublish gate
+- `plan` command deprecated (replaced by `fix --dry-run`)
+- Test suite expanded from 42 to 93 tests
+
 ## [0.2.0] - 2026-02-17
 
 ### Added

package/README.md

@@ -19,9 +19,9 @@
 
 ## What it is
 
-**mcpt-publishing** is a portable "publishing layer" that sits between your repos and public registries.
+**mcpt-publishing** is a portable publishing layer that sits between your repos and public registries.
 
-It answers the annoying questions humans actually have:
+It answers the questions humans actually have:
 
 - *Are my registry pages stale or embarrassing?*
 - *Do tags/releases match what's published?*
@@ -38,7 +38,7 @@ Every run produces **receipts**: immutable JSON artifacts with SHA-256 hashes, c
 
 - You publish to **npm and/or NuGet** and your pages drift over time (they do).
 - You want a single place to enforce "registry truth" (versions, tags, URLs, READMEs, icons).
-- You want automation that's safe: **plans, PRs, receipts**, and no surprise pushes.
+- You want automation that's safe: **audit, fix, receipts**, and no surprise pushes.
 
 **Not for you if...**
 
@@ -67,17 +67,31 @@ This scaffolds:
 - `profiles/` (where repos/packages are declared)
 - `reports/` and `receipts/` output folders
 
-### Run an audit
+### The golden path
 
 ```bash
+# 1. Discover drift
 npx mcpt-publishing audit
+
+# 2. Preview fixes
+npx mcpt-publishing fix --dry-run
+
+# 3. Apply fixes locally
+npx mcpt-publishing fix
+
+# 4. Publish with receipts
+npx mcpt-publishing publish --target npm
+
+# 5. Verify the receipt
+npx mcpt-publishing verify-receipt receipts/publish/...json
 ```
 
-Outputs:
+Or do it all at once:
 
-- `reports/latest.md` (human-readable)
-- `reports/latest.json` (machine-readable)
-- a receipt under `receipts/`
+```bash
+npx mcpt-publishing weekly --dry-run     # preview everything
+npx mcpt-publishing weekly --publish     # the full pipeline
+```
 
 ---
 
@@ -92,34 +106,55 @@ npx mcpt-publishing audit
 npx mcpt-publishing audit --json
 ```
 
-### `mcpt-publishing plan`
-
-Generates a safe plan to fix drift (no network writes). *(coming soon)*
+Outputs:
 
-```bash
-npx mcpt-publishing plan
-npx mcpt-publishing plan --repo mcp-tool-shop-org/soundboard-maui
-```
+- `reports/latest.md` (human-readable)
+- `reports/latest.json` (machine-readable)
+- a receipt under `receipts/`
 
-### `mcpt-publishing apply`
+### `mcpt-publishing fix`
 
-Applies the plan as PRs (never pushes to main). *(coming soon)*
+Applies allowlisted metadata fixes to bring your registry pages into shape.
 
 ```bash
-npx mcpt-publishing apply
-npx mcpt-publishing apply --batch
+npx mcpt-publishing fix --dry-run                     # preview all fixes
+npx mcpt-publishing fix                               # apply locally
+npx mcpt-publishing fix --remote                      # apply via GitHub API (no checkout)
+npx mcpt-publishing fix --pr                          # apply locally + open a PR
+npx mcpt-publishing fix --repo mcp-tool-shop-org/mcpt # fix one repo only
 ```
 
+Supported fixes:
+
+| Fix | What it does |
+|-----|-------------|
+| `npm-repository` | Sets `repository` in package.json |
+| `npm-homepage` | Sets `homepage` in package.json |
+| `npm-bugs` | Sets `bugs.url` in package.json |
+| `npm-keywords` | Adds starter keywords to package.json |
+| `readme-header` | Adds logo + links to README.md |
+| `github-about` | Sets homepage/description via GitHub API |
+| `nuget-csproj` | Adds PackageProjectUrl/RepositoryUrl to .csproj |
+
 ### `mcpt-publishing publish`
 
 Publishes packages to registries and generates immutable receipts.
 
 ```bash
 npx mcpt-publishing publish --repo mcp-tool-shop-org/mcpt --target npm
-npx mcpt-publishing publish --repo mcp-tool-shop-org/soundboard-maui --target nuget --cwd /path/to/repo
 npx mcpt-publishing publish --target npm --dry-run
 ```
 
+### `mcpt-publishing weekly`
+
+Orchestrates the full golden path: audit, fix, and optionally publish.
+
+```bash
+npx mcpt-publishing weekly --dry-run     # audit + fix preview
+npx mcpt-publishing weekly --pr          # audit + fix as PR
+npx mcpt-publishing weekly --publish     # audit + fix + publish
+```
+
 ### `mcpt-publishing providers`
 
 Shows enabled providers and required env vars.
@@ -134,22 +169,44 @@ Validates receipt files against schema and computes integrity hashes.
 
 ```bash
 npx mcpt-publishing verify-receipt receipts/audit/2026-02-17.json
-npx mcpt-publishing verify-receipt receipts/publish/mcp-tool-shop-org--mcpt/npm/1.0.1.json --json
+npx mcpt-publishing verify-receipt receipts/fix/2026-02-17-fleet.json --json
+```
+
+### `mcpt-publishing init`
+
+Scaffolds a new project. Supports `--dry-run` to preview without writing files.
+
+```bash
+npx mcpt-publishing init
+npx mcpt-publishing init --dry-run
 ```
 
 ---
 
-## Optional: assets plugin (logos + images)
+## Optional: assets plugin
 
-Core is zero-dependency. Visual updates (logos, icons, OG images) are handled by an optional plugin: *(coming soon)*
+Core is zero-dependency. Visual updates (logos, icons) are handled by an optional plugin:
 
 ```bash
 npm i -D @mcptoolshop/mcpt-publishing-assets
-npx mcpt-publishing assets doctor
-npx mcpt-publishing assets logo --repo mcp-tool-shop-org/mcpt
 ```
 
-This plugin depends on `sharp` and is kept separate so installs remain fast and reliable.
+Once installed, `mcpt-publishing` auto-detects it:
+
+```bash
+npx mcpt-publishing assets doctor              # check sharp is working
+npx mcpt-publishing assets logo --input src.png # generate icon + logo
+npx mcpt-publishing assets wire --repo owner/name  # wire into project files
+```
+
+The plugin depends on `sharp` and is kept separate so core installs remain fast and reliable.
+
+---
+
+## Upgrading from 0.2.x
+
+- `mcpt-publishing plan` is deprecated — use `mcpt-publishing fix --dry-run` instead.
+- Install the assets plugin for logo/icon generation: `npm i -D @mcptoolshop/mcpt-publishing-assets`
 
 ---
 
@@ -172,6 +229,8 @@ Schemas live in:
 
 - `schemas/profile.schema.json`
 - `schemas/receipt.schema.json`
+- `schemas/fix-receipt.schema.json`
+- `schemas/assets-receipt.schema.json`
 
 Contract + phases: `docs/CONTRACT.md`
 
@@ -199,6 +258,7 @@ These are only needed when you publish or call APIs that require auth.
 | `3` | Configuration or schema error |
 | `4` | Missing credentials for a requested operation |
 | `5` | One or more publishes failed |
+| `6` | One or more fixes failed |
 
 ---
 
@@ -213,6 +273,8 @@ They include:
 - URLs
 - SHA-256 hashes of key artifacts
 
+Types: `audit`, `publish`, `fix`, `assets`
+
 If you like receipts, you can plug this into the receipt factory as the "publishing plugin."
 
 ---
@@ -221,13 +283,7 @@ If you like receipts, you can plug this into the receipt factory as the "publish
 
 ```bash
 npm test
-node scripts/audit.mjs
-```
-
-Smoke tests:
-
-```bash
-node scripts/test-providers.mjs
+node bin/mcpt-publishing.mjs audit
 ```
 
 ---

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@mcptoolshop/mcpt-publishing",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Publishing health auditor and receipt factory plugin for MCP Tool Shop packages.",
   "type": "module",
   "bin": {
     "mcpt-publishing": "./bin/mcpt-publishing.mjs"
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "files": [
     "bin/",
     "src/",
@@ -22,6 +25,10 @@
   "scripts": {
     "audit": "node bin/mcpt-publishing.mjs audit",
     "audit:json": "node bin/mcpt-publishing.mjs audit --json",
+    "fix": "node bin/mcpt-publishing.mjs fix",
+    "fix:dry": "node bin/mcpt-publishing.mjs fix --dry-run",
+    "weekly": "node bin/mcpt-publishing.mjs weekly",
+    "weekly:dry": "node bin/mcpt-publishing.mjs weekly --dry-run",
     "test": "node scripts/test-providers.mjs"
   },
   "engines": {

package/schemas/assets-receipt.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Assets Receipt",
+  "description": "Receipt for asset generation operations (logo, icon, wire).",
+  "type": "object",
+  "required": ["schemaVersion", "type", "timestamp", "repo", "artifacts"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "type": {
+      "type": "string",
+      "const": "assets"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "repo": {
+      "type": "object",
+      "required": ["owner", "name"],
+      "properties": {
+        "owner": { "type": "string" },
+        "name": { "type": "string" }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "sha256", "size"],
+        "properties": {
+          "name": { "type": "string" },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "size": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
+    "wireChanges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "file": { "type": "string" },
+          "field": { "type": "string" },
+          "before": { "type": "string" },
+          "after": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/fix-receipt.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mcp-tool-shop/mcpt-publishing/schemas/fix-receipt.schema.json",
+  "title": "Fix Receipt",
+  "description": "Record of a publishing metadata fix run.",
+  "type": "object",
+  "required": ["schemaVersion", "type", "timestamp", "repo", "mode", "changes"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "type": {
+      "type": "string",
+      "const": "fix"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the fix ran"
+    },
+    "repo": {
+      "type": "string",
+      "description": "Repo slug (owner/name) or '*' for fleet-wide"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["local", "remote", "pr", "dry-run"],
+      "description": "How fixes were applied"
+    },
+    "dryRun": {
+      "type": "boolean"
+    },
+    "prUrl": {
+      "type": ["string", "null"],
+      "description": "URL of the PR created (--pr mode only)"
+    },
+    "branchName": {
+      "type": ["string", "null"],
+      "description": "Branch name used for --pr mode"
+    },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["fixerCode", "target", "field", "before", "after"],
+        "additionalProperties": false,
+        "properties": {
+          "fixerCode": {
+            "type": "string",
+            "description": "Machine-readable fixer identifier (e.g. npm-repository)"
+          },
+          "target": {
+            "type": "string",
+            "description": "Ecosystem (npm, nuget, readme, github)"
+          },
+          "packageName": {
+            "type": "string",
+            "description": "Package name affected"
+          },
+          "field": {
+            "type": "string",
+            "description": "Field that was changed (e.g. repository.url)"
+          },
+          "before": {
+            "description": "Value before the fix (null if missing)"
+          },
+          "after": {
+            "description": "Value after the fix"
+          },
+          "file": {
+            "type": ["string", "null"],
+            "description": "Relative path of the file changed"
+          }
+        }
+      }
+    },
+    "auditBefore": {
+      "type": "object",
+      "description": "Finding counts before fix",
+      "properties": {
+        "RED": { "type": "integer", "minimum": 0 },
+        "YELLOW": { "type": "integer", "minimum": 0 },
+        "GRAY": { "type": "integer", "minimum": 0 },
+        "INFO": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "auditAfter": {
+      "type": "object",
+      "description": "Finding counts after fix (if re-audited)",
+      "properties": {
+        "RED": { "type": "integer", "minimum": 0 },
+        "YELLOW": { "type": "integer", "minimum": 0 },
+        "GRAY": { "type": "integer", "minimum": 0 },
+        "INFO": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "commitSha": {
+      "type": ["string", "null"],
+      "pattern": "^[0-9a-f]{40}$",
+      "description": "Commit SHA at time of fix (null in dry-run)"
+    },
+    "fileHashes": {
+      "type": "object",
+      "description": "SHA-256 hashes of files modified",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^[0-9a-f]{64}$"
+      }
+    }
+  }
+}

package/scripts/lib/providers/npm.mjs

@@ -159,6 +159,16 @@ export default class NpmProvider extends Provider {
       findings.push({ severity: "GRAY", code: "missing-homepage", msg: `${pkg.name} has no homepage` });
     }
 
+    // Bugs URL
+    if (!meta.bugs?.url) {
+      findings.push({ severity: "GRAY", code: "missing-bugs-url", msg: `${pkg.name} has no bugs URL` });
+    }
+
+    // Keywords
+    if (!meta.keywords?.length) {
+      findings.push({ severity: "GRAY", code: "missing-keywords", msg: `${pkg.name} has no keywords` });
+    }
+
     return findings;
   }
 

package/src/audit/run-audit.mjs

@@ -0,0 +1,108 @@
+/**
+ * Shared audit loop — runs publishing health audit and returns structured results.
+ *
+ * Used by both `audit` (to generate reports) and `fix` (to discover fixable drift).
+ * Does NOT write reports or emit receipts — callers handle that.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Run the audit loop across all manifest entries.
+ *
+ * @param {object} config   - Resolved config (from loader.mjs)
+ * @param {object} manifest - Parsed manifest ({ npm: [...], nuget: [...], ... })
+ * @returns {Promise<{ results: object, allFindings: Array, counts: object }>}
+ */
+export async function runAudit(config, manifest) {
+  // Import provider registry (reuse existing working code in scripts/lib/)
+  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} 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");
+  const counts = { RED: red.length, YELLOW: yellow.length, GRAY: gray.length, INFO: info.length };
+  results.counts = counts;
+
+  // Count total packages
+  let totalPackages = 0;
+  for (const [, val] of Object.entries(results)) {
+    if (Array.isArray(val)) totalPackages += val.length;
+  }
+  results.totalPackages = totalPackages;
+
+  return { results, allFindings, counts };
+}

package/src/cli/exit-codes.mjs

@@ -7,6 +7,7 @@
  *   3 — config or schema error
  *   4 — missing credentials for a requested operation
  *   5 — one or more publishes failed
+ *   6 — one or more fixes failed to apply
  */
 export const EXIT = {
   SUCCESS: 0,
@@ -14,4 +15,5 @@ export const EXIT = {
   CONFIG_ERROR: 3,
   MISSING_CREDENTIALS: 4,
   PUBLISH_FAILURE: 5,
+  FIX_FAILURE: 6,
 };

package/src/cli/help.mjs

@@ -10,23 +10,30 @@ Usage:
 
 Commands:
   audit           Run publishing health audit across all registries
-  init            Scaffold publishing.config.json and starter manifest
+  fix             Apply allowlisted metadata fixes (local, --remote, --pr)
   publish         Publish packages to registries with receipts
+  weekly          Audit + fix + optionally publish (one command)
+  assets          Logo/icon generation and wiring [plugin]
   providers       List registered providers and their status
   verify-receipt  Validate a receipt file (schema + integrity)
-  plan            Dry-run publish plan [coming soon]
+  init            Scaffold publishing.config.json and starter manifest
+  plan            [deprecated — use fix --dry-run]
 
 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
+Golden path:
+  mcpt-publishing audit                           # 1. discover drift
+  mcpt-publishing fix --dry-run                   # 2. preview fixes
+  mcpt-publishing fix                             # 3. apply fixes locally
+  mcpt-publishing publish --target npm --dry-run  # 4. preview publish
+  mcpt-publishing publish --target npm            # 5. publish with receipts
+
+  # Or do it all at once:
+  mcpt-publishing weekly --dry-run                # preview everything
+  mcpt-publishing weekly --publish                # the full pipeline
 
 Environment:
   PUBLISHING_CONFIG   Path to publishing.config.json (overrides walk-up discovery)

package/src/cli/router.mjs

@@ -12,10 +12,13 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Lazy-loaded command map. Keys are subcommand names. */
 const COMMANDS = {
   audit:            () => import("../commands/audit.mjs"),
+  fix:              () => import("../commands/fix.mjs"),
   init:             () => import("../commands/init.mjs"),
   plan:             () => import("../commands/plan.mjs"),
   publish:          () => import("../commands/publish.mjs"),
   providers:        () => import("../commands/providers.mjs"),
+  weekly:           () => import("../commands/weekly.mjs"),
+  assets:           () => import("../commands/assets.mjs"),
   "verify-receipt": () => import("../commands/verify-receipt.mjs"),
 };