@mcptoolshop/promo-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 — 2026-02-16
+
+Initial release of the portable promotion engine.
+
+### Included
+
+- `promo-kit init` — bootstrap 17 zero-state seed files (auto-creates kit.config.json)
+- `promo-kit selftest` — validate config, seeds, and dry-runs
+- `promo-kit migrate` — apply schema version upgrades
+- `promo-kit --print-config` — show resolved config after defaults
+- Programmatic API: `bootstrap()`, `migrate()`, `getConfig()`, `getRoot()`, `loadKitConfig()`
+- 10 portable core generators (promo-decisions, experiment-decisions, baseline, feedback-summary, queue-health, telemetry-aggregate, recommendations, recommendation-patch, decision-drift, trust-receipt)
+- 2 apply scripts (control-patch, submission-status)
+- Example config template (`kit.config.example.json`)
+- Zero runtime dependencies

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# @mcptoolshop/promo-kit
+
+Portable promotion engine for tool catalogs. Receipt-backed promotions, freeze modes, drift detection — zero dependencies.
+
+## What it does
+
+`promo-kit` gives your tool catalog a complete promotion pipeline:
+
+- **Bootstrap** 17 zero-state seed files (governance, promo queue, experiments, etc.)
+- **Generate** promotion decisions, baselines, drift reports, and trust receipts
+- **Verify** everything with SHA-256 hashed inputs and commit SHAs
+- **Freeze** automation when you need human review
+
+All data stays local. No cloud dependencies. No runtime npm dependencies.
+
+## Quickstart
+
+```bash
+npm install @mcptoolshop/promo-kit
+
+# Initialize (auto-creates kit.config.json from template)
+npx promo-kit init
+
+# Edit kit.config.json with your org details:
+#   org.name, org.account, site.title, contact.email
+
+# Validate the installation
+npx promo-kit selftest
+```
+
+## CLI Commands
+
+### `promo-kit init`
+
+Creates `kit.config.json` (if absent) and bootstraps 17 seed files in your data directory.
+
+```bash
+promo-kit init              # create config + seeds
+promo-kit init --dry-run    # show what would be created
+promo-kit init --force      # overwrite existing kit.config.json
+```
+
+### `promo-kit selftest`
+
+Validates config, seed files, and runs all portable core generators in dry-run mode.
+
+```bash
+promo-kit selftest
+```
+
+### `promo-kit migrate`
+
+Applies schema version upgrades when `kitVersion` changes.
+
+```bash
+promo-kit migrate
+```
+
+### Flags
+
+```bash
+promo-kit --version         # show version
+promo-kit --help            # show usage
+promo-kit --print-config    # show resolved config after defaults
+```
+
+## Programmatic API
+
+```js
+import { bootstrap, migrate, getConfig, getRoot, loadKitConfig } from "@mcptoolshop/promo-kit";
+
+// Bootstrap seed files in a directory
+const result = bootstrap("/path/to/your/project");
+// => { success: true, errors: [], created: [...], skipped: [...] }
+
+// Get resolved config (deep-merged with defaults)
+const config = getConfig();
+
+// Run migrations
+const migrationResult = migrate("/path/to/your/project");
+```
+
+Config utilities are also available as a separate export:
+
+```js
+import { getConfig, getRoot } from "@mcptoolshop/promo-kit/config";
+```
+
+## What it generates
+
+`promo-kit init` creates these seed files in your data directory:
+
+| File | Purpose |
+|------|---------|
+| `governance.json` | Freeze modes, promo caps, hard rules |
+| `promo-queue.json` | Weekly promotion candidates |
+| `experiments.json` | Active A/B experiments |
+| `submissions.json` | External tool submissions |
+| `overrides.json` | Per-tool metadata overrides |
+| `ops-history.json` | Workflow run history |
+| `feedback.jsonl` | Append-only feedback log |
+| `worthy.json` | Worthiness rubric and scores |
+| `promo-decisions.json` | Generated promotion decisions |
+| `experiment-decisions.json` | Generated experiment decisions |
+| `baseline.json` | Computed baseline metrics |
+| `feedback-summary.json` | Aggregated feedback |
+| `queue-health.json` | Queue health metrics |
+| `recommendations.json` | Advisory recommendations |
+| `recommendation-patch.json` | Recommended data patches |
+| `decision-drift.json` | Week-over-week drift report |
+| `telemetry/rollup.json` | Telemetry aggregates |
+
+## Environment
+
+| Variable | Purpose |
+|----------|---------|
+| `KIT_CONFIG` | Path to an alternate `kit.config.json` (overrides cwd discovery) |
+
+## Requirements
+
+- Node.js >= 22
+- Zero runtime dependencies
+
+## Links
+
+- [Portable Core docs](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/portable-core.md) — full contract and field reference
+- [Presskit Handbook](https://github.com/mcp-tool-shop/mcp-tool-shop/blob/main/docs/presskit-handbook.md) — brand assets and verification walkthrough
+- [Trust Center](https://mcp-tool-shop.github.io/trust/) — live verification infrastructure
+
+## License
+
+MIT

package/bin/promo-kit.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * promo-kit CLI
+ *
+ * Portable promotion engine for tool catalogs.
+ *
+ * Usage:
+ *   promo-kit init [--dry-run] [--force]
+ *   promo-kit selftest [--skip-build] [--skip-invariants]
+ *   promo-kit migrate
+ *   promo-kit --print-config
+ *   promo-kit --version
+ *   promo-kit --help
+ */
+
+import { existsSync, copyFileSync, readFileSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { fork } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "..");
+const SCRIPTS = join(PKG_ROOT, "scripts");
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// ── --version ───────────────────────────────────────────────
+
+if (args.includes("--version") || args.includes("-v")) {
+  const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
+  console.log(`${pkg.name} v${pkg.version}`);
+  process.exit(0);
+}
+
+// ── --help ──────────────────────────────────────────────────
+
+if (!command || args.includes("--help") || args.includes("-h")) {
+  console.log(`
+  @mcptoolshop/promo-kit — Portable promotion engine for tool catalogs
+
+  Usage:
+    promo-kit init [--dry-run] [--force]   Bootstrap seed files (auto-creates kit.config.json)
+    promo-kit selftest                     Validate config, seeds, and dry-runs
+    promo-kit migrate                      Apply schema version upgrades
+    promo-kit --print-config               Show resolved config after defaults
+    promo-kit --version                    Show version
+    promo-kit --help                       Show this help
+
+  Environment:
+    KIT_CONFIG=/path/to/kit.config.json    Point at an alternate config root
+`.trimEnd());
+  process.exit(0);
+}
+
+// ── Config resolution ───────────────────────────────────────
+
+const cwdConfig = resolve(process.cwd(), "kit.config.json");
+
+function resolveConfig() {
+  if (process.env.KIT_CONFIG) return; // already set
+  if (existsSync(cwdConfig)) {
+    process.env.KIT_CONFIG = cwdConfig;
+  }
+}
+
+// ── --print-config ──────────────────────────────────────────
+
+if (args.includes("--print-config")) {
+  resolveConfig();
+  const { getConfig, getRoot } = await import(pathToFileURL(join(SCRIPTS, "lib", "config.mjs")).href);
+  console.log("Root:", getRoot());
+  console.log(JSON.stringify(getConfig(), null, 2));
+  process.exit(0);
+}
+
+// ── init ────────────────────────────────────────────────────
+
+if (command === "init") {
+  const dryRun = args.includes("--dry-run");
+  const force = args.includes("--force");
+
+  // Auto-create kit.config.json if absent
+  if (!process.env.KIT_CONFIG && !existsSync(cwdConfig)) {
+    const exampleConfig = join(PKG_ROOT, "kit.config.example.json");
+    if (dryRun) {
+      console.log("[dry-run] Would create kit.config.json from template");
+      console.log("[dry-run] Would bootstrap seed files in current directory");
+      process.exit(0);
+    }
+    copyFileSync(exampleConfig, cwdConfig);
+    console.log("Created kit.config.json from template.");
+    console.log("  Edit these fields: org.name, org.account, site.title, contact.email\n");
+    process.env.KIT_CONFIG = cwdConfig;
+  } else if (process.env.KIT_CONFIG) {
+    // KIT_CONFIG already set, use it
+  } else if (existsSync(cwdConfig)) {
+    if (!force) {
+      console.log("kit.config.json already exists (use --force to overwrite).");
+    } else {
+      const exampleConfig = join(PKG_ROOT, "kit.config.example.json");
+      copyFileSync(exampleConfig, cwdConfig);
+      console.log("Overwrote kit.config.json from template.");
+    }
+    process.env.KIT_CONFIG = cwdConfig;
+  }
+
+  const child = fork(join(SCRIPTS, "kit-bootstrap.mjs"), [], {
+    env: { ...process.env },
+    stdio: "inherit",
+  });
+  child.on("exit", (code) => {
+    if (code === 0) {
+      console.log("\nNext: promo-kit selftest");
+    }
+    process.exit(code);
+  });
+}
+
+// ── selftest ────────────────────────────────────────────────
+
+else if (command === "selftest") {
+  resolveConfig();
+  const childArgs = args.slice(1); // forward flags like --skip-build
+  const child = fork(join(SCRIPTS, "kit-selftest.mjs"), childArgs, {
+    env: { ...process.env },
+    stdio: "inherit",
+  });
+  child.on("exit", (code) => process.exit(code));
+}
+
+// ── migrate ─────────────────────────────────────────────────
+
+else if (command === "migrate") {
+  resolveConfig();
+  const child = fork(join(SCRIPTS, "kit-migrate.mjs"), [], {
+    env: { ...process.env },
+    stdio: "inherit",
+  });
+  child.on("exit", (code) => process.exit(code));
+}
+
+// ── unknown command ─────────────────────────────────────────
+
+else {
+  console.error(`Unknown command: ${command}`);
+  console.error("Run promo-kit --help for usage.");
+  process.exit(1);
+}

package/index.mjs

@@ -0,0 +1,9 @@
+export { bootstrap } from "./scripts/kit-bootstrap.mjs";
+export { migrate } from "./scripts/kit-migrate.mjs";
+export {
+  getConfig,
+  getRoot,
+  loadKitConfig,
+  resetConfigCache,
+  KIT_VERSION_SUPPORTED,
+} from "./scripts/lib/config.mjs";

package/kit.config.example.json

@@ -0,0 +1,19 @@
+{
+  "kitVersion": 1,
+  "org": {
+    "name": "your-org",
+    "account": "your-github-account",
+    "url": "https://github.com/your-org"
+  },
+  "site": {
+    "title": "Your Tool Catalog",
+    "url": "https://your-org.github.io",
+    "description": "Your catalog description."
+  },
+  "repo": {
+    "marketing": "your-account/your-repo"
+  },
+  "contact": {
+    "email": "team@example.com"
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mcptoolshop/promo-kit",
+  "version": "0.1.0",
+  "description": "Portable promotion engine for tool catalogs. Receipt-backed promotions, freeze modes, drift detection.",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./config": "./scripts/lib/config.mjs"
+  },
+  "bin": {
+    "promo-kit": "./bin/promo-kit.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "index.mjs",
+    "kit.config.example.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcp-tool-shop/mcp-tool-shop.git",
+    "directory": "packages/promo-kit"
+  },
+  "homepage": "https://github.com/mcp-tool-shop/mcp-tool-shop/tree/main/packages/promo-kit",
+  "bugs": {
+    "url": "https://github.com/mcp-tool-shop/mcp-tool-shop/issues"
+  },
+  "keywords": [
+    "mcp",
+    "tools",
+    "promotion",
+    "catalog",
+    "receipts",
+    "verification"
+  ],
+  "author": "mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>",
+  "license": "MIT"
+}

package/scripts/apply-control-patch.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+
+/**
+ * Apply Control Patch
+ *
+ * Validates and applies a JSON patch to governance and promo data files.
+ * Called from the apply-control-patch workflow.
+ *
+ * Usage:
+ *   node scripts/apply-control-patch.mjs '{"governance.json":{"decisionsFrozen":true}}'
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { getConfig, getRoot } from "./lib/config.mjs";
+
+const ROOT = getRoot();
+const config = getConfig();
+const DATA_DIR = join(ROOT, config.paths.dataDir);
+
+// ── Allowed files and field validators ───────────────────────
+
+const ALLOWED_FILES = new Set([
+  "governance.json",
+  "promo.json",
+  "promo-queue.json",
+  "experiments.json",
+]);
+
+const PROTECTED_FIELDS = new Set(["schemaVersion", "hardRules"]);
+
+const GOVERNANCE_VALIDATORS = {
+  decisionsFrozen: (v) => typeof v === "boolean",
+  experimentsFrozen: (v) => typeof v === "boolean",
+  maxPromosPerWeek: (v) => Number.isInteger(v) && v > 0 && v <= 20,
+  cooldownDaysPerSlug: (v) => Number.isInteger(v) && v > 0 && v <= 90,
+  cooldownDaysPerPartner: (v) => Number.isInteger(v) && v > 0 && v <= 90,
+  minCoverageScore: (v) => typeof v === "number" && v >= 0 && v <= 100,
+  minExperimentDataThreshold: (v) => Number.isInteger(v) && v > 0 && v <= 1000,
+};
+
+const PROMO_VALIDATORS = {
+  enabled: (v) => typeof v === "boolean",
+  learningMode: (v) => ["off", "shadow", "active"].includes(v),
+};
+
+const FILE_VALIDATORS = {
+  "governance.json": GOVERNANCE_VALIDATORS,
+  "promo.json": PROMO_VALIDATORS,
+};
+
+// ── Risk notes ───────────────────────────────────────────────
+
+const RISK_NOTES = {
+  "governance.json": {
+    decisionsFrozen: (v) => v === true ? "Decisions will NOT update until unfrozen" : "Decisions will resume updating",
+    experimentsFrozen: (v) => v === true ? "Experiments will NOT update until unfrozen" : "Experiments will resume updating",
+    maxPromosPerWeek: (v) => `Max promos per week changed to ${v} — affects budget allocation`,
+    cooldownDaysPerSlug: (v) => `Slug cooldown changed to ${v} days`,
+    cooldownDaysPerPartner: (v) => `Partner cooldown changed to ${v} days`,
+    minCoverageScore: (v) => `Coverage threshold changed to ${v}`,
+    minExperimentDataThreshold: (v) => `Experiment data threshold changed to ${v}`,
+  },
+  "promo.json": {
+    enabled: (v) => v ? "Promotion ENABLED — outreach will run" : "Promotion DISABLED — no outreach",
+    learningMode: (v) => `Learning mode set to "${v}"`,
+  },
+};
+
+// ── Core functions (exported for testing) ────────────────────
+
+/**
+ * Validate a patch object.
+ * @param {Record<string, Record<string, unknown>>} patch
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validatePatch(patch) {
+  const errors = [];
+
+  if (!patch || typeof patch !== "object") {
+    return { valid: false, errors: ["Patch must be a JSON object"] };
+  }
+
+  for (const [file, fields] of Object.entries(patch)) {
+    if (!ALLOWED_FILES.has(file)) {
+      errors.push(`File "${file}" is not in the allowed list: ${[...ALLOWED_FILES].join(", ")}`);
+      continue;
+    }
+
+    if (!fields || typeof fields !== "object") {
+      errors.push(`Fields for "${file}" must be an object`);
+      continue;
+    }
+
+    for (const [field, value] of Object.entries(fields)) {
+      if (PROTECTED_FIELDS.has(field)) {
+        errors.push(`Field "${field}" in "${file}" is protected and cannot be patched`);
+        continue;
+      }
+
+      const validators = FILE_VALIDATORS[file];
+      if (validators && validators[field]) {
+        if (!validators[field](value)) {
+          errors.push(`Invalid value for "${file}".${field}: ${JSON.stringify(value)}`);
+        }
+      }
+      // Files without validators (promo-queue.json, experiments.json) allow any non-protected fields
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Apply a validated patch to data files.
+ * @param {Record<string, Record<string, unknown>>} patch
+ * @param {{ dataDir?: string }} opts
+ * @returns {{ applied: string[], riskNotes: string[] }}
+ */
+export function applyPatch(patch, opts = {}) {
+  const { dataDir = DATA_DIR } = opts;
+  const applied = [];
+  const riskNotes = [];
+
+  for (const [file, fields] of Object.entries(patch)) {
+    const filePath = join(dataDir, file);
+    let current = {};
+    try {
+      current = JSON.parse(readFileSync(filePath, "utf8"));
+    } catch { /* start fresh if missing */ }
+
+    // Merge fields
+    const updated = { ...current, ...fields };
+    writeFileSync(filePath, JSON.stringify(updated, null, 2) + "\n", "utf8");
+    applied.push(file);
+
+    // Generate risk notes
+    const noteGenerators = RISK_NOTES[file] || {};
+    for (const [field, value] of Object.entries(fields)) {
+      if (noteGenerators[field]) {
+        riskNotes.push(noteGenerators[field](value));
+      }
+    }
+  }
+
+  return { applied, riskNotes };
+}
+
+/**
+ * Full pipeline: parse, validate, apply.
+ * @param {string} patchJson - JSON string from CLI arg
+ * @param {{ dataDir?: string, riskNotesPath?: string }} opts
+ */
+export function applyControlPatch(patchJson, opts = {}) {
+  const { dataDir = DATA_DIR, riskNotesPath = "/tmp/patch-risk-notes.txt" } = opts;
+
+  let patch;
+  try {
+    patch = JSON.parse(patchJson);
+  } catch (e) {
+    console.error(`  Error: Invalid JSON — ${e.message}`);
+    process.exitCode = 1;
+    return { success: false, error: "Invalid JSON" };
+  }
+
+  const validation = validatePatch(patch);
+  if (!validation.valid) {
+    console.error("  Validation errors:");
+    for (const err of validation.errors) {
+      console.error(`    - ${err}`);
+    }
+    process.exitCode = 1;
+    return { success: false, errors: validation.errors };
+  }
+
+  const result = applyPatch(patch, { dataDir });
+
+  console.log(`  Applied patch to: ${result.applied.join(", ")}`);
+  if (result.riskNotes.length > 0) {
+    console.log("  Risk notes:");
+    for (const note of result.riskNotes) {
+      console.log(`    - ${note}`);
+    }
+    // Write risk notes file for workflow
+    try {
+      writeFileSync(riskNotesPath, result.riskNotes.join("\n") + "\n", "utf8");
+    } catch { /* fail soft in non-CI env */ }
+  }
+
+  return { success: true, ...result };
+}
+
+// ── Entry point ──────────────────────────────────────────────
+
+const isMain = process.argv[1] && resolve(process.argv[1]).endsWith("apply-control-patch.mjs");
+if (isMain) {
+  const patchJson = process.argv[2];
+  if (!patchJson) {
+    console.error("Usage: node scripts/apply-control-patch.mjs '<patch-json>'");
+    process.exitCode = 1;
+  } else {
+    console.log("Applying control patch...");
+    applyControlPatch(patchJson);
+  }
+}