@rune-kit/rune 2.16.1 → 2.18.0

package/compiler/adapters/qoder.js

@@ -0,0 +1,102 @@
+/**
+ * Qoder Adapter
+ *
+ * Emits per-skill rule files into .qoder/rules/ — Qoder's documented project-level
+ * rule directory. Qoder also reads AGENTS.md as its project-context file.
+ *
+ * Qoder rules dir: .qoder/rules/
+ * Qoder rule file: .qoder/rules/rune-{name}.md (one file per skill)
+ * Qoder project context: AGENTS.md (open AGENTS.md standard)
+ *
+ * @see https://docs.qoder.com/user-guide/rules
+ * @see https://agents.md/
+ *
+ * MODEL TIER MAPPING (v2.18+):
+ * Qoder is provider-agnostic — emits semantic tier hints rather than concrete
+ * model names. Qoder IDE resolves the tier to its configured provider model.
+ */
+
+import { BRANDING_FOOTER } from '../transforms/branding.js';
+
+const MODEL_MAP = {
+  opus: 'tier:heavy',
+  sonnet: 'tier:mid',
+  haiku: 'tier:light',
+};
+
+const TOOL_MAP = {
+  Read: 'read the file',
+  Write: 'write/create the file',
+  Edit: 'edit the file',
+  Glob: 'find files by pattern',
+  Grep: 'search file contents',
+  Bash: 'run a shell command',
+  TodoWrite: 'track task progress',
+  Skill: 'follow the referenced rune-{name} rule',
+  Agent: 'execute the workflow',
+};
+
+export default {
+  name: 'qoder',
+  outputDir: '.qoder/rules',
+  fileExtension: '.md',
+  skillPrefix: 'rune-',
+  skillSuffix: '',
+
+  // Qoder rules are flat .md files, not directory-per-skill
+  useSkillDirectories: false,
+
+  transformReference(skillName, raw) {
+    const isBackticked = raw.startsWith('`') && raw.endsWith('`');
+    const ref = `the rune-${skillName} rule`;
+    return isBackticked ? `\`${ref}\`` : ref;
+  },
+
+  transformToolName(toolName) {
+    return TOOL_MAP[toolName] || toolName;
+  },
+
+  generateHeader(skill) {
+    const desc = (skill.description || '').replace(/"/g, '\\"');
+    const lines = ['---', `name: rune-${skill.name}`, `description: "${desc}"`];
+    const translatedModel = skill.model ? MODEL_MAP[skill.model] || skill.model : null;
+    if (translatedModel) lines.push(`model: ${translatedModel}`);
+    lines.push('---', '', '');
+    return lines.join('\n');
+  },
+
+  generateFooter() {
+    return BRANDING_FOOTER;
+  },
+
+  transformSubagentInstruction(text) {
+    return text;
+  },
+
+  scriptsDir(skillName) {
+    return `rune-${skillName}-scripts`;
+  },
+
+  postProcess(content) {
+    return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
+  },
+
+  // Qoder reads AGENTS.md at the project root as its high-level context file.
+  generateExtraFiles({ stats }) {
+    const agentsMd = [
+      '# Rune — Project Configuration',
+      '',
+      'Rune is an interconnected skill ecosystem for AI coding assistants.',
+      `${stats.skillCount} core skills + ${stats.packCount} extension packs.`,
+      '',
+      'Per-skill rules live under `.qoder/rules/rune-<name>.md`. Qoder loads them automatically.',
+      '',
+      'Reference a skill by name (e.g. "follow the rune-cook rule") inside any chat — the rule file is auto-injected.',
+      '',
+      '---',
+      '> Rune Skill Mesh — https://github.com/rune-kit/rune',
+      '',
+    ].join('\n');
+    return [{ path: 'AGENTS.md', content: agentsMd }];
+  },
+};

package/compiler/adapters/qwen.js

@@ -0,0 +1,111 @@
+/**
+ * Qwen Coder Adapter
+ *
+ * Emits per-skill rule files into qwen/skills/ and a top-level QWEN.md that
+ * uses Qwen Code's @import syntax to load each rule file. Qwen Code loads
+ * QWEN.md hierarchically (cwd → parent → ~/.qwen/QWEN.md).
+ *
+ * Qwen rules dir: qwen/skills/
+ * Qwen rule file: qwen/skills/rune-{name}.md
+ * Qwen project context: QWEN.md at project root (with @path imports)
+ *
+ * @see https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/
+ * @see https://github.com/QwenLM/qwen-code
+ *
+ * MODEL TIER MAPPING (v2.18+):
+ * Qwen Coder defaults to Qwen3-Coder family. Anthropic-style tier names
+ * translate to Qwen size hints (heavy=qwen3-coder-plus, mid=qwen3-coder,
+ * light=qwen3-coder-flash). Hint only — Qwen Code reads model from settings.
+ */
+
+import { BRANDING_FOOTER } from '../transforms/branding.js';
+
+const MODEL_MAP = {
+  opus: 'qwen3-coder-plus',
+  sonnet: 'qwen3-coder',
+  haiku: 'qwen3-coder-flash',
+};
+
+const TOOL_MAP = {
+  Read: 'read the file',
+  Write: 'write/create the file',
+  Edit: 'edit the file',
+  Glob: 'find files by pattern',
+  Grep: 'search file contents',
+  Bash: 'run a shell command',
+  TodoWrite: 'track task progress',
+  Skill: 'follow the imported rune-{name} skill',
+  Agent: 'execute the workflow',
+};
+
+export default {
+  name: 'qwen',
+  outputDir: 'qwen/skills',
+  fileExtension: '.md',
+  skillPrefix: 'rune-',
+  skillSuffix: '',
+
+  // Qwen skills are flat per-skill markdown files imported from QWEN.md.
+  useSkillDirectories: false,
+
+  transformReference(skillName, raw) {
+    const isBackticked = raw.startsWith('`') && raw.endsWith('`');
+    const ref = `the rune-${skillName} skill`;
+    return isBackticked ? `\`${ref}\`` : ref;
+  },
+
+  transformToolName(toolName) {
+    return TOOL_MAP[toolName] || toolName;
+  },
+
+  generateHeader(skill) {
+    const desc = (skill.description || '').replace(/"/g, '\\"');
+    const lines = ['---', `name: rune-${skill.name}`, `description: "${desc}"`];
+    const translatedModel = skill.model ? MODEL_MAP[skill.model] || skill.model : null;
+    if (translatedModel) lines.push(`# model-hint: ${translatedModel}`);
+    lines.push('---', '', '');
+    return lines.join('\n');
+  },
+
+  generateFooter() {
+    return BRANDING_FOOTER;
+  },
+
+  transformSubagentInstruction(text) {
+    return text;
+  },
+
+  scriptsDir(skillName) {
+    return `rune-${skillName}-scripts`;
+  },
+
+  postProcess(content) {
+    return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
+  },
+
+  // Emit QWEN.md at project root with @import lines for every per-skill file.
+  generateExtraFiles({ stats }) {
+    const skillFiles = stats.files
+      .filter((f) => f.startsWith('rune-') && f.endsWith('.md') && !f.includes('/') && !f.includes('\\'))
+      .sort();
+
+    const qwenMd = [
+      '# Rune — Project Configuration',
+      '',
+      'Rune is an interconnected skill ecosystem for AI coding assistants.',
+      `${stats.skillCount} core skills + ${stats.packCount} extension packs.`,
+      '',
+      '## Loaded Skills',
+      '',
+      'Qwen Code loads each referenced file as part of this project context.',
+      '',
+      ...skillFiles.map((f) => `@qwen/skills/${f}`),
+      '',
+      '---',
+      '> Rune Skill Mesh — https://github.com/rune-kit/rune',
+      '',
+    ].join('\n');
+
+    return [{ path: 'QWEN.md', content: qwenMd }];
+  },
+};

package/compiler/bin/rune.js

@@ -13,15 +13,18 @@
 
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { getAdapter, listPlatforms } from '../adapters/index.js';
 import { getAllAnalytics } from '../analytics.js';
 import { dispatchHook } from '../commands/hook-dispatch.js';
+import { checkHookDrift, formatHookDriftResult } from '../commands/hooks/drift.js';
 import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
+import { formatSetupResult, runSetup } from '../commands/setup.js';
 import { generateDashboardHTML } from '../dashboard.js';
 import { checkMeshIntegrity, formatDoctorResults, formatMeshResults, runDoctor } from '../doctor.js';
 import { buildAll } from '../emitter.js';
@@ -241,6 +244,14 @@ async function cmdBuild(projectRoot, args) {
 async function cmdDoctor(projectRoot, args) {
   const config = await readConfig(projectRoot);
 
+  // --hooks flag: run hook drift report only (reporter, exit 0 always)
+  if (args.hooks) {
+    log('');
+    const driftResult = await checkHookDrift(projectRoot);
+    log(formatHookDriftResult(driftResult));
+    return;
+  }
+
   // --mesh flag: run mesh integrity check only
   if (args.mesh) {
     log('');
@@ -294,6 +305,45 @@ async function cmdDoctor(projectRoot, args) {
   if (!results.healthy) process.exit(1);
 }
 
+async function cmdSetup(projectRoot, args) {
+  log('');
+  log('  Rune Setup Wizard');
+  log('  ──────────────────');
+  log(`  Free version:    ${await readVersion()} (cached)`);
+
+  // Print detected tiers banner
+  const { detectTiers } = await import('../commands/setup.js');
+  const detected = detectTiers(projectRoot);
+  if (detected.pro) {
+    log(`  Pro detected:    ${detected.pro.source} (v${detected.pro.version})`);
+  } else {
+    log('  Pro:             not detected');
+  }
+  if (detected.business) {
+    log(`  Business:        ${detected.business.source} (v${detected.business.version})`);
+  } else {
+    log('  Business:        not detected');
+  }
+
+  try {
+    const result = await runSetup({ projectRoot, runeRoot: RUNE_ROOT, args });
+    log(formatSetupResult(result));
+  } catch (err) {
+    log('');
+    log(`  ✗ Setup failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+async function readVersion() {
+  try {
+    const pkg = JSON.parse(await readFile(path.join(RUNE_ROOT, 'package.json'), 'utf-8'));
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
 async function cmdStatus(projectRoot, args) {
   const config = await readConfig(projectRoot);
   const tierSources = resolveTierSources(config?.tiers, projectRoot);
@@ -458,10 +508,13 @@ async function cmdHooks(projectRoot, args, subcommand) {
   switch (subcommand) {
     case 'install': {
       const tierArg = parseTierFlag(args.tier);
-      const result = await installHooks(projectRoot, {
+      // --global writes to ~/.claude/settings.json (covers every Claude Code session)
+      const targetRoot = args.global ? os.homedir() : projectRoot;
+      const platform = args.global ? 'claude' : args.platform;
+      const result = await installHooks(targetRoot, {
         preset: args.preset,
         dry: args.dry,
-        platform: args.platform,
+        platform,
         tier: tierArg,
       });
       log('');
@@ -636,6 +689,9 @@ async function main() {
     case 'doctor':
       await cmdDoctor(projectRoot, args);
       break;
+    case 'setup':
+      await cmdSetup(projectRoot, args);
+      break;
     case 'status':
       await cmdStatus(projectRoot, args);
       break;
@@ -664,17 +720,22 @@ async function main() {
       log('  Rune CLI — Skill mesh for AI coding assistants');
       log('');
       log('  Commands:');
-      log('    init     Interactive setup (auto-detects platform)');
+      log(
+        '    setup    Interactive wizard — auto-detect tiers, pick scope, install hooks (recommended for first-time)',
+      );
+      log('             [--here|--global] [--tier pro,business] [--preset gentle|strict] [--dry]');
+      log('    init     Interactive setup for build pipeline (auto-detects platform)');
       log('    build    Compile skills for configured platform');
       log('    doctor   Validate compiled output + mesh integrity');
       log('             --mesh   Mesh integrity only (reciprocals, versions, sections)');
+      log('             --hooks  Hook drift report — compare installed vs canonical preset (reporter, exit 0)');
       log('             --strict Fail on warnings (for CI)');
       log('    status   Project dashboard (skills, signals, packs, health)');
       log('    visualize  Interactive mesh graph (opens in browser)');
       log('    analytics  Usage analytics dashboard (Business tier)');
       log('    hooks      Install/uninstall/status for multi-platform auto-discipline');
       log(
-        '               hooks install [--preset gentle|strict|off] [--platform claude|cursor|windsurf|antigravity|all]',
+        '               hooks install [--preset gentle|strict|off] [--platform claude|cursor|windsurf|antigravity|all] [--global]',
       );
       log('               hooks uninstall [--platform <name>|all]');
       log('               hooks status [--platform <name>|all]');

package/compiler/commands/hooks/drift.js

@@ -0,0 +1,170 @@
+/**
+ * Hook drift reporter.
+ *
+ * Compares Rune-managed Free-preset entries in `.claude/settings.json` against
+ * the canonical `buildPreset()` output for the detected preset. Flags missing
+ * entries (preset wired more than what's installed) and drifted entries
+ * (installed command differs from canonical shape).
+ *
+ * Reporter, NOT a gate — exit 0 always. Operators legitimately edit settings.json
+ * (custom user hooks alongside Rune hooks). Auto-fix would be hostile.
+ *
+ * Scope: Free preset only. Tier-emitted entries (`${RUNE_PRO_ROOT}` /
+ * `${RUNE_BUSINESS_ROOT}`) are filtered out — those are checked separately
+ * by tier doctor (out of scope for v2.17.0).
+ *
+ * Use case: diagnostic before users file "skill is broken" issues. Local drift
+ * is a common cause of unexplained hook behavior — a check that points at the
+ * actual deviation saves a round-trip with the maintainer.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { detectPlatforms } from '../../adapters/hooks/index.js';
+import { detectPreset } from './merge.js';
+import { buildPreset, isRuneManaged, SETTINGS_REL_PATH } from './presets.js';
+
+const TIER_ENV_RE = /\$\{RUNE_[A-Z][A-Z0-9_]*_ROOT\}/;
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<{findings: Array, summary: object, platforms: string[]}>}
+ */
+export async function checkHookDrift(projectRoot) {
+  const platforms = detectPlatforms(projectRoot);
+  const findings = [];
+  const checked = [];
+
+  for (const id of platforms) {
+    if (id !== 'claude') continue; // Settings drift is Claude-specific
+    const settingsPath = path.join(projectRoot, SETTINGS_REL_PATH);
+    if (!existsSync(settingsPath)) continue;
+
+    let settings;
+    try {
+      const raw = await readFile(settingsPath, 'utf-8');
+      settings = raw.trim() ? JSON.parse(raw) : {};
+    } catch (err) {
+      findings.push({
+        platform: id,
+        event: null,
+        status: 'error',
+        message: `Cannot parse ${SETTINGS_REL_PATH}: ${err.message}`,
+      });
+      continue;
+    }
+
+    const preset = detectPreset(settings);
+    if (preset === 'none') continue; // No Rune hooks installed
+    if (preset === 'mixed') {
+      findings.push({
+        platform: id,
+        event: null,
+        status: 'mixed-preset',
+        message:
+          'settings.json contains both gentle and strict Rune entries — re-run `rune hooks install --preset <gentle|strict>` to converge',
+      });
+    }
+
+    // For mixed preset, fall back to gentle for canonical comparison
+    const canonicalPreset = preset === 'mixed' ? 'gentle' : preset;
+    const canonical = buildPreset(canonicalPreset);
+    checked.push({ platform: id, preset });
+
+    for (const event of ['PreToolUse', 'PostToolUse', 'Stop']) {
+      const actualCommands = collectFreePresetCommands(settings.hooks?.[event] || []);
+      const canonicalCommands = collectFreePresetCommands(canonical.hooks?.[event] || []);
+
+      // Missing: canonical entry not present in actual
+      for (const cmd of canonicalCommands) {
+        if (!actualCommands.includes(cmd)) {
+          findings.push({ platform: id, event, status: 'missing', expected: cmd });
+        }
+      }
+
+      // Drift: actual entry not in canonical (extra or modified)
+      for (const cmd of actualCommands) {
+        if (!canonicalCommands.includes(cmd)) {
+          findings.push({ platform: id, event, status: 'drift', actual: cmd });
+        }
+      }
+    }
+  }
+
+  const summary = {
+    drifted: findings.filter((f) => f.status === 'drift').length,
+    missing: findings.filter((f) => f.status === 'missing').length,
+    errors: findings.filter((f) => f.status === 'error' || f.status === 'mixed-preset').length,
+  };
+
+  return { findings, summary, platforms: checked };
+}
+
+/**
+ * Pull Rune-managed Free-preset commands out of a matcher-group list.
+ * Tier-emitted entries (`${RUNE_*_ROOT}/...`) are excluded — those are tier-managed,
+ * not Free-preset, and have their own check path.
+ */
+function collectFreePresetCommands(matcherGroups) {
+  const cmds = [];
+  if (!Array.isArray(matcherGroups)) return cmds;
+  for (const group of matcherGroups) {
+    if (!Array.isArray(group?.hooks)) continue;
+    for (const entry of group.hooks) {
+      if (!isRuneManaged(entry)) continue;
+      if (TIER_ENV_RE.test(entry.command)) continue; // tier entry — not our concern here
+      cmds.push(entry.command);
+    }
+  }
+  return cmds;
+}
+
+/**
+ * Format drift result as human-readable lines.
+ *
+ * @param {Awaited<ReturnType<typeof checkHookDrift>>} result
+ * @returns {string}
+ */
+export function formatHookDriftResult(result) {
+  const lines = [];
+  lines.push('  Hook Drift Report');
+  lines.push('  ──────────────────');
+
+  if (result.platforms.length === 0) {
+    lines.push('');
+    lines.push('  ℹ No installed Rune hooks detected on Claude. Run `rune hooks install --preset gentle` first.');
+    return lines.join('\n');
+  }
+
+  for (const { platform, preset } of result.platforms) {
+    lines.push(`  Platform: ${platform} (preset: ${preset})`);
+  }
+  lines.push('');
+
+  if (result.findings.length === 0) {
+    lines.push('  ✓ All Rune-managed entries match canonical preset.');
+    return lines.join('\n');
+  }
+
+  for (const f of result.findings) {
+    if (f.status === 'mixed-preset' || f.status === 'error') {
+      lines.push(`  ⚠ ${f.platform}: ${f.message}`);
+    } else if (f.status === 'missing') {
+      lines.push(`  ✗ ${f.platform} ${f.event}: missing canonical entry`);
+      lines.push(`      expected: ${f.expected}`);
+    } else if (f.status === 'drift') {
+      lines.push(`  ✗ ${f.platform} ${f.event}: drift — installed command not in canonical preset`);
+      lines.push(`      actual:   ${f.actual}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(
+    `  Summary: ${result.summary.drifted} drifted, ${result.summary.missing} missing, ${result.summary.errors} error(s).`,
+  );
+  lines.push('  Resolution: re-run `rune hooks install --preset <gentle|strict>` to re-converge.');
+  lines.push('  This is a reporter — operator decides what to do with the findings.');
+
+  return lines.join('\n');
+}

package/compiler/commands/hooks/presets.js

@@ -81,6 +81,16 @@ export function buildPreset(preset) {
             },
           ],
         },
+        {
+          matcher: 'mcp__.*|WebFetch|Read',
+          hooks: [
+            {
+              type: 'command',
+              command: `${DISPATCH_CMD} quarantine${flag}`,
+              async: true,
+            },
+          ],
+        },
       ],
       Stop: [
         {
@@ -101,7 +111,7 @@ export function buildPreset(preset) {
 /**
  * Skills wired by presets — used by `rune hooks status` to verify skill existence.
  */
-export const WIRED_SKILLS = ['preflight', 'sentinel', 'dependency-doctor', 'completion-gate'];
+export const WIRED_SKILLS = ['preflight', 'sentinel', 'dependency-doctor', 'completion-gate', 'quarantine'];
 
 /**
  * Detect if a hook command entry is Rune-managed.