@rune-kit/rune 2.10.0 → 2.12.0

package/skills/onboard/references/invariants-template.md

@@ -0,0 +1,76 @@
+# Project Invariants
+
+> Auto-seeded by `rune onboard`. Edit freely — your changes survive re-runs.
+> Append-only: new auto-detections land under `## Auto-detected (new)` and never
+> overwrite existing rules.
+
+This file is the project's truth-source for rules that code changes must respect.
+`logic-guardian` loads it as a pre-edit gate, and `session-bridge` surfaces the
+most critical rules at session start so agents know the danger zones immediately.
+
+## How to read an entry
+
+```
+### <short rule title>
+- **WHAT**: one-sentence statement of the rule (what must hold)
+- **WHERE**: glob patterns for files this rule applies to
+- **WHY**: why this rule exists — past incident, cross-file coupling,
+  compliance, external contract, etc.
+```
+
+If an entry becomes stale, move it to `## Archived` with a one-line note.
+Never delete — the archive is evidence of past decisions.
+
+---
+
+## Danger Zones
+
+Paths that disproportionately affect the rest of the codebase. Test coverage,
+review, and change-review should be stricter here.
+
+<!-- auto-generated entries appear below -->
+
+---
+
+## Critical Invariants
+
+Rules that cross file boundaries — shared constants, contract values, protocol
+fields. Breaking any one silently breaks downstream code.
+
+<!-- auto-generated entries appear below -->
+
+---
+
+## State Machine Rules
+
+Legal transitions for state machines in the project. Illegal transitions are
+often the root cause of hard-to-reproduce bugs.
+
+<!-- auto-generated entries appear below -->
+
+---
+
+## Cross-File Consistency
+
+Fields, enums, or schemas mirrored in multiple places. Updates must propagate
+together or the project enters an inconsistent state.
+
+<!-- auto-generated entries appear below -->
+
+---
+
+## Auto-detected (new)
+
+New detections from the most recent `rune onboard` run. Review these, promote
+the real ones into the sections above, and drop the noise.
+
+<!-- placeholder — each run appends or replaces this block -->
+
+---
+
+## Archived
+
+Rules that were once invariants but are no longer — kept here as history. Do
+not delete; their absence later makes reasoning harder.
+
+<!-- empty on first run -->

package/skills/onboard/scripts/detect-invariants.js

@@ -0,0 +1,439 @@
+#!/usr/bin/env node
+
+/**
+ * detect-invariants.js — Scan a project and emit candidate invariant rules
+ * for `.rune/INVARIANTS.md`.
+ *
+ * Detection buckets (ordered by specificity, not confidence):
+ *   1. Danger zones     — directories with high churn signals (deep + many files)
+ *   2. Critical         — shared constants exported and imported in ≥ 3 places
+ *   3. State machines   — reducer shapes, switch(state), enum-driven transitions
+ *   4. Cross-file       — duplicated literal tuples (suggests mirrored schemas)
+ *
+ * Heuristics favor recall over precision for danger zones (let the user prune),
+ * precision over recall for critical invariants (don't cry wolf).
+ *
+ * Usage as CLI:
+ *   node detect-invariants.js --root <project-root> [--json]
+ *
+ * Usage as module:
+ *   import { detectInvariants } from './detect-invariants.js';
+ *   const rules = await detectInvariants({ root });
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '.next',
+  '.nuxt',
+  '.svelte-kit',
+  '.turbo',
+  '.cache',
+  '__pycache__',
+  '.venv',
+  'venv',
+  'target',
+  '.rune',
+]);
+
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs']);
+
+/**
+ * Files whose presence marks a directory as a first-class artifact (AI skills,
+ * extension packs, plugin manifests). These directories become danger-zone
+ * candidates even if they contain no SOURCE_EXTS files — a SKILL.md edit can
+ * reshape runtime behavior for every consumer.
+ */
+const SIGNAL_FILES = new Set(['SKILL.md', 'PACK.md', 'plugin.json']);
+
+const MAX_FILES = 2000;
+const MAX_FILE_BYTES = 200_000;
+
+/**
+ * Main entry — returns structured rule objects.
+ *
+ * @param {{root: string, maxFiles?: number}} opts
+ * @returns {Promise<{danger: Rule[], critical: Rule[], state: Rule[], cross: Rule[], stats: Object}>}
+ */
+export async function detectInvariants(opts) {
+  const { root } = opts;
+  const maxFiles = opts.maxFiles ?? MAX_FILES;
+  if (!root) throw new Error('detectInvariants: root is required');
+
+  const index = await buildIndex(root, maxFiles);
+
+  const danger = detectDangerZones(index);
+  const critical = await detectCriticalConstants(root, index);
+  const state = await detectStateMachines(root, index);
+  const cross = await detectCrossFileConsistency(root, index);
+
+  return {
+    danger,
+    critical,
+    state,
+    cross,
+    stats: {
+      filesScanned: index.files.length,
+      directoriesSeen: index.dirs.size,
+      truncated: index.truncated,
+    },
+  };
+}
+
+/**
+ * Walk the tree, collecting source files with size + path.
+ */
+async function buildIndex(root, maxFiles) {
+  const files = [];
+  const dirs = new Set();
+  const signalDirs = new Map(); // rel-dir -> count of signal files
+  let truncated = false;
+
+  async function walk(dir, depth) {
+    if (files.length >= maxFiles) {
+      truncated = true;
+      return;
+    }
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    dirs.add(path.relative(root, dir) || '.');
+    for (const entry of entries) {
+      if (files.length >= maxFiles) {
+        truncated = true;
+        return;
+      }
+      if (IGNORED_DIRS.has(entry.name)) continue;
+      if (entry.name.startsWith('.') && depth === 0) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full, depth + 1);
+      } else if (entry.isFile() && SIGNAL_FILES.has(entry.name)) {
+        const relDir = path.relative(root, dir).replace(/\\/g, '/') || '.';
+        signalDirs.set(relDir, (signalDirs.get(relDir) || 0) + 1);
+      }
+      if (entry.isFile() && SOURCE_EXTS.has(path.extname(entry.name))) {
+        try {
+          const s = await stat(full);
+          if (s.size <= MAX_FILE_BYTES) {
+            files.push({
+              abs: full,
+              rel: path.relative(root, full).replace(/\\/g, '/'),
+              size: s.size,
+            });
+          }
+        } catch {
+          /* skip unreadable */
+        }
+      }
+    }
+  }
+
+  await walk(root, 0);
+  return { files, dirs, signalDirs, truncated };
+}
+
+/**
+ * Danger-zone heuristic: directories with ≥ 5 source files AND depth ≥ 2
+ * OR directories whose relative path contains high-risk keywords.
+ * Sort by file count desc, take top 5.
+ */
+function detectDangerZones(index) {
+  const HIGH_RISK_KEYWORDS = [
+    'auth',
+    'payment',
+    'billing',
+    'router',
+    'session',
+    'security',
+    'crypto',
+    'migration',
+    'compiler',
+    'parser',
+    'state',
+  ];
+
+  const byDir = new Map();
+  for (const f of index.files) {
+    const dir = path.posix.dirname(f.rel);
+    byDir.set(dir, (byDir.get(dir) || 0) + 1);
+  }
+
+  // Fold signal-file directories (SKILL.md / PACK.md / plugin.json) into the
+  // scoring pool so AI-skill repos surface their orchestrators as danger zones
+  // even when the directory contains no SOURCE_EXTS files.
+  const signalDirs = index.signalDirs ?? new Map();
+  const scored = [];
+  const consideredDirs = new Set([...byDir.keys(), ...signalDirs.keys()]);
+  for (const dir of consideredDirs) {
+    if (dir === '.' || dir === '') continue;
+    const count = byDir.get(dir) ?? 0;
+    const signalCount = signalDirs.get(dir) ?? 0;
+    const depth = dir.split('/').length;
+    const keywordHit = HIGH_RISK_KEYWORDS.find((kw) => dir.toLowerCase().includes(kw));
+    let score = 0;
+    if (count >= 5 && depth >= 2) score += count;
+    if (keywordHit) score += 20;
+    if (signalCount > 0) score += 15 + signalCount;
+    if (score === 0) continue;
+    scored.push({ dir, count: count + signalCount, keyword: keywordHit, signal: signalCount > 0, score });
+  }
+
+  scored.sort((a, b) => b.score - a.score);
+  const top = scored.slice(0, 5);
+
+  return top.map((s) => {
+    const artifactLabel = s.signal ? 'skill / pack artifacts' : 'source files';
+    const why = s.keyword
+      ? `High-risk keyword "${s.keyword}" in path + ${s.count} ${artifactLabel}. Cross-cutting concerns amplify blast radius.`
+      : s.signal
+        ? `${s.count} skill/pack artifact(s) under \`${s.dir}/\` — SKILL.md / PACK.md edits reshape runtime behavior for every consumer.`
+        : `${s.count} source files in a directory ≥ depth 2 — concentrated surface area.`;
+    return {
+      section: 'danger',
+      title: `${s.dir} — ${s.count} ${artifactLabel}`,
+      what: `Changes under \`${s.dir}/\` touch core logic; require tests before merge.`,
+      where: [`${s.dir}/**`],
+      why,
+    };
+  });
+}
+
+/**
+ * Shared constant detection:
+ * Find `export const FOO = "literal"` (or UPPER_CASE) in ≤ 50 files,
+ * then count imports of FOO across the index. If imported ≥ 3 times, flag it.
+ */
+async function detectCriticalConstants(_root, index) {
+  const CONST_REGEX = /export\s+const\s+([A-Z][A-Z0-9_]+)\s*=\s*(?:['"`]|\d|\{|\[)/g;
+  const candidates = new Map(); // name -> { file, value-snippet }
+  let examined = 0;
+
+  for (const f of index.files) {
+    if (examined >= 50) break;
+    if (!/\.(ts|tsx|js|jsx|mjs)$/.test(f.rel)) continue;
+    if (f.size > 80_000) continue;
+    examined += 1;
+    let content;
+    try {
+      content = await readFile(f.abs, 'utf-8');
+    } catch {
+      continue;
+    }
+    let match;
+    CONST_REGEX.lastIndex = 0;
+    while ((match = CONST_REGEX.exec(content))) {
+      const name = match[1];
+      if (!candidates.has(name)) {
+        candidates.set(name, { file: f.rel, hits: 0 });
+      }
+    }
+  }
+
+  if (candidates.size === 0) return [];
+
+  // Count usages for each candidate across all indexed source files
+  const importRegexes = new Map();
+  for (const name of candidates.keys()) {
+    importRegexes.set(name, new RegExp(`\\b${escapeRegex(name)}\\b`, 'g'));
+  }
+
+  let usageScanned = 0;
+  for (const f of index.files) {
+    if (usageScanned >= 200) break;
+    if (!/\.(ts|tsx|js|jsx|mjs)$/.test(f.rel)) continue;
+    if (f.size > 80_000) continue;
+    usageScanned += 1;
+    let content;
+    try {
+      content = await readFile(f.abs, 'utf-8');
+    } catch {
+      continue;
+    }
+    for (const [name, re] of importRegexes) {
+      const matches = content.match(re);
+      if (matches && matches.length > 0) {
+        const c = candidates.get(name);
+        if (f.rel !== c.file) c.hits += matches.length;
+      }
+    }
+  }
+
+  const rules = [];
+  for (const [name, { file, hits }] of candidates) {
+    if (hits < 3) continue;
+    rules.push({
+      section: 'critical',
+      title: `Shared constant ${name}`,
+      what: `\`${name}\` (defined in \`${file}\`) is referenced ${hits} times across the codebase. Changing its value affects every consumer.`,
+      where: [file, `**/*.{ts,tsx,js,jsx,mjs}`],
+      why: `Widely imported constants are effectively part of the project's contract. Renames or value changes must propagate atomically.`,
+    });
+  }
+  rules.sort((a, b) => (b.what.match(/\d+/) || 0) - (a.what.match(/\d+/) || 0));
+  return rules.slice(0, 10);
+}
+
+/**
+ * State-machine detection: files that contain both a state enum/union AND
+ * a switch or reducer acting on it. Surface the pair as a single rule.
+ */
+async function detectStateMachines(_root, index) {
+  const rules = [];
+  const STATE_HINT = /\b(state|status|phase|stage)\s*[:=]\s*(?:['"])([a-z_]+)(?:['"])/i;
+  const SWITCH_HINT = /switch\s*\(\s*(?:\w+\.)?(?:state|status|phase|stage)\s*\)/;
+  const REDUCER_HINT = /case\s+['"`][A-Z_][A-Z0-9_]+['"`]\s*:/;
+
+  let scanned = 0;
+  for (const f of index.files) {
+    if (scanned >= 150) break;
+    if (!/\.(ts|tsx|js|jsx|mjs|py)$/.test(f.rel)) continue;
+    if (f.size > 80_000) continue;
+    scanned += 1;
+    let content;
+    try {
+      content = await readFile(f.abs, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const hasSwitch = SWITCH_HINT.test(content);
+    const hasReducer = REDUCER_HINT.test(content);
+    const stateMatch = STATE_HINT.exec(content);
+    if (!(hasSwitch || hasReducer) || !stateMatch) continue;
+
+    rules.push({
+      section: 'state',
+      title: `State machine in ${f.rel}`,
+      what: `Transitions in \`${f.rel}\` must respect declared states. New states require updating every switch/case site.`,
+      where: [f.rel],
+      why: `Detected ${hasSwitch ? 'switch(state)' : 'reducer'} + state literal (e.g. "${stateMatch[2]}"). Missing-case bugs are a classic regression vector.`,
+    });
+    if (rules.length >= 5) break;
+  }
+  return rules;
+}
+
+/**
+ * Cross-file consistency heuristic: find string literal tuples that appear
+ * verbatim in ≥ 3 files (e.g. `["pending", "active", "closed"]`). Often these
+ * are mirrored schemas/enums that must stay in lock-step.
+ */
+async function detectCrossFileConsistency(_root, index) {
+  const TUPLE_REGEX = /\[\s*(['"][a-z_-]{2,}['"](?:\s*,\s*['"][a-z_-]{2,}['"]){2,})\s*\]/gi;
+  const byTuple = new Map();
+
+  let scanned = 0;
+  for (const f of index.files) {
+    if (scanned >= 150) break;
+    if (!/\.(ts|tsx|js|jsx|mjs|py)$/.test(f.rel)) continue;
+    if (f.size > 80_000) continue;
+    scanned += 1;
+    let content;
+    try {
+      content = await readFile(f.abs, 'utf-8');
+    } catch {
+      continue;
+    }
+    const seen = new Set();
+    TUPLE_REGEX.lastIndex = 0;
+    let match;
+    while ((match = TUPLE_REGEX.exec(content))) {
+      const normalized = match[1].replace(/\s+/g, '').toLowerCase();
+      if (seen.has(normalized)) continue;
+      seen.add(normalized);
+      if (!byTuple.has(normalized)) byTuple.set(normalized, new Set());
+      byTuple.get(normalized).add(f.rel);
+    }
+  }
+
+  const rules = [];
+  for (const [tuple, fileSet] of byTuple) {
+    if (fileSet.size < 3) continue;
+    const sample = tuple.split(',').slice(0, 4).join(', ');
+    rules.push({
+      section: 'cross',
+      title: `Mirrored literal tuple (${sample}${tuple.includes(',') ? '…' : ''})`,
+      what: `Identical literal list appears in ${fileSet.size} files; updates must land in every location.`,
+      where: Array.from(fileSet).sort().slice(0, 10),
+      why: `Duplicated tuples are typically mirrored schemas (DB columns, API fields, state enums). Drift between copies causes subtle bugs.`,
+    });
+  }
+  rules.sort((a, b) => b.where.length - a.where.length);
+  return rules.slice(0, 5);
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Render a detection result into the markdown block that gets injected under
+ * `## Auto-detected (new)` in INVARIANTS.md.
+ */
+export function renderInvariants(result) {
+  const lines = [];
+  const sections = [
+    ['Danger Zones', result.danger],
+    ['Critical Invariants', result.critical],
+    ['State Machine Rules', result.state],
+    ['Cross-File Consistency', result.cross],
+  ];
+  for (const [title, rules] of sections) {
+    if (!rules || rules.length === 0) continue;
+    lines.push(`### ${title}`);
+    lines.push('');
+    for (const rule of rules) {
+      lines.push(`#### ${rule.title}`);
+      lines.push(`- **WHAT**: ${rule.what}`);
+      lines.push(`- **WHERE**: ${rule.where.map((w) => `\`${w}\``).join(', ')}`);
+      lines.push(`- **WHY**: ${rule.why}`);
+      lines.push('');
+    }
+  }
+  if (lines.length === 0) return '_No invariants detected in this run._\n';
+  return `${lines.join('\n')}`;
+}
+
+// ─── CLI ───
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      root: { type: 'string', default: process.cwd() },
+      json: { type: 'boolean', default: false },
+    },
+  });
+  const result = await detectInvariants({ root: values.root });
+  if (values.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(renderInvariants(result));
+  process.stdout.write(`\n_Scanned ${result.stats.filesScanned} files._\n`);
+}
+
+// Only run main() when invoked directly as a CLI
+const isMain = (() => {
+  try {
+    return import.meta.url === `file://${process.argv[1]}` || import.meta.url.endsWith(path.basename(process.argv[1]));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  main().catch((err) => {
+    process.stderr.write(`detect-invariants: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/skills/onboard/scripts/inject-claude-md.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * inject-claude-md.js — Idempotent editor for CLAUDE.md that maintains an
+ * auto-generated "Invariants (auto-detected)" pointer block.
+ *
+ * The block is delimited by HTML comment markers that are valid in Markdown:
+ *
+ *   <!-- @rune-invariants-pointer:start -->
+ *   ...
+ *   <!-- @rune-invariants-pointer:end -->
+ *
+ * Content outside these markers is NEVER touched. Re-running replaces only the
+ * content between the markers. Users can delete the markers to opt out — a
+ * subsequent run will re-inject them once and respect a user-placed
+ * `<!-- @rune-invariants-pointer:skip -->` directive indefinitely.
+ *
+ * Usage as CLI:
+ *   node inject-claude-md.js --claude-md <path> --invariants <path>
+ *
+ * Usage as module:
+ *   import { injectInvariantsPointer, buildPointerBlock } from './inject-claude-md.js';
+ *   const { action, content } = injectInvariantsPointer({ claudeMd, globs });
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+
+export const MARKER_START = '<!-- @rune-invariants-pointer:start -->';
+export const MARKER_END = '<!-- @rune-invariants-pointer:end -->';
+export const SKIP_DIRECTIVE = '<!-- @rune-invariants-pointer:skip -->';
+
+const DEFAULT_INVARIANTS_PATH = '.rune/INVARIANTS.md';
+const MAX_GLOBS_IN_POINTER = 8;
+
+export function buildPointerBlock({ globs = [], invariantsPath = DEFAULT_INVARIANTS_PATH } = {}) {
+  const unique = Array.from(new Set(globs.filter((g) => typeof g === 'string' && g.trim())));
+  const shown = unique.slice(0, MAX_GLOBS_IN_POINTER);
+  const overflow = unique.length - shown.length;
+
+  const lines = [
+    MARKER_START,
+    '## Invariants (auto-detected)',
+    '',
+    `Before editing these paths, read [\`${invariantsPath}\`](${invariantsPath}) —`,
+    'it lists danger zones and cross-file invariants this project enforces.',
+    '',
+  ];
+
+  if (shown.length === 0) {
+    lines.push('_No danger zones detected yet. Re-run `rune onboard` after the codebase grows._');
+  } else {
+    for (const glob of shown) {
+      lines.push(`- \`${glob}\``);
+    }
+    if (overflow > 0) {
+      lines.push(`- _…and ${overflow} more — see \`${invariantsPath}\`_`);
+    }
+  }
+
+  lines.push('', MARKER_END);
+  return lines.join('\n');
+}
+
+export function injectInvariantsPointer({ claudeMd = '', globs = [], invariantsPath = DEFAULT_INVARIANTS_PATH } = {}) {
+  if (claudeMd.includes(SKIP_DIRECTIVE)) {
+    return { action: 'skipped', reason: 'skip-directive', content: claudeMd };
+  }
+
+  const block = buildPointerBlock({ globs, invariantsPath });
+
+  const startIdx = claudeMd.indexOf(MARKER_START);
+  const endIdx = claudeMd.indexOf(MARKER_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = claudeMd.slice(0, startIdx);
+    const after = claudeMd.slice(endIdx + MARKER_END.length);
+    const next = `${before}${block}${after}`;
+    if (next === claudeMd) {
+      return { action: 'unchanged', content: claudeMd };
+    }
+    return { action: 'updated', content: next };
+  }
+
+  if (startIdx !== -1 || endIdx !== -1) {
+    return {
+      action: 'error',
+      reason: 'marker-mismatch',
+      content: claudeMd,
+    };
+  }
+
+  const separator = claudeMd.length === 0 || claudeMd.endsWith('\n\n') ? '' : claudeMd.endsWith('\n') ? '\n' : '\n\n';
+  const next = `${claudeMd}${separator}${block}\n`;
+  return { action: 'created', content: next };
+}
+
+export async function applyInvariantsPointer({
+  claudeMdPath,
+  globs = [],
+  invariantsPath = DEFAULT_INVARIANTS_PATH,
+  dryRun = false,
+} = {}) {
+  if (!claudeMdPath) {
+    throw new Error('claudeMdPath is required');
+  }
+
+  const existing = existsSync(claudeMdPath) ? await readFile(claudeMdPath, 'utf8') : '';
+  const result = injectInvariantsPointer({ claudeMd: existing, globs, invariantsPath });
+
+  if (!dryRun && (result.action === 'created' || result.action === 'updated')) {
+    await writeFile(claudeMdPath, result.content, 'utf8');
+  }
+
+  return { ...result, path: claudeMdPath, existed: existing.length > 0 };
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      'claude-md': { type: 'string' },
+      invariants: { type: 'string', default: DEFAULT_INVARIANTS_PATH },
+      globs: { type: 'string', multiple: true, default: [] },
+      dry: { type: 'boolean', default: false },
+    },
+  });
+
+  const claudeMdPath = values['claude-md'];
+  if (!claudeMdPath) {
+    console.error('Usage: inject-claude-md.js --claude-md <path> [--invariants <path>] [--globs glob ...] [--dry]');
+    process.exit(2);
+  }
+
+  const result = await applyInvariantsPointer({
+    claudeMdPath,
+    globs: values.globs,
+    invariantsPath: values.invariants,
+    dryRun: values.dry,
+  });
+
+  console.log(JSON.stringify({ path: result.path, action: result.action, reason: result.reason ?? null }));
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('inject-claude-md.js')) {
+  main().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
+}