@mcptoolshop/promo-kit 0.1.0

package/scripts/gen-trust-receipt.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+/**
+ * Trust Receipt Generator
+ *
+ * Generates site/public/trust.json — a machine-readable provenance artifact.
+ * Emitted at build time so every deploy carries verifiable metadata.
+ *
+ * Usage:
+ *   node scripts/gen-trust-receipt.mjs [--dry-run]
+ *
+ * Reads:
+ *   site/src/data/marketir/marketir.snapshot.json  (lock hash)
+ *   site/src/data/marketir/data/tools/*.json       (proven claims)
+ *   site/src/data/worthy.json                      (worthy stats)
+ *   site/src/data/projects.json                    (artifact hash)
+ *   site/src/data/overrides.json                   (artifact hash)
+ *   site/src/data/promo.json                       (artifact hash)
+ *   site/src/data/baseline.json                    (artifact hash)
+ *   site/src/data/ops-history.json                 (artifact hash)
+ *   site/src/data/promo-decisions.json             (artifact hash)
+ *   site/src/data/experiment-decisions.json        (artifact hash)
+ *
+ * Writes:
+ *   site/public/trust.json
+ */
+
+import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { getConfig, getRoot } from "./lib/config.mjs";
+
+const ROOT = getRoot();
+const config = getConfig();
+const DATA_DIR = join(ROOT, config.paths.dataDir);
+const PUBLIC_DIR = join(ROOT, config.paths.publicDir);
+
+// ── Helpers ─────────────────────────────────────────────────
+
+function safeParseJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function hashFile(filePath) {
+  try {
+    const content = readFileSync(filePath, "utf8");
+    return "sha256:" + createHash("sha256").update(content).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+// ── Core ────────────────────────────────────────────────────
+
+/**
+ * Build a trust receipt object from available data.
+ *
+ * @param {{ dataDir?: string, root?: string }} opts
+ * @returns {object} Trust receipt
+ */
+export function buildTrustReceipt(opts = {}) {
+  const { dataDir = DATA_DIR, root = ROOT } = opts;
+
+  // 1. Git SHA
+  let commit = "unknown";
+  try {
+    commit = execSync("git rev-parse --short HEAD", { cwd: root, encoding: "utf8" }).trim();
+  } catch { /* fail soft */ }
+
+  // 2. MarketIR lock hash
+  const snapshot = safeParseJson(join(dataDir, "marketir", "marketir.snapshot.json"), {});
+  const marketirLockHash = snapshot.lockSha256 || null;
+
+  // 3. COE version
+  let coeVersion = "unknown";
+  try {
+    const rootPkg = safeParseJson(join(root, "package.json"), {});
+    const deps = { ...rootPkg.dependencies, ...rootPkg.devDependencies };
+    if (deps["@mcptoolshop/clearance-opinion-engine"]) {
+      coeVersion = deps["@mcptoolshop/clearance-opinion-engine"].replace(/^\^|~/, "");
+    }
+  } catch { /* fail soft */ }
+
+  // 4. Proven claim count
+  let provenClaims = 0;
+  const toolsDir = join(dataDir, "marketir", "data", "tools");
+  try {
+    if (existsSync(toolsDir)) {
+      const files = readdirSync(toolsDir).filter((f) => f.endsWith(".json"));
+      for (const file of files) {
+        const tool = safeParseJson(join(toolsDir, file), {});
+        if (tool.claims) {
+          provenClaims += tool.claims.filter((c) => c.status === "proven").length;
+        }
+      }
+    }
+  } catch { /* fail soft */ }
+
+  // 5. Worthy stats
+  const worthy = safeParseJson(join(dataDir, "worthy.json"), {});
+  const repos = worthy.repos || {};
+  const repoEntries = Object.values(repos);
+  const worthyStats = {
+    total: repoEntries.length,
+    worthy: repoEntries.filter((r) => r.worthy).length,
+    notWorthy: repoEntries.filter((r) => !r.worthy).length,
+  };
+
+  // 6. Artifact manifest — SHA-256 of key data files
+  const MANIFEST_FILES = [
+    "projects.json",
+    "overrides.json",
+    "worthy.json",
+    "promo.json",
+    "baseline.json",
+    "ops-history.json",
+    "promo-decisions.json",
+    "experiment-decisions.json",
+  ];
+
+  const artifactManifest = {};
+  for (const file of MANIFEST_FILES) {
+    const hash = hashFile(join(dataDir, file));
+    if (hash) {
+      artifactManifest[file] = hash;
+    }
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    commit,
+    marketirLockHash,
+    coeVersion,
+    provenClaims,
+    worthyStats,
+    artifactManifest,
+  };
+}
+
+/**
+ * Full pipeline: build receipt and write to site/public/trust.json.
+ *
+ * @param {{ dataDir?: string, publicDir?: string, root?: string, dryRun?: boolean }} opts
+ * @returns {object} Trust receipt
+ */
+export function generateTrustReceipt(opts = {}) {
+  const { publicDir = PUBLIC_DIR, dryRun = false, ...buildOpts } = opts;
+
+  const receipt = buildTrustReceipt(buildOpts);
+
+  if (dryRun) {
+    console.log(`  [dry-run] Would write trust.json (commit: ${receipt.commit})`);
+    console.log(`  [dry-run] MarketIR lock: ${receipt.marketirLockHash || "N/A"}`);
+    console.log(`  [dry-run] Proven claims: ${receipt.provenClaims}`);
+    console.log(`  [dry-run] Artifacts: ${Object.keys(receipt.artifactManifest).length} files hashed`);
+    return receipt;
+  }
+
+  writeFileSync(join(publicDir, "trust.json"), JSON.stringify(receipt, null, 2) + "\n", "utf8");
+  console.log(`  Wrote trust.json (commit: ${receipt.commit}, ${Object.keys(receipt.artifactManifest).length} artifacts)`);
+
+  return receipt;
+}
+
+// ── Entry point ─────────────────────────────────────────────
+
+const isMain = process.argv[1] &&
+  resolve(process.argv[1]).endsWith("gen-trust-receipt.mjs");
+
+if (isMain) {
+  const dryRun = process.argv.includes("--dry-run");
+  console.log("Generating trust receipt...");
+  if (dryRun) console.log("  Mode: DRY RUN");
+
+  const receipt = generateTrustReceipt({ dryRun });
+  console.log(`  Commit: ${receipt.commit}`);
+  console.log(`  Proven claims: ${receipt.provenClaims}`);
+  console.log(`  Worthy: ${receipt.worthyStats.worthy}/${receipt.worthyStats.total}`);
+}

package/scripts/kit-bootstrap.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+/**
+ * Kit Bootstrap
+ *
+ * Validates the environment and creates zero-state seed files
+ * required by the portable core. Idempotent — skips existing files.
+ *
+ * Usage:
+ *   node scripts/kit-bootstrap.mjs
+ */
+
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { loadKitConfig, KIT_VERSION_SUPPORTED } from "./lib/config.mjs";
+
+const SCRIPT_ROOT = resolve(import.meta.dirname, "..");
+
+// ── Environment checks ──────────────────────────────────────
+
+function checkEnvironment(root) {
+  const errors = [];
+
+  // Node 22+
+  const major = parseInt(process.versions.node.split(".")[0], 10);
+  if (major < 22) {
+    errors.push(`Node 22+ required (found ${process.versions.node})`);
+  }
+
+  // kit.config.json exists
+  const configPath = join(root, "kit.config.json");
+  if (!existsSync(configPath)) {
+    errors.push(
+      `kit.config.json not found at ${configPath}. ` +
+      `Fix: create it or set KIT_CONFIG=/path/to/kit.config.json`
+    );
+  }
+
+  return errors;
+}
+
+// ── Seed file definitions ───────────────────────────────────
+
+function getSeedFiles(config, root) {
+  const dataDir = join(root, config.paths.dataDir);
+  const publicDir = join(root, config.paths.publicDir);
+
+  return [
+    // Human-owned governance
+    {
+      path: join(dataDir, "governance.json"),
+      content: {
+        schemaVersion: 2,
+        decisionsFrozen: false,
+        experimentsFrozen: false,
+        maxPromosPerWeek: 3,
+        cooldownDaysPerSlug: 14,
+        cooldownDaysPerPartner: 14,
+        minCoverageScore: 80,
+        minExperimentDataThreshold: 10,
+        hardRules: ["never push directly to main"],
+      },
+    },
+    // Promo queue
+    {
+      path: join(dataDir, "promo-queue.json"),
+      content: {
+        week: new Date().toISOString().slice(0, 10),
+        slugs: [],
+        promotionType: "own",
+        notes: "",
+      },
+    },
+    // Experiments
+    {
+      path: join(dataDir, "experiments.json"),
+      content: { schemaVersion: 1, experiments: [] },
+    },
+    // Submissions
+    {
+      path: join(dataDir, "submissions.json"),
+      content: { schemaVersion: 1, submissions: [] },
+    },
+    // Overrides (empty object)
+    {
+      path: join(dataDir, "overrides.json"),
+      content: {},
+    },
+    // Ops history
+    {
+      path: join(dataDir, "ops-history.json"),
+      content: { schemaVersion: 1, runs: [] },
+    },
+    // Feedback (empty JSONL)
+    {
+      path: join(dataDir, "feedback.jsonl"),
+      content: null, // empty file
+    },
+    // Worthy rubric
+    {
+      path: join(dataDir, "worthy.json"),
+      content: {
+        rubric: {
+          criteria: [
+            "README exists with purpose, install, quickstart",
+            "Has at least one release or tag",
+            "Tests exist and pass in CI",
+            "License file present",
+            "No critical security issues",
+          ],
+          minimumScore: 3,
+        },
+        scores: {},
+      },
+    },
+    // Generated outputs (zero-state seeds)
+    {
+      path: join(dataDir, "promo-decisions.json"),
+      content: { generatedAt: null, decisions: [] },
+    },
+    {
+      path: join(dataDir, "experiment-decisions.json"),
+      content: { generatedAt: null, decisions: [] },
+    },
+    {
+      path: join(dataDir, "baseline.json"),
+      content: { generatedAt: null, totalRuns: 0 },
+    },
+    {
+      path: join(dataDir, "feedback-summary.json"),
+      content: { generatedAt: null, channels: {}, slugs: {} },
+    },
+    {
+      path: join(dataDir, "queue-health.json"),
+      content: { generatedAt: null },
+    },
+    {
+      path: join(dataDir, "recommendations.json"),
+      content: { generatedAt: null, recommendations: [] },
+    },
+    {
+      path: join(dataDir, "recommendation-patch.json"),
+      content: { generatedAt: null, patches: [], advisoryNotes: [], riskNotes: [], frozenActions: [] },
+    },
+    {
+      path: join(dataDir, "decision-drift.json"),
+      content: {
+        generatedAt: null,
+        entrants: [],
+        exits: [],
+        scoreDeltas: [],
+        reasonChanges: [],
+        summary: { totalChanged: 0, newEntrants: 0, exits: 0, scoreChanges: 0, actionOnlyChanges: 0 },
+      },
+    },
+    // Telemetry directories
+    {
+      path: join(dataDir, "telemetry", "rollup.json"),
+      content: { generatedAt: null, eventCounts: {}, dailySummaries: [] },
+    },
+  ];
+}
+
+// ── Main ─────────────────────────────────────────────────────
+
+export function bootstrap(root = SCRIPT_ROOT) {
+  console.log("Kit Bootstrap");
+  console.log("=".repeat(40));
+
+  // 1. Environment check
+  const envErrors = checkEnvironment(root);
+  if (envErrors.length > 0) {
+    console.error("\nEnvironment errors:");
+    envErrors.forEach((e) => console.error(`  ✗ ${e}`));
+    return { success: false, errors: envErrors, created: [], skipped: [] };
+  }
+  console.log("✓ Environment OK");
+
+  // 2. Load config
+  const config = loadKitConfig(root);
+  const v = config.kitVersion;
+  if (v < KIT_VERSION_SUPPORTED[0] || v > KIT_VERSION_SUPPORTED[1]) {
+    const msg = `kitVersion ${v} not in supported range [${KIT_VERSION_SUPPORTED.join(", ")}]`;
+    console.error(`  ✗ ${msg}`);
+    return { success: false, errors: [msg], created: [], skipped: [] };
+  }
+  console.log(`✓ Config loaded (kitVersion: ${v})`);
+
+  // 3. Create seed files
+  const seeds = getSeedFiles(config, root);
+  const created = [];
+  const skipped = [];
+
+  for (const seed of seeds) {
+    if (existsSync(seed.path)) {
+      skipped.push(seed.path);
+      continue;
+    }
+
+    // Ensure parent directory exists
+    mkdirSync(dirname(seed.path), { recursive: true });
+
+    if (seed.content === null) {
+      writeFileSync(seed.path, "");
+    } else {
+      writeFileSync(seed.path, JSON.stringify(seed.content, null, 2) + "\n");
+    }
+    created.push(seed.path);
+  }
+
+  // Ensure telemetry events dir exists
+  const eventsDir = join(root, config.paths.dataDir, "telemetry", "events");
+  if (!existsSync(eventsDir)) {
+    mkdirSync(eventsDir, { recursive: true });
+    created.push(eventsDir);
+  }
+
+  // Ensure telemetry daily dir exists
+  const dailyDir = join(root, config.paths.dataDir, "telemetry", "daily");
+  if (!existsSync(dailyDir)) {
+    mkdirSync(dailyDir, { recursive: true });
+    created.push(dailyDir);
+  }
+
+  console.log(`\n✓ Created: ${created.length} files/dirs`);
+  created.forEach((f) => console.log(`  + ${f.replace(root, ".")}`));
+  console.log(`✓ Skipped: ${skipped.length} (already exist)`);
+
+  console.log("\nNext steps:");
+  console.log("  1. Edit kit.config.json with your org details");
+  console.log("  2. Run: npm run kit:selftest");
+  console.log("  3. Commit and push");
+
+  return { success: true, errors: [], created, skipped };
+}
+
+// ── CLI entry point ──────────────────────────────────────────
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(import.meta.filename);
+if (isMain) {
+  const root = process.env.KIT_CONFIG
+    ? dirname(resolve(process.env.KIT_CONFIG))
+    : SCRIPT_ROOT;
+  const result = bootstrap(root);
+  process.exit(result.success ? 0 : 1);
+}

package/scripts/kit-migrate.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * Kit Migrate
+ *
+ * Reads kitVersion from kit.config.json and applies schema transforms
+ * to bring data files up to the current version.
+ *
+ * v1 → v1 is a no-op (current).
+ *
+ * Usage:
+ *   node scripts/kit-migrate.mjs
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { loadKitConfig, KIT_VERSION_SUPPORTED } from "./lib/config.mjs";
+
+const SCRIPT_ROOT = resolve(import.meta.dirname, "..");
+
+// ── Migration registry ──────────────────────────────────────
+
+/**
+ * Each migration transforms from version N to N+1.
+ * Add entries here when kitVersion increments.
+ * @type {Map<number, { label: string, migrate: (root: string, config: object) => void }>}
+ */
+const MIGRATIONS = new Map([
+  // Example for future:
+  // [2, {
+  //   label: "v1 → v2: Add guardrails.maxRecommendations",
+  //   migrate(root, config) {
+  //     // transform data files for v2
+  //   },
+  // }],
+]);
+
+// ── Main ─────────────────────────────────────────────────────
+
+export function migrate(root = SCRIPT_ROOT) {
+  console.log("Kit Migrate");
+  console.log("=".repeat(40));
+
+  const config = loadKitConfig(root);
+  const currentVersion = config.kitVersion;
+  const targetVersion = KIT_VERSION_SUPPORTED[1];
+
+  console.log(`  Current kitVersion: ${currentVersion}`);
+  console.log(`  Target kitVersion:  ${targetVersion}`);
+  console.log(`  Supported range:    [${KIT_VERSION_SUPPORTED.join(", ")}]`);
+
+  // Validate range
+  if (currentVersion < KIT_VERSION_SUPPORTED[0]) {
+    console.error(`\n✗ kitVersion ${currentVersion} is below minimum supported (${KIT_VERSION_SUPPORTED[0]})`);
+    console.error("  Manual migration required. See docs/portable-core.md.");
+    return { success: false, from: currentVersion, to: targetVersion, migrationsApplied: 0 };
+  }
+
+  if (currentVersion > targetVersion) {
+    console.error(`\n✗ kitVersion ${currentVersion} is above maximum supported (${targetVersion})`);
+    console.error("  Update the kit code to a newer version.");
+    return { success: false, from: currentVersion, to: targetVersion, migrationsApplied: 0 };
+  }
+
+  if (currentVersion === targetVersion) {
+    console.log(`\n✓ Already up to date (v${currentVersion}).`);
+    return { success: true, from: currentVersion, to: targetVersion, migrationsApplied: 0 };
+  }
+
+  // Apply sequential migrations
+  let applied = 0;
+  for (let v = currentVersion + 1; v <= targetVersion; v++) {
+    const migration = MIGRATIONS.get(v);
+    if (!migration) {
+      console.error(`\n✗ No migration found for v${v - 1} → v${v}`);
+      return { success: false, from: currentVersion, to: targetVersion, migrationsApplied: applied };
+    }
+
+    console.log(`\n  Applying: ${migration.label}`);
+    try {
+      migration.migrate(root, config);
+      applied++;
+      console.log(`  ✓ Done.`);
+    } catch (err) {
+      console.error(`  ✗ Failed: ${err.message}`);
+      return { success: false, from: currentVersion, to: targetVersion, migrationsApplied: applied };
+    }
+  }
+
+  // Update kitVersion in config file
+  const configPath = join(root, "kit.config.json");
+  const raw = JSON.parse(readFileSync(configPath, "utf8"));
+  raw.kitVersion = targetVersion;
+  writeFileSync(configPath, JSON.stringify(raw, null, 2) + "\n");
+
+  console.log(`\n✓ Migrated from v${currentVersion} to v${targetVersion} (${applied} migration${applied !== 1 ? "s" : ""}).`);
+  console.log("  Run: npm run kit:selftest");
+
+  return { success: true, from: currentVersion, to: targetVersion, migrationsApplied: applied };
+}
+
+// ── CLI entry point ──────────────────────────────────────────
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(import.meta.filename);
+if (isMain) {
+  const root = process.env.KIT_CONFIG
+    ? dirname(resolve(process.env.KIT_CONFIG))
+    : SCRIPT_ROOT;
+  const result = migrate(root);
+  process.exit(result.success ? 0 : 1);
+}