@bonesofspring/ai-rules 0.2.25 → 0.2.26

package/scripts/lib/generate-mavis-adapter.mjs

@@ -0,0 +1,489 @@
+/**
+ * Derive presets/mavis/<stack>/** and adapter-map.json from cursor/<stack>.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  countAgentRoleFiles,
+  deriveAdapterStack,
+  dropLeadingHeading,
+  extractSkillsFragment,
+  isEmbedEntryBody,
+  readSiblingReadme,
+  replaceCursorFrontmatterReadonlyBlock,
+  rewriteAgentRosterCount,
+  rewriteConsumerRoot,
+  rewriteCursorModelPinBullet,
+  rewriteCursorPipelineIntro,
+  rewriteMdcToMd,
+  rewriteOrchestratorCursorNotes,
+  sharedCoreStem,
+  standardTierCell,
+  strongTierCell,
+  stripFrontmatter,
+  stripInstallSection,
+} from './generate-adapter-common.mjs';
+import { getStackProfile, parseStackArg } from './stack-platform-profiles.mjs';
+
+const libDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(libDirectory, '..', '..');
+const sharedCoreRoot = path.join(packageRoot, 'presets', '_shared', 'core');
+
+const OMIT = new Map([
+  [
+    'BUGBOT.md',
+    'no-equivalent: Bugbot is Cursor-only; review stays a Verifier skill/role',
+  ],
+  [
+    'hooks.json',
+    'omit until a documented MiniMax hook schema exists',
+  ],
+  [
+    'hooks/guard-shell-command.sh',
+    'omit from active wiring; safety policy stays in entry prose, not enforcement',
+  ],
+  [
+    'hooks/examples/format-edited.example.sh',
+    'omit until a Mavis hook event API is confirmed',
+  ],
+  [
+    'hooks/examples/secret-guard.example.sh',
+    'omit until a Mavis hook event API is confirmed',
+  ],
+  [
+    'hooks/examples/test-on-save.example.sh',
+    'omit until a Mavis hook event API is confirmed',
+  ],
+]);
+
+function rewriteConsumerPaths(text) {
+  return rewriteConsumerRoot(text, 'cursor', 'mavis');
+}
+
+function finalizeMavisProse(text, stack) {
+  return rewriteCursorModelPinBullet(
+    rewriteMdcToMd(rewriteConsumerPaths(text))
+      .replaceAll('init cursor --preset', 'init mavis --preset')
+      .replaceAll(`# MCP (preset \`${stack}\`, Cursor)`, `# MCP (preset \`${stack}\`, Mavis)`)
+      .replaceAll(`(preset \`${stack}\`, Cursor)`, `(preset \`${stack}\`, Mavis)`)
+      .replaceAll('Copied to `.cursor/mcp.json`', 'Staged at `.mavis/mcp.json`')
+      .replaceAll('OAuth in Cursor', 'OAuth in MiniMax Code (manual import)'),
+    '- omit on `standard` → operator default (no YAML `model` frontmatter)',
+  );
+}
+
+function transformOrchestrator(markdown) {
+  return rewriteOrchestratorCursorNotes(markdown, {
+    frontmatterLine:
+      '**Mavis packaging:** team pipeline agents are plain Markdown with no YAML frontmatter (`name`, `readonly`, `model`). Attach with `mcode exec --file`. Production/app restrictions live in the agent prompt body. See `agents/README.md`.',
+    stackNotes:
+      'Roles and write scopes — **`agents/README.md`**. Mavis agents have no YAML `readonly` / `model` frontmatter.',
+  });
+}
+
+function stripEmbeddedCatalogLine(body) {
+  return body.replace(
+    /^See `\.mavis\/rules\/README\.md` for the full catalog[^\n]*\n+/m,
+    '',
+  );
+}
+
+function transformMarkdown(sourceText, stack, { command = false, allowEmbedEntry = true } = {}) {
+  const rewriteProse = (text) => finalizeMavisProse(text, stack);
+  const { body } = stripFrontmatter(sourceText);
+  const stem =
+    allowEmbedEntry && isEmbedEntryBody(body) ? sharedCoreStem(body) : undefined;
+  let next;
+  if (stem) {
+    const corePath = path.join(sharedCoreRoot, stem);
+    if (!fs.existsSync(corePath)) {
+      // Silently rewriting the Cursor body here would ship stale prose for a typo'd stem.
+      throw new Error(`missing shared-core embed target _shared/core/${stem}`);
+    }
+    const coreBody = fs.readFileSync(corePath, 'utf8').trimEnd();
+    const marker = `<!-- shared-core: ${stem} -->`;
+    next = `${marker}\n\n${coreBody}\n`;
+    next = rewriteConsumerPaths(next);
+  } else {
+    next = rewriteProse(body);
+  }
+  if (command) {
+    next = next
+      .replaceAll('`/task-continue <slug>`', 'continue `<slug>` using `.mavis/commands/task-continue.md`')
+      .replaceAll('`/task-continue`', 'the task-continue procedure in `.mavis/commands/task-continue.md`')
+      .replaceAll('`/technical-retro`', 'the technical-retro procedure in `.mavis/commands/technical-retro.md`')
+      .replaceAll('`/spec-start`', 'the spec-start procedure in `.mavis/commands/spec-start.md`')
+      .replaceAll('`/task`', 'the task procedure in `.mavis/commands/task.md`');
+  }
+  return next.endsWith('\n') ? next : `${next}\n`;
+}
+
+function mavisEntryTitle(sourceText) {
+  const first = sourceText.split('\n')[0] || '';
+  const match = first.match(/^# (.+) — Cursor agent team\s*$/);
+  if (match) {
+    return `# ${match[1]} — Mavis agent team`;
+  }
+  return first.replace('Cursor', 'Mavis') || '# Mavis agent team';
+}
+
+function buildMavisEntry(sourceText, stack, profile) {
+  const rewriteProse = (text) => finalizeMavisProse(text, stack);
+  const body = stripEmbeddedCatalogLine(
+    stripInstallSection(
+      dropLeadingHeading(rewriteProse(stripFrontmatter(sourceText).body)),
+    ),
+  );
+  const essential = profile.alwaysOn
+    .map((stem) => `- \`.mavis/rules/${stem}.md\``)
+    .join('\n');
+  const skills = extractSkillsFragment(sourceText);
+  const skillsLine = skills
+    ? `${skills} Import MCP from \`.mavis/mcp.json\`\nin the MiniMax Code UI.`
+    : 'Import MCP from `.mavis/mcp.json` in the MiniMax Code UI.';
+  return `${mavisEntryTitle(sourceText)}
+
+Short Mavis entry. Detailed rules live under \`.mavis/rules/*.md\`; procedures
+under \`.mavis/skills/**\`. This file is ai-rules-owned (\`.mavis/AGENTS.md\`),
+not a MiniMax-reserved filename.
+
+Root \`AGENTS.md\` is the compatibility floor. Read it first, then this file.
+Do not write \`~/.minimax/**\`.
+
+## How to load
+
+- Rules and skills: follow the explicit paths in this file and root \`AGENTS.md\`.
+  Native project discovery without a reference is unconfirmed.
+- Roles: \`mcode exec --file .mavis/agents/<role>.md --output-format json\`.
+- Commands: natural-language procedures in \`.mavis/commands/\`, or
+  \`mcode exec --file .mavis/commands/task.md "<task>"\`.
+- After a producer receipt, run \`bash .mavis/hooks/chain-team-phases.sh\`.
+  Agents must not write lifecycle fields in \`status.json\` / \`metrics.json\`.
+
+## Essential rules (read every turn)
+
+${essential}
+
+See \`.mavis/rules/README.md\` for the full catalog and loading strategy.
+
+**Platform docs:** published with the \`@bonesofspring/ai-rules\` package
+(\`docs/MAVIS.md\`, \`docs/MAVIS-COMPATIBILITY.md\`) — **not** copied into
+the consumer repo. Source: https://github.com/bonesofspring/ai-rules
+
+${body}
+
+## Install
+
+\`\`\`bash
+npx @bonesofspring/ai-rules init mavis --preset ${stack}
+\`\`\`
+
+Copies rules, commands, agents, hooks, skills, \`MAVIS.md\` → \`.mavis/AGENTS.md\`,
+\`MCP.md\`, \`mcp.json\` → \`.mavis/mcp.json\`, plus \`REPO_AGENTS.md\` → root \`AGENTS.md\`.
+Seeds \`.ai.local/team/\`.
+${skillsLine}
+`;
+}
+
+function buildCommandsReadme(cursorRoot, stack, cursorFiles) {
+  const rewriteProse = (text) => finalizeMavisProse(text, stack);
+  let text = rewriteProse(readSiblingReadme(cursorRoot, 'commands/README.md'));
+  text = text.replace(
+    `# Cursor commands (${stack} preset)`,
+    `# Mavis commands (${stack} preset)`,
+  );
+  text = text.replace(
+    `Slash commands are copied to \`.mavis/commands/\` on \`ai-rules init mavis --preset ${stack}\`.`,
+    `Procedure files are copied to \`.mavis/commands/\` on \`ai-rules init mavis --preset ${stack}\`. Invoke via \`mcode exec --file .mavis/commands/<name>.md\` or natural-language procedures in the MiniMax UI.`,
+  );
+  text = rewriteAgentRosterCount(
+    text,
+    countAgentRoleFiles(cursorFiles),
+    `mavis/${stack}/commands/README.md`,
+  );
+  text = text.replace(
+    '- Orchestrator: `../rules/agent-team-orchestrator.mdc`',
+    '- Orchestrator: `../rules/agent-team-orchestrator.md`',
+  );
+  text = text.replace(
+    '- Artifacts: `../team/README.md` (`pipeline.json`, `status.json`)',
+    '- Artifacts: `.ai.local/team/README.md` (`pipeline.json`, `status.json`)',
+  );
+  text = text.replace(
+    '- Hooks: `../hooks.json`, `../hooks/chain-team-phases.sh`',
+    '- Hooks: `../hooks/chain-team-phases.sh` only (semi-auto runner; no `hooks.json` in mavis)',
+  );
+  text = text.replace(
+    'Create and edit commands via `/commands` in Cursor or directly in this preset folder.',
+    'Edit procedure files in this preset folder or in the installed `.mavis/commands/` copy after `init`.',
+  );
+  return text.endsWith('\n') ? text : `${text}\n`;
+}
+
+function buildAgentsReadme(cursorRoot, stack, profile) {
+  const rewriteProse = (text) => finalizeMavisProse(text, stack);
+  let text = rewriteProse(readSiblingReadme(cursorRoot, 'agents/README.md'));
+  text = rewriteCursorPipelineIntro(
+    text,
+    'Role-based subagents for the Mavis team pipeline (`mcode exec --file`)',
+  );
+  text = replaceCursorFrontmatterReadonlyBlock(
+    text,
+    `## Mavis packaging (no YAML frontmatter)
+
+Mavis agents ship as **plain Markdown** without Cursor-style YAML frontmatter (\`name\`, \`readonly\`, \`model\`). Adapter-map marks every agent \`loadMode: manual\`; attach with:
+
+\`\`\`bash
+mcode exec --file .mavis/agents/<role>.md --output-format json
+\`\`\`
+
+**Team artifacts:** agents write \`.ai.local/team/**\` deliverables (\`pipeline.json\`, \`brief.md\`, \`review.md\`, \`artifact-manifest.json\`, …). They must **not** mutate lifecycle fields in \`status.json\` or \`metrics.json\` — \`bash .mavis/hooks/chain-team-phases.sh\` owns those after each producer receipt.
+
+Production-code restrictions live in each agent's **prompt body**, not in frontmatter flags.
+
+## Model tiers (advisory)
+
+Model routing is **prose-only** in this preset (no YAML \`model\` frontmatter). Optional \`steps[].model\` in \`pipeline.json\` (\`cheap\` | \`standard\` | \`strong\`) is advisory for \`mcode\` operators — see \`task-router.md\` and \`agent-team-orchestrator.md\`.
+
+| Tier | Agents |
+|------|--------|
+| **cheap** | \`task-router\`, \`task-analyst\`, \`build-verifier\`, \`code-reviewer\`, \`tech-writer\`, \`codebase-analyzer\` |
+| **standard** | ${standardTierCell(profile)} |
+| **strong** | ${strongTierCell(profile)} |
+`,
+    `mavis/${stack}`,
+  );
+  return text.endsWith('\n') ? text : `${text}\n`;
+}
+
+function buildStackReadme(stack, profile) {
+  const releasedNote = `Install id: \`${stack}\`. Listed in \`platform-contract.json\` \`releasedStacks\`.\n`;
+  return `# ${profile.title} preset (Mavis)
+
+Sibling adapter derived from \`presets/cursor/${stack}\`. Platform id \`mavis\`;
+runtime \`mcode\`. Consumer install root is \`.mavis/\` (ai-rules-owned).
+
+Mapping: \`adapter-map.json\`. Do not derive this tree from Claude.
+
+\`\`\`bash
+npx @bonesofspring/ai-rules init mavis --preset ${stack}
+\`\`\`
+
+${releasedNote}
+\`init\` writes \`.mavis/**\` plus root \`AGENTS.md\` and seeds \`.ai.local/team/\`.
+No \`hooks.json\` / Bugbot; chain with \`bash .mavis/hooks/chain-team-phases.sh\`.
+\`clean mavis\` does not delete \`.ai.local/\`.
+`;
+}
+
+function formatAlwaysOnStems(alwaysOn) {
+  const ticks = alwaysOn.map((stem) => `\`${stem}\``);
+  if (ticks.length <= 1) {
+    return `${ticks.join(', ')}.`;
+  }
+  return `${ticks.slice(0, -1).join(', ')},\n${ticks[ticks.length - 1]}.`;
+}
+
+function buildRulesReadme(profile) {
+  const heading =
+    profile.title === 'Next.js' ? '# Mavis Next rules' : `# Mavis ${profile.title} rules`;
+  return `${heading}
+
+Plain Markdown. MiniMax does not auto-load these files; root \`AGENTS.md\` and
+\`.mavis/AGENTS.md\` reference them explicitly.
+
+## Essential (entry-critical)
+
+${formatAlwaysOnStems(profile.alwaysOn)}
+
+## Requestable
+
+All other \`*.md\` files in this directory. Read when the task matches the
+catalog in the Cursor source \`rules/README.md\` (same stems).
+
+Shared-core markers (\`<!-- shared-core: … -->\`) are preserved from Cursor.
+`;
+}
+
+function buildHooksReadme() {
+  return `# Mavis hooks
+
+No documented MiniMax project hook API is assumed.
+
+## Shipped
+
+\`chain-team-phases.sh\` — manual/semi-auto runner. After a producer receipt:
+
+\`\`\`bash
+printf '%s\\n' '{"status":"completed","attemptId":"<runtime-attempt-id>"}' \\
+  | bash .mavis/hooks/chain-team-phases.sh
+\`\`\`
+
+\`<runtime-attempt-id>\` comes from \`.ai.local/team/tasks/<slug>/status.json\`.
+Do not invent it. Agents never write lifecycle fields in \`status.json\` or
+\`metrics.json\`.
+
+## Omitted
+
+- \`hooks.json\` — no native registration schema
+- \`guard-shell-command.sh\` — not wired; do not describe it as enforcement
+- \`hooks/examples/**\` — no confirmed Mavis event API
+`;
+}
+
+export { parseStackArg };
+
+export function generateMavisStack(stack, { root = packageRoot } = {}) {
+  const profile = getStackProfile(stack);
+  const alwaysOn = new Set(profile.alwaysOn);
+  const rewriteProse = (text) => finalizeMavisProse(text, stack);
+
+  return deriveAdapterStack({
+    platform: 'mavis',
+    stack,
+    root,
+    omit: OMIT,
+    // First match wins — keep specific paths above generic prefixes.
+    rules: [
+      {
+        match: (source) => source === 'AGENTS.md',
+        map: ({ sourceText }) => ({
+          target: 'MAVIS.md',
+          content: buildMavisEntry(sourceText, stack, profile),
+          category: 'entry',
+          disposition: 'embed-entry',
+          loadMode: 'root-entry',
+          reason: 'Cursor AGENTS.md semantics feed .mavis/AGENTS.md; not a MiniMax-reserved name',
+        }),
+      },
+      {
+        match: (source) => source === 'REPO_AGENTS.md',
+        map: ({ source, sourceText }) => ({
+          target: source,
+          content: sourceText,
+          category: 'entry',
+          disposition: 'copy',
+          loadMode: 'root-entry',
+          reason: 'Canonical cross-tool root AGENTS.md; identical for all platforms',
+        }),
+      },
+      {
+        match: (source) => source.startsWith('rules/') && source.endsWith('.mdc'),
+        map: ({ source, sourceText }) => {
+          const stem = path.basename(source, '.mdc');
+          let markdown = transformMarkdown(sourceText, stack);
+          if (stem === 'agent-team-orchestrator') {
+            markdown = transformOrchestrator(markdown);
+          }
+          return {
+            target: `rules/${stem}.md`,
+            content: markdown,
+            category: 'rules',
+            disposition: 'transform',
+            loadMode: alwaysOn.has(stem) ? 'root-entry' : 'referenced',
+            reason: alwaysOn.has(stem)
+              ? 'Essential always-on Cursor rule: summary in entry files; full body referenced from .mavis/rules'
+              : 'Requestable Cursor rule: referenced from entry files; not claimed as MiniMax auto-load',
+          };
+        },
+      },
+      {
+        match: (source) => source.startsWith('agents/') && source.endsWith('.md'),
+        map: ({ source, sourceText }) => ({
+          target: source,
+          content: transformMarkdown(sourceText, stack, { allowEmbedEntry: false }),
+          category: 'agents',
+          disposition: 'transform',
+          loadMode: 'manual',
+          reason: 'Native workspace agent discovery is unknown; attach with mcode exec --file',
+        }),
+      },
+      {
+        match: (source) => source.startsWith('skills/') && source.endsWith('/SKILL.md'),
+        map: ({ source, sourceText }) => ({
+          target: source,
+          content: transformMarkdown(sourceText, stack),
+          category: 'skills',
+          disposition: 'transform',
+          loadMode: 'referenced',
+          reason: 'Workspace skill discovery without a root reference is unknown',
+        }),
+      },
+      {
+        match: (source) => source.startsWith('commands/') && source.endsWith('.md'),
+        map: ({ source, sourceText }) => ({
+          target: source,
+          content: transformMarkdown(sourceText, stack, { command: true }),
+          category: 'commands',
+          disposition: 'transform',
+          loadMode: 'manual',
+          reason: 'No file-defined slash command API; keep as an explicit procedure plus exec --file',
+        }),
+      },
+      {
+        match: (source) => source === 'hooks/chain-team-phases.sh',
+        map: ({ source, sourceText }) => {
+          const next = rewriteProse(sourceText);
+          if (next.includes("const PLATFORM = 'cursor'")) {
+            throw new Error(`hooks/chain-team-phases.sh PLATFORM rewrite did not apply for mavis/${stack}`);
+          }
+          return {
+            target: source,
+            content: next,
+            category: 'hooks',
+            disposition: 'transform',
+            loadMode: 'manual',
+            reason: 'Manual/semi-auto chain runner under .mavis/hooks; not auto-registered',
+          };
+        },
+      },
+      {
+        match: (source) => source === 'mcp.json' || source === 'MCP.md',
+        map: ({ source, sourceText }) => ({
+          target: source,
+          content: source === 'MCP.md' ? rewriteProse(sourceText) : sourceText,
+          category: 'mcp',
+          disposition: source === 'MCP.md' ? 'transform' : 'copy',
+          loadMode: 'manual',
+          reason: 'Fallback merge into .mavis/mcp.json plus manual MiniMax UI import',
+        }),
+      },
+      {
+        match: (source) => source.startsWith('ai-local/'),
+        map: ({ source, sourceText }) => ({
+          target: source,
+          content: rewriteProse(sourceText),
+          category: 'ai-local',
+          disposition: 'transform',
+          loadMode: 'manual',
+          reason: 'Consumer-owned overlay template; seeded to .ai.local/conventions.md on init',
+        }),
+      },
+      {
+        match: (source) => source.startsWith('team/'),
+        map: ({ source, sourceText }) => {
+          const transformed = source.endsWith('.md') ? rewriteProse(sourceText) : sourceText;
+          return {
+            target: source,
+            content:
+              transformed.endsWith('\n') || !source.endsWith('.md') ? transformed : `${transformed}\n`,
+            category: 'team',
+            disposition: source.endsWith('.md') ? 'transform' : 'copy',
+            loadMode: 'manual',
+            reason: 'File pipeline templates; runtime artifacts seed to .ai.local/team',
+          };
+        },
+      },
+    ],
+    finalize: ({ writeFile, cursorRoot, cursorFiles }) => {
+      writeFile('README.md', buildStackReadme(stack, profile));
+      writeFile('rules/README.md', buildRulesReadme(profile));
+      writeFile('agents/README.md', buildAgentsReadme(cursorRoot, stack, profile));
+      writeFile('skills/README.md', rewriteProse(readSiblingReadme(cursorRoot, 'skills/README.md')));
+      writeFile('commands/README.md', buildCommandsReadme(cursorRoot, stack, cursorFiles));
+      writeFile('hooks/README.md', buildHooksReadme());
+      writeFile('team/README.md', rewriteProse(readSiblingReadme(cursorRoot, 'team/README.md')));
+    },
+  });
+}