@vibecodetown/mcp-server 1.3.1 → 1.5.0

package/scripts/check-pr-scope.mjs

@@ -1,121 +1,121 @@
-import { execFileSync } from "node:child_process";
-
-function runGit(args) {
-  return execFileSync("git", args, { encoding: "utf8" });
-}
-
-function fail(msg) {
-  console.error(`[check-pr-scope] ${msg}`);
-  process.exit(1);
-}
-
-function parseArgs(argv) {
-  const out = {
-    mode: null,
-    base: null,
-  };
-
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--mode") out.mode = argv[i + 1] ?? null, i++;
-    else if (a.startsWith("--mode=")) out.mode = a.slice("--mode=".length);
-    else if (a === "--base") out.base = argv[i + 1] ?? null, i++;
-    else if (a.startsWith("--base=")) out.base = a.slice("--base=".length);
-  }
-
-  if (!out.mode) {
-    fail("missing --mode (source|artifacts|bin)");
-  }
-  return out;
-}
-
-function resolveDefaultBase() {
-  try {
-    runGit(["rev-parse", "--verify", "origin/main"]);
-    return "origin/main";
-  } catch {
-    return "main";
-  }
-}
-
-function listChangedFiles(base) {
-  // Use triple-dot so changes are relative to merge-base (PR-like).
-  const raw = runGit(["diff", "--name-only", "--diff-filter=ACMRTUXB", `${base}...HEAD`]);
-  return raw
-    .split(/\r?\n/g)
-    .map((s) => s.trim())
-    .filter(Boolean);
-}
-
-function isAllowedForMode(mode, file) {
-  const allow = (prefixes) => prefixes.some((p) => file === p || file.startsWith(`${p}/`));
-
-  if (mode === "source") {
-    if (file === "package.json") return true;
-    if (file === "tsconfig.json") return true;
-    if (file === "vitest.config.ts") return true;
-    if (file === "README.md") return true;
-    if (file === "CHANGELOG.md") return true;
-    if (file === "BUILD_ARTIFACT_POLICY.md") return true;
-    if (file === "CLAUDE.md") return true;
-    if (file === ".gitignore") return true;
-    if (file === ".npmignore") return true;
+import { execFileSync } from "node:child_process";
+
+function runGit(args) {
+  return execFileSync("git", args, { encoding: "utf8" });
+}
+
+function fail(msg) {
+  console.error(`[check-pr-scope] ${msg}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const out = {
+    mode: null,
+    base: null,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--mode") out.mode = argv[i + 1] ?? null, i++;
+    else if (a.startsWith("--mode=")) out.mode = a.slice("--mode=".length);
+    else if (a === "--base") out.base = argv[i + 1] ?? null, i++;
+    else if (a.startsWith("--base=")) out.base = a.slice("--base=".length);
+  }
+
+  if (!out.mode) {
+    fail("missing --mode (source|artifacts|bin)");
+  }
+  return out;
+}
+
+function resolveDefaultBase() {
+  try {
+    runGit(["rev-parse", "--verify", "origin/main"]);
+    return "origin/main";
+  } catch {
+    return "main";
+  }
+}
+
+function listChangedFiles(base) {
+  // Use triple-dot so changes are relative to merge-base (PR-like).
+  const raw = runGit(["diff", "--name-only", "--diff-filter=ACMRTUXB", `${base}...HEAD`]);
+  return raw
+    .split(/\r?\n/g)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function isAllowedForMode(mode, file) {
+  const allow = (prefixes) => prefixes.some((p) => file === p || file.startsWith(`${p}/`));
+
+  if (mode === "source") {
+    if (file === "package.json") return true;
+    if (file === "tsconfig.json") return true;
+    if (file === "vitest.config.ts") return true;
+    if (file === "README.md") return true;
+    if (file === "CHANGELOG.md") return true;
+    if (file === "BUILD_ARTIFACT_POLICY.md") return true;
+    if (file === "CLAUDE.md") return true;
+    if (file === ".gitignore") return true;
+    if (file === ".npmignore") return true;
     if (allow(["src", "tests", "scripts", "schemas", "templates", "skills", "config", "docs", ".github", "engines"])) return true;
-
-    // Explicitly forbidden in a source-only PR.
-    if (allow(["build", "bin"])) return false;
-    if (file === "package-lock.json") return false;
-
-    // Default deny (forces explicit discussion for new top-level changes).
-    return false;
-  }
-
-  if (mode === "artifacts") {
-    if (allow(["build"])) return true;
-    if (file === "package-lock.json") return true;
-    return false;
-  }
-
-  if (mode === "bin") {
-    if (allow(["bin"])) return true;
-    return false;
-  }
-
-  fail(`unknown mode: ${mode}`);
-}
-
-function main() {
-  try {
-    const inside = runGit(["rev-parse", "--is-inside-work-tree"]).trim();
-    if (inside !== "true") fail("not inside a git work tree");
-  } catch {
-    fail("git not available");
-  }
-
-  const args = parseArgs(process.argv.slice(2));
-  const base = args.base ?? process.env.SCOPE_BASE ?? resolveDefaultBase();
-  const mode = args.mode;
-
-  const changed = listChangedFiles(base);
-  if (changed.length === 0) {
-    console.error(`[check-pr-scope] OK (${mode}): no changes detected vs ${base}`);
-    return;
-  }
-
-  const outOfScope = changed.filter((f) => !isAllowedForMode(mode, f));
-  if (outOfScope.length > 0) {
-    console.error(`[check-pr-scope] FAIL (${mode}): out-of-scope files detected vs ${base}`);
-    for (const f of outOfScope) console.error(`- ${f}`);
-    console.error("");
-    console.error("[check-pr-scope] Hint:");
-    console.error("- source PR: src/** + tests/** (+ small docs/config), no build/**, no package-lock.json, no bin/**");
-    console.error("- artifacts PR: build/** (+ package-lock.json if required), nothing else");
-    console.error("- bin PR: bin/** only");
-    process.exit(2);
-  }
-
-  console.error(`[check-pr-scope] OK (${mode}): ${changed.length} files within scope vs ${base}`);
-}
-
-main();
-
+
+    // Explicitly forbidden in a source-only PR.
+    if (allow(["build", "bin"])) return false;
+    if (file === "package-lock.json") return false;
+
+    // Default deny (forces explicit discussion for new top-level changes).
+    return false;
+  }
+
+  if (mode === "artifacts") {
+    if (allow(["build"])) return true;
+    if (file === "package-lock.json") return true;
+    return false;
+  }
+
+  if (mode === "bin") {
+    if (allow(["bin"])) return true;
+    return false;
+  }
+
+  fail(`unknown mode: ${mode}`);
+}
+
+function main() {
+  try {
+    const inside = runGit(["rev-parse", "--is-inside-work-tree"]).trim();
+    if (inside !== "true") fail("not inside a git work tree");
+  } catch {
+    fail("git not available");
+  }
+
+  const args = parseArgs(process.argv.slice(2));
+  const base = args.base ?? process.env.SCOPE_BASE ?? resolveDefaultBase();
+  const mode = args.mode;
+
+  const changed = listChangedFiles(base);
+  if (changed.length === 0) {
+    console.error(`[check-pr-scope] OK (${mode}): no changes detected vs ${base}`);
+    return;
+  }
+
+  const outOfScope = changed.filter((f) => !isAllowedForMode(mode, f));
+  if (outOfScope.length > 0) {
+    console.error(`[check-pr-scope] FAIL (${mode}): out-of-scope files detected vs ${base}`);
+    for (const f of outOfScope) console.error(`- ${f}`);
+    console.error("");
+    console.error("[check-pr-scope] Hint:");
+    console.error("- source PR: src/** + tests/** (+ small docs/config), no build/**, no package-lock.json, no bin/**");
+    console.error("- artifacts PR: build/** (+ package-lock.json if required), nothing else");
+    console.error("- bin PR: bin/** only");
+    process.exit(2);
+  }
+
+  console.error(`[check-pr-scope] OK (${mode}): ${changed.length} files within scope vs ${base}`);
+}
+
+main();
+

package/scripts/check-template-runner-contract.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT = process.cwd();
+
+function fail(message) {
+  console.error(`[template-runner-check] ${message}`);
+  process.exit(1);
+}
+
+const schemaPath = path.resolve(ROOT, 'schemas/template-run.session.v1.schema.json');
+if (!fs.existsSync(schemaPath)) {
+  fail(`missing schema file: ${schemaPath}`);
+}
+
+const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+if (schema?.$id !== 'template-run.session.v1') {
+  fail(`schema $id mismatch: expected template-run.session.v1, got ${schema?.$id}`);
+}
+if (!schema?.properties || typeof schema.properties !== 'object') {
+  fail('schema properties are missing');
+}
+for (const key of ['run_id', 'template_id', 'status', 'steps', 'timeline', 'screenshot_artifacts']) {
+  if (!(key in schema.properties)) {
+    fail(`schema is missing required property '${key}'`);
+  }
+}
+
+const templatesToolPath = path.resolve(ROOT, 'src/mcp/tools/templates.ts');
+if (!fs.existsSync(templatesToolPath)) {
+  fail(`missing templates tool source: ${templatesToolPath}`);
+}
+const templatesToolSource = fs.readFileSync(templatesToolPath, 'utf8');
+for (const token of [
+  'system.template_run_start',
+  'system.template_run_status',
+  'system.template_run_recover',
+  'system.template_run_maintenance',
+  'template-run.session.v1',
+  'screenshot_artifacts',
+  'MUSU_TEMPLATE_ALLOWED_TOOL_PREFIXES',
+]) {
+  if (!templatesToolSource.includes(token)) {
+    fail(`templates.ts is missing required runner token '${token}'`);
+  }
+}
+
+const registryTestPath = path.resolve(ROOT, 'tests/mcp/tool_registry_shape_contract.test.ts');
+if (!fs.existsSync(registryTestPath)) {
+  fail(`missing registry contract test: ${registryTestPath}`);
+}
+const registryTestSource = fs.readFileSync(registryTestPath, 'utf8');
+for (const name of [
+  'system.template_run_start',
+  'system.template_run_status',
+  'system.template_run_recover',
+  'system.template_run_maintenance',
+]) {
+  if (!registryTestSource.includes(name)) {
+    fail(`registry contract test snapshot missing '${name}'`);
+  }
+}
+
+console.error('[template-runner-check] OK');

package/scripts/check-template-ui-contract-sync.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+const ROOT = process.cwd();
+const REPO_ROOT = path.resolve(ROOT, '..', '..');
+const templatesPath = path.resolve(ROOT, 'catalogs/templates.json');
+const defaultRegistryPaths = [
+  '/home/hugh/design_work/unified-uiux/registry/screens.yaml',
+  '/home/hugh/hivelink-design/unified-uiux/registry/screens.yaml',
+];
+const localSnapshotPath = path.resolve(ROOT, 'catalogs/hivelink_screens.snapshot.yaml');
+
+function pickRegistryPath() {
+  const env = process.env.HIVELINK_UI_REGISTRY_PATH?.trim();
+  if (env && fs.existsSync(env)) return env;
+  for (const candidate of defaultRegistryPaths) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  if (fs.existsSync(localSnapshotPath)) return localSnapshotPath;
+  return null;
+}
+
+function fail(message) {
+  console.error(`[template-sync] ${message}`);
+  process.exit(1);
+}
+
+function resolveEvidencePath(evidenceRef) {
+  const direct = path.resolve(ROOT, evidenceRef);
+  if (fs.existsSync(direct)) return direct;
+  const repoRootRef = path.resolve(REPO_ROOT, evidenceRef);
+  if (fs.existsSync(repoRootRef)) return repoRootRef;
+  return null;
+}
+
+function resolveMaybeRelative(baseDir, refPath) {
+  if (!refPath) return null;
+  const raw = refPath.trim().replace(/^`|`$/g, '').replace(/^"|"$/g, '').replace(/^'|'$/g, '');
+  if (!raw) return null;
+  if (path.isAbsolute(raw)) {
+    return fs.existsSync(raw) ? raw : null;
+  }
+  const fromEvidence = path.resolve(baseDir, raw);
+  if (fs.existsSync(fromEvidence)) return fromEvidence;
+  const fromRepoRoot = path.resolve(REPO_ROOT, raw);
+  if (fs.existsSync(fromRepoRoot)) return fromRepoRoot;
+  const fromMcpRoot = path.resolve(ROOT, raw);
+  if (fs.existsSync(fromMcpRoot)) return fromMcpRoot;
+  return null;
+}
+
+if (!fs.existsSync(templatesPath)) {
+  fail(`templates catalog missing: ${templatesPath}`);
+}
+
+const registryPath = pickRegistryPath();
+if (!registryPath) {
+  fail(
+    `registry not found. Set HIVELINK_UI_REGISTRY_PATH or provide ${localSnapshotPath}`,
+  );
+}
+
+const templatesDoc = JSON.parse(fs.readFileSync(templatesPath, 'utf8'));
+if (templatesDoc.schema_version !== 'template-catalog.v1.1') {
+  fail(
+    `templates schema_version must be template-catalog.v1.1 (got ${templatesDoc.schema_version})`,
+  );
+}
+
+const registryRaw = fs.readFileSync(registryPath, 'utf8');
+const registryDoc = parseYaml(registryRaw) ?? {};
+const screens = Array.isArray(registryDoc.screens) ? registryDoc.screens : [];
+const registryIds = new Set(
+  screens
+    .map((screen) => (screen && typeof screen.id === 'string' ? screen.id : null))
+    .filter((id) => typeof id === 'string' && id.length > 0),
+);
+
+const errors = [];
+let uiContractTemplates = 0;
+
+for (const template of templatesDoc.templates ?? []) {
+  if (!template.ui_contract) continue;
+  uiContractTemplates += 1;
+
+  const ids = Array.isArray(template.ui_contract.screen_ids)
+    ? template.ui_contract.screen_ids
+    : [];
+
+  if (ids.length === 0) {
+    errors.push(`${template.id}: ui_contract.screen_ids is empty`);
+    continue;
+  }
+
+  for (const screenId of ids) {
+    if (!registryIds.has(screenId)) {
+      errors.push(`${template.id}: unknown screen_id '${screenId}'`);
+    }
+  }
+
+  const evidenceRef =
+    typeof template.ui_contract.screenshot_evidence_ref === 'string'
+      ? template.ui_contract.screenshot_evidence_ref.trim()
+      : '';
+  if (!evidenceRef) {
+    errors.push(`${template.id}: screenshot_evidence_ref is required for ui_contract templates`);
+    continue;
+  }
+
+  const evidencePath = resolveEvidencePath(evidenceRef);
+  if (!evidencePath) {
+    errors.push(`${template.id}: evidence file not found '${evidenceRef}'`);
+    continue;
+  }
+
+  const evidenceText = fs.readFileSync(evidencePath, 'utf8');
+  if (!/desktop/i.test(evidenceText)) {
+    errors.push(`${template.id}: evidence file '${evidenceRef}' missing desktop section`);
+  }
+  if (!/mobile/i.test(evidenceText)) {
+    errors.push(`${template.id}: evidence file '${evidenceRef}' missing mobile section`);
+  }
+
+  const evidenceDir = path.dirname(evidencePath);
+  const artifactRegex = /(desktop_artifact|mobile_artifact)\s*:\s*(.+)/g;
+  const desktopArtifacts = [];
+  const mobileArtifacts = [];
+  let match;
+  while ((match = artifactRegex.exec(evidenceText)) !== null) {
+    const kind = match[1];
+    const ref = match[2].trim();
+    const resolved = resolveMaybeRelative(evidenceDir, ref);
+    if (!resolved) {
+      errors.push(`${template.id}: artifact not found '${ref}' from evidence '${evidenceRef}'`);
+      continue;
+    }
+    if (kind === 'desktop_artifact') {
+      desktopArtifacts.push(ref);
+    } else {
+      mobileArtifacts.push(ref);
+    }
+  }
+
+  if (desktopArtifacts.length === 0) {
+    errors.push(`${template.id}: evidence '${evidenceRef}' missing desktop_artifact entries`);
+  }
+  if (mobileArtifacts.length === 0) {
+    errors.push(`${template.id}: evidence '${evidenceRef}' missing mobile_artifact entries`);
+  }
+}
+
+console.error(
+  `[template-sync] templates=${templatesDoc.templates.length}, ui_contract_templates=${uiContractTemplates}, registry_ids=${registryIds.size}, registry_path=${registryPath}`,
+);
+
+if (errors.length > 0) {
+  for (const err of errors) {
+    console.error(`[template-sync] ERROR ${err}`);
+  }
+  process.exit(1);
+}
+
+console.error('[template-sync] OK');

package/scripts/clean-build.mjs

@@ -1,20 +1,20 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const projectRoot = path.resolve(__dirname, "..");
-const buildDir = path.join(projectRoot, "build");
-
-try {
-  if (fs.existsSync(buildDir)) {
-    fs.rmSync(buildDir, { recursive: true, force: true });
-  }
-} catch (e) {
-  // Best-effort: do not block builds on cleanup failures.
-  // tsc will still fail if the output dir is not writable.
-  console.error("[clean-build] failed:", e instanceof Error ? e.message : String(e));
-}
-
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const projectRoot = path.resolve(__dirname, "..");
+const buildDir = path.join(projectRoot, "build");
+
+try {
+  if (fs.existsSync(buildDir)) {
+    fs.rmSync(buildDir, { recursive: true, force: true });
+  }
+} catch (e) {
+  // Best-effort: do not block builds on cleanup failures.
+  // tsc will still fail if the output dir is not writable.
+  console.error("[clean-build] failed:", e instanceof Error ? e.message : String(e));
+}
+

package/scripts/diagram-render-metrics-report.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const METRICS_FILE = "render_metrics.json";
+
+function parseArgs(argv) {
+  const args = new Map();
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    if (!key.startsWith("--")) continue;
+    const value = argv[i + 1];
+    if (typeof value === "string" && !value.startsWith("--")) {
+      args.set(key, value);
+      i += 1;
+    } else {
+      args.set(key, "true");
+    }
+  }
+  return args;
+}
+
+function inferRunId(filePath) {
+  const normalized = filePath.replaceAll("\\", "/");
+  const marker = "/.vibe/runs/";
+  const idx = normalized.indexOf(marker);
+  if (idx < 0) return null;
+  const remain = normalized.slice(idx + marker.length);
+  const runId = remain.split("/")[0];
+  return runId || null;
+}
+
+function safeNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+async function walk(dir, out) {
+  let entries = [];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walk(fullPath, out);
+      continue;
+    }
+    if (entry.isFile() && entry.name === METRICS_FILE) {
+      out.push(fullPath);
+    }
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = path.resolve(args.get("--root") ?? path.join(process.cwd(), ".vibe", "runs"));
+  const summaryPath = path.resolve(
+    args.get("--summary") ??
+      path.join(process.cwd(), ".vibe", "reports", "diagram_render_metrics_summary.v1.json")
+  );
+  const jsonlPath = path.resolve(
+    args.get("--jsonl") ??
+      path.join(process.cwd(), ".vibe", "reports", "diagram_render_metrics_records.v1.jsonl")
+  );
+
+  const files = [];
+  await walk(root, files);
+
+  const records = [];
+  for (const filePath of files) {
+    try {
+      const raw = await fs.readFile(filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      const cacheHits = safeNumber(parsed.cache_hits);
+      const cacheMisses = safeNumber(parsed.cache_misses);
+      const renderSuccess = safeNumber(parsed.render_success);
+      const renderErrors = safeNumber(parsed.render_errors);
+      const totalLatencyMs = safeNumber(parsed.total_latency_ms);
+      const lastLatencyMs = safeNumber(parsed.last_latency_ms);
+      const requestCount = cacheHits + cacheMisses;
+      const renderAttempts = renderSuccess + renderErrors;
+
+      records.push({
+        schema_version: "diagram.render.metrics.record.v1",
+        source_path: filePath,
+        run_id: inferRunId(filePath),
+        updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : null,
+        request_count: requestCount,
+        cache_hits: cacheHits,
+        cache_misses: cacheMisses,
+        cache_hit_ratio: requestCount > 0 ? cacheHits / requestCount : 0,
+        render_attempts: renderAttempts,
+        render_success: renderSuccess,
+        render_errors: renderErrors,
+        render_success_ratio: renderAttempts > 0 ? renderSuccess / renderAttempts : 0,
+        total_latency_ms: totalLatencyMs,
+        last_latency_ms: lastLatencyMs,
+        avg_request_latency_ms: requestCount > 0 ? totalLatencyMs / requestCount : 0,
+      });
+    } catch {
+      // Skip invalid files; keep report generation fail-open.
+    }
+  }
+
+  const totals = records.reduce(
+    (acc, row) => {
+      acc.request_count += row.request_count;
+      acc.cache_hits += row.cache_hits;
+      acc.cache_misses += row.cache_misses;
+      acc.render_attempts += row.render_attempts;
+      acc.render_success += row.render_success;
+      acc.render_errors += row.render_errors;
+      acc.total_latency_ms += row.total_latency_ms;
+      return acc;
+    },
+    {
+      request_count: 0,
+      cache_hits: 0,
+      cache_misses: 0,
+      render_attempts: 0,
+      render_success: 0,
+      render_errors: 0,
+      total_latency_ms: 0,
+    }
+  );
+
+  const summary = {
+    schema_version: "diagram.render.metrics.summary.v1",
+    generated_at: new Date().toISOString(),
+    source_root: root,
+    files_scanned: files.length,
+    files_valid: records.length,
+    totals: {
+      ...totals,
+      cache_hit_ratio: totals.request_count > 0 ? totals.cache_hits / totals.request_count : 0,
+      render_success_ratio:
+        totals.render_attempts > 0 ? totals.render_success / totals.render_attempts : 0,
+      avg_request_latency_ms:
+        totals.request_count > 0 ? totals.total_latency_ms / totals.request_count : 0,
+    },
+  };
+
+  await fs.mkdir(path.dirname(summaryPath), { recursive: true });
+  await fs.writeFile(summaryPath, `${JSON.stringify(summary, null, 2)}\n`, "utf-8");
+
+  await fs.mkdir(path.dirname(jsonlPath), { recursive: true });
+  const jsonl = records.map((row) => JSON.stringify(row)).join("\n");
+  await fs.writeFile(jsonlPath, jsonl.length > 0 ? `${jsonl}\n` : "", "utf-8");
+
+  console.log(
+    `[diagram-render-metrics-report] files=${files.length} valid=${records.length} summary=${summaryPath} jsonl=${jsonlPath}`
+  );
+}
+
+main().catch((error) => {
+  console.error(`[diagram-render-metrics-report] failed: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});
+