@rune-kit/rune 2.11.0 → 2.12.0

package/compiler/__tests__/onboard-invariants.test.js

@@ -0,0 +1,240 @@
+import assert from 'node:assert';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, test } from 'node:test';
+import {
+  collectPointerGlobs,
+  loadTemplate,
+  mergeInvariantsContent,
+  runOnboardInvariants,
+} from '../../skills/onboard/scripts/onboard-invariants.js';
+
+describe('mergeInvariantsContent', () => {
+  test('seeds from template when existing is empty', () => {
+    const template = '# Project Invariants\n\n## Auto-detected (new)\n\n<!-- placeholder -->\n';
+    const detected = {
+      danger: [{ title: 'core', what: '10 files', where: ['src/core/**'], why: 'hub' }],
+      critical: [],
+      state: [],
+      cross: [],
+    };
+    const merged = mergeInvariantsContent({ existing: '', autoDetected: detected, template });
+    assert.ok(merged.seeded);
+    assert.ok(merged.content.includes('# Project Invariants'));
+    assert.ok(merged.content.includes('#### core'));
+  });
+
+  test('replaces ONLY the auto-detected block on re-run', () => {
+    const first = mergeInvariantsContent({
+      existing: '',
+      autoDetected: {
+        danger: [{ title: 'v1', what: 'old', where: ['src/v1/**'], why: 'first' }],
+        critical: [],
+        state: [],
+        cross: [],
+      },
+      template: '# Project Invariants\n\n## Auto-detected (new)\n\n<!-- placeholder -->\n',
+    });
+
+    const userEdited = first.content.replace(
+      '# Project Invariants',
+      '# Project Invariants\n\n## Danger Zones\n\n#### UserRule\n- **WHAT**: custom\n- **WHERE**: `src/custom/**`\n- **WHY**: user-added\n',
+    );
+
+    const second = mergeInvariantsContent({
+      existing: userEdited,
+      autoDetected: {
+        danger: [{ title: 'v2', what: 'new', where: ['src/v2/**'], why: 'second' }],
+        critical: [],
+        state: [],
+        cross: [],
+      },
+      template: '',
+    });
+
+    assert.ok(second.replaced);
+    assert.ok(second.content.includes('UserRule'), 'user edits must be preserved');
+    assert.ok(second.content.includes('#### v2'), 'new detection must appear');
+    assert.ok(!second.content.includes('#### v1'), 'old detection must be replaced');
+  });
+
+  test('appends Auto-detected header if missing from existing file', () => {
+    const existing = '# Project Invariants\n\n## Danger Zones\n\n#### legacy\n';
+    const merged = mergeInvariantsContent({
+      existing,
+      autoDetected: {
+        danger: [{ title: 'fresh', what: 'n', where: ['src/x/**'], why: 'y' }],
+        critical: [],
+        state: [],
+        cross: [],
+      },
+      template: '',
+    });
+    assert.ok(merged.appended);
+    assert.ok(merged.content.includes('## Auto-detected (new)'));
+    assert.ok(merged.content.includes('legacy'), 'existing user content preserved');
+  });
+
+  test('renders placeholder line when no detections', () => {
+    const merged = mergeInvariantsContent({
+      existing: '',
+      autoDetected: { danger: [], critical: [], state: [], cross: [] },
+      template: '# X\n\n## Auto-detected (new)\n\n<!-- placeholder -->\n',
+    });
+    assert.match(merged.content, /No new detections on this run/);
+  });
+
+  test('Phase 2 C1: code-fence with `## ` inside auto-detected block does not corrupt merge', () => {
+    // User manually edits the file and embeds a markdown example showing a `## `
+    // line inside a fenced code block (e.g. illustrating markdown syntax).
+    // The old regex-based boundary scan would treat that `## ` as a real section
+    // header and drop everything after it. This test locks in the line-walking
+    // fence-aware boundary detection.
+    const existing = [
+      '# Project Invariants',
+      '',
+      '## Danger Zones',
+      '',
+      '#### PreservedRule',
+      '- **WHAT**: do not touch',
+      '',
+      '## Auto-detected (new)',
+      '',
+      '```markdown',
+      '## This heading is inside a fence',
+      'example content',
+      '```',
+      '',
+      '#### OldDetection',
+      '',
+      '## Notes (user section)',
+      '',
+      'should survive too',
+      '',
+    ].join('\n');
+
+    const merged = mergeInvariantsContent({
+      existing,
+      autoDetected: {
+        danger: [{ title: 'NewDetection', what: 'fresh', where: ['src/fresh/**'], why: 'new' }],
+        critical: [],
+        state: [],
+        cross: [],
+      },
+      template: '',
+    });
+
+    assert.ok(merged.replaced);
+    assert.ok(merged.content.includes('PreservedRule'), 'content above Auto-detected preserved');
+    assert.ok(merged.content.includes('NewDetection'), 'new detection inserted');
+    assert.ok(!merged.content.includes('OldDetection'), 'old auto-detected content replaced');
+    assert.ok(merged.content.includes('Notes (user section)'), 'real `## ` section after block survives');
+    assert.ok(merged.content.includes('should survive too'), 'body of real section survives');
+  });
+});
+
+describe('collectPointerGlobs', () => {
+  test('extracts and dedupes globs from danger + critical buckets', () => {
+    const globs = collectPointerGlobs({
+      danger: [{ where: ['src/a/**'] }, { where: ['src/b/**'] }, { where: ['src/a/**'] }],
+      critical: [{ where: ['src/b/**'] }, { where: ['src/c/**'] }],
+      state: [],
+      cross: [],
+    });
+    assert.deepStrictEqual(globs.sort(), ['src/a/**', 'src/b/**', 'src/c/**']);
+  });
+});
+
+describe('loadTemplate', () => {
+  test('reads the bundled template file', async () => {
+    const content = await loadTemplate();
+    assert.ok(content.includes('Project Invariants'));
+    assert.ok(content.includes('Auto-detected (new)'));
+  });
+});
+
+describe('runOnboardInvariants — end-to-end', () => {
+  test('seeds INVARIANTS.md and injects CLAUDE.md pointer', async () => {
+    const root = await mkdtemp(path.join(tmpdir(), 'rune-onboard-'));
+    try {
+      await mkdir(path.join(root, 'src', 'core'), { recursive: true });
+      for (let i = 0; i < 12; i++) {
+        await writeFile(path.join(root, 'src', 'core', `file${i}.ts`), `export const X${i} = ${i};\n`, 'utf8');
+      }
+      await writeFile(path.join(root, 'CLAUDE.md'), '# Fresh Project\n', 'utf8');
+
+      const result = await runOnboardInvariants({ root });
+
+      assert.strictEqual(result.invariants.action, 'seeded');
+      assert.ok(['created', 'updated'].includes(result.claudeMd.action));
+
+      const invariants = await readFile(path.join(root, '.rune', 'INVARIANTS.md'), 'utf8');
+      assert.ok(invariants.includes('Project Invariants'));
+
+      const claudeMd = await readFile(path.join(root, 'CLAUDE.md'), 'utf8');
+      assert.ok(claudeMd.includes('@rune-invariants-pointer:start'));
+      assert.ok(claudeMd.includes('.rune/INVARIANTS.md'));
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test('Phase 2 H1: SKILL.md / PACK.md directories surface as danger zones', async () => {
+    const root = await mkdtemp(path.join(tmpdir(), 'rune-onboard-skills-'));
+    try {
+      // Seed an AI-skills-repo shape: directories containing SKILL.md but no
+      // SOURCE_EXTS files. Old detector (exts-only scan) missed these entirely.
+      await mkdir(path.join(root, 'skills', 'skill-router'), { recursive: true });
+      await mkdir(path.join(root, 'skills', 'cook'), { recursive: true });
+      await mkdir(path.join(root, 'extensions', 'ui'), { recursive: true });
+      await writeFile(path.join(root, 'skills', 'skill-router', 'SKILL.md'), '# Router\n', 'utf8');
+      await writeFile(path.join(root, 'skills', 'cook', 'SKILL.md'), '# Cook\n', 'utf8');
+      await writeFile(path.join(root, 'extensions', 'ui', 'PACK.md'), '# UI Pack\n', 'utf8');
+      await writeFile(path.join(root, 'CLAUDE.md'), '# P\n', 'utf8');
+
+      const result = await runOnboardInvariants({ root });
+      assert.strictEqual(result.invariants.action, 'seeded');
+
+      const invariants = await readFile(path.join(root, '.rune', 'INVARIANTS.md'), 'utf8');
+      const hasSkillRouter = invariants.includes('skills/skill-router');
+      const hasCook = invariants.includes('skills/cook');
+      const hasUiPack = invariants.includes('extensions/ui');
+      assert.ok(
+        hasSkillRouter || hasCook || hasUiPack,
+        'at least one signal-file directory must surface as a danger zone',
+      );
+      assert.ok(invariants.includes('skill/pack artifact') || invariants.includes('High-risk keyword'));
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test('second run preserves user edits above Auto-detected', async () => {
+    const root = await mkdtemp(path.join(tmpdir(), 'rune-onboard-'));
+    try {
+      await mkdir(path.join(root, 'src', 'core'), { recursive: true });
+      for (let i = 0; i < 10; i++) {
+        await writeFile(path.join(root, 'src', 'core', `f${i}.ts`), `export const Y${i} = ${i};\n`, 'utf8');
+      }
+      await writeFile(path.join(root, 'CLAUDE.md'), '# P\n', 'utf8');
+
+      await runOnboardInvariants({ root });
+
+      const invariantsPath = path.join(root, '.rune', 'INVARIANTS.md');
+      const original = await readFile(invariantsPath, 'utf8');
+      const edited = original.replace(
+        '## Auto-detected (new)',
+        '## Danger Zones\n\n#### UserRule\n- **WHAT**: sacred\n- **WHERE**: `src/sacred/**`\n- **WHY**: must-not-touch\n\n## Auto-detected (new)',
+      );
+      await writeFile(invariantsPath, edited, 'utf8');
+
+      await runOnboardInvariants({ root });
+      const after = await readFile(invariantsPath, 'utf8');
+      assert.ok(after.includes('UserRule'), 'user section must survive re-run');
+      assert.ok(after.includes('## Auto-detected (new)'));
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/compiler/adapters/hooks/antigravity.js

@@ -0,0 +1,140 @@
+/**
+ * Google Antigravity hooks adapter (experimental).
+ *
+ * Antigravity uses `.antigravity/rules/*.md` for persistent agent context.
+ * There is no tool-level hook primitive yet, so we mirror Cursor's pattern:
+ * emit rule files that cascade into the agent's prompt. This is the weakest
+ * fidelity tier — documented so users know what they're getting.
+ */
+
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { platformEntries, renderTierRule, unsupportedEntries } from './tier-emitter.js';
+
+export const id = 'antigravity';
+
+const RULES_REL_DIR = '.antigravity/rules';
+const RUNE_PREFIX = 'rune-';
+const AUTO_SIGNATURE = '@rune-kit/rune hook-dispatch';
+
+export function detect(projectRoot) {
+  return existsSync(path.join(projectRoot, '.antigravity'));
+}
+
+export async function emit({ preset, projectRoot, tierManifests = [] }) {
+  if (preset === 'off' && tierManifests.length === 0) return uninstall({ projectRoot });
+  if (preset !== 'off' && preset !== 'strict' && preset !== 'gentle') {
+    throw new Error(`antigravity adapter: invalid preset '${preset}'`);
+  }
+
+  const mode = preset === 'strict' ? 'BLOCK' : 'WARN';
+  const rulesDir = path.join(projectRoot, RULES_REL_DIR);
+
+  const rules = [
+    { name: 'preflight', description: 'Run preflight review before any source edit.' },
+    { name: 'sentinel', description: 'Security review before shell / infra edits.' },
+    { name: 'dependency-doctor', description: 'Dependency audit after manifest edits.' },
+  ];
+
+  const files =
+    preset === 'off'
+      ? []
+      : rules.map((r) => ({
+          path: path.join(rulesDir, `${RUNE_PREFIX}${r.name}.md`),
+          content: renderRule(r, mode),
+        }));
+
+  const notes =
+    preset === 'off'
+      ? []
+      : [
+          'Antigravity support is experimental — rule-injection only, no true hook.',
+          `Preset: ${preset} (${mode}). \`completion-gate\` must be invoked manually.`,
+        ];
+
+  for (const manifest of tierManifests) {
+    for (const entry of platformEntries(manifest, 'antigravity')) {
+      const content = renderTierRule(entry, 'antigravity', { mode, tier: manifest.tier });
+      if (!content) continue;
+      files.push({
+        path: path.join(rulesDir, `${RUNE_PREFIX}${manifest.tier}-${entry.id}.md`),
+        content,
+      });
+    }
+    const skipped = unsupportedEntries(manifest, 'antigravity');
+    if (skipped.length > 0) {
+      notes.push(
+        `antigravity: ${manifest.tier} skipped ${skipped.length} entr${skipped.length === 1 ? 'y' : 'ies'} (${skipped.map((e) => e.id).join(', ')}) — platform-unsupported or Claude-only.`,
+      );
+    }
+  }
+
+  return { files, notes };
+}
+
+export async function uninstall({ projectRoot }) {
+  const rulesDir = path.join(projectRoot, RULES_REL_DIR);
+  if (!existsSync(rulesDir)) return { files: [], notes: [] };
+  const entries = await readdir(rulesDir, { withFileTypes: true });
+  const runeFiles = entries.filter((e) => e.isFile() && e.name.startsWith(RUNE_PREFIX) && e.name.endsWith('.md'));
+  const files = [];
+  for (const file of runeFiles) {
+    const abs = path.join(rulesDir, file.name);
+    const content = await readFile(abs, 'utf-8');
+    if (content.includes(AUTO_SIGNATURE) || content.includes('rune-managed: true')) {
+      files.push({ path: abs, content: null });
+    }
+  }
+  return { files, notes: files.length === 0 ? ['no Rune-managed antigravity rules'] : [] };
+}
+
+export async function status(projectRoot) {
+  const rulesDir = path.join(projectRoot, RULES_REL_DIR);
+  if (!existsSync(rulesDir)) {
+    return {
+      installed: false,
+      preset: null,
+      wired: [],
+      missing: ['preflight', 'sentinel', 'dependency-doctor'],
+      notes: ['no .antigravity/rules directory'],
+    };
+  }
+  const entries = await readdir(rulesDir, { withFileTypes: true });
+  const runeFiles = entries.filter((e) => e.isFile() && e.name.startsWith(RUNE_PREFIX) && e.name.endsWith('.md'));
+  const wired = runeFiles.map((f) => f.name.replace(RUNE_PREFIX, '').replace('.md', ''));
+  const expected = ['preflight', 'sentinel', 'dependency-doctor'];
+  const missing = expected.filter((s) => !wired.includes(s));
+
+  let preset = null;
+  for (const file of runeFiles) {
+    const content = await readFile(path.join(rulesDir, file.name), 'utf-8');
+    if (/^mode: BLOCK$/m.test(content)) {
+      preset = 'strict';
+      break;
+    }
+    if (/^mode: WARN$/m.test(content)) preset = preset ?? 'gentle';
+  }
+
+  return { installed: runeFiles.length > 0, preset, wired, missing, notes: ['experimental — rule-injection only'] };
+}
+
+function renderRule(rule, mode) {
+  return [
+    '---',
+    `description: ${rule.description}`,
+    'rune-managed: true',
+    `rune-skill: ${rule.name}`,
+    `mode: ${mode}`,
+    '---',
+    '',
+    `# Rune ${rule.name}`,
+    '',
+    `${rule.description} Mode: ${mode}.`,
+    '',
+    'Refer to the Rune skill SKILL.md for the full checklist — apply those checks mentally before each matching edit.',
+    '',
+    `_Auto-generated by \`rune hooks install\` (${AUTO_SIGNATURE})._`,
+    '',
+  ].join('\n');
+}

package/compiler/adapters/hooks/claude.js

@@ -0,0 +1,166 @@
+/**
+ * Claude Code hooks adapter.
+ *
+ * Target: `.claude/settings.json` — native hook primitive (PreToolUse /
+ * PostToolUse / Stop). This is the stable reference adapter; other adapters
+ * degrade gracefully against Claude's capabilities.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  appendHookBlock,
+  detectPreset,
+  stripHooksBySkill,
+  stripRuneHooks,
+  summarizeRuneHooks,
+} from '../../commands/hooks/merge.js';
+import { buildPreset, SETTINGS_REL_PATH, WIRED_SKILLS } from '../../commands/hooks/presets.js';
+import { buildTierBlock } from './tier-emitter.js';
+
+export const id = 'claude';
+
+export function detect(projectRoot) {
+  return existsSync(path.join(projectRoot, '.claude'));
+}
+
+export async function emit({ preset, projectRoot, tierManifests = [] }) {
+  if (preset === 'off' && tierManifests.length === 0) return uninstall({ projectRoot });
+  if (preset !== 'off' && preset !== 'strict' && preset !== 'gentle') {
+    throw new Error(`claude adapter: invalid preset '${preset}'`);
+  }
+
+  const settingsPath = path.join(projectRoot, SETTINGS_REL_PATH);
+  const existing = await readJson(settingsPath);
+
+  // Strip ONCE up-front — preset + tier layers then merge additively without
+  // the next layer wiping the previous.
+  let merged = stripRuneHooks(existing);
+  // Clear any existing Rune-managed statusLine so re-install is idempotent.
+  if (merged.statusLine?.command && isRuneStatusLine(merged.statusLine.command)) {
+    const { statusLine: _unused, ...rest } = merged;
+    merged = rest;
+  }
+  const notes = [];
+
+  if (preset !== 'off') {
+    merged = appendHookBlock(merged, buildPreset(preset));
+  }
+
+  for (const manifest of tierManifests) {
+    // Apply `overrides` — strip any surviving entries whose extracted skill name
+    // matches an override key. Example: Pro's `context-sense` replaces the older
+    // `context-watch` hook, so a pre-migration settings.json that still carries
+    // a `context-watch` entry gets cleaned up here.
+    const overrideKeys = Object.keys(manifest.overrides || {});
+    if (overrideKeys.length > 0) {
+      const before = JSON.stringify(merged.hooks || {});
+      merged = stripHooksBySkill(merged, overrideKeys);
+      const after = JSON.stringify(merged.hooks || {});
+      if (before !== after) {
+        notes.push(
+          `claude: applied ${manifest.tier} overrides — stripped legacy entr${overrideKeys.length === 1 ? 'y' : 'ies'} (${overrideKeys.join(', ')}).`,
+        );
+      }
+    }
+
+    const tierBlock = buildTierBlock(manifest, 'claude');
+    if (tierBlock.hooks && Object.keys(tierBlock.hooks).length > 0) {
+      merged = appendHookBlock(merged, { hooks: tierBlock.hooks });
+    }
+    if (tierBlock.statusLine) {
+      const existingStatus = merged.statusLine;
+      if (!existingStatus || isRuneStatusLine(existingStatus.command)) {
+        merged = { ...merged, statusLine: tierBlock.statusLine };
+      } else {
+        notes.push(
+          `claude: user-owned statusLine detected — skipping Rune tier statusLine ('${tierBlock.statusLine.command}'). Remove your statusLine and re-install to adopt Rune's.`,
+        );
+      }
+    }
+    if (tierBlock.notes?.length) notes.push(...tierBlock.notes);
+  }
+
+  return {
+    files: [
+      {
+        path: settingsPath,
+        content: `${JSON.stringify(merged, null, 2)}\n`,
+      },
+    ],
+    notes,
+  };
+}
+
+export async function uninstall({ projectRoot }) {
+  const settingsPath = path.join(projectRoot, SETTINGS_REL_PATH);
+  if (!existsSync(settingsPath)) {
+    return { files: [], notes: ['no .claude/settings.json — nothing to uninstall'] };
+  }
+  const existing = await readJson(settingsPath);
+  const stripped = stripRuneHooks(existing);
+  // statusLine with Rune hook-dispatch or a rune-managed tier command is Rune-owned — strip it.
+  if (stripped.statusLine?.command && isRuneStatusLine(stripped.statusLine.command)) {
+    delete stripped.statusLine;
+  }
+  return {
+    files: [
+      {
+        path: settingsPath,
+        content: `${JSON.stringify(stripped, null, 2)}\n`,
+      },
+    ],
+    notes: [],
+  };
+}
+
+const RUNE_TIER_STATUSLINE_RE = /\$\{RUNE_[A-Z][A-Z0-9_]*_ROOT\}/;
+
+function isRuneStatusLine(command) {
+  if (typeof command !== 'string') return false;
+  // Match the installer's own output shapes only — not any command that happens
+  // to contain the substring "rune-pulse" (a user alias could legitimately contain it).
+  // Accepts: (1) npx @rune-kit/rune ..., (2) tier-rendered `${RUNE_*_ROOT}/hooks/...`.
+  if (RUNE_TIER_STATUSLINE_RE.test(command)) return true;
+  return /(^|\s)npx(\s+--yes)?\s+@rune-kit\/rune\b/.test(command);
+}
+
+export async function status(projectRoot) {
+  const settingsPath = path.join(projectRoot, SETTINGS_REL_PATH);
+  if (!existsSync(settingsPath)) {
+    return {
+      installed: false,
+      preset: null,
+      wired: [],
+      missing: [...WIRED_SKILLS],
+      notes: ['no .claude/settings.json'],
+    };
+  }
+  const settings = await readJson(settingsPath);
+  const summary = summarizeRuneHooks(settings);
+  const preset = detectPreset(settings);
+  const wired = Array.from(new Set(Object.values(summary.events).flat()));
+  const missing = WIRED_SKILLS.filter((s) => !wired.includes(s));
+  return {
+    installed: summary.total > 0,
+    preset: preset === 'none' ? null : preset,
+    wired,
+    missing,
+    events: summary.events,
+    notes: [],
+  };
+}
+
+async function readJson(settingsPath) {
+  if (!existsSync(settingsPath)) return {};
+  const raw = await readFile(settingsPath, 'utf-8');
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `${settingsPath} is not valid JSON — fix it manually or delete the file and re-run \`rune hooks install\`. (${err.message})`,
+    );
+  }
+}