@mcptoolshop/promo-kit 0.1.0

package/scripts/kit-selftest.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+/**
+ * Kit Self-Test
+ *
+ * Validates the kit installation: config, seeds, invariants, dry-runs, build.
+ *
+ * Usage:
+ *   node scripts/kit-selftest.mjs [--skip-build] [--skip-invariants]
+ *
+ * Environment:
+ *   KIT_CONFIG=/path/to/kit.config.json — point at an alternate config root
+ */
+
+import { existsSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { execSync } from "node:child_process";
+import { loadKitConfig, KIT_VERSION_SUPPORTED } from "./lib/config.mjs";
+
+const SCRIPT_ROOT = resolve(import.meta.dirname, ".."); // where scripts live
+const DATA_ROOT = process.env.KIT_CONFIG
+  ? dirname(resolve(process.env.KIT_CONFIG))
+  : SCRIPT_ROOT;
+
+// Auto-skip when running from npm package (dirs don't exist)
+const autoSkipInvariants = !existsSync(join(SCRIPT_ROOT, "tests", "invariants"));
+const autoSkipBuild = !existsSync(join(SCRIPT_ROOT, "site"));
+
+const skipBuild = process.argv.includes("--skip-build") || autoSkipBuild;
+const skipInvariants = process.argv.includes("--skip-invariants") || autoSkipInvariants;
+
+// ── Test runner ──────────────────────────────────────────────
+
+const results = [];
+
+function check(label, fn) {
+  try {
+    fn();
+    results.push({ label, pass: true });
+    console.log(`  ✓ ${label}`);
+  } catch (err) {
+    results.push({ label, pass: false, error: err.message });
+    console.log(`  ✗ ${label}: ${err.message}`);
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+// ── Tests ────────────────────────────────────────────────────
+
+console.log("Kit Self-Test");
+console.log("=".repeat(40));
+if (DATA_ROOT !== SCRIPT_ROOT) {
+  console.log(`  Config root: ${DATA_ROOT}`);
+  console.log(`  Script root: ${SCRIPT_ROOT}`);
+}
+
+// 1. Config
+console.log("\n[Config]");
+
+check("kit.config.json exists", () => {
+  const configPath = join(DATA_ROOT, "kit.config.json");
+  assert(
+    existsSync(configPath),
+    `kit.config.json not found at ${configPath}. Fix: create it or set KIT_CONFIG=/path/to/kit.config.json`
+  );
+});
+
+let config;
+check("kit.config.json is valid JSON with required fields", () => {
+  config = loadKitConfig(DATA_ROOT);
+  assert(config.kitVersion, "kitVersion missing");
+  assert(config.org?.name || config.org?.account, "org name or account missing");
+  assert(config.site?.title, "site.title missing");
+  assert(config.paths?.dataDir, "paths.dataDir missing");
+  assert(config.paths?.publicDir, "paths.publicDir missing");
+});
+
+check("kitVersion in supported range", () => {
+  const v = config.kitVersion;
+  assert(
+    v >= KIT_VERSION_SUPPORTED[0] && v <= KIT_VERSION_SUPPORTED[1],
+    `kitVersion ${v} not in [${KIT_VERSION_SUPPORTED.join(", ")}]`
+  );
+});
+
+// 2. Seed files
+console.log("\n[Seed Files]");
+
+const coreSeedFiles = [
+  "governance.json",
+  "promo-queue.json",
+  "experiments.json",
+  "submissions.json",
+  "overrides.json",
+  "ops-history.json",
+  "worthy.json",
+  "promo-decisions.json",
+  "experiment-decisions.json",
+  "baseline.json",
+  "feedback-summary.json",
+  "queue-health.json",
+  "recommendations.json",
+  "recommendation-patch.json",
+  "decision-drift.json",
+];
+
+for (const file of coreSeedFiles) {
+  check(`${file} exists`, () => {
+    const fullPath = join(DATA_ROOT, config.paths.dataDir, file);
+    assert(existsSync(fullPath), `Missing: ${fullPath}. Fix: run npm run kit:init`);
+  });
+}
+
+// 3. Invariant tests
+if (!skipInvariants) {
+  console.log("\n[Invariant Tests]");
+
+  check("invariant tests pass", () => {
+    try {
+      execSync("node --test tests/invariants/*.test.mjs", {
+        cwd: SCRIPT_ROOT,
+        stdio: "pipe",
+        timeout: 60000,
+        env: { ...process.env },
+      });
+    } catch (err) {
+      throw new Error(`Invariant tests failed: ${err.stderr?.toString().slice(-200) || err.message}`);
+    }
+  });
+} else {
+  console.log("\n[Invariant Tests] Skipped (--skip-invariants)");
+}
+
+// 4. Core dry-runs
+console.log("\n[Core Dry-Runs]");
+
+const dryRunScripts = [
+  "scripts/gen-promo-decisions.mjs",
+  "scripts/gen-experiment-decisions.mjs",
+  "scripts/gen-baseline.mjs",
+  "scripts/gen-feedback-summary.mjs",
+  "scripts/gen-queue-health.mjs",
+  "scripts/gen-telemetry-aggregate.mjs",
+  "scripts/gen-recommendations.mjs",
+  "scripts/gen-recommendation-patch.mjs",
+  "scripts/gen-decision-drift.mjs",
+  "scripts/gen-trust-receipt.mjs",
+];
+
+for (const script of dryRunScripts) {
+  const name = script.split("/").pop();
+  check(`${name} --dry-run`, () => {
+    try {
+      execSync(`node ${script} --dry-run`, {
+        cwd: SCRIPT_ROOT,
+        stdio: "pipe",
+        timeout: 30000,
+        env: { ...process.env },
+      });
+    } catch (err) {
+      throw new Error(
+        `${name} failed. Fix: ensure kit:init has been run and data files exist. ` +
+        (err.stderr?.toString().slice(-200) || err.message)
+      );
+    }
+  });
+}
+
+// 5. Site build (optional)
+if (!skipBuild) {
+  console.log("\n[Site Build]");
+
+  check("Astro build succeeds", () => {
+    try {
+      execSync("npm run build", {
+        cwd: join(SCRIPT_ROOT, "site"),
+        stdio: "pipe",
+        timeout: 120000,
+      });
+    } catch (err) {
+      throw new Error(err.stderr?.toString().slice(-300) || err.message);
+    }
+  });
+} else {
+  console.log("\n[Site Build] Skipped (--skip-build)");
+}
+
+// ── Summary ──────────────────────────────────────────────────
+
+console.log("\n" + "=".repeat(40));
+const passed = results.filter((r) => r.pass).length;
+const failed = results.filter((r) => !r.pass).length;
+console.log(`Results: ${passed} passed, ${failed} failed, ${results.length} total`);
+
+if (failed > 0) {
+  console.log("\nFailed checks:");
+  results.filter((r) => !r.pass).forEach((r) => {
+    console.log(`  ✗ ${r.label}: ${r.error}`);
+  });
+  process.exit(1);
+} else {
+  console.log("\n✓ All checks passed.");
+  process.exit(0);
+}

package/scripts/lib/config.mjs

@@ -0,0 +1,124 @@
+/**
+ * Kit configuration loader.
+ *
+ * Reads kit.config.json from the repo root and deep-merges with defaults.
+ * All scripts in the portable core import from here instead of hardcoding values.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ── Defaults ─────────────────────────────────────────────────
+
+const DEFAULTS = {
+  kitVersion: 1,
+  org: { name: "", account: "", url: "" },
+  site: { title: "", url: "", description: "" },
+  repo: { marketing: "" },
+  contact: { email: "" },
+  paths: { dataDir: "site/src/data", publicDir: "site/public" },
+  guardrails: {
+    maxDataPatchesPerRun: 5,
+    dailyTelemetryCapPerType: 50,
+    spikeThreshold: 300,
+    maxRecommendations: 20,
+  },
+};
+
+export const KIT_VERSION_SUPPORTED = [1, 1]; // [min, max]
+
+// ── Deep merge ───────────────────────────────────────────────
+
+function deepMerge(base, override) {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (value && typeof value === "object" && !Array.isArray(value) && base[key] && typeof base[key] === "object") {
+      result[key] = deepMerge(base[key], value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// ── Loader ───────────────────────────────────────────────────
+
+/**
+ * Load kit config from a specific root directory.
+ * @param {string} root - repo root path
+ * @returns {object} merged config
+ */
+export function loadKitConfig(root) {
+  const configPath = join(root, "kit.config.json");
+  if (!existsSync(configPath)) {
+    return { ...DEFAULTS };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(configPath, "utf8"));
+    return deepMerge(DEFAULTS, raw);
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+// ── Cached singleton ─────────────────────────────────────────
+
+let _cached = null;
+let _cachedRoot = null;
+
+/**
+ * Find the kit root directory.
+ * Priority: KIT_CONFIG env var > walk up from scripts/lib/ > fallback 2 levels up.
+ */
+function findRoot() {
+  // 1. KIT_CONFIG env var takes precedence
+  if (process.env.KIT_CONFIG) {
+    const envPath = resolve(process.env.KIT_CONFIG);
+    if (existsSync(envPath)) return dirname(envPath);
+    console.warn(
+      `  \u26A0 KIT_CONFIG="${process.env.KIT_CONFIG}" not found, falling back to auto-discovery`
+    );
+  }
+
+  // 2. Walk up from scripts/lib/ looking for kit.config.json
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  let dir = thisDir;
+  for (let i = 0; i < 5; i++) {
+    if (existsSync(join(dir, "kit.config.json"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // 3. Fallback: assume scripts/lib/ is 2 levels deep from root
+  return resolve(thisDir, "..", "..");
+}
+
+/**
+ * Get the kit root directory. Prefers KIT_CONFIG env var, then auto-discovery.
+ * Use this for data/config path resolution in portable core scripts.
+ * @returns {string} absolute root path
+ */
+export function getRoot() {
+  return findRoot();
+}
+
+/**
+ * Get the kit config singleton. Discovers repo root automatically.
+ * @returns {object} merged config
+ */
+export function getConfig() {
+  const root = findRoot();
+  if (_cached && _cachedRoot === root) return _cached;
+  _cached = loadKitConfig(root);
+  _cachedRoot = root;
+  return _cached;
+}
+
+/**
+ * Reset the cached config (for testing).
+ */
+export function resetConfigCache() {
+  _cached = null;
+  _cachedRoot = null;
+}