faf-mcp 2.0.1 → 2.1.1

package/project.faf

@@ -1,142 +1,40 @@
-faf_version: 2.5.0
-ai_scoring_system: 2025-09-20
-ai_score: 85%
-ai_confidence: HIGH
-ai_value: 30_seconds_replaces_20_minutes_of_questions
-ai_tldr:
-  project: faf-mcp - "USE>FAF™ - IANA-registered format (application/vnd.faf+yaml) • Universal AI context • MCP server for all platforms • Start with 'Use FAF'"
-  stack: CLI/TypeScript/TypeScript (tsc)/npm registry/Node.js
-  quality_bar: ZERO_ERRORS_F1_STANDARDS
-  current_focus: Production deployment preparation
-  your_role: Build features with perfect context
-instant_context:
-  what_building: USE>FAF™ - IANA-registered format (application/vnd.faf+yaml) • Universal AI context • MCP server for all platforms • Start with 'Use FAF'
-  tech_stack: CLI/TypeScript/TypeScript (tsc)/npm registry/Node.js
-  main_language: TypeScript
-  deployment: npm registry
-  key_files:
-    - package.json
-    - tsconfig.json
-context_quality:
-  slots_filled: 21/21 (100%)
-  ai_confidence: HIGH
-  handoff_ready: true
-  missing_context: []
+faf_version: "3.0"
 project:
   name: faf-mcp
-  goal: USE>FAF™ - IANA-registered format (application/vnd.faf+yaml) • Universal AI context • MCP server for all platforms • Start with 'Use FAF'
+  goal: The Interop MCP for Context. Universal .faf MCP server for Cursor, Windsurf, Cline, VS Code, and all MCP-compatible IDEs. IANA-registered application/vnd.faf+yaml. Start with "Use FAF".
   main_language: TypeScript
-  type: cli-ts
-  generated: 2025-11-13T20:02:03.291Z
-  mission: 🚀 Make Your AI Happy! 🧡 Trust-Driven 🤖
-  revolution: 30 seconds replaces 20 minutes of questions
-  brand: F1-Inspired Software Engineering - Championship AI Context
-ai_instructions:
-  how_to_start: Just USE FAF - Start every prompt with 'Use FAF to...' and MCP tools handle the rest
-  priority_order:
-    - 1. Read THIS .faf file first
-    - 2. Check CLAUDE.md for session context
-    - 3. Review package.json for dependencies
-  quick_commands:
-    - Use FAF to initialize your project
-    - Use FAF to sync my project.faf to all platforms
-    - Use FAF to score my AI-readiness
-  working_style:
-    code_first: true
-    explanations: minimal
-    quality_bar: zero_errors
-    testing: required
-  warnings:
-    - Never modify dial components without approval
-    - All TypeScript must pass strict mode
-    - Test coverage required for new features
+  type: mcp
+  framework: MCP SDK (TS)
 stack:
-  frontend: CLI
-  css_framework: None
-  ui_library: None
-  state_management: None
-  backend: Node.js
-  runtime: Node.js >=18.0.0
-  database: None
+  frontend: slotignored
+  css_framework: slotignored
+  ui_library: slotignored
+  state_management: slotignored
+  backend: MCP SDK (TS)
+  api_type: MCP (stdio/HTTP-SSE)
+  runtime: Node.js >=18
+  database: slotignored
+  connection: slotignored
+  hosting: Vercel
   build: TypeScript (tsc)
+  cicd: GitHub Actions
+  monorepo_tool: slotignored
   package_manager: npm
-  api_type: CLI
-  hosting: npm registry
-  cicd: Vercel
-  targetUser: developers
-  coreProblem: understanding project
-  missionPurpose: project documentation
-  packageManager: npm/yarn/pnpm
-  mainLanguage: JavaScript/TypeScript
-preferences:
-  quality_bar: zero_errors
-  commit_style: conventional_emoji
-  response_style: concise_code_first
-  explanation_level: minimal
-  communication: direct
-  testing: required
-  documentation: as_needed
-state:
-  phase: development
-  version: 2.0.0
-  focus: interop_mcp_for_context
-  status: green_flag
-  next_milestone: npm_publish_v2
-  blockers: null
-tags:
-  auto_generated:
-    - faf-mcp
-    - cli
-    - typescript
-    - typescript-(tsc)
-    - npm-registry
-    - node.js
-  smart_defaults:
-    - .faf
-    - ai-ready
-    - "2025"
-    - software
-    - open-source
-  user_defined: null
+  workspaces: slotignored
+  admin: slotignored
+  cache: slotignored
+  search: slotignored
+  storage: slotignored
 human_context:
   who: Developers using Claude, Cursor, Windsurf, VS Code, Cline, and any MCP-compatible IDE
-  what: Universal MCP server providing .faf context tools - 61 tools (25 core + 36 advanced), interop with AGENTS.md, .cursorrules, GEMINI.md
-  why: Eliminate the 20-minute AI context tax - give AI instant project understanding in 30 seconds
-  where: npm registry, MCP ecosystem, Claude Desktop, Cursor IDE, Windsurf Editor
-  when: Production/Stable - v2.0.0 WJTTC certified (309/309 tests, 9 suites)
+  what: Universal MCP server providing .faf context tools — 25 core + 36 advanced, interop with AGENTS.md, .cursorrules, GEMINI.md
+  why: Eliminate the 20-minute AI context tax — give AI instant project understanding in 30 seconds
+  where: Vercel web (faf-mcp.vercel.app) · npm · MCP Registry · any MCP-compatible IDE — people get it how they wish
+  when: Production/Stable — v2.0.0 WJTTC certified (309/309 tests, 9 suites)
   how: npx faf-mcp or npm install -g faf-mcp, then add to your MCP config
-  additional_context: IANA-registered format (application/vnd.faf+yaml), The Interop MCP for Context, HTTP-SSE transport for Cursor/Windsurf/Cline
-  context_score: 100
-  total_prd_score: 100
-  success_rate: 100%
-ai_scoring_details:
-  system_date: 2025-09-20
-  slot_based_percentage: 76
-  ai_score: 85
-  total_slots: 21
-  filled_slots: 16
-  scoring_method: Honest percentage - no fake minimums
-  trust_embedded: COUNT ONCE architecture - trust MY embedded scores
-faf_dna:
-  birth_dna: 22
-  birth_certificate: FAF-2025-FAFMCP-NR94
-  birth_date: 2025-11-13T20:02:03.306Z
-  current_score: 83
-projectName: faf-mcp
-projectGoal: faf-mcp | use>faf • IANA-registered format (application/vnd.faf+yaml) • Universal MCP server for Cursor, Windsurf, Cline, VS Code, and all platforms
-generated: 2025-12-18T20:38:25.477Z
-stack_signature: typescript-nodejs-javascript
-detected_frameworks:
-  - Jest
-  - Node.js
-  - JavaScript
-  - TypeScript
-  - Vercel
-  - npm
-turbo_cat_intelligence: 360
-stats:
-  last_auto_time: 0.6
-  times_run: 1
-metadata:
-  last_claude_sync: 2026-03-07T17:36:56.430Z
-  bi_sync: active
+monorepo:
+  packages_count: slotignored
+  build_orchestrator: slotignored
+  versioning_strategy: slotignored
+  shared_configs: slotignored
+  remote_cache: slotignored

package/scripts/check-stylesheet-drift.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * faf-mcp · style-sheet drift check
+ *
+ * Contract: docs/style-source.html is the canonical visual vROM.
+ * Every surface carries a sentinel-wrapped copy of the :root token block.
+ * This gate verifies the BRAND SIGNATURE (token name→value map, whitespace
+ * & case normalized) is identical across surfaces — fast, non-visual.
+ *
+ * It checks the vocabulary (right tokens, right values, none missing, none
+ * extra). It does NOT check which element uses which token — that needs
+ * rendering, which is deliberately out of scope. Vocabulary integrity at
+ * zero cost.
+ *
+ * Exit 1 on drift. Rogue off-palette hex outside the token block = warn only.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const SOURCE = 'docs/style-source.html';
+const SURFACES = ['docs/index.html', 'api/index.ts'];
+
+const OPEN = '/* === faf-mcp:stylesheet canonical';
+const CLOSE = '/* === /faf-mcp:stylesheet canonical === */';
+
+function extractBlock(file) {
+  const text = readFileSync(join(ROOT, file), 'utf8');
+  const i = text.indexOf(OPEN);
+  const j = text.indexOf(CLOSE);
+  if (i === -1 || j === -1 || j < i) {
+    return null; // surface not wired
+  }
+  return text.slice(i, j + CLOSE.length);
+}
+
+// name -> normalized value (whitespace stripped, lowercased)
+function signature(block) {
+  const map = {};
+  const re = /--([\w-]+)\s*:\s*([^;]+);/g;
+  let m;
+  while ((m = re.exec(block)) !== null) {
+    map[m[1]] = m[2].replace(/\s+/g, '').toLowerCase();
+  }
+  return map;
+}
+
+function diff(srcSig, surfSig) {
+  const out = [];
+  const keys = new Set([...Object.keys(srcSig), ...Object.keys(surfSig)]);
+  for (const k of [...keys].sort()) {
+    if (!(k in surfSig)) out.push(`  - missing --${k} (source: ${srcSig[k]})`);
+    else if (!(k in srcSig)) out.push(`  - extra   --${k} (surface: ${surfSig[k]})`);
+    else if (srcSig[k] !== surfSig[k])
+      out.push(`  - drift   --${k}: source ${srcSig[k]} ≠ surface ${surfSig[k]}`);
+  }
+  return out;
+}
+
+const srcBlock = extractBlock(SOURCE);
+if (!srcBlock) {
+  console.error(`✗ canonical block not found in source ${SOURCE}`);
+  process.exit(1);
+}
+const srcSig = signature(srcBlock);
+const palette = new Set(
+  Object.values(srcSig)
+    .join(' ')
+    .match(/#[0-9a-f]{3,8}/g) || []
+);
+
+let failed = false;
+for (const surface of SURFACES) {
+  const block = extractBlock(surface);
+  if (!block) {
+    console.error(`✗ ${surface}: canonical block missing — surface not wired`);
+    failed = true;
+    continue;
+  }
+  const d = diff(srcSig, signature(block));
+  if (d.length) {
+    console.error(`✗ ${surface}: brand signature drift\n${d.join('\n')}`);
+    failed = true;
+  } else {
+    console.log(`✓ ${surface}: brand signature matches canonical`);
+  }
+
+  // warn-only: off-palette hex outside the token block.
+  // Only meaningful for single-surface .html files; a multi-page server
+  // file (.ts) legitimately hosts sibling pages with their own palettes,
+  // so the signature gate above is the real check there.
+  if (surface.endsWith('.html')) {
+    const text = readFileSync(join(ROOT, surface), 'utf8');
+    const i = text.indexOf(OPEN);
+    const j = text.indexOf(CLOSE);
+    const outside = text.slice(0, i) + text.slice(j + CLOSE.length);
+    const rogue = [
+      ...new Set(
+        (outside.match(/#[0-9a-fA-F]{6}\b/g) || []).map((h) => h.toLowerCase())
+      ),
+    ].filter((h) => !palette.has(h));
+    if (rogue.length) {
+      console.warn(`  ⚠ ${surface}: off-palette hex outside token block: ${rogue.join(', ')}`);
+    }
+  }
+}
+
+if (failed) {
+  console.error('\nstyle-source drift gate FAILED — edit docs/style-source.html only, then re-sync surfaces.');
+  process.exit(1);
+}
+console.log('\nstyle-sheet drift gate PASSED — all surfaces derive from canonical.');