@bonesofspring/ai-rules 0.2.22 → 0.2.24

package/scripts/check-mavis-platform-contract.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * Validate presets/mavis/platform-contract.json against architecture §3.4.
+ *
+ * Usage:
+ *   node scripts/check-mavis-platform-contract.mjs
+ *   node scripts/check-mavis-platform-contract.mjs --contract <path>
+ *   node scripts/check-mavis-platform-contract.mjs --self-test
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(scriptDirectory, '..');
+const defaultContractPath = path.join(
+  packageRoot,
+  'presets',
+  'mavis',
+  'platform-contract.json',
+);
+const fixtureDirectory = path.join(
+  scriptDirectory,
+  'fixtures',
+  'mavis-platform-contract',
+);
+
+const ALLOWED_STATUS = new Set([
+  'confirmed',
+  'partial',
+  'unknown',
+  'no-equivalent',
+]);
+const KNOWN_STACKS = new Set([
+  'next',
+  'nuxt',
+  'svelte',
+  'ios-swift',
+  'android-kotlin',
+  'go',
+  'java',
+  'mcp-ts',
+  'php-hexagonal',
+  'php-laravel',
+]);
+const REQUIRED_CAPABILITIES = [
+  'cliVersion',
+  'rootAgents',
+  'explicitAgentFile',
+  'structuredOutput',
+  'referencedRule',
+  'referencedSkill',
+  'freshInit',
+  'nativeProjectRules',
+  'nativeWorkspaceSkills',
+  'nativeWorkspaceAgents',
+  'projectMcp',
+  'projectHooks',
+  'slashCommands',
+  'pluginSkillMcp',
+  'nativeTeam',
+];
+const REQUIRED_ENTRY_PAIRS = [
+  { source: 'REPO_AGENTS.md', destination: 'AGENTS.md' },
+  { source: 'MAVIS.md', destination: '.mavis/AGENTS.md' },
+];
+const REQUIRED_DIRECTORY_SOURCES = [
+  'rules',
+  'agents',
+  'skills',
+  'commands',
+  'hooks',
+  'team',
+];
+const FORBIDDEN_PATH_RE =
+  /(?:^|[\\/])\.minimax(?:[\\/]|$)|(?:^|[\\/])\.minimax-code(?:[\\/]|$)|~\/\.minimax|\$HOME\/\.minimax/i;
+const VERSION_PIN_KEYS = new Set([
+  'requiredCliVersion',
+  'requiredDesktopVersion',
+  'minCliVersion',
+  'pinnedVersion',
+  'requiredVersion',
+]);
+const EVIDENCE_MARKER = 'MAVIS-COMPATIBILITY.md';
+
+export function validateContract(contract, options = {}) {
+  const failures = [];
+  const fail = (message) => {
+    failures.push(message);
+  };
+
+  if (contract === null || typeof contract !== 'object' || Array.isArray(contract)) {
+    return ['contract must be a JSON object'];
+  }
+
+  if (contract.schemaVersion !== 1) {
+    fail('schemaVersion must be 1');
+  }
+  if (contract.id !== 'mavis') {
+    fail('id must be "mavis"');
+  }
+  if (contract.runtimeExecutable !== 'mcode') {
+    fail('runtimeExecutable must be "mcode"');
+  }
+  if (contract.sourceRoot !== 'presets/mavis') {
+    fail('sourceRoot must be "presets/mavis"');
+  }
+  if (contract.managedRoot !== '.mavis') {
+    fail('managedRoot must be ".mavis"');
+  }
+  if (contract.cleanStrategy !== 'manifest-owned') {
+    fail('cleanStrategy must be "manifest-owned"');
+  }
+
+  for (const key of Object.keys(contract)) {
+    if (VERSION_PIN_KEYS.has(key)) {
+      fail(`forbidden version-pin key "${key}"`);
+    }
+  }
+
+  if (!Array.isArray(contract.releasedStacks)) {
+    fail('releasedStacks must be an array');
+  } else {
+    for (const stack of contract.releasedStacks) {
+      if (typeof stack !== 'string' || !KNOWN_STACKS.has(stack)) {
+        fail(`releasedStacks contains unknown stack "${stack}"`);
+        continue;
+      }
+      if (options.requireReleasedStackDir) {
+        const stackDir = path.join(packageRoot, 'presets', 'mavis', stack);
+        if (!fs.existsSync(stackDir)) {
+          fail(`released stack "${stack}" has no source directory ${stackDir}`);
+        }
+      }
+    }
+  }
+
+  if (!Array.isArray(contract.entryFiles)) {
+    fail('entryFiles must be an array');
+  } else {
+    const pairs = new Set(
+      contract.entryFiles.map((entry) => `${entry?.source}→${entry?.destination}`),
+    );
+    for (const required of REQUIRED_ENTRY_PAIRS) {
+      if (!pairs.has(`${required.source}→${required.destination}`)) {
+        fail(
+          `entryFiles must include ${required.source} → ${required.destination}`,
+        );
+      }
+    }
+    for (const [index, entry] of contract.entryFiles.entries()) {
+      if (!isSourceDestination(entry)) {
+        fail(`entryFiles[${index}] must have string source and destination`);
+        continue;
+      }
+      failIfForbiddenPath(fail, `entryFiles[${index}].destination`, entry.destination);
+      if (
+        entry.destination !== 'AGENTS.md' &&
+        !entry.destination.startsWith('.mavis/')
+      ) {
+        fail(
+          `entryFiles[${index}].destination must be AGENTS.md or under .mavis/`,
+        );
+      }
+    }
+  }
+
+  if (!Array.isArray(contract.directoryMappings)) {
+    fail('directoryMappings must be an array');
+  } else {
+    const sources = new Set(
+      contract.directoryMappings
+        .filter((entry) => entry && typeof entry.source === 'string')
+        .map((entry) => entry.source),
+    );
+    for (const source of REQUIRED_DIRECTORY_SOURCES) {
+      if (!sources.has(source)) {
+        fail(`directoryMappings must include source "${source}"`);
+      }
+    }
+    for (const [index, entry] of contract.directoryMappings.entries()) {
+      if (!isSourceDestination(entry)) {
+        fail(
+          `directoryMappings[${index}] must have string source and destination`,
+        );
+        continue;
+      }
+      failIfForbiddenPath(
+        fail,
+        `directoryMappings[${index}].destination`,
+        entry.destination,
+      );
+      if (!entry.destination.startsWith('.mavis/')) {
+        fail(
+          `directoryMappings[${index}].destination must start with .mavis/`,
+        );
+      }
+    }
+  }
+
+  const mcp = contract.mcp;
+  if (mcp === null || typeof mcp !== 'object' || Array.isArray(mcp)) {
+    fail('mcp must be an object');
+  } else {
+    if (mcp.source !== 'mcp.json') {
+      fail('mcp.source must be "mcp.json"');
+    }
+    if (mcp.fallbackDestination !== '.mavis/mcp.json') {
+      fail('mcp.fallbackDestination must be ".mavis/mcp.json"');
+    }
+    if (mcp.mode !== 'fallback-manual-import') {
+      fail('mcp.mode must be "fallback-manual-import"');
+    }
+    failIfForbiddenPath(fail, 'mcp.fallbackDestination', mcp.fallbackDestination);
+  }
+
+  const docsSeed = contract.docsSeed;
+  if (docsSeed === null || typeof docsSeed !== 'object' || Array.isArray(docsSeed)) {
+    fail('docsSeed must be an object');
+  } else {
+    if (docsSeed.source !== 'presets/_shared/assets/docs-specs') {
+      fail('docsSeed.source must be "presets/_shared/assets/docs-specs"');
+    }
+    if (docsSeed.behavior !== 'absent-only') {
+      fail('docsSeed.behavior must be "absent-only"');
+    }
+  }
+
+  const capabilities = contract.nativeCapabilities;
+  if (
+    capabilities === null ||
+    typeof capabilities !== 'object' ||
+    Array.isArray(capabilities)
+  ) {
+    fail('nativeCapabilities must be an object');
+  } else {
+    for (const key of REQUIRED_CAPABILITIES) {
+      if (!Object.hasOwn(capabilities, key)) {
+        fail(`nativeCapabilities missing required key "${key}"`);
+      }
+    }
+    for (const [key, capability] of Object.entries(capabilities)) {
+      if (capability === null || typeof capability !== 'object' || Array.isArray(capability)) {
+        fail(`nativeCapabilities.${key} must be an object`);
+        continue;
+      }
+      if (!ALLOWED_STATUS.has(capability.status)) {
+        fail(
+          `nativeCapabilities.${key}.status must be confirmed|partial|unknown|no-equivalent`,
+        );
+      }
+      if (
+        typeof capability.evidence !== 'string' ||
+        !capability.evidence.includes(EVIDENCE_MARKER)
+      ) {
+        fail(
+          `nativeCapabilities.${key}.evidence must reference ${EVIDENCE_MARKER}`,
+        );
+      }
+      const nativePath = capability.nativePath ?? null;
+      if (nativePath !== null && typeof nativePath !== 'string') {
+        fail(`nativeCapabilities.${key}.nativePath must be a string or null`);
+        continue;
+      }
+      if (
+        (capability.status === 'unknown' || capability.status === 'no-equivalent') &&
+        nativePath
+      ) {
+        fail(
+          `nativeCapabilities.${key} is ${capability.status} and cannot declare nativePath`,
+        );
+      }
+      if (nativePath) {
+        failIfForbiddenPath(fail, `nativeCapabilities.${key}.nativePath`, nativePath);
+      }
+    }
+  }
+
+  return failures;
+}
+
+function isSourceDestination(entry) {
+  return (
+    entry &&
+    typeof entry === 'object' &&
+    typeof entry.source === 'string' &&
+    entry.source.length > 0 &&
+    typeof entry.destination === 'string' &&
+    entry.destination.length > 0
+  );
+}
+
+function failIfForbiddenPath(fail, label, value) {
+  if (typeof value === 'string' && FORBIDDEN_PATH_RE.test(value)) {
+    fail(`${label} claims a MiniMax-native or home path: ${value}`);
+  }
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function printFailures(label, failures) {
+  for (const failure of failures) {
+    console.error(`FAIL ${label}: ${failure}`);
+  }
+}
+
+function runSelfTest() {
+  const cases = [
+    { name: 'valid.json', expectFail: false },
+    { name: 'invalid-unknown-native-path.json', expectFail: true },
+    { name: 'invalid-minimax-destination.json', expectFail: true },
+    { name: 'invalid-missing-capability.json', expectFail: true },
+    { name: 'invalid-released-unknown-stack.json', expectFail: true },
+    { name: 'invalid-version-pin.json', expectFail: true },
+  ];
+  let failed = 0;
+  for (const testCase of cases) {
+    const filePath = path.join(fixtureDirectory, testCase.name);
+    const failures = validateContract(readJson(filePath));
+    const didFail = failures.length > 0;
+    if (didFail !== testCase.expectFail) {
+      failed += 1;
+      console.error(
+        `FAIL self-test ${testCase.name}: expected ${
+          testCase.expectFail ? 'invalid' : 'valid'
+        }, got ${didFail ? 'invalid' : 'valid'}`,
+      );
+      printFailures(testCase.name, failures);
+    } else {
+      console.log(
+        `ok self-test ${testCase.name} (${didFail ? 'invalid' : 'valid'})`,
+      );
+    }
+  }
+  return failed;
+}
+
+function parseArgs(argv) {
+  const options = { contract: defaultContractPath, selfTest: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--self-test') {
+      options.selfTest = true;
+    } else if (arg === '--contract') {
+      options.contract = argv[index + 1];
+      index += 1;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  let exitCode = 0;
+
+  if (options.selfTest) {
+    exitCode = runSelfTest() === 0 ? 0 : 1;
+  }
+
+  if (!options.selfTest || exitCode === 0) {
+    const liveFailures = validateContract(readJson(options.contract), {
+      requireReleasedStackDir: options.contract === defaultContractPath,
+    });
+    if (liveFailures.length > 0) {
+      printFailures(path.relative(packageRoot, options.contract), liveFailures);
+      exitCode = 1;
+    } else if (!options.selfTest) {
+      console.log(`ok ${path.relative(packageRoot, options.contract)}`);
+    } else {
+      console.log('ok live platform-contract.json');
+    }
+  }
+
+  process.exit(exitCode);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`FAIL: ${error.message}`);
+    process.exit(1);
+  }
+}

package/scripts/check-mavis-token-budget.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Isolated Mavis token-budget analog. Does not change Cursor/Claude 3/4 caps.
+ * Root-entry rules in adapter-map.json must stay ≤ 4.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadReleasedMavisStacks } from './lib/discover-hooks.mjs';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const presetsRoot = path.join(scriptDirectory, '..', 'presets');
+const ROOT_ENTRY_CAP = 4;
+
+const stacks = loadReleasedMavisStacks(presetsRoot);
+if (stacks.length === 0) {
+  console.log('ok mavis token-budget: no released stacks');
+  process.exit(0);
+}
+
+let failed = 0;
+for (const stack of stacks) {
+  const mapPath = path.join(presetsRoot, 'mavis', stack, 'adapter-map.json');
+  if (!fs.existsSync(mapPath)) {
+    console.error(`FAIL mavis/${stack}: missing adapter-map.json`);
+    failed += 1;
+    continue;
+  }
+  const map = JSON.parse(fs.readFileSync(mapPath, 'utf8'));
+  const rootRules = (map.entries || []).filter(
+    (entry) =>
+      entry.category === 'rules' &&
+      entry.loadMode === 'root-entry' &&
+      entry.target,
+  );
+  if (rootRules.length > ROOT_ENTRY_CAP) {
+    console.error(
+      `FAIL mavis/${stack}: ${rootRules.length} root-entry rules (cap ${ROOT_ENTRY_CAP})`,
+    );
+    failed += 1;
+  } else {
+    console.log(
+      `ok mavis/${stack}: ${rootRules.length} root-entry rules (cap ${ROOT_ENTRY_CAP})`,
+    );
+  }
+}
+
+process.exit(failed === 0 ? 0 : 1);